feature/SOF-8065 Feature: tutorial for graphene on SiO2, doping and gap at the Dirac point

lang/en/docs/index-guide.md

@@ -44,7 +44,7 @@ Step-by-step recipes reproducing published work, one row per publication: the st
 | Liu et al. (2014)[^9]             | Twisted bilayer           | [MoS2](tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide.md) | [Band structure](tutorials/materials/specific/interface-bilayer-twisted-commensurate-lattices-molybdenum-disulfide-simulation.md) |
 | Jung et al. (2015)[^10]           | 2D–2D interface           | [Graphene / h-BN](tutorials/materials/specific/interface-2d-2d-graphene-boron-nitride.md) | Band structure, total energies (Coming Soon) |
 | Shan et al. (2011)[^11]           | 3D–3D interface           | [Cu / SiO2](tutorials/materials/specific/interface-3d-3d-copper-silicon-dioxide.md) | Band structure (Coming Soon) |
-| Kang et al. (2008)[^12]           | 2D–3D interface           | [Graphene / SiO2](tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide.md) | Band structure (Coming Soon) |
+| Kang et al. (2008)[^12]           | 2D–3D interface           | [Graphene / SiO2](tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide.md) | [Doping and gap at the Dirac point](tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide-simulation.md) |
 | Dahal et al. (2014)[^13]          | Interface optimization    | [Graphene / Ni(111)](tutorials/materials/specific/optimization-interface-film-xy-position-graphene-nickel.md) | [Registry and work of adhesion](tutorials/materials/specific/optimization-interface-film-xy-position-graphene-nickel-simulation.md) |
 | Saidi et al. (2015)[^14]          | Adatom island             | [Pt on MoS2](tutorials/materials/specific/defect-point-adatom-island-molybdenum-disulfide-platinum.md) | Binding energy per Pt atom, density of states (Coming Soon) |
 | Aradi et al. (2007)[^15]          | H-passivated nanowire     | [Si](tutorials/materials/specific/passivation-edge-nanowire-silicon.md) | Band gap, density of states, formation energy (Coming Soon) |

lang/en/docs/tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide-simulation.md

