update/SOF 7691 1

lang/en/docs/tutorials/materials/specific/defect-planar-grain-boundary-2d-boron-nitride.md

@@ -54,21 +54,33 @@ Find and open `create_grain_boundary_film.ipynb`. Edit the grain boundary parame
 `EDGE_INCLUSION_TOLERANCE = 0.0` -- Edge inclusion parameter, in Angstroms. Controls the overlap of the second phase onto the first phase.
 
 ```python
+# Material selection
+MATERIAL_INDEX = 0  # Index in the list of materials
+
 # Grain boundary parameters
 TARGET_TWIST_ANGLE = 9.0  # in degrees
-BOUNDARY_GAP = 0.0  # Gap between orientations in X direction
-XY_SUPERCELL_MATRIX = [[1, 0], [0, 2]]
+BOUNDARY_GAP = 0.0  # Gap between two orientations in X direction, in Angstroms
+XY_SUPERCELL_MATRIX = [[1, 0], [0, 2]] # Supercell matrix to be applied to each of the orientations before matching
+MILLER_INDICES = (0, 0, 1)  # Miller indices for the supercell matching
+VACUUM = 10.0  # Vacuum thickness in Angstroms, added to the top and bottom of the grain boundary
 
 # Search algorithm parameters
-MAX_REPETITION = None
+MAX_REPETITION = None  # Maximum supercell matrix element value
 ANGLE_TOLERANCE = 0.5  # in degrees
-RETURN_FIRST_MATCH = True
+RETURN_FIRST_MATCH = True  # If True, returns first solution within tolerance
 
-# Distance tolerance for atom merging
+# Distance tolerance for two atoms to be considered too close. 
+# Used when merging two orientations to remove the atoms of the first one. 
+# Should be less than the expected bond length
 DISTANCE_TOLERANCE = 1.43  # in Angstroms
 
-# Edge inclusion parameter
+# How much to expand inclusion of the edge atoms for both orientations and fill in the gap region.
+# A fine-tuning parameter
 EDGE_INCLUSION_TOLERANCE = 0.0  # in Angstroms
+
+# Visualization parameters
+SHOW_INTERMEDIATE_STEPS = True
+CELL_REPETITIONS_FOR_VISUALIZATION = [3, 3, 1]
 ```
 
 ![Notebook Setup](../../../images/tutorials/materials/defects/defect_planar_grain_boundary_2d_boron_nitride/2-jl-setup-nb-gb.webp "Notebook Setup")
@@ -95,21 +107,16 @@ Open JupyterLite Session and find `create_point_defect.ipynb` notebook.
 Select the h-BN grain boundary structure as input material and configure the adatom defect parameters in the "1.1. Set Notebook Parameters" section:
 
 ```python
-DEFECT_TYPE = "interstitial"  # (e.g. "vacancy", "substitution", "interstitial")
-SITE_ID = None  # Site index of the defect
-COORDINATE = [0.5, 0.45, 0.5]  # Position of the defect in crystal coordinates
-APPROXIMATE_COORDINATE = None  # Approximate coordinates of the defect in crystal coordinates
-CHEMICAL_ELEMENT = "N"  # Element to be placed at the site (ignored for vacancy)
-
+# Selected material will be used as a unit cell to create a supercell first.
 SUPERCELL_MATRIX = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
 
-# List of dictionaries with defect parameters
 DEFECT_CONFIGS = [
     {
-        "defect_type": DEFECT_TYPE,
-        "coordinate": COORDINATE,
-        "chemical_element": CHEMICAL_ELEMENT,
-    }
+        "type": "interstitial",
+        "coordinate": [0.5, 0.45, 0.5],  # Crystal coordinates
+        "element": "N",
+        "placement_method": "closest_site",
+    },
 ]
 ```
 

lang/en/docs/tutorials/materials/specific/defect-point-adatom-island-molybdenum-disulfide-platinum.md

