From 60ee809b16d93b632849cbbed4e172c1b6d26a03 Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Wed, 8 Jul 2026 19:15:20 -0700 Subject: [PATCH 01/11] update: formation energy tutorial (gemini) --- .../scalar/formation-energy.md | 10 +++- .../dft/thermodynamic/formation-energy.md | 59 +++++++++++++++++++ mkdocs.yml | 4 +- 3 files changed, 68 insertions(+), 5 deletions(-) create mode 100644 lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md diff --git a/lang/en/docs/properties-directory/scalar/formation-energy.md b/lang/en/docs/properties-directory/scalar/formation-energy.md index 174eaf192..1a1484a57 100644 --- a/lang/en/docs/properties-directory/scalar/formation-energy.md +++ b/lang/en/docs/properties-directory/scalar/formation-energy.md @@ -11,6 +11,10 @@ $$ $$ `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. + + !!!note "Zero Point Energy" + The inclusion of Zero Point Energy ($E_{zpe}$) is optional and depends on the specific computational workflow. The standard Quantum ESPRESSO workflow uses only the ground-state total energy ($E_{tot}$). + +## Tutorials + +- [Calculate Formation Energy]({{ reference_url }}/tutorials/dft/thermodynamic/formation-energy/) diff --git a/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md new file mode 100644 index 000000000..56e6435e6 --- /dev/null +++ b/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md @@ -0,0 +1,59 @@ +# 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), ensure you have calculated the [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) for each of its unique elements (e.g., Si and C) using the corresponding elemental reference materials from Standata. + +## 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. + +## 2. Understand the workflow structure + +
+ Expand to view unit details + +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. + +
+ +## 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. + +## 4. 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. + +## 5. Submit the job + +Review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) to ensure sufficient compute resources are allocated, then [submit]({{ interface_url }}/jobs/actions/run/) the job. + +## 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 **Formation Energy** property will be displayed. More negative values indicate greater thermodynamic stability relative to the elemental standard states. + +## Notebook Alternative + +You can also run this workflow programmatically using the JupyterLite notebook. See the `formation_energy.ipynb` tutorial in the `materials_designer/workflows/` directory of the API Examples repository. diff --git a/mkdocs.yml b/mkdocs.yml index 688221c94..89f845e50 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -126,6 +126,7 @@ nav: - Phonons on Grid: tutorials/dft/vibrational/phonons-grid.md - Thermodynamic Prop.: - Surface Energy: tutorials/dft/thermodynamic/surface-energy.md + - Formation Energy: tutorials/dft/thermodynamic/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 +585,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 From 90c49e66489dccce66c1488c073c1123b4598f6a Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Thu, 9 Jul 2026 09:02:28 -0700 Subject: [PATCH 02/11] chore: cleanup --- lang/en/docs/properties-directory/scalar/formation-energy.md | 3 --- lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md | 2 -- 2 files changed, 5 deletions(-) diff --git a/lang/en/docs/properties-directory/scalar/formation-energy.md b/lang/en/docs/properties-directory/scalar/formation-energy.md index 1a1484a57..6142438fc 100644 --- a/lang/en/docs/properties-directory/scalar/formation-energy.md +++ b/lang/en/docs/properties-directory/scalar/formation-energy.md @@ -11,9 +11,6 @@ $$ $$ `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 "Zero Point Energy" - The inclusion of Zero Point Energy ($E_{zpe}$) is optional and depends on the specific computational workflow. The standard Quantum ESPRESSO workflow uses only the ground-state total energy ($E_{tot}$). ## Tutorials diff --git a/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md index 56e6435e6..3526b6291 100644 --- a/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md +++ b/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md @@ -54,6 +54,4 @@ Review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) to ensu 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. -## Notebook Alternative -You can also run this workflow programmatically using the JupyterLite notebook. See the `formation_energy.ipynb` tutorial in the `materials_designer/workflows/` directory of the API Examples repository. From 27e04ce5664f869f3beede799efd7595b8f9d291 Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Thu, 16 Jul 2026 13:38:30 -0700 Subject: [PATCH 03/11] update: cleanup --- .../dft/thermodynamic/formation-energy.md | 35 +++++++++++++++---- 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md index 3526b6291..1d7073c9b 100644 --- a/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md +++ b/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md @@ -9,7 +9,11 @@ This tutorial explains how to calculate the [formation energy]({{ reference_url 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), ensure you have calculated the [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) for each of its unique elements (e.g., Si and C) using the corresponding elemental reference materials from Standata. +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 @@ -17,6 +21,8 @@ Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) to create a 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
@@ -42,15 +48,32 @@ The [workflow]({{ reference_url }}/workflows/overview/) is composed of the follo In the Job Designer, [select]({{ interface_url }}/jobs-designer/actions-header-menu/select-workflow/) the Formation Energy workflow and add it to the job. -## 4. Set parameters +![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. -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. +![Job Designer parameter configuration for Formation Energy](/images/tutorials/formation_energy/formation-energy-parameters.png) -## 5. Submit the job +## 6. Submit the job -Review the [Compute tab]({{ interface_url }}/jobs-designer/compute-tab/) to ensure sufficient compute resources are allocated, then [submit]({{ interface_url }}/jobs/actions/run/) 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. -## 6. Examine the results +## 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. From 8d4690ba5a2a35fcffe1960b13f89b3fe049ca81 Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Tue, 4 Aug 2026 19:50:46 -0700 Subject: [PATCH 04/11] update: add interface + defect energy --- .../thermodynamic/defect-formation-energy.md | 65 +++++++++++++++++++ .../dft/thermodynamic/interfacial-energy.md | 59 +++++++++++++++++ mkdocs.yml | 2 + 3 files changed, 126 insertions(+) create mode 100644 lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md create mode 100644 lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md diff --git a/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md new file mode 100644 index 000000000..62658a7cf --- /dev/null +++ b/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 + +
+ Expand to view unit details + +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. + +
+ +## 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. diff --git a/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md new file mode 100644 index 000000000..1990d354e --- /dev/null +++ b/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 + +
+ Expand to view unit details + +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. + +
+ +## 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. diff --git a/mkdocs.yml b/mkdocs.yml index 89f845e50..23a2af1e9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -126,7 +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 From 69543725134e25dd7281ab5b1f1a9a63ff271c9d Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Tue, 4 Aug 2026 20:23:43 -0700 Subject: [PATCH 05/11] update: images for formation energy --- .../formation_energy/formation-energy-compute-tab.png | 3 +++ images/tutorials/formation_energy/formation-energy-group.png | 3 +++ .../formation_energy/formation-energy-material-selection.png | 3 +++ .../tutorials/formation_energy/formation-energy-parameters.png | 3 +++ .../formation_energy/formation-energy-workflow-selection.png | 3 +++ 5 files changed, 15 insertions(+) create mode 100644 images/tutorials/formation_energy/formation-energy-compute-tab.png create mode 100644 images/tutorials/formation_energy/formation-energy-group.png create mode 100644 images/tutorials/formation_energy/formation-energy-material-selection.png create mode 100644 images/tutorials/formation_energy/formation-energy-parameters.png create mode 100644 images/tutorials/formation_energy/formation-energy-workflow-selection.png diff --git a/images/tutorials/formation_energy/formation-energy-compute-tab.png b/images/tutorials/formation_energy/formation-energy-compute-tab.png new file mode 100644 index 000000000..0e821e02a --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-compute-tab.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:515dff6fb61ed5ebad3a5ad2b384aa7b351a50ba5ef0139480f1ae56e95e8ccc +size 183599 diff --git a/images/tutorials/formation_energy/formation-energy-group.png b/images/tutorials/formation_energy/formation-energy-group.png new file mode 100644 index 000000000..5ce0fa331 --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-group.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7dc30e0f540bfddb2a0236a98088fc1d6b30de4146a88ac806b536d9a0b685b8 +size 107313 diff --git a/images/tutorials/formation_energy/formation-energy-material-selection.png b/images/tutorials/formation_energy/formation-energy-material-selection.png new file mode 100644 index 000000000..dea4acb73 --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-material-selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4b0293dc7efffd41bc3ea3400ec6db9cb8d8fd85c0d34211917c32b757f3fe81 +size 119936 diff --git a/images/tutorials/formation_energy/formation-energy-parameters.png b/images/tutorials/formation_energy/formation-energy-parameters.png new file mode 100644 index 000000000..8141f7b47 --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-parameters.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7679e55137b77f54539ba5fdaead77d97afa9647a9f8be1be28c88544d7969f0 +size 168457 diff --git a/images/tutorials/formation_energy/formation-energy-workflow-selection.png b/images/tutorials/formation_energy/formation-energy-workflow-selection.png new file mode 100644 index 000000000..761b0020e --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-workflow-selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e8090b405848f59f721284fd732ea040914b8371e1436ab18fd897751ee27318 +size 133348 From f70d0e05ef7c8936d38774ba8837d35304f3aa2b Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Tue, 4 Aug 2026 20:56:25 -0700 Subject: [PATCH 06/11] update: corrections --- ...formation-energy-assign-te-source-unit.png | 3 ++ .../formation-energy-assign-te-source.png | 3 ++ .../formation-energy-group.png | 3 -- .../thermodynamic/defect-formation-energy.md | 38 +++++++++++++++---- .../dft/thermodynamic/formation-energy.md | 28 ++++++++------ .../dft/thermodynamic/interfacial-energy.md | 26 +++++++------ 6 files changed, 67 insertions(+), 34 deletions(-) create mode 100644 images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png create mode 100644 images/tutorials/formation_energy/formation-energy-assign-te-source.png delete mode 100644 images/tutorials/formation_energy/formation-energy-group.png diff --git a/images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png b/images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png new file mode 100644 index 000000000..a539e90a4 --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:09e9109453ee467f34e6f69ea69a5929702dc60fa53d734ad59d4743a1dc4b9c +size 271588 diff --git a/images/tutorials/formation_energy/formation-energy-assign-te-source.png b/images/tutorials/formation_energy/formation-energy-assign-te-source.png new file mode 100644 index 000000000..4b928ff69 --- /dev/null +++ b/images/tutorials/formation_energy/formation-energy-assign-te-source.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3761262e94f707ba82e59d75093861a436bbda0b074fbd8c97156287111c76f9 +size 289851 diff --git a/images/tutorials/formation_energy/formation-energy-group.png b/images/tutorials/formation_energy/formation-energy-group.png deleted file mode 100644 index 5ce0fa331..000000000 --- a/images/tutorials/formation_energy/formation-energy-group.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:7dc30e0f540bfddb2a0236a98088fc1d6b30de4146a88ac806b536d9a0b685b8 -size 107313 diff --git a/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md index 62658a7cf..b07f90edd 100644 --- a/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md +++ b/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md @@ -8,9 +8,9 @@ The defect formation energy is calculated with respect to the pristine material 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). +2. **Calculate Total Energy**: For each elemental material, run a standard SCF [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) job on it. - **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. + - **Crucial**: Ensure you note the property **Group** (e.g., `qe:dft:gga:pbe`) under which the elemental Total Energies were calculated, as you will need to specify this group in the Defect Formation Energy workflow. ## 2. Create the materials @@ -37,24 +37,46 @@ The defect formation energy [workflow]({{ reference_url }}/workflows/overview/) ### 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. +### 5. Resolve Elemental Materials +- Resolves the Standata elemental reference materials for every element present in either the defective or the pristine structure. -### 6. Compute Defect Formation Energy +### 6. Resolve Total Energies for Elemental Materials +- **assign-source-of-te-for-an-element** / **assign-group-for-material** set which elemental reference records to search for (see [step 5](#5-set-group-and-source-of-properties) below). +- Contains a loop (`init-element-index` / `check-te-for-elemental-materials-loop` / `assign-current-element`) that iterates over elements. +- **io-te-for-an-element** retrieves the pre-calculated `total_energy` property for the current element's standard state reference material, filtered by that Group and Source. + +### 7. 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.
## 4. Select the workflow and create the job -1. Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) and select your defective material. +This is a **multi-material** workflow: the job must be submitted with exactly two materials, in this order: + +1. **Defective supercell** (position 0) — its total energy is computed by the job itself. +2. **Pristine supercell** (position 1) — its total energy is fetched from that material's own most recently finished Total Energy job, so it must already exist on the platform (see [step 2](#2-create-the-materials)). + +To set this up: + +1. Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) and add the defective material first, then the pristine material, so they occupy positions 0 and 1 respectively. 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). +This step only applies to the **elemental reference** lookup — the pristine material's total energy (fetched in the **Fetch Total Energy for Pristine Material** subworkflow) is read directly from that material's own most recent finished Total Energy job and does not use a Group or Source setting. + +Inside the **Resolve Total Energies for Elemental Materials** subworkflow, switch to the **Detailed view** tab and check two assignment units: + +- **assign-source-of-te-for-an-element**: who owns the elemental Total Energy record to search for — `'public'` by default, or `'my_account'`/`'curators'` if you calculated the elemental references yourself or want curated results only. +- **assign-group-for-material**: the property group (e.g., `qe:dft:gga:pbe`) to filter the elemental Total Energy results by computational method. This must match the property group of the individual elemental total energies you calculated previously. + +This is the same **Resolve Total Energies for Elemental Materials** subworkflow used by the Formation Energy workflow: + +![Job Designer source assignment for Defect Formation Energy](/images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png) + +![Unit settings for assign-source-of-te-for-an-element](/images/tutorials/formation_energy/formation-energy-assign-te-source.png) ## 6. Submit the job diff --git a/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md index 1d7073c9b..7d5741fe3 100644 --- a/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md +++ b/lang/en/docs/tutorials/dft/thermodynamic/formation-energy.md @@ -11,9 +11,9 @@ The formation energy of a compound is calculated with respect to its constituent 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). +2. **Calculate Total Energy**: For each elemental material, run a standard SCF [Total Energy]({{ reference_url }}/properties-directory/scalar/total-energy/) job on it. - **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. + - **Crucial**: Ensure you note the property **Group** (e.g., `qe:dft:gga:pbe`) under which the elemental Total Energies were calculated, as you will need to specify this group in the Formation Energy workflow. ## 1. Create a job @@ -30,15 +30,15 @@ Under the *Choose A Material* section, select the compound material for which yo 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. +**pw_scf** (in the **Compute Total Energy** subworkflow) — 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. +**assign-source-of-te-for-an-element** / **assign-group-for-material** (in the **Resolve Total Energies for Elemental Materials** subworkflow) — Set which elemental reference records to search for: the **Source** is the record's owner (`public` by default, `my_account`, or `curators`), and the **Group** is the computational-method slug (e.g., `qe:dft:gga:pbe`) the elemental Total Energies were calculated under. -**init-element-index** / **check-elemental-te-loop** / **assign-current-element** — A loop construct that iterates over each unique element present in the compound. +**init-element-index** / **check-te-for-elemental-materials-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. +**io-te-for-an-element** — 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, filtered by the Group and Source set above, 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. +**assign-formation-energy** (in the **Calculate Formation Energy** subworkflow) — 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. @@ -52,20 +52,22 @@ In the Job Designer, [select]({{ interface_url }}/jobs-designer/actions-header-m ## 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: +Inside the **Resolve Total Energies for Elemental Materials** subworkflow (not the earlier **Get Elemental Materials** subworkflow, which only resolves the elemental reference *materials* — not their total energies), 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. +**assign-source-of-te-for-an-element**: This unit sets who owns the elemental Total Energy record to search for — `'public'` by default, or `'my_account'`/`'curators'` if you calculated the elemental references yourself or want curated results only. This is unrelated to Standata: Standata is only where the elemental reference *materials* (structures) come from; the Source setting is about who calculated the *total energy property* on those materials. -![Job Designer group assignment for Formation Energy](/images/tutorials/formation_energy/formation-energy-group.png) +![Job Designer source assignment for Formation Energy](/images/tutorials/formation_energy/formation-energy-assign-te-source-unit.png) -**assign-source-of-te-for-an-element**: This unit specifies the source of the property. By default, it queries Standata for elemental energies. +![Unit settings for assign-source-of-te-for-an-element](/images/tutorials/formation_energy/formation-energy-assign-te-source.png) + +**assign-group-for-material**: This unit sets the property group (e.g., `qe:dft:gga:pbe`) to filter the elemental Total Energy results by computational method. The group selected here must match the property group of the elemental total energies you calculated previously. ## 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. + 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-te-for-an-element` unit does not verify this for you — it simply picks the highest-precision matching reference it finds, so a mismatch will silently produce an incorrect formation energy. ![Job Designer parameter configuration for Formation Energy](/images/tutorials/formation_energy/formation-energy-parameters.png) @@ -73,6 +75,8 @@ In the workflow unit settings, ensure the [k-point grid]({{ reference_url }}/mod 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. +![Job Designer compute tab for Formation Energy](/images/tutorials/formation_energy/formation-energy-compute-tab.png) + ## 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. diff --git a/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md index 1990d354e..3cd8ee478 100644 --- a/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md +++ b/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md @@ -24,13 +24,13 @@ The interfacial energy [workflow]({{ reference_url }}/workflows/overview/) is co - 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`. +- Looks up the substrate material's own most recently finished Total Energy job and extracts its highest-precision `total_energy` property using `io-bulk-te-job` and `io-te-bulk`. Unlike the Formation Energy and Defect Formation Energy workflows, there is no Group or Source assignment unit to configure here — the lookup is tied directly to the substrate material you submitted, not to a property group or an owner filter. ### 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. +- Same lookup as above, applied to the film material. ### 6. Compute Interfacial Energy - **pw_scf**: Performs a self-consistent field (SCF) calculation to determine the total energy of the combined interface structure. @@ -40,20 +40,24 @@ The interfacial energy [workflow]({{ reference_url }}/workflows/overview/) is co ## 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) +This is a **multi-material** workflow: the job must be submitted with exactly three materials, in this order: + +1. **Interface** (position 0) — its total energy is computed by the job itself. +2. **Substrate** (position 1) — its total energy is fetched from that material's own most recently finished Total Energy job. +3. **Film** (position 2) — same as the substrate. -## 4. Set Group and Source of Properties +Both the substrate's and film's Total Energy jobs must already exist on the platform before you submit this job (see [step 1](#1-create-the-materials)). -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). +1. Open the [Job Designer]({{ interface_url }}/jobs-designer/overview/) and add the interface material first, then the substrate, then the film, so they occupy positions 0, 1, and 2 respectively. +![Material Selection](/images/tutorials/interfacial_energy/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/tutorials/interfacial_energy/interfacial-energy-workflow-selection.png) -## 5. Submit the job +## 4. 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 +## 5. 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. From 66480967cb2e025978772c339915b7861954e01b Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Tue, 4 Aug 2026 23:26:24 -0700 Subject: [PATCH 07/11] update: corrections 2 --- .../defect-formation-energy-result.png | 3 +++ .../interfacial-energy-material-selection.png | 3 +++ .../interfacial_energy/interfacial-energy-parameters.png | 3 +++ .../interfacial_energy/interfacial-energy-result.png | 3 +++ .../interfacial-energy-workflow-selection.png | 3 +++ .../tutorials/dft/thermodynamic/defect-formation-energy.md | 2 ++ .../en/docs/tutorials/dft/thermodynamic/interfacial-energy.md | 4 ++++ 7 files changed, 21 insertions(+) create mode 100644 images/tutorials/defect_formation_energy/defect-formation-energy-result.png create mode 100644 images/tutorials/interfacial_energy/interfacial-energy-material-selection.png create mode 100644 images/tutorials/interfacial_energy/interfacial-energy-parameters.png create mode 100644 images/tutorials/interfacial_energy/interfacial-energy-result.png create mode 100644 images/tutorials/interfacial_energy/interfacial-energy-workflow-selection.png diff --git a/images/tutorials/defect_formation_energy/defect-formation-energy-result.png b/images/tutorials/defect_formation_energy/defect-formation-energy-result.png new file mode 100644 index 000000000..e356dfe22 --- /dev/null +++ b/images/tutorials/defect_formation_energy/defect-formation-energy-result.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:70180006c89135daef139d72a33407dc87f3450fa31fb0fd3e30a9a4616f8934 +size 206897 diff --git a/images/tutorials/interfacial_energy/interfacial-energy-material-selection.png b/images/tutorials/interfacial_energy/interfacial-energy-material-selection.png new file mode 100644 index 000000000..42ce0612e --- /dev/null +++ b/images/tutorials/interfacial_energy/interfacial-energy-material-selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:13f2d44609dbe2c31e5e288334d8657d0db13c2f962569bf300b17cabd8794e2 +size 148498 diff --git a/images/tutorials/interfacial_energy/interfacial-energy-parameters.png b/images/tutorials/interfacial_energy/interfacial-energy-parameters.png new file mode 100644 index 000000000..eb014465b --- /dev/null +++ b/images/tutorials/interfacial_energy/interfacial-energy-parameters.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e29fe0b2e0e27cf73e50b46404380b85b301ce81f0074427d907d358f8bdab6b +size 195597 diff --git a/images/tutorials/interfacial_energy/interfacial-energy-result.png b/images/tutorials/interfacial_energy/interfacial-energy-result.png new file mode 100644 index 000000000..37e25c536 --- /dev/null +++ b/images/tutorials/interfacial_energy/interfacial-energy-result.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8968a07afdb3170e8a676b0105dd417c853e3399d3e4ecc4699fd66f9431e71c +size 223617 diff --git a/images/tutorials/interfacial_energy/interfacial-energy-workflow-selection.png b/images/tutorials/interfacial_energy/interfacial-energy-workflow-selection.png new file mode 100644 index 000000000..7927408d1 --- /dev/null +++ b/images/tutorials/interfacial_energy/interfacial-energy-workflow-selection.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7848e0f3507423fc2e334ef5aa226ec79f466c1ba388f2bf29e721e05112b69f +size 143623 diff --git a/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md index b07f90edd..64b25f3dd 100644 --- a/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md +++ b/lang/en/docs/tutorials/dft/thermodynamic/defect-formation-energy.md @@ -85,3 +85,5 @@ Before [submitting]({{ interface_url }}/jobs/actions/run/) the [job]({{ referenc ## 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. + +![Job Viewer results for Defect Formation Energy](/images/tutorials/defect_formation_energy/defect-formation-energy-result.png) diff --git a/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md b/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md index 3cd8ee478..9f96aa02d 100644 --- a/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md +++ b/lang/en/docs/tutorials/dft/thermodynamic/interfacial-energy.md @@ -58,6 +58,10 @@ Both the substrate's and film's Total Energy jobs must already exist on the plat 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. +![Job Designer compute tab for Interfacial Energy](/images/tutorials/interfacial_energy/interfacial-energy-parameters.png) + ## 5. 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. + +![Job Viewer results for Interfacial Energy](/images/tutorials/interfacial_energy/interfacial-energy-result.png) From ad740d6d28f006745bb4422a6206f833bc6654b9 Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Wed, 5 Aug 2026 13:34:28 -0700 Subject: [PATCH 08/11] update: correction to use relative file paths that match the current unified structure --- lang/en/docs/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/lang/en/docs/index.md b/lang/en/docs/index.md index 151c373be..7e709b7df 100644 --- a/lang/en/docs/index.md +++ b/lang/en/docs/index.md @@ -12,37 +12,37 @@ Mat3ra.com is an online platform for digital materials R&D. This documentation e New to the platform? Start here for a quick onboarding walkthrough, key concepts, and useful links. - + Tutorials Step-by-step tutorials for DFT, ML, materials construction, and simulation workflows. - + User Interface Interface components, entity management, designer tools, and platform actions reference. - + Command Line CLI environment, batch jobs, and remote connection methods. - + Concepts & Reference In-depth explanations of models, methods, properties, software directory, and the science behind the platform. - + Resources / Infrastructure Compute clusters, storage systems, queues, quotas, and resource management. - + Software Developers REST API reference, authentication, endpoints, and contribution guides. - + Data Standards JSON schemas, ESSE data convention, and structured data representations. From 935945aa076ed1ca5d6c7fabe0fc99aba546773a Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Fri, 7 Aug 2026 16:18:39 -0700 Subject: [PATCH 09/11] chore: relative --- lang/en/docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lang/en/docs/index.md b/lang/en/docs/index.md index 7e709b7df..202bbb949 100644 --- a/lang/en/docs/index.md +++ b/lang/en/docs/index.md @@ -42,7 +42,7 @@ Mat3ra.com is an online platform for digital materials R&D. This documentation e REST API reference, authentication, endpoints, and contribution guides. - + Data Standards JSON schemas, ESSE data convention, and structured data representations. From 65f33018b10b164a5b43d9368547b56b3eb2b04f Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Fri, 7 Aug 2026 17:20:18 -0700 Subject: [PATCH 10/11] update: tutorials images directive --- AGENTS.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index a43266283..9660a098e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -271,6 +271,33 @@ Then, search for `MatterSim` and click **Copy** ... - Use `` to allow soft word-breaks in long slash-separated terms (e.g. `flavor/template`). +## Generating Tutorial Screenshots + +When asked to capture or update screenshots for tutorials, follow this approach: + +We use **Cypress** integration tests (located in the `web-app` repository) to automate the generation of screenshots for tutorials. + +1. **Test Files**: The Cypress feature files/tests are typically stored in the `cypress/e2e/tutorials/` directory within the web application codebase. +2. **Screenshot Capture**: Within these tests, we use the `cy.screenshot('filename')` command to capture specific states of the application UI (e.g., material selection, workflow designer tabs, job submission). +3. **Integration**: The generated images are then placed into the `images/tutorials/` folder of this `documentation` repository and referenced in the markdown files. + +### Workflow for Regenerating Content + +To regenerate the screenshots for a tutorial: +1. Locate the corresponding Cypress test in the `web-app` project. +2. Ensure the test correctly navigates to the state you want to capture. +3. Insert or update `cy.screenshot('desired-image-name')` at the appropriate steps. +4. Run the Cypress test. +5. Copy the newly generated images from Cypress's screenshots directory to the `documentation/images/tutorials/...` directory. +6. Update the markdown file in `documentation/lang/en/docs/tutorials/...` to reference the new images if filenames have changed. + +### Caveats and Troubleshooting + +- **Headless Mode and Incomplete UI Rendering**: When running Cypress in headless mode (e.g., via the default Electron browser in CI), complex UI widgets like `ag-grid`, dropdown menus, and workflow designer canvases may fail to render fully before the screenshot is taken. This results in empty or incorrect images. **Workaround**: Run Cypress in **headed mode** for screenshot generation, or ensure you have robust assertions (e.g., waiting for specific network requests to complete or using `cy.wait()`) prior to calling `cy.screenshot()`. +- **Uncaught Exceptions Breaking Tests**: Sometimes, the application may throw benign console errors (e.g., `ResizeObserver loop limit exceeded`) that cause Cypress to fail the test prematurely before taking the screenshot. **Workaround**: These exceptions can be suppressed in `cypress/support/e2e.ts` by intercepting the `uncaught:exception` event and returning `false`. +- **Correct Terminology (Group vs. Property Group)**: When documenting thermodynamic workflows (Formation Energy, Defect Formation, Interfacial Energy) that use the `assign-group-for-material` unit, be clear that **Group** in this context refers to the **property calculation group** (the DFT methodology, e.g., `dft:qe:gga:pbe`), *not* the user's account or organization group. + + ## Working with the Repo - Make the smallest diff that satisfies the request. Don't touch files From 7836bd6cd67fd2dbc09c593757118a53a9154eaa Mon Sep 17 00:00:00 2001 From: VsevolodX Date: Fri, 7 Aug 2026 17:55:08 -0700 Subject: [PATCH 11/11] chore: remove useless --- AGENTS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9660a098e..d028a7285 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -295,7 +295,6 @@ To regenerate the screenshots for a tutorial: - **Headless Mode and Incomplete UI Rendering**: When running Cypress in headless mode (e.g., via the default Electron browser in CI), complex UI widgets like `ag-grid`, dropdown menus, and workflow designer canvases may fail to render fully before the screenshot is taken. This results in empty or incorrect images. **Workaround**: Run Cypress in **headed mode** for screenshot generation, or ensure you have robust assertions (e.g., waiting for specific network requests to complete or using `cy.wait()`) prior to calling `cy.screenshot()`. - **Uncaught Exceptions Breaking Tests**: Sometimes, the application may throw benign console errors (e.g., `ResizeObserver loop limit exceeded`) that cause Cypress to fail the test prematurely before taking the screenshot. **Workaround**: These exceptions can be suppressed in `cypress/support/e2e.ts` by intercepting the `uncaught:exception` event and returning `false`. -- **Correct Terminology (Group vs. Property Group)**: When documenting thermodynamic workflows (Formation Energy, Defect Formation, Interfacial Energy) that use the `assign-group-for-material` unit, be clear that **Group** in this context refers to the **property calculation group** (the DFT methodology, e.g., `dft:qe:gga:pbe`), *not* the user's account or organization group. ## Working with the Repo