feature/SOF 7969

AGENTS.md

@@ -271,6 +271,32 @@ Then, search for `MatterSim` and click **Copy** ...
 - Use `<wbr/>` to allow soft word-breaks in long slash-separated terms
   (e.g. `flavor/<wbr/>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`.
+
+
 ## Working with the Repo
 
 - Make the smallest diff that satisfies the request. Don't touch files

lang/en/docs/index.md

@@ -12,32 +12,32 @@ Mat3ra.com is an online platform for digital materials R&D. This documentation e
 <span>New to the platform? Start here for a quick onboarding walkthrough, key concepts, and useful links.</span>
 </a>
 
-<a href="/guide/" class="grid-card">
+<a href="tutorials/overview/" class="grid-card">
 <strong>Tutorials</strong>
 <span>Step-by-step tutorials for DFT, ML, materials construction, and simulation workflows.</span>
 </a>
 
-<a href="/interface/" class="grid-card">
+<a href="ui/overview/" class="grid-card">
 <strong>User Interface</strong>
 <span>Interface components, entity management, designer tools, and platform actions reference.</span>
 </a>
 
-<a href="/command-line/" class="grid-card">
+<a href="cli/overview/" class="grid-card">
 <strong>Command Line</strong>
 <span>CLI environment, batch jobs, and remote connection methods.</span>
 </a>
 
-<a href="/reference/" class="grid-card">
+<a href="models/overview/" class="grid-card">
 <strong>Concepts & Reference</strong>
 <span>In-depth explanations of models, methods, properties, software directory, and the science behind the platform.</span>
 </a>
 
-<a href="/resources/" class="grid-card">
+<a href="infrastructure/overview/" class="grid-card">
 <strong>Resources / Infrastructure</strong>
 <span>Compute clusters, storage systems, queues, quotas, and resource management.</span>
 </a>
 
-<a href="/developers/" class="grid-card">
+<a href="rest-api/overview/" class="grid-card">
 <strong>Software Developers</strong>
 <span>REST API reference, authentication, endpoints, and contribution guides.</span>
 </a>

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,89 @@
+# 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 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 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
+
+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. Resolve Elemental Materials
+- Resolves the Standata elemental reference materials for every element present in either the defective or the pristine structure.
+
+### 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.
+
+</details>
+
+## 4. Select the workflow and create the job
+
+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
+
+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
+
+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.
+
+![Job Viewer results for Defect Formation Energy](/images/tutorials/defect_formation_energy/defect-formation-energy-result.png)