@@ -53,47 +53,48 @@ Find and open the `create_adatom_defect.ipynb` notebook. Select MoS2 as input ma
 Set up the slab and defect parameters in the notebook:
 
 ```python
-# Slab parameters
-MILLER_INDICES = (0, 0, 1)  # MoS2 basal plane
-SLAB_THICKNESS = 1  # Single layer
-VACUUM = 10.0  # in Angstrom
-SUPERCELL_MATRIX = [[3, 0, 0], [0, 3, 0], [0, 0, 1]]  # 3x3 supercell
+# Index in the list of materials, to access as materials[MATERIAL_INDEX]
+MATERIAL_INDEX = 0
+ELEMENT = "Pt"  # Chemical element of the adatom
 
-# Defect configurations for all Pt atoms
+# Dictionaries are validated and converted to AdatomDefectDict objects below
 DEFECT_CONFIGS = [
     {
-        "defect_type": "adatom",
-        "placement_method": "coordinate",
-        "chemical_element": "Pt",
-        "position_on_surface": [5/9, 4/9],  # First Pt: atop central Mo
-        "distance_z": 1.2, # Distance from surface S atoms
-        "use_cartesian_coordinates": False
+        "type": "adatom",
+        "coordinate_2d": [5/9, 4/9], # Crystal coordinates on the surface (x, y)
+        "distance_z": 1.2,  # Method to place the adatom
+        "element": ELEMENT,
     },
     {
-        "defect_type": "adatom",
-        "placement_method": "coordinate",
-        "chemical_element": "Pt",
-        "position_on_surface": [2/9, 4/9],  # Second Pt: next clockwise atop Mo
-        "distance_z": 1.2, # Distance from surface S atoms
-        "use_cartesian_coordinates": False
+        "type": "adatom",
+        "coordinate_2d": [2/9, 4/9], # Crystal coordinates on the surface (x, y)
+        "distance_z": 1.2,  # Method to place the adatom
+        "element": ELEMENT,
     },
     {
-        "defect_type": "adatom",
-        "placement_method": "coordinate",
-        "chemical_element": "Pt",
-        "position_on_surface": [5/9, 7/9],  # Third Pt: next clockwise atop Mo
-        "distance_z": 1.2, # Distance from surface S atoms
-        "use_cartesian_coordinates": False
+        "type": "adatom",
+        "coordinate_2d": [5/9, 7/9], # Crystal coordinates on the surface (x, y)
+        "distance_z": 1.2,  # Method to place the adatom
+        "element": ELEMENT,
     },
     {
-        "defect_type": "adatom",
-        "placement_method": "coordinate",
-        "chemical_element": "Pt",
-        "position_on_surface": [4/9, 5/9],  # Fourth Pt: centered atop S
-        "distance_z": 1.6,  # Distance between Pt atom layers, in Angstrom
-        "use_cartesian_coordinates": False
-    }
+        "type": "adatom",
+        "coordinate_2d": [4/9, 5/9], # Crystal coordinates on the surface (x, y)
+        "distance_z": 1.6,  # Method to place the adatom
+        "element": ELEMENT,
+    },
 ]
+
+
+PLACEMENT_METHOD = "new_crystal_site"  # Method to place the adatom, e.g., "new_crystal_site", "exact_coordinate", "equidistant"
+
+
+# Slab parameters
+MILLER_INDICES = (0, 0, 1)  # Miller indices of the surface
+SLAB_THICKNESS = 1  # Thickness of the slab in unit cells
+VACUUM = 10.0  # Vacuum thickness in Angstrom
+XY_SUPERCELL_MATRIX = [[3, 0], [0, 3]]  # Supercell matrix for the slab
+TERMINATION_FORMULA = None  # Stoichiometric formula of the slab termination to be used.
 ```
 
 Key parameters explained:

lang/en/docs/tutorials/materials/specific/defect-point-interstitial-tin-oxide.md

