feature/SOF-8044 Feature: add the h-BN boron-vacancy formation-energy tutorial page

lang/en/docs/includes/references.bib

@@ -94,7 +94,7 @@ @doi =
 @article{Bertoldo2022,
     title = {Quantum point defects in 2D materials - the QPOD database},
     author = {Bertoldo, Fabian and Ali, Sajid and Manti, Simone and Thygesen, Kristian S.},
-    journal = {Nature},
+    journal = {npj Computational Materials},
     year = {2022},
     @doi = {10.1038/s41524-022-00730-w},
     url = {https://doi.org/10.1038/s41524-022-00730-w}

lang/en/docs/index-guide.md

@@ -35,7 +35,7 @@ Step-by-step recipes reproducing published work, one row per publication: the st
 |:----------------------------------|:--------------------------|:---------|:-----------|
 | Fujimoto et al. (2011)[^1]        | Substitutional defect     | [Graphene](tutorials/materials/specific/defect-point-substitution-graphene.md) | [Band structure](tutorials/materials/specific/defect-point-substitution-graphene-simulation.md) |
 | Miceli et al. (2016)[^2]          | Vacancy-substitution pair | [GaN](tutorials/materials/specific/defect-point-pair-gallium-nitride.md) | Defect formation energies (Coming Soon) |
-| Bertoldo et al. (2022)[^3]        | Vacancy defect            | [h-BN](tutorials/materials/specific/defect-point-vacancy-boron-nitride.md) | Formation energies (Coming Soon) |
+| Bertoldo et al. (2022)[^3]        | Vacancy defect            | [h-BN](tutorials/materials/specific/defect-point-vacancy-boron-nitride.md) | [Formation energy](tutorials/materials/specific/defect-point-vacancy-boron-nitride-simulation.md) |
 | Togo et al. (2006)[^4]            | Interstitial defect       | [SnO](tutorials/materials/specific/defect-point-interstitial-tin-oxide.md) | Formation energies, band structure (Coming Soon) |
 | Sangiovanni et al. (2018)[^5]     | Island surface defect     | [TiN](tutorials/materials/specific/defect-surface-island-titanium-nitride.md) | Island formation energy (Coming Soon) |
 | Šljivančanin et al. (2002)[^6]    | Step surface defect       | [Pt(111)](tutorials/materials/specific/defect-surface-step-platinum.md) | Energy of dissociation (Coming Soon) |

lang/en/docs/tutorials/materials/specific/defect-point-vacancy-boron-nitride-simulation.md

@@ -0,0 +1,249 @@
+---
+tags:
+  - defects
+  - vacancy
+  - point-defects
+  - h-BN
+  - boron-nitride
+  - 2D-materials
+  - formation-energy
+  - D-0D-VAC
+
+hide:
+  - tags
+# YAML header
+render_macros: true
+---
+
+# Vacancy Point Defects in Hexagonal Boron Nitride (Formation Energy)
+
+## 1. Introduction
+
+This tutorial calculates the formation energy of a neutral boron vacancy in h-BN, reproducing
+results from the following manuscript:
+
+!!!note "Manuscript"
+    Fabian Bertoldo, Sajid Ali, Simone Manti & Kristian S. Thygesen, "Quantum point defects in 2D
+    materials - the QPOD database", npj Computational Materials, 2022.
+    [DOI:10.1038/s41524-022-00730-w](https://doi.org/10.1038/s41524-022-00730-w){:target='_blank'}.
+    [@Bertoldo2022]
+
+This tutorial builds upon the [Vacancy Point Defect in h-BN](defect-point-vacancy-boron-nitride.md)
+tutorial, where the defective structure is created. Here, the formation energy is calculated using
+Quantum ESPRESSO and compared with QPOD's value for the same defect.
+
+### 1.1. What is being reproduced
+
+QPOD's [entry `1BN-1.2d.v_B.0.1`](https://qpod.fysik.dtu.dk/material/1BN-1.2d.v_B.0.1) gives the
+neutral vacancy formation energy at standard-state chemical potentials:
+
+| | E_f (eV) |
+|---|---|
+| QPOD, standard states | 10.18 |
+| QPOD, B-poor | 8.89 |
+
+Only the neutral (q = 0) defect is compared; QPOD's charged states need a finite-size correction
+this workflow does not apply.
+
+## 2. Prerequisites
+
+Before starting this tutorial, one of the following steps should be completed:
+
+1. Complete the [Vacancy Point Defect in h-BN](defect-point-vacancy-boron-nitride.md) tutorial,
+   using the `defect_point_vacancy_boron_nitride.ipynb` notebook embedded in its section 6, to
+   create and save `h-BN supercell` and `B-vacancy h-BN`, OR
+2. Have both materials saved in the `uploads` folder or in the account's materials collection
+
+## 3. Workflow overview
+
+The defect formation energy calculation consists of the following steps:
+
+1. **Set up the environment and parameters**: Configure material names, the DFT model, and
+   compute resources
+2. **Authenticate and initialize API client**: Connect to the platform
+3. **Load materials**: Import the pristine and defective structures, and resolve the elemental
+   reference materials
+4. **Submit prerequisite jobs**: Compute (or reuse) the pristine, boron and nitrogen Total Energy
+   jobs
+5. **Relax the defective cell** (optional): Only if `RELAX` is set, reusing an existing relaxed
+   structure if one is found
+6. **Create and submit the defect job**: Assemble and run the formation energy workflow
+7. **Monitor job status**: Wait for completion
+8. **Retrieve and compare results**: Print the formation energy and the comparison with QPOD
+
+## 4. Calculation parameters
+
+| | this tutorial | QPOD |
+|---|---|---|
+| Code | Quantum ESPRESSO | GPAW |
+| Functional | PBE | PBE |
+| Pseudopotentials | ultrasoft (GBRV) | PAW (GPAW setups) |
+| Cutoff | 40 / 200 Ry | 800 eV |
+| k-points | density 6 Å⁻¹ (3×5×1 for the defect cell) | 6 Å⁻¹ (relaxation), 12 Å⁻¹ (ground state) |
+| Spin | fixed total magnetization, 1 μB (doublet) | 1.018 μB (doublet) |
+| Cell | 48 → 47 atoms, 8.69 Å defect spacing, 20 Å vacuum | 84 → 83 atoms, 15.06 Å defect spacing, 15 Å vacuum |
+
+By default (`RELAX = False`), the calculation uses the structure as given. Setting `RELAX = True`
+relaxes the defective cell first, to 0.01 eV/Å — QPOD's own threshold, and the one QPOD applies to
+every structure; only the defective cell is relaxed here. If the account already holds a relaxed
+version of this structure, the notebook reuses it whatever settings produced it, and prints its
+name and id; a settings change therefore does not trigger a fresh relaxation. To compute one with
+different settings, run the notebook under a different account, or relax the structure separately
+and point `DEFECTIVE_NAME` at that structure with `RELAX = False`.
+
+## 5. Step-by-step instructions
+
+### 5.1. Open the notebook
+
+Navigate to the API examples repository and open the defect formation energy notebook:
+
+```
+other/materials_designer/specific_examples/defect_point_vacancy_boron_nitride_SIMULATION.ipynb
+```
+
+### 5.2. Configure parameters
+
+The parameters cells set the material names, the DFT model, and the compute resources:
+
+```python
+# Material names — saved by defect_point_vacancy_boron_nitride.ipynb
+PRISTINE_NAME = "h-BN supercell"
+DEFECTIVE_NAME = "B-vacancy h-BN"
+
+# False: use the structure as given, fast. True: use the relaxed structure, running the
+# relaxation once if it does not exist yet.
+RELAX = False
+
+CLUSTER_NAME = None  # or a specific cluster name
+QUEUE_NAME = QueueName.OF
+PPN = 40
+TIME_LIMIT = "12:00:00"
+
+# DFT model
+FUNCTIONAL = "pbe"
+PSEUDOPOTENTIAL_TYPE = "us"
+ECUTWFC = 40   # Ry
+ECUTRHO = 200  # Ry
+KPOINT_DENSITY = 6
+```
+
+### 5.3. Run the notebook
+
+Execute all cells by selecting *Run* > *Run All* from the menu.
+
+The notebook will:
+
+1. [Authenticate with the platform]({{ interface_url }}/jupyterlite/authentication.md) and
+   initialize the API client
+2. Load the two materials from the uploads folder or the account's materials collection, and
+   resolve the elemental reference materials
+3. Submit the prerequisite Total Energy jobs, reusing any that already match
+4. Relax the defective cell first, if `RELAX` is set and no relaxed structure exists yet
+5. Create, submit and monitor the defect formation energy job
+6. Print the result and the comparison with QPOD
+
+### 5.4. Monitor progress
+
+The notebook includes automatic job monitoring with status updates. The default run
+(`RELAX = False`) completes in about 15 minutes the first time, or about 6 minutes once the
+reference jobs are reused. With `RELAX = True`, relaxing the defective cell takes about 52
+minutes; once that relaxed structure exists, later runs find it and skip the relaxation.
+
+### 5.5. Analyze results
+
+Once the job completes, the formation energy is displayed next to QPOD's value, and the last cell
+prints the comparison:
+
+```
+Reproduces Bertoldo et al. (2022): no (unrelaxed SCF)
+```
+
+or, with `RELAX = True`:
+
+```
+Reproduces Bertoldo et al. (2022): yes (relaxed defect)
+```
+
+## 6. Expected results
+
+The defect formation energy job produces one number, printed next to QPOD's target and QPOD's
+B-poor value for context.
+
+### 6.1. Comparison with published results
+
+| configuration | E_f (eV) | vs QPOD 10.18 eV | verdict |
+|---|---|---|---|
+| unrelaxed SCF | 10.46 | +0.28 | `no (unrelaxed SCF)` |
+| relaxed defect | 10.12 | −0.06 | `yes (relaxed defect)` |
+
+## 7. Customization options
+
+### 7.1. Relax the defective cell
+
+Set `RELAX = True` in the parameters cell to use the relaxed defective cell — closer to the paper.
+The first run relaxes it and saves the result in the account's materials collection under
+`B-vacancy h-BN relaxed`, reused by later runs of this notebook (and loadable by name elsewhere):
+
+```python
+RELAX = True
+```
+
+To use a structure already relaxed elsewhere, set `DEFECTIVE_NAME = "B-vacancy h-BN relaxed"`
+(the name the relaxation saves) with `RELAX = False`; the notebook finds it in the account's
+materials collection, though the verdict line still reads `(unrelaxed SCF)` — the provenance
+lines above the results name the structure that was actually used.
+
+### 7.2. Adjust computational resources
+
+Modify the compute parameters in the parameters cell. The default, `CLUSTER_NAME = None`, uses the
+account's first listed cluster; setting a specific name picks that cluster instead, and a name
+that is not available makes the notebook stop and list the ones that are:
+
+```python
+CLUSTER_NAME = None  # or a specific cluster name
+QUEUE_NAME = QueueName.OF
+PPN = 40
+TIME_LIMIT = "12:00:00"
+```
+
+### 7.3. Change the supercell or the defect
+
+The supercell size and the vacancy site are set in the
+[structure notebook](defect-point-vacancy-boron-nitride.md); this notebook loads whatever it
+saves, by name.
+
+## 8. Troubleshooting
+
+### 8.1. Material not found
+
+If a material is not found in the `uploads` folder:
+
+1. Run the [Vacancy Point Defect in h-BN](defect-point-vacancy-boron-nitride.md) tutorial first
+2. Ensure the materials are saved with the exact names (`h-BN supercell`, `B-vacancy h-BN`)
+3. Check that the material files are in the correct `uploads` folder
+
+### 8.2. Missing elemental reference materials
+
+If boron or nitrogen has no platform material tagged `elemental`, the notebook stops before
+submitting anything — seed one for the missing element first.
+
+### 8.3. Job errors or time limit
+
+The 12-hour time limit is the notebook's default ceiling; the measured relaxation took about 52
+minutes on 40 cores. Increase `TIME_LIMIT` if a job runs out of time before finishing.
+
+## 9. Interactive JupyterLite notebook
+
+The following JupyterLite notebook demonstrates the workflow for calculating the formation energy
+of a boron vacancy in h-BN. Select *Run* > *Run All Cells*.
+
+{% with origin_url=config.extra.jupyterlite.origin_url_lab %}
+{% with notebooks_path_root=config.extra.jupyterlite.notebooks_path_root %}
+{% with notebook_name='specific_examples/defect_point_vacancy_boron_nitride_SIMULATION.ipynb' %}
+{% include 'jupyterlite_embed.html' %}
+{% endwith %}
+{% endwith %}
+{% endwith %}
+
+
+## 10. References

lang/en/docs/tutorials/materials/specific/defect-point-vacancy-boron-nitride.md

@@ -21,7 +21,7 @@ render_macros: true
 This tutorial demonstrates the process of creating materials with vacancy point defects, based on the work presented in the following manuscript:
 
 !!!note "Manuscript"
-    Fabian Bertoldo, Sajid Ali, Simone Manti & Kristian S. Thygesen, "Quantum point defects in 2D materials - the QPOD database", Nature, 2022. [DOI:10.1038/s41524-022-00730-w](https://doi.org/10.1038/s41524-022-00730-w){:target='_blank'}. [@Bertoldo2022; @Kohan2000]
+    Fabian Bertoldo, Sajid Ali, Simone Manti & Kristian S. Thygesen, "Quantum point defects in 2D materials - the QPOD database", npj Computational Materials, 2022. [DOI:10.1038/s41524-022-00730-w](https://doi.org/10.1038/s41524-022-00730-w){:target='_blank'}. [@Bertoldo2022; @Kohan2000]
 
 We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) and JupyterLite environment to create a nanoribbon of hexagonal boron nitride (h-BN) and introduce vacancy defects. The process combines the capabilities of nanoribbon creation and point defect introduction.
 
@@ -126,7 +126,7 @@ Click `Run` > `Run All` in the top menu to run the notebook and preview the resu
 
 ## 5. Save the Material
 
-After running both notebooks, user can visualize the structure of h-BN with the vacancy defect in the Materials Designer 3D viewer.
+After running both notebooks, user can visualize the structure of h-BN with the vacancy defect in the Materials Designer 3D viewer. The combined notebook embedded in section 6 below names and saves both structures — the pristine supercell as `h-BN supercell` and the defective one as `B-vacancy h-BN` — so a later tutorial can load each by name.
 
 ![Vacancy in h-BN](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/6-wave-result.webp "Vacancy in h-BN")
 

lang/en/docs/tutorials/materials/specific/overview.md

@@ -195,7 +195,7 @@ This document provides a comprehensive catalog of materials science tutorials or
 ##### 3.3.3.1. Vacancy Point Defect in h-BN <span class="btn badge b-info border-50">D-0D-VAC</span>
 
 **Structure**: [Create Vacancy Defect in h-BN](defect-point-vacancy-boron-nitride.md)  
-**Properties**: Calculate formation energies (Coming Soon)  
+**Properties**: [Calculate Formation Energy of a Boron Vacancy in h-BN](defect-point-vacancy-boron-nitride-simulation.md)  
 **DOI**: [10.1038/s41524-022-00730-w](https://doi.org/10.1038/s41524-022-00730-w){:target='_blank'}
 
 ![Vacancy in h-BN](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/0-figure-from-manuscript.webp "Vacancy in h-BN"){ style="max-height:500px;width:auto;" }

mkdocs-guide.yml

@@ -196,6 +196,7 @@ nav:
             - Substitutional Defects in Graphene (Band Structure):              tutorials/materials/specific/defect-point-substitution-graphene-simulation.md
             - Vacancy-Substitution Pair in GaN:                                 tutorials/materials/specific/defect-point-pair-gallium-nitride.md
             - Vacancy Defect in h-BN:                                           tutorials/materials/specific/defect-point-vacancy-boron-nitride.md
+            - Vacancy Defect in h-BN (Formation Energy):                        tutorials/materials/specific/defect-point-vacancy-boron-nitride-simulation.md
             - Interstitial Defect in SnO:                                       tutorials/materials/specific/defect-point-interstitial-tin-oxide.md
             - Island Surface Defect in TiN:                                     tutorials/materials/specific/defect-surface-island-titanium-nitride.md
             - Step Surface Defect on Pt(111):                                   tutorials/materials/specific/defect-surface-step-platinum.md

mkdocs.yml

@@ -156,6 +156,7 @@ nav:
             - Substitutional Point Defects in Graphene (Band Structure):    tutorials/materials/specific/defect-point-substitution-graphene-simulation.md
             - Vacancy-Substitution Pair Defects in GaN:                     tutorials/materials/specific/defect-point-pair-gallium-nitride.md
             - Vacancy Point Defect in h-BN:                                 tutorials/materials/specific/defect-point-vacancy-boron-nitride.md
+            - Vacancy Point Defect in h-BN (Formation Energy):              tutorials/materials/specific/defect-point-vacancy-boron-nitride-simulation.md
             - Interstitial Point Defect in SnO:                             tutorials/materials/specific/defect-point-interstitial-tin-oxide.md
             - Island Surface Defect Formation in TiN:                       tutorials/materials/specific/defect-surface-island-titanium-nitride.md
             - Step Surface Defect on Pt(111):                               tutorials/materials/specific/defect-surface-step-platinum.md