update: formation energy tutorial (gemini)

lang/en/docs/properties-directory/scalar/formation-energy.md

@@ -11,6 +11,7 @@ $$
 $$	
 
  `E_fmt` and `E_tot`, `E_zpe` are the formation energy, total energy and zero point energy for the compound and lowest energy elemental structures, correspondingly.
-
- !!!note "Note: feature under development"
-    The calculation of Formation energies is not yet available as a Workflow computation on our platform.
+
+## Tutorials
+
+- [Calculate Formation Energy]({{ reference_url }}/tutorials/dft/thermodynamic/formation-energy/)

lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md

@@ -0,0 +1,65 @@
+# Calculate Defect Formation Energy
+
+This tutorial explains how to calculate the [defect formation energy]({{ reference_url }}/properties-directory/scalar/formation-energy/) of a defective material using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). 
+
+## 1. Prerequisites
+
+The defect formation energy is calculated with respect to the pristine material and its constituent elements in their standard states. For the workflow to succeed, the **elemental total energies must already exist** on the platform.
+
+Before running the defect formation energy workflow for a defective compound (e.g., Nitrogen vacancy in GaN), you must first calculate the [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) for each of its constituent elements that are added or removed to create the defect:
+1. **Get Elemental Materials**: Navigate to your Materials collection and import the relevant elemental reference materials from Standata, saving them to your account.
+2. **Calculate Total Energy**: For each elemental material, run a Total Energy calculation by following the [Total Energy tutorial](total-energy.md). 
+   - **Crucial**: The precision settings (e.g., KPPRA, kinetic energy cutoffs) used for the elements must exactly match the settings you will use for the defective material's calculation.
+   - **Crucial**: Ensure you note the **Group** under which these elemental properties are saved, as you will need to specify this group in the Defect Formation Energy workflow.
+
+## 2. Create the materials
+
+1. Create the pristine bulk material structure using the [Materials Designer]({{ interface_url }}/materials-designer/overview/).
+2. Create the defective structure. You can follow tutorials on creating defects, such as [Create Point Defect Pair in GaN](../../materials/specific/defect-point-pair-gallium-nitride.md).
+3. Ensure that the total energy for the pristine material has been calculated with the same precision parameters that you plan to use for the defect calculation.
+
+## 3. Understand the workflow structure
+
+<details markdown="1">
+  <summary>Expand to view unit details</summary>
+
+The defect formation energy [workflow]({{ reference_url }}/workflows/overview/) is composed of several [subworkflows]({{ reference_url }}/workflows/components/subworkflows/) that load the materials, fetch their pre-calculated total energies, and compute the final energy.
+
+### 1. Load Defective Material
+- Loads the defective material into the workflow.
+
+### 2. Compute Total Energy for Defective Material
+- **pw_scf**: Performs an SCF calculation on the defective structure.
+
+### 3. Load Pristine Material
+- Loads the standalone pristine bulk material into the workflow.
+
+### 4. Fetch Total Energy for Pristine Material
+- Queries the platform for the total energy of the pristine material and extracts it using `io-bulk-te-job` and `io-te-bulk`.
+
+### 5. Get Elemental Materials
+- Contains a loop (`init-element-index` / `check-elemental-te-loop` / `assign-current-element`) that iterates over elements.
+- **io-elemental-energy** retrieves the pre-calculated `total_energy` property for the current element's standard state reference material.
+
+### 6. Compute Defect Formation Energy
+- **assign-defect-formation-energy**: Uses [Python]({{ reference_url }}/software-directory/scripting/python/overview/) to compute the defect formation energy by finding the difference in total energy between the defective and pristine materials, adjusted for the chemical potentials (elemental reference energies) of any atoms added or removed.
+
+</details>
+
+## 4. Select the workflow and create the job
+
+1. Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) and select your defective material.
+2. [Workflows]({{ reference_url }}/workflows/overview/) for defect formation energy calculations with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/).
+3. Once imported, [select]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) the Defect Formation Energy workflow and add it to your job.
+
+## 5. Set Group and Source of Properties
+
+Inside the **Fetch Total Energy for Pristine Material** and **Get Elemental Materials** subworkflows, switch to the **Detailed view** tab. Check the [assignment units]({{ reference_url }}/workflows/components/units/#assignment) and ensure the groups are set correctly to match the group under which you calculated the individual total energies (e.g., your account).
+
+## 6. Submit the job
+
+Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) to verify the compute parameters. Ensure that the K-point grid and cutoffs match those used for the pristine material and elemental reference calculations.
+
+## 7. Examine the results
+
+Once the job completes, navigate to the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of the [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). The **Defect Formation Energy** property will be displayed.

lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md