@@ -54,23 +54,21 @@ We'll modify its parameters to create the Sn-vacancy O-interstitial defects acco
 Replace the default parameters in section 1.1 with:
 
 ```python
-# Supercell parameters.
+# Selected material will be used as a unit cell to create a supercell first.
 SUPERCELL_MATRIX = [[2, 0, 0], [0, 2, 0], [0, 0, 2]]
 
-# Defect parameters.
 DEFECT_CONFIGS = [
     {
-        "defect_type": "vacancy",
-        # Coordiante will be resolved to nearest atom.
-        "approximate_coordinate": [0.0, 0.25, 0.525],
+        "type": "vacancy",
+        "coordinate": [0.0, 0.25, 0.525],  # Crystal coordinates
+        "placement_method": "closest_site",
     },
     {
-        "defect_type": "interstitial",
-        # Coordiante will be resolved to nearest Voronoi site.
-        "coordinate": [0.0, 0.25, 0.35], 
-        "chemical_element": "O",
-        "placement_method": "voronoi_site"
-    }
+        "type": "interstitial",
+        "coordinate": [0.0, 0.25, 0.35],  # Crystal coordinates
+        "element": "O",
+        "placement_method": "voronoi_site",
+    },
 ]
 ```
 ![Defect Parameters](../../../images/tutorials/materials/defects/defect_point_interstitial_tin_oxide/3-jl-setup-nb.webp "Defect parameters for O-interstitial in SnO")

lang/en/docs/tutorials/materials/specific/defect-point-pair-gallium-nitride.md

@@ -82,21 +82,28 @@ Next, edit `create_point_defect_pair.ipynb` notebook to modify the parameters by
 Copy the below content and edit the "1.1. Set up defect parameters" cell in the notebook as follows:
 
 ```python
+from types import SimpleNamespace
+
+# Selected material will be used as a unit cell to create a supercell first.
 SUPERCELL_MATRIX = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
 
 # List of dictionaries with defect parameters
-PRIMARY_DEFECT_CONFIG = {
-    "defect_type": "substitution",
-    "approximate_coordinate": [1.608, 4.642, 5.240],
-    "chemical_element": "Mg",
-    "use_cartesian_coordinates": True,
-}
-
-SECONDARY_DEFECT_CONFIG = {
-    "defect_type": "vacancy",
-    "approximate_coordinate": [1.608, 4.642, 7.210],
-    "use_cartesian_coordinates": True,
-}
+PRIMARY_DEFECT_CONFIG = SimpleNamespace(
+    defect_type="substitution",
+    coordinate=[1.608, 4.642, 5.240],  # Approx. coord that will be resolved to the closest site
+    use_cartesian_coordinates=True,  # Use cartesian or crystal coordinates
+    chemical_element="Mg",
+    # "site_id": 0, # Index of the atom in the host material
+    # "coordinate": None, # Exact position (override the approximate coordinate)
+)
+
+SECONDARY_DEFECT_CONFIG = SimpleNamespace(
+    defect_type="vacancy",
+    approximate_coordinate=[1.608, 4.642, 7.210],  # Approx. coord that will be resolved to the closest site
+    use_cartesian_coordinates=True,
+    # "site_id": 0, # Index of the atom in the host material
+    # "coordinate": None, # Exact position (override the approximate coordinate)
+)
 ```
 
 Here's the visual of the updated content:

lang/en/docs/tutorials/materials/specific/defect-point-substitution-graphene.md