@@ -0,0 +1,203 @@
+---
+tags:
+  - 2D
+  - 3D
+  - graphene
+  - silicon dioxide
+  - interface
+  - band-structure
+  - C-2D-INT-Z
+
+hide:
+  - tags
+# YAML header
+render_macros: true
+---
+
+# Graphene on SiO2 (alpha-quartz): Doping and Gap at the Dirac Point
+
+
+## 1. Introduction
+
+This tutorial calculates the band structure of the graphene on O-terminated α-quartz(0001) interface created in the structure tutorial, then reads the position of the Dirac point relative to the Fermi level and the gap at K, reproducing results from the following manuscript. The calculation uses density functional theory (DFT) in the local density approximation (LDA) with GBRV (Garrity-Bennett-Rabe-Vanderbilt) ultrasoft pseudopotentials; a self-consistent field (SCF) step precedes the band path.
+
+!!!note "Manuscript"
+    **Yong-Ju Kang, Joongoo Kang, and K. J. Chang**
+    **Electronic structure of graphene and doping effect on SiO2**
+    Physical Review B 78, 115404 (2008)
+    [DOI: 10.1103/PhysRevB.78.115404](https://doi.org/10.1103/PhysRevB.78.115404){:target='_blank'} [@Kang2008]
+
+The compared quantities are from Sec. III and Fig. 3(a) of the manuscript, for the metastable geometry with the graphene at d = 2.58 Å above the surface: graphene is p-doped, the gap at the Dirac point is 0.13 eV, and the Dirac point lies about 1.28 eV above the Fermi level (the midpoint of the two Dirac bands at K on Fig. 3(a), +1.21 and +1.35 eV).
+
+![Band structure of graphene on SiO2 from the manuscript](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/kang2008-fig3a-band-structure.webp "Band structure of graphene on the O-terminated surface, metastable geometry (Kang et al. 2008, Fig. 3(a)); path Γ-M-K-Γ, energy in eV relative to the Fermi level")
+
+
+## 2. Prerequisites
+
+Run the [structure creation tutorial](interface-2d-3d-graphene-silicon-dioxide.md) first. Its `interface_2d_3d_graphene_silicon_dioxide.ipynb` notebook saves the interface in the 120° setting to the `uploads` folder under the name `C(001)-O2Si(001), Interface, Strain 1.875pct`, which this notebook loads. It also shifts graphene to the metastable registry and centers the slab along z. An interface from the generic ZSL notebook comes out at 60°, where the band path's K is not graphene's K.
+
+
+## 3. Workflow overview
+
+The notebook runs the Standata `band_structure.json` workflow, which chains `pw_scf` and `pw_bands`, as one job on the interface. With `RELAX = True`, `add_relaxation()` puts a relaxation (fixed cell, the `pw_vc-relax` unit with `calculation = 'relax'`, the same k-mesh as the SCF) in front of it in the same job, and the band structure runs on the relaxed structure.
+
+The notebook then reads the band structure at K, takes the Dirac point as the midpoint of the Dirac pair of bands, and prints it and the gap beside the manuscript's values. Re-running the notebook finds an already-finished job by its material and workflow name and reuses it instead of resubmitting.
+
+
+## 4. Calculation parameters
+
+Cell 1.2 sets the material name:
+
+```python
+# Name saved by interface_2d_3d_graphene_silicon_dioxide.ipynb.
+INTERFACE_NAME = "C(001)-O2Si(001), Interface, Strain 1.875pct"
+```
+
+Cell 1.3 sets the organization, the cluster and the workflow names:
+
+```python
+from datetime import datetime
+from mat3ra.ide.compute import QueueName
+
+ORGANIZATION_NAME = None  # set to your organization name (full or partial); otherwise, your default one is used
+FOLDER = "./uploads"
+
+BAND_STRUCTURE_WORKFLOW_SEARCH_TERM = "band_structure.json"
+MY_WORKFLOW_NAME = "Band Structure"
+APPLICATION_NAME = "espresso"
+
+# NOTE: False reads the band structure of the structure as built: E_D - E_F +1.171 eV, gap at K
+# 0.062 eV, about 1 h on OR/16. True relaxes all atoms at fixed cell to 0.03 eV/Å (Kang et al.
+# Sec. II) before the band structure, in the same job; on OR/16 it did 5 BFGS steps in the 4 h
+# TIME_LIMIT with the force still falling (job 25yp4K2SMNJgJMmBy).
+RELAX = False
+
+CLUSTER_NAME = "001"  # specify full or partial name i.e. "cluster-001" to select
+QUEUE_NAME = QueueName.OR
+PPN = 16  # queue OR on cluster-001 allows at most 16 cores per node
+TIME_LIMIT = "04:00:00"
+
+timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+POLL_INTERVAL = 60  # seconds
+```
+
+Cell 1.4 sets the DFT parameters:
+
+```python
+MODEL_SUBTYPE = "lda"
+FUNCTIONAL = "pz"  # Kang et al. 2008 use LDA
+PSEUDOPOTENTIAL_TYPE = "us"  # GBRV ultrasoft, the only LDA family the platform publishes for Si, O and C
+GBRV_VALENCE = {"Si": 4, "O": 6, "C": 4}  # valence electrons per atom of the GBRV pseudopotentials
+ECUTWFC = 40   # Ry, GBRV's recommended wavefunction cutoff
+ECUTRHO = 200  # Ry, GBRV's recommended charge-density cutoff
+
+KPOINT_DENSITY = 4  # gives 6 x 6 x 1 on the 1x1 quartz cell, Kang et al. Sec. II
+SMEARING_SETTINGS = {"degauss": 0.01}  # Ry; the doped graphene has no gap at E_F
+KPATH_STEPS = 20
+MODEL_TAG = (f"{FUNCTIONAL}-{PSEUDOPOTENTIAL_TYPE} {ECUTWFC}-{ECUTRHO}Ry k{KPOINT_DENSITY} "
+             f"p{KPATH_STEPS} g{SMEARING_SETTINGS['degauss']}")
+
+SCF_UNIT = "pw_scf"
+BANDS_UNIT = "pw_bands"
+RELAX_UNIT = "pw_vc-relax"
+# Fixed cell, 0.03 eV/Å, Kang et al. 2008 Sec. II
+RELAXATION_SETTINGS = {"calculation": "relax", "forc_conv_thr": 1.17e-3, "nstep": 100}
+WORKFLOW_TAG = MODEL_TAG + (f" relax f{RELAXATION_SETTINGS['forc_conv_thr']}" if RELAX else "")
+
+KPATH = [
+    {"point": "K", "steps": KPATH_STEPS},
+    {"point": "Γ", "steps": KPATH_STEPS},
+    {"point": "M", "steps": KPATH_STEPS},
+    {"point": "K", "steps": 1},
+]
+K_INDEX = 0  # KPATH starts at K, so the first point of the band structure's path is K
+```
+
+| manuscript | this notebook |
+|---|---|
+| LDA | LDA (`pz`) |
+| ultrasoft pseudopotentials, VASP, 396 eV cutoff (Sec. II) | GBRV ultrasoft, 40/200 Ry |
+| 6×6×1 k-mesh, 1×1 quartz cell (Sec. II) | `KPOINT_DENSITY = 4`, 6×6×1 |
+| 2×2 graphene on 1×1 quartz | the same, as built by the structure notebook, graphene strained +1.875 % |
+| 14 SiO2 bilayers, H-passivated back side | 15 Si planes (5 conventional cells; one bilayer read as one Si plane with its O), bare back side |
+| 20 Å vacuum | about 20 Å, as built by the structure notebook |
+| manuscript quartz cell | standata quartz cell, 2.3 % larger in a |
+| d = 2.58 Å, metastable geometry (Sec. III) | d = 2.58 Å, graphene shifted in-plane to the metastable registry (`REGISTRY_SHIFT` in the structure notebook); surface O at 0.354 Å and 1.095 Å from the nearest C |
+
+The structure is the example as the structure notebook builds it. The bare back surface is the face the manuscript (p. 2) calls chemically inactive. The structure notebook's cell 3.6 sets the cell to the 120° hexagonal setting and types it `HEX`, so the symbolic K point of `KPATH` lies on the band path.
+
+
+## 5. Step-by-step instructions
+
+### 5.1. Open the notebook
+
+Navigate to the API examples repository and open:
+
+```
+other/materials_designer/specific_examples/interface_2d_3d_graphene_silicon_dioxide_SIMULATION.ipynb
+```
+
+### 5.2. Configure parameters
+
+In cell 1.3, set `ORGANIZATION_NAME` and `CLUSTER_NAME` to the account's organization and cluster. `INTERFACE_NAME` in cell 1.2 already holds the name the structure notebook saves; leave it unchanged unless the material was renamed.
+
+### 5.3. Run the notebook
+
+Select *Run* > *Run All*. The notebook [authenticates with the platform]({{ interface_url }}/jupyterlite/authentication.md), loads the interface and prints its provenance (composition, number of atoms, gamma, interlayer distance of 2.580 Å, valence electrons, occupied bands), configures the DFT model and the k-grid, creates the compute configuration, saves the material to the account, then submits the band structure job and waits for it to finish. For the example as built the provenance reads Si15O30C8, 53 atoms, gamma = 120.000°, 272 valence electrons and 136 occupied bands. Once finished (measured with `RELAX = False` on cluster-001, queue OR with 16 cores, called OR/16 below: about 1 h), the notebook retrieves the band structure, prints the bands at K around the Fermi level and the Dirac pair, then E_F, E_D − E_F and the gap at K, and prints the comparison with the manuscript.
+
+### 5.4. Relax the interface (optional)
+
+Set `RELAX = True` in cell 1.3 and run the notebook. The relaxation (all atoms, fixed cell, force threshold 0.03 eV/Å, Sec. II) runs in the same job before the band structure, and the band structure is taken on the relaxed structure. On OR/16 it did 5 BFGS steps in the 4 h `TIME_LIMIT` with the force still falling (job 25yp4K2SMNJgJMmBy).
+
+### 5.5. Re-run the notebook
+
+Running the notebook again finds the finished job by material and workflow name and reuses it rather than resubmitting.
+
+
+## 6. Expected results
+
+| quantity | manuscript | this notebook, `RELAX = False` |
+|---|---|---|
+| doping | p-type (Sec. III) | p-type |
+| E_D − E_F (eV) | +1.28 (midpoint of the two Dirac bands at K on Fig. 3(a), +1.21 and +1.35 eV) | +1.171 |
+| gap at K (eV) | 0.13 (Sec. III) | 0.062 |
+
+Kang's gap is for the relaxed metastable geometry (Sec. III); the values above are for `RELAX = False` on the shifted registry (job F6AmKDRpQ6nFqiokb, unrelaxed, about 1 h on OR/16). The relaxed regime did not converge within the 4 h limit (5 BFGS steps on OR/16). The notebook's final cell prints:
+
+```
+Regime: unrelaxed SCF
+                 this notebook    Kang et al. (2008)
+Doping                  p-type                p-type
+E_D - E_F             1.171 eV              1.280 eV
+Gap at K              0.062 eV              0.130 eV
+```
+
+The band structure of the structure after 5 BFGS steps of the `RELAX = True` relaxation (job domjmuR4659Rj8np5) is p-type, E_D − E_F +1.179 eV, gap at K 0.071 eV, beside the unrelaxed +1.171 eV and 0.062 eV.
+
+![Band structure of graphene on SiO2 from this notebook](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/band-structure-this-notebook.webp "Band structure of the interface near the Fermi level, job F6AmKDRpQ6nFqiokb, shifted registry, unrelaxed; path Γ-M-K-Γ, energies relative to E_F")
+
+
+## 7. Customization options
+
+Changing `ECUTWFC`, `ECUTRHO`, `KPOINT_DENSITY`, `KPATH_STEPS`, `SMEARING_SETTINGS["degauss"]`, `RELAX` or `RELAXATION_SETTINGS["forc_conv_thr"]` changes the workflow name, so a new job is created rather than the finished one reused.
+
+
+## 8. Troubleshooting
+
+### 8.1. Material not found
+
+`ValueError: No material named …` means the structure notebook has not been run, or `INTERFACE_NAME` does not match. Run the [structure tutorial](interface-2d-3d-graphene-silicon-dioxide.md) first; the name must be exactly `C(001)-O2Si(001), Interface, Strain 1.875pct`.
+
+
+## 9. Interactive JupyterLite notebook
+
+{% with origin_url=config.extra.jupyterlite.origin_url_lab %}
+{% with notebooks_path_root=config.extra.jupyterlite.notebooks_path_root %}
+{% with notebook_name='specific_examples/interface_2d_3d_graphene_silicon_dioxide_SIMULATION.ipynb' %}
+{% include 'jupyterlite_embed.html' %}
+{% endwith %}
+{% endwith %}
+{% endwith %}
+
+
+## 10. References

lang/en/docs/tutorials/materials/specific/interface-2d-3d-graphene-silicon-dioxide.md

@@ -30,7 +30,7 @@ This tutorial demonstrates the process of creating interfaces between 2D and 3D
 
 We use the [Materials Designer]({{ interface_url }}/materials-designer/overview/) to create interfaces between graphene and silicon dioxide with oxygen termination, as shown in the manuscript.
 
-We will focus on replicating the material from FIG. 1. (b) -- with Graphene on O-terminated SiO<sub>2</sub>. The material (a) requires relaxation to correctly reproduce the structure, which is not covered in this tutorial.
+We will focus on replicating the metastable geometry of Kang et al. Sec. III: graphene 2.58 Å above the O-terminated surface, shifted from the C-over-O registry of Fig. 1(b).
 
 ![Graphene on Silicon Dioxide](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/0-figure-from-manuscript.webp "Graphene on Silicon Dioxide, FIG. 1(b)")
 
@@ -55,9 +55,9 @@ Select the input materials with the first being the substrate (SiO₂) and the s
 Open the `create_interface_with_min_strain_zsl.ipynb` notebook and modify the parameters as follows:
 
 - Miller indices: `(0, 0, 1)` for both materials
-- Thickness: `1` layer for graphene, `7` layers for SiO₂ (resulting in 14 bilayers as specified in the manuscript)
+- Thickness: `1` layer for graphene, `5` layers for SiO₂ (5 conventional cells: 15 Si planes; the manuscript has 14 bilayers)
 - Interface distance: `2.58` Å (as stated in the manuscript)
-- Interface vacuum: `20.0` Å (as specified in the manuscript)
+- Interface vacuum: `17.5` Å (gives about 20 Å above graphene, as specified in the manuscript)
 
 Let's set `MAX_AREA=150` Ų to allow for a larger search area for the superlattice search algorithm.
 
@@ -79,14 +79,14 @@ FILM_USE_ORTHOGONAL_C = True
 
 SUBSTRATE_INDEX = 0
 SUBSTRATE_MILLER_INDICES = (0, 0, 1)
-SUBSTRATE_THICKNESS = 7  # in atomic layers (for 14 bilayers -- from manuscript)
+SUBSTRATE_THICKNESS = 5  # conventional cells along c: 15 Si planes; the manuscript has 14 bilayers
 SUBSTRATE_TERMINATION_FORMULA = None  # if None, the first termination will be used
 SUBSTRATE_VACUUM = 0.0  # in angstroms
 SUBSTRATE_XY_SUPERCELL_MATRIX = [[1, 0], [0, 1]]
 SUBSTRATE_USE_ORTHOGONAL_C = True
 
 INTERFACE_DISTANCE = 2.58  # Gap between substrate and film, in Angstrom
-INTERFACE_VACUUM = 20.0  # Vacuum over film, in Angstrom
+INTERFACE_VACUUM = 17.5  # in Angstrom
 
 # Whether to convert materials to conventional cells before creating slabs.
 # To create interfaces with smaller cells, set this flag to False. (and pass already conventional cells as input)
@@ -104,7 +104,43 @@ MAX_ANGLE_TOLERANCE = 0.02
 REDUCE_RESULT_CELL_TO_PRIMITIVE = True
 ```
 
-![Notebook Setup](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/2-jl-setup-notebook.webp "Notebook Setup")
+The specific-example notebook `interface_2d_3d_graphene_silicon_dioxide.ipynb` continues after the ZSL step with two more cells, which the generic notebook does not have. The ZSL match leaves the registry of graphene on the quartz surface undefined. The notebook shifts the film in-plane by `REGISTRY_SHIFT` to the registry of the manuscript's metastable geometry (Sec. III), where one surface O sits near a C atom and the other near a hexagon centre, and prints each surface O's in-plane distance to the nearest C. Its parameter, set in the notebook's parameter cell, and cell 3.5:
+
+```python
+REGISTRY_SHIFT = [-1.011, -0.725, 0.0]
+```
+
+```python
+import numpy as np
+from mat3ra.made.tools.modify import interface_displace_part
+
+interface = interface_displace_part(interface, displacement=REGISTRY_SHIFT, use_cartesian_coordinates=True)
+
+interface_in_cartesian = interface.clone()
+interface_in_cartesian.to_cartesian()
+coordinates = np.array(interface_in_cartesian.basis.coordinates.values)
+elements = np.array(interface.basis.elements.values)
+cell_xy = np.array(interface.lattice.vector_arrays)[:2, :2]
+carbons = coordinates[elements == "C"]
+oxygens = coordinates[elements == "O"]
+for oxygen in oxygens[np.argsort(-oxygens[:, 2])[:2]]:
+    distances = [np.linalg.norm(oxygen[:2] - carbon[:2] - i * cell_xy[0] - j * cell_xy[1])
+                 for carbon in carbons for i in (-1, 0, 1) for j in (-1, 0, 1)]
+    print(f"surface O at z = {oxygen[2]:.3f} Å: nearest C in the plane {min(distances):.3f} Å")
+```
+
+Cell 3.6 puts the cell in the 120° hexagonal setting and centers the slab along z, so that no atom sits at z = 0, where a relaxation would wrap it to the top of the cell:
+
+```python
+from mat3ra.made.tools.helpers import create_supercell
+from mat3ra.made.tools.modify import translate_to_center
+
+interface = create_supercell(interface, supercell_matrix=[[1, 0, 0], [-1, 1, 0], [0, 0, 1]])
+interface = translate_to_center(interface, axes=["z"])
+interface.lattice.type = "HEX"
+print(f"{interface.basis.number_of_atoms} atoms, a = {interface.lattice.a:.4f} Å, "
+      f"gamma = {interface.lattice.gamma:.1f}°")
+```
 
 ### 2.3 Run the Notebook
 
@@ -117,7 +153,7 @@ Run the notebook to generate the interface structure between graphene and silico
 The generation might take some time.
 After that, the user can pass the material to the Materials Designer for further analysis.
 
-![Gr/SiO2 Interface](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/3-jl-result-preview.webp "Gr/SiO2 Interface")
+![Gr/SiO2 Interface](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/3-structure-5-cells.webp "Gr/SiO2 Interface, side view: graphene on 5 conventional quartz cells (Si15O30C8, 53 atoms)")
 
 ## 4. Pass the Material to Materials Designer
 

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

@@ -49,7 +49,7 @@ This document provides a comprehensive catalog of materials science tutorials or
 ##### 2.1.1.2. Graphene/SiO2 Interface <span class="btn badge b-info border-50">C-2D-INT-Z</span>
 
 **Structure**: [Create Graphene/SiO2 Interface](interface-2d-3d-graphene-silicon-dioxide.md)  
-**Properties**: Calculate band structure (Coming Soon)  
+**Properties**: [Calculate Doping and Gap at the Dirac Point of Graphene on SiO2](interface-2d-3d-graphene-silicon-dioxide-simulation.md)  
 **DOI**: [10.1103/PhysRevB.78.115404](https://doi.org/10.1103/PhysRevB.78.115404){:target='_blank'}
 
 ![Graphene on Silicon Dioxide](../../../images/tutorials/materials/interfaces/interface_2d_3d_graphene_silicon_dioxide/0-figure-from-manuscript.webp "Graphene on Silicon Dioxide, FIG. 1(b)"){ style="max-height:500px;width:auto;" }