@mat3ra/made 2025.8.8-0 → 2025.8.9-0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2025.8.8-0",
+    "version": "2025.8.9-0",
     "description": "MAterials DEsign library",
     "scripts": {
         "lint": "eslint --cache src/js tests/js && prettier --write src/js tests/js",

package/src/py/mat3ra/made/tools/analyze/interface/simple.py

@@ -1,5 +1,5 @@
 from functools import cached_property
-from typing import Optional
+from typing import Optional, Tuple
 
 import numpy as np
 from mat3ra.code.entity import InMemoryEntityPydantic
@@ -14,7 +14,10 @@ from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab.configurat
 from ...build.pristine_structures.two_dimensional.slab_strained_supercell.configuration import (
     SlabStrainedSupercellConfiguration,
 )
+from ...operations.core.unary import supercell
+from ...utils import unwrap
 from ..interface.utils.holders import MatchedSubstrateFilmConfigurationHolder
+from ..utils import calculate_von_mises_strain
 
 
 class InterfaceAnalyzer(InMemoryEntityPydantic):
@@ -30,6 +33,7 @@ class InterfaceAnalyzer(InMemoryEntityPydantic):
     film_slab_configuration: SlabConfiguration
     substrate_build_parameters: Optional[SlabBuilderParameters] = None
     film_build_parameters: Optional[SlabBuilderParameters] = None
+    optimize_film_supercell: bool = False
 
     def get_component_material(self, configuration: SlabConfiguration):
         return SlabBuilder().get_material(configuration)
@@ -87,6 +91,83 @@ class InterfaceAnalyzer(InMemoryEntityPydantic):
     def get_substrate_strain_matrix(self) -> Matrix3x3Schema:
         return self._no_strain_matrix
 
+    def _calculate_strain_for_film_supercell(self, film_n: int, film_m: int) -> float:
+        """
+        Calculate strain for given film supercell configuration against unchanged substrate.
+
+        Args:
+            film_n: Film supercell multiplier in a direction
+            film_m: Film supercell multiplier in b direction
+
+        Returns:
+            Von Mises strain percentage
+        """
+
+        # Apply supercell to film material
+        supercell_matrix = [[film_n, 0], [0, film_m]]
+        film_with_supercell = supercell(self.film_material, supercell_matrix)
+
+        # Use existing get_film_strain_matrix with supercelled film
+        strain_matrix = self.get_film_strain_matrix(
+            self.substrate_material.lattice.vector_arrays, film_with_supercell.lattice.vector_arrays
+        )
+
+        return calculate_von_mises_strain(np.array(unwrap(strain_matrix.root)))
+
+    def _find_optimal_supercell_factor_for_direction(self, substrate_length: float, film_length: float) -> int:
+        """
+        Finds a multiplier for the component of diagonal supercell matrix
+            that will get film supercell lattice vector length around substrate length.
+            The N leads to the film supercell vector length being shorter than substrate length,
+            and N+1 leads to the film supercell vector length being longer than substrate length.
+        """
+
+        # Find optimal: when n*film_length < substrate_length < (n+1)*film_length
+        optimal = max(1, int(substrate_length / film_length))
+        if (optimal + 1) * film_length - substrate_length < substrate_length - optimal * film_length:
+            optimal += 1
+
+        return optimal
+
+    def find_optimal_film_supercell(self) -> Tuple[int, int]:
+        """
+        Find optimal (n, m) supercell multipliers for film that minimize strain.
+
+        Returns:
+            Tuple of (n, m) supercell multipliers that minimize strain
+        """
+        substrate_vectors = np.array(self.substrate_material.lattice.vector_arrays[:2])
+        film_vectors = np.array(self.film_material.lattice.vector_arrays[:2])
+
+        substrate_lengths = [np.linalg.norm(substrate_vectors[i, :2]) for i in range(2)]
+        film_lengths = [np.linalg.norm(film_vectors[i, :2]) for i in range(2)]
+
+        optimal_values = []
+        for substrate_length, film_length in zip(substrate_lengths, film_lengths):
+            optimal = self._find_optimal_supercell_factor_for_direction(substrate_length, film_length)
+            optimal_values.append(optimal)
+
+        n_optimal, m_optimal = optimal_values
+
+        # Test neighboring values to find minimum strain
+        candidates = [
+            (n_optimal, m_optimal),
+            (n_optimal + 1, m_optimal),
+            (n_optimal, m_optimal + 1),
+            (n_optimal + 1, m_optimal + 1),
+        ]
+
+        min_strain = float("inf")
+        best_n, best_m = n_optimal, m_optimal
+
+        for n, m in candidates:
+            strain = self._calculate_strain_for_film_supercell(n, m)
+            if strain < min_strain:
+                min_strain = strain
+                best_n, best_m = n, m
+
+        return best_n, best_m
+
     def get_component_strained_configuration(
         self,
         configuration: SlabConfiguration,
@@ -146,7 +227,10 @@ class InterfaceAnalyzer(InMemoryEntityPydantic):
 
     @property
     def film_supercell_matrix(self) -> SupercellMatrix2DSchema:
-        if self.film_build_parameters and self.film_build_parameters.xy_supercell_matrix:
+        if self.optimize_film_supercell:
+            n, m = self.find_optimal_film_supercell()
+            return SupercellMatrix2DSchema(root=[[n, 0], [0, m]])
+        elif self.film_build_parameters and self.film_build_parameters.xy_supercell_matrix:
             return SupercellMatrix2DSchema(root=self.film_build_parameters.xy_supercell_matrix)
         return self.identity_supercell
 

package/src/py/mat3ra/made/tools/analyze/other.py

@@ -2,9 +2,9 @@ from typing import Callable, List, Literal, Optional
 
 import numpy as np
 from mat3ra.made.material import Material
-from mat3ra.made.tools.build.processed_structures.two_dimensional.passivation.enums import SurfaceTypesEnum
 from scipy.spatial import cKDTree
 
+from ..build.processed_structures.two_dimensional.passivation.enums import SurfaceTypesEnum
 from ..convert import decorator_convert_material_args_kwargs_to_atoms, to_pymatgen
 from ..third_party import ASEAtoms, PymatgenIStructure
 from ..utils import decorator_convert_position_to_coordinate

package/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/heterostructure/__init__.py

@@ -0,0 +1,7 @@
+from .helpers import create_heterostructure
+from .types import StackComponentDict
+
+__all__ = [
+    "create_heterostructure",
+    "StackComponentDict",
+]

package/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/heterostructure/helpers.py

@@ -0,0 +1,101 @@
+from typing import List
+
+from mat3ra.esse.models.core.reusable.axis_enum import AxisEnum
+
+from .types import StackComponentDict
+from mat3ra.made.utils import adjust_material_cell_to_set_gap_along_direction
+from ....pristine_structures.two_dimensional.slab.helpers import create_slab
+from ....pristine_structures.two_dimensional.slab_strained_supercell.builder import SlabStrainedSupercellBuilder
+from .....analyze import BaseMaterialAnalyzer
+from .....analyze.interface import InterfaceAnalyzer
+from .....analyze.slab import SlabMaterialAnalyzer
+from .....build_components import MaterialWithBuildMetadata
+from .....operations.core.binary import stack
+
+
+def create_heterostructure(
+    stack_component_dicts: List[StackComponentDict],
+    gaps: List[float],
+    vacuum: float = 10.0,
+    use_conventional_cell: bool = True,
+    optimize_layer_supercells: bool = True,
+) -> MaterialWithBuildMetadata:
+    """
+    Create a heterostructure by stacking multiple slabs, while applying strain to each slab relative to the first slab.
+
+    Args:
+        stack_component_dicts: List of validated stack component configurations
+        gaps: List of gaps between adjacent slabs (in Angstroms)
+        vacuum: Size of vacuum layer in Angstroms
+        use_conventional_cell: Whether to use conventional cell
+        optimize_layer_supercells: Whether to find optimal supercells for strained layers
+
+    Returns:
+        Heterostructure material with stacked strained slabs
+    """
+    if len(stack_component_dicts) < 2:
+        raise ValueError("At least 2 stack components are required for a heterostructure")
+
+    if len(gaps) != len(stack_component_dicts) - 1:
+        raise ValueError("Number of gaps must be one less than number of stack components")
+
+    slabs = []
+    for i, component in enumerate(stack_component_dicts):
+        slab = create_slab(
+            crystal=component.crystal,
+            miller_indices=component.miller_indices,
+            number_of_layers=component.thickness,
+            vacuum=0.0 if i < len(stack_component_dicts) - 1 else vacuum,
+            use_conventional_cell=use_conventional_cell,
+            xy_supercell_matrix=component.xy_supercell_matrix or [[1, 0], [0, 1]],
+        )
+        slabs.append(slab)
+
+    strained_slabs = [slabs[0]]  # First slab is the substrate, not strained
+
+    for i in range(1, len(slabs)):
+        substrate_slab = strained_slabs[0]
+        film_slab = slabs[i]
+
+        substrate_analyzer = SlabMaterialAnalyzer(material=substrate_slab)
+        film_analyzer = SlabMaterialAnalyzer(material=film_slab)
+
+        analyzer = InterfaceAnalyzer(
+            substrate_slab_configuration=substrate_analyzer.build_configuration,
+            film_slab_configuration=film_analyzer.build_configuration,
+            substrate_build_parameters=substrate_analyzer.build_parameters,
+            film_build_parameters=film_analyzer.build_parameters,
+            optimize_film_supercell=optimize_layer_supercells,
+        )
+
+        strained_film_config = analyzer.film_strained_configuration
+
+        builder = SlabStrainedSupercellBuilder()
+        strained_slab = builder.get_material(strained_film_config)
+        strained_slabs.append(strained_slab)
+
+    stacked_materials = []
+    for i, slab in enumerate(strained_slabs):
+        if i < len(gaps):
+            slab_with_gap = adjust_material_cell_to_set_gap_along_direction(slab, gaps[i], AxisEnum.z)
+            stacked_materials.append(slab_with_gap)
+        else:
+            stacked_materials.append(slab)
+
+    heterostructure = stack(stacked_materials, AxisEnum.z)
+    heterostructure.name = generate_heterostructure_name(stack_component_dicts)
+
+    return heterostructure
+
+
+def generate_heterostructure_name(stack_component_dicts: List[StackComponentDict]):
+    """Generate a descriptive name for the heterostructure."""
+
+    components = []
+    for component in stack_component_dicts:
+        analyzer = BaseMaterialAnalyzer(material=component.crystal)
+        formula = analyzer.formula
+        miller_str = "".join(map(str, component.miller_indices))
+        components.append(f"{formula}({miller_str})")
+
+    return f"Heterostructure [{'-'.join(components)}]"

package/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/heterostructure/types.py

@@ -0,0 +1,26 @@
+from typing import List, Optional, Tuple, Union
+
+from mat3ra.code.entity import InMemoryEntityPydantic
+from pydantic import Field
+
+from mat3ra.made.material import Material
+from .....build_components import MaterialWithBuildMetadata
+
+
+class StackComponentDict(InMemoryEntityPydantic):
+    """
+    Pydantic model for heterostructure stack component configurations.
+
+    Required fields:
+        crystal: The crystal material to create a slab from
+        miller_indices: Miller indices for the slab surface as (h, k, l)
+        thickness: Number of layers in the slab
+
+    Optional fields:
+        xy_supercell_matrix: Optional supercell matrix for the xy plane
+    """
+
+    crystal: Union[Material, MaterialWithBuildMetadata] = Field(..., description="Crystal material for the slab")
+    miller_indices: Tuple[int, int, int] = Field(..., description="Miller indices for the slab surface")
+    thickness: int = Field(..., gt=0, description="Number of layers in the slab")
+    xy_supercell_matrix: Optional[List[List[int]]] = Field(None, description="Optional xy supercell matrix")

package/src/py/mat3ra/made/tools/build/defective_structures/two_dimensional/adatom/helpers.py

@@ -1,4 +1,3 @@
-from types import SimpleNamespace
 from typing import List, Optional
 
 from mat3ra.made.material import Material
@@ -6,6 +5,7 @@ from .builder import AdatomDefectBuilder
 from .configuration import (
     AdatomDefectConfiguration,
 )
+from .types import AdatomDefectDict
 from .....analyze.crystal_site.adatom_crystal_site_material_analyzer import (
     AdatomCrystalSiteMaterialAnalyzer,
 )
@@ -52,12 +52,14 @@ def create_defect_adatom(
     slab_with_adatom = create_multiple_adatom_defects(
         slab,
         defect_dicts=[
-            {
-                "element": element or "Si",  # Default to Silicon if no element provided
-                "coordinate": position_on_surface,
-                "distance_z": distance_z,
-                "use_cartesian_coordinates": use_cartesian_coordinates,
-            }
+            AdatomDefectDict(
+                **{
+                    "element": element or "Si",  # Default to Silicon if no element provided
+                    "coordinate_2d": position_on_surface,
+                    "distance_z": distance_z,
+                    "use_cartesian_coordinates": use_cartesian_coordinates,
+                }
+            )
         ],
         placement_method=placement_method,
     )
@@ -65,10 +67,10 @@ def create_defect_adatom(
 
 
 def create_multiple_adatom_defects(
-    slab: MaterialWithBuildMetadata, defect_dicts: List[dict], placement_method: str
+    slab: MaterialWithBuildMetadata, defect_dicts: List[AdatomDefectDict], placement_method: str
 ) -> Material:
     """
-    Create multiple adatom defects (at once) from a list of dictionaries.
+    Create multiple adatom defects from a list of AdatomDefectDict.
 
     Args:
         slab: The slab material.
@@ -99,10 +101,8 @@ def create_multiple_adatom_defects(
     last_analyzer = None
 
     for defect_dict in defect_dicts:
-        defect_configuration = SimpleNamespace(**defect_dict)
-
-        coordinate_2d = defect_configuration.coordinate
-        use_cartesian = getattr(defect_configuration, "use_cartesian_coordinates", False)
+        coordinate_2d = defect_dict.coordinate_2d
+        use_cartesian = defect_dict.use_cartesian_coordinates
 
         if use_cartesian:
             coordinate_3d = coordinate_2d + [0.0]
@@ -112,9 +112,9 @@ def create_multiple_adatom_defects(
         analyzer = analyzer_cls(
             material=slab,
             coordinate_2d=coordinate_2d,
-            distance_z=defect_configuration.distance_z,
+            distance_z=defect_dict.distance_z,
             placement_method=placement_method,
-            element=defect_configuration.element,
+            element=defect_dict.element,
         )
         last_analyzer = analyzer
         all_adatom_configs.append(analyzer.added_component)

package/src/py/mat3ra/made/tools/build/defective_structures/two_dimensional/adatom/types.py

@@ -0,0 +1,22 @@
+from typing import List
+
+from pydantic import BaseModel, Field
+
+
+class AdatomDefectDict(BaseModel):
+    """
+    Pydantic model for adatom defect configurations used with create_multiple_adatom_defects.
+
+    Required fields:
+        element: Chemical element for the adatom
+        coordinate: Position on surface as [x, y] list
+        distance_z: Distance above surface in Angstroms
+
+    Optional fields:
+        use_cartesian_coordinates: Whether coordinates are in Cartesian units
+    """
+
+    element: str = Field(..., description="Chemical element for the adatom")
+    coordinate_2d: List[float] = Field(..., min_items=2, max_items=2, description="Position on surface as [x, y]")
+    distance_z: float = Field(..., gt=0, description="Distance above surface in Angstroms")
+    use_cartesian_coordinates: bool = False

package/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/helpers.py

@@ -1,4 +1,3 @@
-from types import SimpleNamespace
 from typing import List, Union
 
 from mat3ra.made.material import Material
@@ -7,6 +6,7 @@ from .interstitial.interstitial_placement_method_enum import InterstitialPlaceme
 from .point_defect_type_enum import PointDefectTypeEnum
 from .substitutional.helpers import create_defect_point_substitution
 from .substitutional.substitution_placement_method_enum import SubstitutionPlacementMethodEnum
+from .types import PointDefectDict
 from .vacancy.helpers import create_defect_point_vacancy
 from .vacancy.vacancy_placement_method_enum import VacancyPlacementMethodEnum
 from .....build_components import MaterialWithBuildMetadata
@@ -32,14 +32,14 @@ DEFECT_TYPE_MAPPING = {
 
 def create_multiple_defects(
     material: Union[Material, MaterialWithBuildMetadata],
-    defect_dicts: List[dict],
+    defect_dicts: List[PointDefectDict],
 ) -> Material:
     """
-    Create multiple point defects from a list of dictionaries.
+    Create multiple point defects from a list of PointDefectDict.
 
     Args:
         material (Material): The host material.
-        defect_dicts (List[dict]): List of defect dictionaries with keys:
+        defect_dicts (List[PointDefectDict]): List of defect dictionaries with keys:
             - type: str ("vacancy", "substitution", "interstitial")
             - coordinate: List[float]
             - element: str (required for substitution and interstitial)
@@ -56,39 +56,36 @@ def create_multiple_defects(
     current_material = material
 
     for defect_dict in defect_dicts:
-        defect_configuration = SimpleNamespace(**defect_dict)
-        defect_type = defect_configuration.type
+        defect_type = defect_dict.type
 
         if defect_type not in [e.value for e in PointDefectTypeEnum]:
-            raise ValueError(f"Unsupported defect type: {defect_configuration.type}")
+            raise ValueError(f"Unsupported defect type: {defect_dict.type}")
 
-        use_cartesian = getattr(defect_configuration, "use_cartesian_coordinates", False)
+        use_cartesian = getattr(defect_dict, "use_cartesian_coordinates", False)
 
         if defect_type == "vacancy":
             current_material = create_defect_point_vacancy(
                 current_material,
-                coordinate=defect_configuration.coordinate,
-                placement_method=defect_configuration.placement_method or VacancyPlacementMethodEnum.CLOSEST_SITE.value,
+                coordinate=defect_dict.coordinate,
+                placement_method=defect_dict.placement_method or VacancyPlacementMethodEnum.CLOSEST_SITE.value,
                 use_cartesian_coordinates=use_cartesian,
             )
 
         elif defect_type == "substitution":
             current_material = create_defect_point_substitution(
                 current_material,
-                coordinate=defect_configuration.coordinate,
-                element=defect_configuration.element,
-                placement_method=defect_configuration.placement_method
-                or SubstitutionPlacementMethodEnum.CLOSEST_SITE.value,
+                coordinate=defect_dict.coordinate,
+                element=defect_dict.element,  # type: ignore # Pydantic validates this at creation
+                placement_method=defect_dict.placement_method or SubstitutionPlacementMethodEnum.CLOSEST_SITE.value,
                 use_cartesian_coordinates=use_cartesian,
             )
 
         elif defect_type == "interstitial":
             current_material = create_defect_point_interstitial(
                 current_material,
-                coordinate=defect_configuration.coordinate,
-                element=defect_configuration.element,
-                placement_method=defect_configuration.placement_method
-                or InterstitialPlacementMethodEnum.EXACT_COORDINATE.value,
+                coordinate=defect_dict.coordinate,
+                element=defect_dict.element,  # type: ignore # Pydantic validates this at creation
+                placement_method=defect_dict.placement_method or InterstitialPlacementMethodEnum.EXACT_COORDINATE.value,
                 use_cartesian_coordinates=use_cartesian,
             )
 

package/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/types.py

@@ -0,0 +1,24 @@
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class PointDefectDict(BaseModel):
+    """
+    Pydantic model for point defect configurations used with create_multiple_defects.
+
+    Required fields:
+        type: The type of defect ("vacancy", "substitution", "interstitial")
+        coordinate: Position coordinates as [x, y, z] list
+
+    Optional fields:
+        element: Chemical element (required for substitution and interstitial)
+        placement_method: Method for placing the defect
+        use_cartesian_coordinates: Whether coordinates are in Cartesian units
+    """
+
+    type: Literal["vacancy", "substitution", "interstitial"]
+    coordinate: List[float] = Field(..., min_items=3, max_items=3, description="Position coordinates as [x, y, z]")
+    element: Optional[str] = None
+    placement_method: Optional[Literal["closest_site", "exact_coordinate", "voronoi_site"]] = None
+    use_cartesian_coordinates: bool = False

package/src/py/mat3ra/made/tools/build/pristine_structures/two_dimensional/nanoribbon/__init__.py

@@ -3,7 +3,7 @@ from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lin
     CrystalLatticeLinesConfiguration,
 )
 from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines.edge_types import (
-    EdgeTypes,
+    EdgeTypesEnum,
 )
 from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines_unique_repeated import (
     CrystalLatticeLinesRepeatedBuilder,
@@ -25,5 +25,5 @@ __all__ = [
     "CrystalLatticeLinesBuilder",
     "CrystalLatticeLinesRepeatedBuilder",
     "create_nanoribbon",
-    "EdgeTypes",
+    "EdgeTypesEnum",
 ]

package/src/py/mat3ra/made/tools/build/pristine_structures/two_dimensional/nanoribbon/helpers.py

@@ -10,7 +10,7 @@ from ..nanotape import NanoTapeConfiguration
 from .....build_components import MaterialWithBuildMetadata
 from .....build_components.entities.core.two_dimensional.vacuum.configuration import VacuumConfiguration
 from .....build_components.entities.reusable.base_builder import BaseBuilderParameters
-from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines.edge_types import EdgeTypes
+from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines.edge_types import EdgeTypesEnum
 from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines.helpers import (
     create_lattice_lines_config_and_material,
 )
@@ -21,7 +21,7 @@ P = TypeVar("P", bound=BaseBuilderParameters)
 def create_nanoribbon(
     material: Union[Material, MaterialWithBuildMetadata],
     miller_indices_2d: Optional[Tuple[int, int]] = None,
-    edge_type: EdgeTypes = EdgeTypes.zigzag,
+    edge_type: EdgeTypesEnum = EdgeTypesEnum.zigzag,
     width: int = 2,
     length: int = 2,
     vacuum_width: float = 10.0,

package/src/py/mat3ra/made/tools/build/pristine_structures/two_dimensional/nanotape/builders.py

@@ -5,7 +5,7 @@ from mat3ra.made.material import Material
 from . import NanoTapeBuilderParameters
 from .configuration import NanoTapeConfiguration
 from .....build_components import MaterialWithBuildMetadata, TypeConfiguration
-from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines.edge_types import EdgeTypes
+from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines.edge_types import EdgeTypesEnum
 from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines_unique_repeated.builder import (
     CrystalLatticeLinesRepeatedBuilder,
 )
@@ -44,9 +44,9 @@ class NanoTapeBuilder(StackNComponentsBuilder):
 
     def _get_edge_type_from_miller_indices(self, miller_indices_2d: tuple) -> str:
         if miller_indices_2d == (1, 1):
-            return EdgeTypes.armchair.value.capitalize()
+            return EdgeTypesEnum.armchair.value.capitalize()
         elif miller_indices_2d == (0, 1):
-            return EdgeTypes.zigzag.value.capitalize()
+            return EdgeTypesEnum.zigzag.value.capitalize()
         else:
             miller_str = f"{miller_indices_2d[0]}{miller_indices_2d[1]}"
             return f"({miller_str})"

package/src/py/mat3ra/made/tools/build/pristine_structures/two_dimensional/nanotape/helpers.py

@@ -7,7 +7,7 @@ from . import NanoTapeConfiguration
 from .builders import NanoTapeBuilder, NanoTapeBuilderParameters
 from .....build_components import MaterialWithBuildMetadata
 from .....build_components.entities.core.two_dimensional.vacuum.configuration import VacuumConfiguration
-from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines.edge_types import EdgeTypes
+from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines.edge_types import EdgeTypesEnum
 from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lines.helpers import (
     create_lattice_lines_config_and_material,
 )
@@ -16,7 +16,7 @@ from .....build_components.entities.reusable.one_dimensional.crystal_lattice_lin
 def create_nanotape(
     material: Union[Material, MaterialWithBuildMetadata],
     miller_indices_2d: Optional[Tuple[int, int]] = None,
-    edge_type: EdgeTypes = EdgeTypes.zigzag,
+    edge_type: EdgeTypesEnum = EdgeTypesEnum.zigzag,
     width: int = 2,
     length: int = 2,
     vacuum_width: float = 10.0,

package/src/py/mat3ra/made/tools/build/pristine_structures/two_dimensional/slab/builder.py

@@ -2,6 +2,7 @@ from typing import Type, cast
 
 from .build_parameters import SlabBuilderParameters
 from .configuration import SlabConfiguration
+from .utils import get_orthogonal_c_slab
 from .....build_components import MaterialWithBuildMetadata
 from .....build_components.entities.reusable.two_dimensional import (
     AtomicLayersUniqueRepeatedConfiguration,
@@ -9,7 +10,6 @@ from .....build_components.entities.reusable.two_dimensional import (
 )
 
 from .....build_components.operations.core.combinations.stack.builder import StackNComponentsBuilder
-from .....build_components.utils import get_orthogonal_c_slab
 from .....operations.core.unary import supercell
 
 

package/src/py/mat3ra/made/tools/build/pristine_structures/two_dimensional/slab/configuration.py

@@ -3,13 +3,13 @@ from typing import List, Optional, Tuple, Union
 from mat3ra.esse.models.core.reusable.axis_enum import AxisEnum
 from mat3ra.esse.models.materials_category.pristine_structures.two_dimensional.slab import SlabConfigurationSchema
 from mat3ra.made.material import Material
+from .termination_utils import select_slab_termination
 
 from .....analyze.lattice_planes import CrystalLatticePlanesMaterialAnalyzer
 from .....build_components.entities.reusable.two_dimensional.atomic_layers_unique_repeated.configuration import (
     AtomicLayersUniqueRepeatedConfiguration,
 )
 from .....build_components.metadata import MaterialWithBuildMetadata
-from .....build_components import select_slab_termination
 from .....build_components.operations.core.combinations.stack.configuration import StackConfiguration
 from .....build_components.entities.core.two_dimensional.vacuum.configuration import VacuumConfiguration
 from .....build_components.entities.auxiliary.two_dimensional.termination import Termination

package/src/py/mat3ra/made/tools/build/pristine_structures/two_dimensional/slab/utils.py

@@ -1,14 +1,26 @@
-from typing import Union
+from typing import Union, Optional, List
 
 import numpy as np
 
 from mat3ra.made.lattice import Lattice
 from mat3ra.made.material import Material
 from .....build_components import MaterialWithBuildMetadata
+from .....build_components.entities.auxiliary.two_dimensional.termination import Termination
 from .....modify import wrap_to_unit_cell
 from .....operations.core.unary import edit_cell
 
 
+def select_slab_termination(terminations: List[Termination], formula: Optional[str] = None) -> Termination:
+    if not terminations:
+        raise ValueError("No terminations available.")
+    if formula is None:
+        return terminations[0]
+    for termination in terminations:
+        if termination.formula == formula:
+            return termination
+    raise ValueError(f"Termination with formula {formula} not found in available terminations: {terminations}")
+
+
 def get_orthogonal_c_slab(material: Union[Material, MaterialWithBuildMetadata]) -> Material:
     """
     Make the c-vector orthogonal to the ab plane and update the basis.

package/src/py/mat3ra/made/tools/build_components/__init__.py

@@ -8,4 +8,3 @@ from mat3ra.made.tools.build_components.entities.reusable.base_builder import (
 )
 
 from .metadata import BuildMetadata, MaterialBuildMetadata, MaterialWithBuildMetadata
-from .utils import get_orthogonal_c_slab, select_slab_termination

package/src/py/mat3ra/made/tools/build_components/entities/reusable/one_dimensional/crystal_lattice_lines/builder.py

@@ -4,10 +4,10 @@ from mat3ra.made.material import Material
 from mat3ra.made.tools.build_components.entities.reusable.base_builder import BaseSingleBuilder, TypeConfiguration
 
 from ......analyze.lattice_lines import CrystalLatticeLinesMaterialAnalyzer
+from ......build.pristine_structures.two_dimensional.slab.utils import get_orthogonal_c_slab
 from ......modify import translate_to_z_level
 from ......operations.core.unary import supercell
 from ..... import MaterialWithBuildMetadata
-from .....utils import get_orthogonal_c_slab
 from .configuration import CrystalLatticeLinesConfiguration
 
 

package/src/py/mat3ra/made/tools/build_components/entities/reusable/one_dimensional/crystal_lattice_lines/edge_types.py

@@ -2,7 +2,7 @@ from enum import Enum
 from typing import Tuple
 
 
-class EdgeTypes(str, Enum):
+class EdgeTypesEnum(str, Enum):
     """
     Enum for nanoribbon/nanotape edge types.
     """
@@ -11,7 +11,7 @@ class EdgeTypes(str, Enum):
     armchair = "armchair"
 
 
-def get_miller_indices_from_edge_type(edge_type: EdgeTypes) -> Tuple[int, int]:
+def get_miller_indices_from_edge_type(edge_type: EdgeTypesEnum) -> Tuple[int, int]:
     """
     Convert edge type shorthand to (u,v) Miller indices.
 
@@ -21,9 +21,9 @@ def get_miller_indices_from_edge_type(edge_type: EdgeTypes) -> Tuple[int, int]:
     Returns:
         Tuple of (u,v) Miller indices.
     """
-    if edge_type == EdgeTypes.zigzag:
+    if edge_type == EdgeTypesEnum.zigzag:
         return (1, 1)
-    elif edge_type == EdgeTypes.armchair:
+    elif edge_type == EdgeTypesEnum.armchair:
         return (0, 1)
     else:
         raise ValueError(f"Unknown edge type: {edge_type}. Use 'zigzag' or 'armchair'.")

package/src/py/mat3ra/made/tools/build_components/entities/reusable/one_dimensional/crystal_lattice_lines/helpers.py

@@ -3,16 +3,16 @@ from typing import Optional, Tuple, Union
 from mat3ra.made.material import Material
 
 from ......analyze.lattice_lines import CrystalLatticeLinesMaterialAnalyzer
+from ......build.pristine_structures.two_dimensional.slab.termination_utils import select_slab_termination
 from ..... import MaterialWithBuildMetadata
-from .....utils import select_slab_termination
 from ..crystal_lattice_lines_unique_repeated.configuration import CrystalLatticeLinesUniqueRepeatedConfiguration
-from .edge_types import EdgeTypes, get_miller_indices_from_edge_type
+from .edge_types import EdgeTypesEnum, get_miller_indices_from_edge_type
 
 
 def create_lattice_lines_config_and_material(
     material: Union[Material, MaterialWithBuildMetadata],
     miller_indices_2d: Optional[Tuple[int, int]],
-    edge_type: Optional[EdgeTypes],
+    edge_type: Optional[EdgeTypesEnum],
     width: int,
     length: int,
     termination_formula: Optional[str] = None,

package/src/py/mat3ra/made/tools/build_components/operations/core/combinations/stack/configuration.py

@@ -15,7 +15,6 @@ class StackConfiguration(StackSchema, BaseConfigurationPydantic):
     direction: AxisEnum = AxisEnum.z
 
     def __init__(self, **data):
-        # Convert gaps to ArrayWithIds if not already
         gaps = data.get("gaps", [])
         if not isinstance(gaps, ArrayWithIds):
             data["gaps"] = ArrayWithIds.from_values(gaps)

package/src/py/mat3ra/made/tools/build_components/utils.py

@@ -1,67 +1,12 @@
-from typing import List, Optional, Union
+from typing import List, Union
 
-import numpy as np
-from mat3ra.made.lattice import Lattice
 from mat3ra.made.material import Material
 
-from ..modify import filter_by_box, wrap_to_unit_cell
-from ..operations.core.unary import edit_cell
+from ..modify import filter_by_box
 from . import MaterialWithBuildMetadata
-from .entities.auxiliary.two_dimensional.termination import Termination
 from .entities.reusable.three_dimensional.supercell.helpers import create_supercell
 
 
-def select_slab_termination(terminations: List[Termination], formula: Optional[str] = None) -> Termination:
-    if not terminations:
-        raise ValueError("No terminations available.")
-    if formula is None:
-        return terminations[0]
-    for termination in terminations:
-        if termination.formula == formula:
-            return termination
-    raise ValueError(f"Termination with formula {formula} not found in available terminations: {terminations}")
-
-
-def get_orthogonal_c_slab(material: Union[Material, MaterialWithBuildMetadata]) -> Material:
-    """
-    Make the c-vector orthogonal to the ab plane and update the basis.
-
-    This function calculates a new c-vector that is orthogonal to the a and b vectors
-    of the lattice. It then computes the transformation matrix between the old and new
-    lattice vectors and applies this transformation to the atomic coordinates.
-
-    A new material is returned with an updated lattice and basis, where the new
-    lattice is defined by its parameters (a, b, c, alpha, beta, gamma) to avoid
-    storing raw vectors, preserving a standard representation.
-
-    Args:
-        material (Material): The input material object.
-
-    Returns:
-        Material: A new material object with an orthogonalized c-vector and
-                  updated basis.
-    """
-    new_material = material.clone()
-    current_vectors = np.array(new_material.lattice.vector_arrays)
-    a_vec, b_vec, c_old_vec = current_vectors
-
-    normal = np.cross(a_vec, b_vec)
-    n_hat = normal / np.linalg.norm(normal)
-    height = float(np.dot(c_old_vec, n_hat))
-    c_new_vec = n_hat * height
-
-    new_vectors = np.array([a_vec, b_vec, c_new_vec])
-    transform_matrix = np.dot(current_vectors, np.linalg.inv(new_vectors))
-
-    new_basis = new_material.basis.clone()
-    new_basis.transform_by_matrix(transform_matrix)
-    new_lattice_from_vectors = Lattice.from_vectors_array(new_vectors.tolist())
-    new_material = edit_cell(new_material, new_lattice_from_vectors.vector_arrays)
-    new_material.basis = new_basis
-    new_material = wrap_to_unit_cell(new_material)
-    return new_material
-
-
 def double_and_filter_material(
     material: Union[Material, MaterialWithBuildMetadata], start: List[float], end: List[float]
 ) -> Material:

package/src/py/mat3ra/made/tools/entities/coordinate/box_coordinate_condition.py

@@ -1,12 +1,13 @@
 from typing import List
 
+from mat3ra.esse.models.core.reusable.coordinate_conditions import BoxCoordinateConditionSchema
 from pydantic import Field
 
 from .coordinate_condition import CoordinateCondition
 from .coordinate_functions import is_coordinate_in_box
 
 
-class BoxCoordinateCondition(CoordinateCondition):
+class BoxCoordinateCondition(BoxCoordinateConditionSchema, CoordinateCondition):
     min_coordinate: List[float] = Field(default_factory=lambda: [0, 0, 0])
     max_coordinate: List[float] = Field(default_factory=lambda: [1, 1, 1])
 

package/src/py/mat3ra/made/tools/entities/coordinate/cylinder_coordinate_condition.py

@@ -1,12 +1,13 @@
 from typing import List
 
+from mat3ra.esse.models.core.reusable.coordinate_conditions import CylinderCoordinateConditionSchema
 from pydantic import Field
 
 from .coordinate_condition import CoordinateCondition
 from .coordinate_functions import is_coordinate_in_cylinder
 
 
-class CylinderCoordinateCondition(CoordinateCondition):
+class CylinderCoordinateCondition(CylinderCoordinateConditionSchema, CoordinateCondition):
     center_position: List[float] = Field(default_factory=lambda: [0.5, 0.5])
     radius: float = 0.25
     min_z: float = 0

package/src/py/mat3ra/made/tools/entities/coordinate/plane_coordinate_condition.py

@@ -1,10 +1,12 @@
 from typing import List
 
+from mat3ra.esse.models.core.reusable.coordinate_conditions import PlaneCoordinateConditionSchema
+
 from .coordinate_condition import CoordinateCondition
 from .coordinate_functions import is_coordinate_behind_plane
 
 
-class PlaneCoordinateCondition(CoordinateCondition):
+class PlaneCoordinateCondition(PlaneCoordinateConditionSchema, CoordinateCondition):
     plane_normal: List[float]
     plane_point_coordinate: List[float]
 

package/src/py/mat3ra/made/tools/entities/coordinate/sphere_coordinate_condition.py

@@ -1,12 +1,13 @@
 from typing import List
 
+from mat3ra.esse.models.core.reusable.coordinate_conditions import SphereCoordinateConditionSchema
 from pydantic import Field
 
 from .coordinate_condition import CoordinateCondition
 from .coordinate_functions import is_coordinate_in_sphere
 
 
-class SphereCoordinateCondition(CoordinateCondition):
+class SphereCoordinateCondition(SphereCoordinateConditionSchema, CoordinateCondition):
     center_coordinate: List[float] = Field(default_factory=lambda: [0.5, 0.5, 0.5])
     radius: float = 0.25
 

package/src/py/mat3ra/made/tools/entities/coordinate/triangular_prism_coordinate_condition.py

@@ -1,10 +1,12 @@
 from typing import List
 
+from mat3ra.esse.models.core.reusable.coordinate_conditions import TriangularPrismCoordinateConditionSchema
+
 from .coordinate_condition import CoordinateCondition
 from .coordinate_functions import is_coordinate_in_triangular_prism
 
 
-class TriangularPrismCoordinateCondition(CoordinateCondition):
+class TriangularPrismCoordinateCondition(TriangularPrismCoordinateConditionSchema, CoordinateCondition):
     position_on_surface_1: List[float] = [0, 0]
     position_on_surface_2: List[float] = [1, 0]
     position_on_surface_3: List[float] = [0, 1]

package/src/py/mat3ra/made/tools/helpers.py

@@ -1,3 +1,7 @@
+# Defective Structures
+from .build.compound_pristine_structures.two_dimensional.heterostructure import create_heterostructure
+from .build.compound_pristine_structures.two_dimensional.heterostructure.types import StackComponentDict
+
 # Compound Pristine Structures
 from .build.compound_pristine_structures.two_dimensional.interface.base.helpers import (
     create_interface_simple,
@@ -21,6 +25,7 @@ from .build.defective_structures.two_dimensional.adatom.helpers import (
     create_multiple_adatom_defects,
     get_adatom_defect_analyzer_cls,
 )
+from .build.defective_structures.two_dimensional.adatom.types import AdatomDefectDict
 from .build.defective_structures.two_dimensional.grain_boundary_planar.helpers import create_grain_boundary_planar
 from .build.defective_structures.two_dimensional.island.helpers import create_defect_island, get_coordinate_condition
 from .build.defective_structures.two_dimensional.terrace.helpers import create_defect_terrace
@@ -32,6 +37,7 @@ from .build.defective_structures.zero_dimensional.point_defect.interstitial.help
 from .build.defective_structures.zero_dimensional.point_defect.substitutional.helpers import (
     create_defect_point_substitution,
 )
+from .build.defective_structures.zero_dimensional.point_defect.types import PointDefectDict
 from .build.defective_structures.zero_dimensional.point_defect.vacancy.helpers import create_defect_point_vacancy
 
 # Pristine Structures
@@ -51,6 +57,9 @@ from .build.pristine_structures.zero_dimensional.nanoparticle.helpers import (
     create_nanoparticle_from_material,
 )
 
+# Enums
+from .build.processed_structures.two_dimensional.passivation.enums import SurfaceTypesEnum
+
 # Processed Structures
 from .build.processed_structures.two_dimensional.passivation.helpers import (
     get_coordination_numbers_distribution,
@@ -58,6 +67,7 @@ from .build.processed_structures.two_dimensional.passivation.helpers import (
     passivate_dangling_bonds,
     passivate_surface,
 )
+from .build_components.entities.reusable.one_dimensional.crystal_lattice_lines.edge_types import EdgeTypesEnum
 from .build_components.entities.reusable.one_dimensional.crystal_lattice_lines.helpers import (
     create_lattice_lines_config_and_material,
 )
@@ -73,6 +83,9 @@ from .build_components.entities.reusable.two_dimensional.slab_stack.helpers impo
 )
 from .build_components.operations.core.modifications.perturb.helpers import create_perturbation
 
+# Entities
+from .entities.coordinate import CoordinateCondition
+
 __all__ = [
     # Slab and related Functions
     "create_slab",
@@ -84,6 +97,8 @@ __all__ = [
     "create_supercell",
     "create_monolayer",
     "create_perturbation",
+    # heterostructure Functions
+    "create_heterostructure",
     "create_lattice_lines_config_and_material",
     # Nanostructure Functions
     "create_nanoparticle_from_material",
@@ -125,6 +140,15 @@ __all__ = [
     "get_coordination_numbers_distribution",
     # Utility Functions
     "get_optimal_film_displacement",
+    # Type Definitions
+    "AdatomDefectDict",
+    "PointDefectDict",
+    "StackComponentDict",
+    # Entities
+    "CoordinateCondition",
+    # Enums
+    "EdgeTypesEnum",
+    "SurfaceTypesEnum",
 ]
 
 # Aliases

package/src/py/mat3ra/made/tools/modify.py

@@ -5,7 +5,7 @@ from mat3ra.made.material import Material
 from mat3ra.made.utils import get_atomic_coordinates_extremum
 
 from .analyze.other import get_atom_indices_with_condition_on_coordinates, get_atom_indices_within_radius_pbc
-from .build_components import MaterialWithBuildMetadata
+from .build_components.metadata import MaterialWithBuildMetadata
 from .convert import from_ase, to_ase
 from .convert.interface_parts_enum import InterfacePartsEnum
 from .entities.coordinate import (

package/src/py/mat3ra/made/tools/operations/core/unary.py

@@ -5,7 +5,7 @@ from mat3ra.code.vector import Vector3D
 from mat3ra.esse.models.core.abstract.matrix_3x3 import Matrix3x3Schema
 from mat3ra.made.material import Material
 
-from ...build_components import MaterialWithBuildMetadata
+from ...build_components.metadata import MaterialWithBuildMetadata
 from ...build_components.operations.core.modifications.perturb import FunctionHolder
 from ...convert import from_ase, to_ase
 from ...modify import translate_by_vector, wrap_to_unit_cell

package/tests/py/unit/fixtures/bulk.py

@@ -4,6 +4,11 @@ from mat3ra.standata.materials import Materials
 
 BULK_SrTiO3 = Materials.get_by_name_first_match("SrTiO3")
 BULK_GRAPHITE = Materials.get_by_name_first_match("Graphite")
+BULK_SiO2 = Materials.get_by_name_first_match("SiO2")
+BULK_Hf2O_MCL = Materials.get_by_name_first_match("Hafnium.*MCL")
+BULK_TiN = Materials.get_by_name_first_match("TiN")
+BULK_Ni_PRIMITIVE = Materials.get_by_name_first_match("Nickel")
+BULK_GRAPHENE = Materials.get_by_name_first_match("Graphene")
 
 BULK_Si_PRIMITIVE: Dict[str, Any] = {
     "name": "Silicon FCC",

package/tests/py/unit/test_tools_analyze_interface.py

@@ -6,7 +6,7 @@ import pytest
 from mat3ra.made.tools.analyze.interface import InterfaceAnalyzer
 from mat3ra.made.tools.analyze.interface.commensurate import CommensurateLatticeInterfaceAnalyzer
 from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab import SlabConfiguration
-from unit.fixtures.bulk import BULK_Ge_CONVENTIONAL, BULK_Si_CONVENTIONAL
+from unit.fixtures.bulk import BULK_GRAPHENE, BULK_Ge_CONVENTIONAL, BULK_Si_CONVENTIONAL
 
 from .fixtures.monolayer import GRAPHENE
 from .utils import assert_two_entities_deep_almost_equal
@@ -35,6 +35,25 @@ EXPECTED_PROPERTIES_SI_GE_001: Final = SimpleNamespace(
 TEST_CASES = [(SUBSTRATE_SI_001, FILM_GE_001, EXPECTED_PROPERTIES_SI_GE_001)]
 
 
+SUBSTRATE_SI_111: Final = SimpleNamespace(
+    bulk_config=BULK_Si_CONVENTIONAL,
+    miller_indices=(1, 1, 1),
+    number_of_layers=2,
+    vacuum=0.0,
+)
+
+FILM_GRAPHENE_001: Final = SimpleNamespace(
+    bulk_config=BULK_GRAPHENE,
+    miller_indices=(0, 0, 1),
+    number_of_layers=1,
+    vacuum=0.0,
+)
+
+OPTIMAL_SUPERCELL_TEST_CASES = [
+    (SUBSTRATE_SI_111, FILM_GRAPHENE_001, 4, 4),  # n, m
+]
+
+
 @pytest.mark.parametrize("substrate, film, expected", TEST_CASES)
 def test_interface_analyzer(substrate, film, expected):
     substrate_slab_config = SlabConfiguration.from_parameters(
@@ -143,3 +162,36 @@ def test_commensurate_analyzer_functionality(
         # Test negative match ID
         with pytest.raises(ValueError, match="Match ID .* out of range"):
             analyzer.get_strained_configuration_by_match_id(-1)
+
+
+@pytest.mark.parametrize("substrate, film, expected_n, expected_m", OPTIMAL_SUPERCELL_TEST_CASES)
+def test_optimal_supercell_functions(substrate, film, expected_n, expected_m):
+    """Test the optimal supercell functions with Si/Ge fixtures."""
+    substrate_slab_config = SlabConfiguration.from_parameters(
+        substrate.bulk_config,
+        substrate.miller_indices,
+        substrate.number_of_layers,
+        vacuum=substrate.vacuum,
+        termination_top_formula=None,
+        termination_bottom_formula=None,
+    )
+    film_slab_config = SlabConfiguration.from_parameters(
+        film.bulk_config,
+        film.miller_indices,
+        film.number_of_layers,
+        vacuum=film.vacuum,
+        termination_top_formula=None,
+        termination_bottom_formula=None,
+    )
+
+    analyzer = InterfaceAnalyzer(
+        substrate_slab_configuration=substrate_slab_config,
+        film_slab_configuration=film_slab_config,
+        optimize_film_supercell=True,
+    )
+
+    # Test find_optimal_film_supercell
+    optimal_n, optimal_m = analyzer.find_optimal_film_supercell()
+
+    assert optimal_n == expected_n
+    assert optimal_m == expected_m

package/tests/py/unit/test_tools_analyze_interface_zsl.py

@@ -9,9 +9,8 @@ from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab_strained_s
     SlabStrainedSupercellBuilder,
 )
 from mat3ra.made.tools.utils import supercell_matrix_2d_schema_to_list, unwrap
-from mat3ra.standata.materials import Materials
 from mat3ra.utils.matrix import convert_2x2_to_3x3
-from unit.fixtures.bulk import BULK_Ge_CONVENTIONAL, BULK_Si_CONVENTIONAL
+from unit.fixtures.bulk import BULK_Ge_CONVENTIONAL, BULK_Ni_PRIMITIVE, BULK_Si_CONVENTIONAL
 
 from .fixtures.monolayer import GRAPHENE
 from .utils import OSPlatform, get_platform_specific_value
@@ -49,7 +48,7 @@ EXPECTED_PROPERTIES_SI_GE_001: Final = SimpleNamespace(
         ),
         (
             SimpleNamespace(
-                bulk_config=Materials.get_by_name_first_match("Nickel"),
+                bulk_config=BULK_Ni_PRIMITIVE,
                 miller_indices=(0, 0, 1),
                 number_of_layers=2,
                 vacuum=0.0,
@@ -123,7 +122,7 @@ def test_zsl_interface_analyzer(substrate, film, zsl_params, expected_matches_mi
     [
         (
             SimpleNamespace(
-                bulk_config=Materials.get_by_name_first_match("Nickel"),
+                bulk_config=BULK_Ni_PRIMITIVE,
                 miller_indices=(1, 1, 1),
                 number_of_layers=3,
                 vacuum=0.0,

package/tests/py/unit/test_tools_build_defect/test_adatom.py

@@ -5,6 +5,7 @@ from mat3ra.made.tools.build.defective_structures.two_dimensional.adatom.helpers
     create_defect_adatom,
     create_multiple_adatom_defects,
 )
+from mat3ra.made.tools.build.defective_structures.two_dimensional.adatom.types import AdatomDefectDict
 from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab.helpers import create_slab
 from mat3ra.made.tools.build_components.operations.core.combinations.enums import AdatomPlacementMethodEnum
 from mat3ra.utils import assertion as assertion_utils
@@ -61,9 +62,9 @@ def test_create_adatom(
         (
             SI_CONVENTIONAL_SLAB_001,
             [
-                {"element": "Si", "coordinate": [0.5, 0.5], "distance_z": 2.0},
-                {"element": "C", "coordinate": [0.25, 0.25], "distance_z": 1.5},
-                {"element": "N", "coordinate": [0.75, 0.75], "distance_z": 1.0},
+                {"element": "Si", "coordinate_2d": [0.5, 0.5], "distance_z": 2.0},
+                {"element": "C", "coordinate_2d": [0.25, 0.25], "distance_z": 1.5},
+                {"element": "N", "coordinate_2d": [0.75, 0.75], "distance_z": 1.0},
             ],
             AdatomPlacementMethodEnum.EXACT_COORDINATE.value,
             SLAB_Si_3_ADATOMS,
@@ -72,6 +73,12 @@ def test_create_adatom(
 )
 def test_create_multiple_adatom_defects(crystal_config, adatom_dicts, placement_method, expected_material_config):
     slab = MaterialWithBuildMetadata.create(crystal_config)
-    defects = create_multiple_adatom_defects(slab, adatom_dicts, placement_method)
+
+    defect_models = []
+    for adatom_data in adatom_dicts:
+        defect_dict = AdatomDefectDict(**adatom_data)
+        defect_models.append(defect_dict)
+
+    defects = create_multiple_adatom_defects(slab, defect_models, placement_method)
     defects.metadata.build = []
     assert_two_entities_deep_almost_equal(defects, expected_material_config)

package/tests/py/unit/test_tools_build_defect/test_point_defect.py

@@ -14,6 +14,7 @@ from mat3ra.made.tools.build.defective_structures.zero_dimensional.point_defect.
     create_defect_point_vacancy,
     create_multiple_defects,
 )
+from mat3ra.made.tools.build.defective_structures.zero_dimensional.point_defect.types import PointDefectDict
 from unit.fixtures.bulk import BULK_Si_CONVENTIONAL, BULK_Si_PRIMITIVE
 from unit.fixtures.point_defects import (
     INTERSTITIAL_DEFECT_BULK_PRIMITIVE_Si,
@@ -123,13 +124,15 @@ def test_create_multiple_defects(material_config, defect_params_list, expected_m
 
     defect_dicts = []
     for defect_params in defect_params_list:
-        defect_dict = {
+        defect_data = {
             "type": defect_params.defect_type,
             "coordinate": defect_params.coordinate,
             "placement_method": defect_params.placement_method if hasattr(defect_params, "placement_method") else None,
             "element": defect_params.element if hasattr(defect_params, "element") else None,
         }
 
+        defect_dict = PointDefectDict(**defect_data)
+
         defect_dicts.append(defect_dict)
 
     defects = create_multiple_defects(

package/tests/py/unit/test_tools_build_heterostructure.py

@@ -0,0 +1,48 @@
+from types import SimpleNamespace
+
+import pytest
+from mat3ra.made.material import Material
+from mat3ra.made.tools.helpers import StackComponentDict, create_heterostructure
+
+from .fixtures.bulk import BULK_Hf2O_MCL, BULK_Si_CONVENTIONAL, BULK_SiO2, BULK_TiN
+
+PRECISION = 1e-3
+
+Si_SiO2_Hf2O_HETEROSTRUCTURE_TEST_CASE = (
+    [
+        SimpleNamespace(bulk_config=BULK_Si_CONVENTIONAL, miller_indices=(0, 0, 1), number_of_layers=4),
+        SimpleNamespace(bulk_config=BULK_SiO2, miller_indices=(1, 1, 1), number_of_layers=5),
+        SimpleNamespace(bulk_config=BULK_Hf2O_MCL, miller_indices=(0, 0, 1), number_of_layers=2),
+        SimpleNamespace(bulk_config=BULK_TiN, miller_indices=(1, 1, 1), number_of_layers=5),
+    ],
+    [1.5, 1.0, 1.0],  # gaps
+    10.0,  # vacuum
+)
+
+
+@pytest.mark.parametrize("layers, gaps, vacuum", [Si_SiO2_Hf2O_HETEROSTRUCTURE_TEST_CASE])
+def test_create_heterostructure_simple(layers, gaps, vacuum):
+    # Convert raw test data to Pydantic models
+    stack_components = []
+    for layer in layers:
+        component_data = {
+            "crystal": Material.create(layer.bulk_config),
+            "miller_indices": layer.miller_indices,
+            "thickness": layer.number_of_layers,
+        }
+        component = StackComponentDict(**component_data)
+        stack_components.append(component)
+
+    heterostructure = create_heterostructure(
+        stack_component_dicts=stack_components,
+        gaps=gaps,
+        vacuum=vacuum,
+    )
+
+    assert isinstance(heterostructure, Material)
+    elements = set()
+    for layer in layers:
+        elements.update(Material.create(layer.bulk_config).basis.elements.values)
+    assert set(heterostructure.basis.elements.values) == elements
+
+    assert len(heterostructure.basis.elements.values) > 0

package/tests/py/unit/test_tools_build_interface.py

@@ -23,8 +23,7 @@ from mat3ra.made.tools.build.pristine_structures.two_dimensional.nanoribbon.help
 from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab import SlabBuilder, SlabConfiguration
 from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab.helpers import create_slab
 from mat3ra.made.tools.helpers import create_interface_simple, create_interface_simple_between_slabs
-from mat3ra.standata.materials import Materials
-from unit.fixtures.bulk import BULK_Ge_CONVENTIONAL, BULK_Si_CONVENTIONAL
+from unit.fixtures.bulk import BULK_Ge_CONVENTIONAL, BULK_Ni_PRIMITIVE, BULK_Si_CONVENTIONAL
 
 from .fixtures.interface.commensurate import INTERFACE_GRAPHENE_GRAPHENE_X, INTERFACE_GRAPHENE_GRAPHENE_Z
 from .fixtures.interface.gr_ni_111_top_hcp import (
@@ -55,7 +54,7 @@ Si_Ge_SIMPLE_INTERFACE_TEST_CASE = (
 
 GRAPHENE_NICKEL_TEST_CASE = (
     SimpleNamespace(
-        bulk_config=Materials.get_by_name_first_match("Nickel"),
+        bulk_config=BULK_Ni_PRIMITIVE,
         miller_indices=(1, 1, 1),
         number_of_layers=3,
         vacuum=0.0,

package/tests/py/unit/test_tools_build_interface_zsl.py

@@ -12,8 +12,8 @@ from mat3ra.made.tools.build.compound_pristine_structures.two_dimensional.interf
 )
 from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab import SlabBuilder, SlabConfiguration
 from mat3ra.made.tools.build_components.entities.core.two_dimensional.vacuum.configuration import VacuumConfiguration
-from mat3ra.standata.materials import Materials
 
+from .fixtures.bulk import BULK_Ni_PRIMITIVE
 from .fixtures.interface.gr_ni_111_top_hcp import (
     GRAPHENE_NICKEL_INTERFACE_TOP_HCP,
     GRAPHENE_NICKEL_INTERFACE_TOP_HCP_GH_WF,
@@ -23,7 +23,7 @@ from .utils import OSPlatform, assert_two_entities_deep_almost_equal, get_platfo
 
 GRAPHENE_NICKEL_TEST_CASE = (
     SimpleNamespace(
-        bulk_config=Materials.get_by_name_first_match("Nickel"),
+        bulk_config=BULK_Ni_PRIMITIVE,
         miller_indices=(1, 1, 1),
         number_of_layers=3,
         vacuum=0.0,