@@ -0,0 +1,80 @@
+# Calculate Formation Energy
+
+This tutorial explains how to calculate the [formation energy]({{ reference_url }}/properties-directory/scalar/formation-energy/) of a compound material using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/).
+
+!!!note "Quantum ESPRESSO version"
+    This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0, 6.0.0, 6.3, and later.
+
+## Prerequisites
+
+The formation energy of a compound is calculated with respect to its constituent elements in their standard states. For the workflow to succeed, the **elemental total energies must already exist** on the platform.
+
+Before running the formation energy workflow for a compound (e.g., Silicon Carbide, SiC), you must first calculate the [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) for each of its constituent elements:
+1. **Get Elemental Materials**: Navigate to your Materials collection and import the relevant elemental reference materials from Standata, saving them to your account.
+2. **Calculate Total Energy**: For each elemental material, run a Total Energy calculation by following the [Total Energy tutorial](total-energy.md). 
+   - **Crucial**: The precision settings (e.g., KPPRA, kinetic energy cutoffs) used for the elements must exactly match the settings you will use for the compound material's calculation.
+   - **Crucial**: Ensure you note the **Group** under which these elemental properties are saved, as you will need to specify this group in the Formation Energy workflow.
+
+## 1. Create a job
+
+Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) to create a new job. 
+
+Under the *Choose A Material* section, select the compound material for which you want to calculate the formation energy. You can import materials from external databases or upload them directly.
+
+![Job Designer material selection for Formation Energy](/images/tutorials/formation_energy/formation-energy-material-selection.png)
+
+## 2. Understand the workflow structure
+
+<details markdown="1">
+  <summary>Expand to view unit details</summary>
+
+The [workflow]({{ reference_url }}/workflows/overview/) is composed of the following key [units]({{ reference_url }}/workflows/components/units/):
+
+**pw_scf** — Performs a self-consistent field (SCF) calculation to determine the total energy of the compound material.
+
+**assign-compound-precision** — Evaluates the grid precision (e.g., KPPRA) used in the SCF calculation to ensure consistent precision matching when retrieving elemental energies.
+
+**init-element-index** / **check-elemental-te-loop** / **assign-current-element** — A loop construct that iterates over each unique element present in the compound.
+
+**io-elemental-energy** — An [I/O unit]({{ reference_url }}/workflows/components/units/#i/o) that queries the platform's REST API to retrieve the pre-calculated `total_energy` property for the current element's standard state reference material. It filters by owner (e.g., public, curators, or my account) and sorts by precision to find the most appropriate reference value.
+
+**assign-formation-energy** — Uses [Python]({{ reference_url }}/software-directory/scripting/python/overview/) logic to subtract the sum of the elemental reference energies (scaled by stoichiometry) from the compound's total energy, yielding the final formation energy.
+
+</details>
+
+## 3. Select the workflow
+
+[Workflows]({{ reference_url }}/workflows/overview/) for calculating formation energy with Quantum ESPRESSO can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/) into your account-owned [collection]({{ reference_url }}/accounts/collections/). 
+
+In the Job Designer, [select]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) the Formation Energy workflow and add it to the job.
+
+![Job Designer workflow selection for Formation Energy](/images/tutorials/formation_energy/formation-energy-workflow-selection.png)
+
+## 4. Set Group and Source of Properties
+
+Inside the **Get Elemental Materials** subworkflow, switch to the **Detailed view** tab. There are two critical [assignment units]({{ reference_url }}/workflows/components/units/#assignment) that must be configured correctly:
+
+**assign-group-for-material**: This unit sets the [group]({{ reference_url }}/accounts/groups/) (e.g. public, curators, or your account) where the platform will search for the elemental Total Energy results. The group selected here must match the owner group of the elemental properties you wish to use.
+
+![Job Designer group assignment for Formation Energy](/images/tutorials/formation_energy/formation-energy-group.png)
+
+**assign-source-of-te-for-an-element**: This unit specifies the source of the property. By default, it queries Standata for elemental energies.
+
+## 5. Set parameters
+
+In the workflow unit settings, ensure the [k-point grid]({{ reference_url }}/models/auxiliary-concepts/reciprocal-space/sampling/) is sufficiently dense for your desired accuracy. A high KPPRA (k-points per reciprocal atom) is typically required for accurate formation energies. 
+
+!!!important "Precision Consistency"
+    The precision settings (e.g., KPPRA, kinetic energy cutoff) used for the compound material's SCF calculation must match the precision settings used to calculate the elemental reference energies. The `io-elemental-energy` unit will attempt to find a reference material matching the target precision.
+
+![Job Designer parameter configuration for Formation Energy](/images/tutorials/formation_energy/formation-energy-parameters.png)
+
+## 6. Submit the job
+
+Once all parameters are set, navigate to the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) to verify the compute resource allocation, then [submit]({{ interface_url }}/jobs/actions/run/) the job.
+
+## 7. Examine the results
+
+Once the job completes, navigate to the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of the [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). The **Formation Energy** property will be displayed. More negative values indicate greater thermodynamic stability relative to the elemental standard states.
+
+

lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md