@@ -73,39 +73,38 @@ Next, edit `create_point_defect.ipynb` notebook to modify the parameters by addi
 Copy the below content and edit the "1.1. Set up defect parameters" cell in the notebook as follows:
 
 ```python
-DEFECT_TYPE = "substitution"
-SITE_ID = None # `from_site_id` method will be ignored
-COORDINATE = None # default method will be ignored
-APPROXIMATE_COORDINATE = None   
-CHEMICAL_ELEMENT = "N"
+# Selected material will be used as a unit cell to create a supercell first.
 SUPERCELL_MATRIX = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
-USE_CARTESIAN_COORDINATES = True
 
 DEFECT_CONFIGS = [
     {
-        "defect_type": "substitution",
-        "approximate_coordinate": [4.9, 2.85, 10],
-        "chemical_element": CHEMICAL_ELEMENT,
-        "use_cartesian_coordinates": USE_CARTESIAN_COORDINATES
+        "type": "substitution",
+        "coordinate": [4.9, 2.85, 10],
+        "element": "N",
+        "placement_method": "closest_site",
+        "use_cartesian_coordinates": True
     },
       {
-        "defect_type": "substitution",
-        "approximate_coordinate": [3.7, 4.9, 10],
-        "chemical_element": CHEMICAL_ELEMENT,
-        "use_cartesian_coordinates": USE_CARTESIAN_COORDINATES
+        "type": "substitution",
+        "coordinate": [3.7, 4.9, 10],
+        "element": "N",
+        "placement_method": "closest_site",
+        "use_cartesian_coordinates": True
     },
       {
-        "defect_type": "substitution",
-        "approximate_coordinate": [2.45, 2.85, 10],
-        "chemical_element": CHEMICAL_ELEMENT,
-        "use_cartesian_coordinates": USE_CARTESIAN_COORDINATES
+        "type": "substitution",
+        "coordinate": [2.45, 2.85, 10],
+        "element": "N",
+        "placement_method": "closest_site",
+        "use_cartesian_coordinates": True
     },
       {
-        "defect_type": "vacancy",
-        "approximate_coordinate": [3.7, 3.55, 10],
-        "use_cartesian_coordinates": USE_CARTESIAN_COORDINATES
+        "type": "vacancy",
+        "coordinate": [3.7, 3.55, 10],
+        "placement_method": "closest_site",
+        "use_cartesian_coordinates": True
     },
-]  
+]
 ```
 
 Here's the visual of the updated content:

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

@@ -59,11 +59,15 @@ Select the "Advanced > [JupyterLite Transformation](../../../materials-designer/
 Find and open `create_nanoribbon.ipynb` in the list of notebooks. Edit the nanoribbon parameters in section 1.1 of the notebook:
 
 ```python
-WIDTH = 3  # in number of unit cells
-LENGTH = 6  # in number of unit cells
-VACUUM_WIDTH = 0  # in number of unit cells
-VACUUM_LENGTH = 0 # in number of unit cells
-EDGE_TYPE = "zigzag"  # "zigzag" or "armchair"
+# Index in the list of materials, to access as materials[MATERIAL_INDEX]
+MATERIAL_INDEX = 0
+
+# Widths and lengths are in number of unit cells
+WIDTH = 3 # in unit cells
+LENGTH = 6 # in unit cells
+VACUUM_WIDTH = 0 # in Angstroms
+VACUUM_LENGTH = 0 # in Angstroms
+EDGE_TYPE = "zigzag" # "zigzag" or "armchair"
 ```
 
 ![Nanoribbon Parameters](../../../images/tutorials/materials/defects/defect_point_vacancy_boron_nitride/2-jl-nb-setup-nanoribbon.webp "Nanoribbon Parameters")
@@ -92,11 +96,14 @@ After creating the nanoribbon, we'll introduce the vacancy defect using the poin
 Open `create_point_defect.ipynb` and modify the defect configuration parameters:
 
 ```python
+# Selected material will be used as a unit cell to create a supercell first.
 SUPERCELL_MATRIX = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
+
 DEFECT_CONFIGS = [
     {
-        "defect_type": "vacancy",
-        "approximate_coordinate": [0.5, 0.5, 0.5],
+        "type": "vacancy",
+        "coordinate": [0.5, 0.5, 0.5],
+        "placement_method": "closest_site",
         "use_cartesian_coordinates": False
     }
 ]