@@ -0,0 +1,59 @@
+# Calculate Interfacial Energy
+
+This tutorial explains how to calculate the interfacial energy between a substrate material and a film material using [Density Functional Theory]({{ reference_url }}/models-directory/dft/overview/) (DFT) with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/).
+
+## 1. Create the materials
+
+To calculate interfacial energy, you need an interface structure that combines both the substrate and the film, as well as the individual substrate and film materials in their bulk forms.
+
+1. Create the substrate and film structures using the [Materials Designer]({{ interface_url }}/materials-designer/overview/).
+2. Create the combined interface structure using the [Interface Builder]({{ interface_url }}/materials-designer/header-menu/advanced/interface/).
+3. Ensure that the total energy for both the standalone substrate and the standalone film has been calculated with the same precision parameters (e.g., KPPRA, kinetic energy cutoffs) that you plan to use for the interface calculation.
+
+## 2. Understand the workflow structure
+
+<details markdown="1">
+  <summary>Expand to view unit details</summary>
+
+The interfacial energy [workflow]({{ reference_url }}/workflows/overview/) is composed of several [subworkflows]({{ reference_url }}/workflows/components/subworkflows/) that load the materials, fetch their pre-calculated total energies, and compute the interface energy.
+
+### 1. Load Interface Material
+- Loads the combined interface material into the workflow using `set-material-index` and `io-material`.
+
+### 2. Load Substrate Material
+- Loads the standalone substrate material into the workflow to be used as a reference.
+
+### 3. Fetch Total Energy for Substrate Material
+- Queries the platform for the total energy of the substrate material and extracts it using `io-bulk-te-job` and `io-te-bulk`.
+
+### 4. Load Film Material
+- Loads the standalone film material into the workflow.
+
+### 5. Fetch Total Energy for Film Material
+- Queries the platform for the total energy of the film material and extracts it.
+
+### 6. Compute Interfacial Energy
+- **pw_scf**: Performs a self-consistent field (SCF) calculation to determine the total energy of the combined interface structure.
+- **assign-interfacial-energy**: Uses [Python]({{ reference_url }}/software-directory/scripting/python/overview/) to compute the interfacial energy by subtracting the substrate and film reference energies from the total energy of the interface, normalized by the interface area.
+
+</details>
+
+## 3. Select the workflow and create the job
+
+1. Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) and select your combined interface material.
+![Material Selection](./images/interfacial-energy-material-selection.png)
+2. [Workflows]({{ reference_url }}/workflows/overview/) for interfacial energy calculations with [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/) can be [imported]({{ interface_url }}/workflows/actions/copy-bank/) from the [Workflows Bank]({{ reference_url }}/workflows/bank/).
+3. Once imported, [select]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) the Interfacial Energy workflow and add it to your job.
+![Workflow Selection](./images/interfacial-energy-workflow-selection.png)
+
+## 4. Set Group and Source of Properties
+
+Inside the subworkflows that fetch the substrate and film total energies, make sure the property owner groups are set correctly to match the group under which you calculated the individual total energies (e.g., your account).
+
+## 5. Submit the job
+
+Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ reference_url }}/jobs/overview/), review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) to verify the compute parameters. Ensure that the K-point grid and cutoffs match those used for the substrate and film reference calculations.
+
+## 6. Examine the results
+
+Once the job completes, navigate to the [Results tab]({{ interface_url }}/jobs/ui/results-tab/) of the [Job Viewer]({{ interface_url }}/jobs/ui/viewer/). The **Interfacial Energy** property will be displayed.

mkdocs.yml

@@ -126,6 +126,9 @@ nav:
                 - Phonons on Grid:                       tutorials/dft/vibrational/phonons-grid.md
             - Thermodynamic Prop.:
                 - Surface Energy:                        tutorials/dft/thermodynamic/surface-energy.md
+                - Interfacial Energy:                    tutorials/dft/thermodynamic/interfacial-energy.md
+                - Formation Energy:                      tutorials/dft/thermodynamic/formation-energy.md
+                - Defect Formation Energy:               tutorials/dft/thermodynamic/defect-formation-energy.md
             - Chemical Prop.:
                 - Reaction Energy Profile (QE):          tutorials/dft/chemical/reaction-profile-qe.md
                 - Reaction Energy Profile (VASP):        tutorials/dft/chemical/reaction-profile-vasp.md
@@ -584,8 +587,7 @@ nav:
         - Scalar:
             - Total Energy:                             properties-directory/scalar/total-energy.md
             - Fermi Energy:                             properties-directory/scalar/fermi-energy.md
-#              TODO: re-enable when implemented
-#            - Formation Energy:                         properties-directory/scalar/formation-energy.md
+            - Formation Energy:                         properties-directory/scalar/formation-energy.md
             - Surface Energy:                           properties-directory/scalar/surface-energy.md
             - Zero Point Energy:                        properties-directory/scalar/zero-point-energy.md
             - Pressure:                                 properties-directory/scalar/pressure.md