Merge pull request #244 from Exabyte-io/update/SOF-7650-1

VsevolodX · web-flow · commit 52abc6fa923b · 2025-08-07T15:51:52.000-07:00
Update/SOF0-7650-1 update: helper functions names
diff --git a/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/__init__.py b/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/__init__.py
@@ -2,21 +2,21 @@
     InterfaceConfiguration,
     InterfaceBuilder,
     InterfaceBuilderParameters,
-    create_simple_interface_between_slabs,
+    create_interface_simple_between_slabs,
 )
 from .commensurate import (
-    create_commensurate_interface,
+    create_interface_commensurate,
     get_commensurate_strained_configurations,
 )
 from .enums import StrainModes
 from .twisted import (
     TwistedNanoribbonsInterfaceConfiguration,
-    create_twisted_interface,
+    create_interface_twisted,
 )
 from .utils import get_optimal_film_displacement, get_slab, remove_duplicate_interfaces
 from .zsl import (
-    create_zsl_interface,
-    create_zsl_interface_between_slabs,
+    create_interface_zsl,
+    create_interface_zsl_between_slabs,
 )
 
 __all__ = [
@@ -25,16 +25,16 @@
     "InterfaceBuilder",
     "InterfaceBuilderParameters",
     # Simple interface
-    "create_simple_interface_between_slabs",
+    "create_interface_simple_between_slabs",
     # ZSL interface
-    "create_zsl_interface",
-    "create_zsl_interface_between_slabs",
+    "create_interface_zsl",
+    "create_interface_zsl_between_slabs",
     # Commensurate interface
-    "create_commensurate_interface",
+    "create_interface_commensurate",
     "get_commensurate_strained_configurations",
     # Twisted interface
     "TwistedNanoribbonsInterfaceConfiguration",
-    "create_twisted_interface",
+    "create_interface_twisted",
     # Utilities
     "get_optimal_film_displacement",
     "get_slab",
diff --git a/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/base/__init__.py b/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/base/__init__.py
@@ -1,11 +1,11 @@
 from .configuration import InterfaceConfiguration
 from .builder import InterfaceBuilder
 from .build_parameters import InterfaceBuilderParameters
-from .helpers import create_simple_interface_between_slabs
+from .helpers import create_interface_simple_between_slabs
 
 __all__ = [
     "InterfaceConfiguration",
     "InterfaceBuilder",
     "InterfaceBuilderParameters",
-    "create_simple_interface_between_slabs",
+    "create_interface_simple_between_slabs",
 ]
diff --git a/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/base/helpers.py b/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/base/helpers.py
@@ -1,4 +1,4 @@
-from typing import List, Optional
+from typing import List, Optional, Tuple, Union
 
 from mat3ra.code.array_with_ids import ArrayWithIds
 
@@ -8,11 +8,12 @@
 from .configuration import InterfaceConfiguration
 from ......analyze.interface import InterfaceAnalyzer
 from ......analyze.slab import SlabMaterialAnalyzer
+from ......build.pristine_structures.two_dimensional.slab.helpers import create_slab
 from ......build_components import MaterialWithBuildMetadata
 from ......build_components.entities.core.two_dimensional.vacuum.configuration import VacuumConfiguration
 
 
-def create_simple_interface_between_slabs(
+def create_interface_simple_between_slabs(
     substrate_slab: MaterialWithBuildMetadata,
     film_slab: MaterialWithBuildMetadata,
     gap: Optional[float] = None,
@@ -61,3 +62,73 @@ def create_simple_interface_between_slabs(
     )
     interface = builder.get_material(config)
     return interface
+
+
+def create_interface_simple(
+    substrate_crystal: Union[Material, MaterialWithBuildMetadata],
+    film_crystal: Union[Material, MaterialWithBuildMetadata],
+    substrate_miller_indices: Tuple[int, int, int] = (0, 0, 1),
+    film_miller_indices: Tuple[int, int, int] = (0, 0, 1),
+    substrate_number_of_layers: int = 1,
+    film_number_of_layers: int = 1,
+    substrate_termination_formula: Optional[str] = None,
+    film_termination_formula: Optional[str] = None,
+    substrate_xy_supercell_matrix: List[List[int]] = [[1, 0], [0, 1]],
+    film_xy_supercell_matrix: List[List[int]] = [[1, 0], [0, 1]],
+    gap: Optional[float] = None,
+    vacuum: float = 10.0,
+    xy_shift: List[float] = [0, 0],
+    use_conventional_cell: bool = True,
+    reduce_result_cell_to_primitive: bool = False,
+) -> Material:
+    """
+    Create an interface between two crystal materials by first creating slabs and then stacking them.
+    No strain matching is performed, the interface is created as a simple stack of two slabs.
+
+    Args:
+        substrate_crystal (Union[Material, MaterialWithBuildMetadata]): Substrate crystal material.
+        film_crystal (Union[Material, MaterialWithBuildMetadata]): Film crystal material.
+        substrate_miller_indices (Tuple[int, int, int]): Miller indices for the substrate slab surface.
+        film_miller_indices (Tuple[int, int, int]): Miller indices for the film slab surface.
+        substrate_number_of_layers (int): Number of atomic layers in the substrate slab.
+        film_number_of_layers (int): Number of atomic layers in the film slab.
+        substrate_termination_formula (Optional[str]): Formula of the termination for substrate slab.
+        film_termination_formula (Optional[str]): Formula of the termination for film slab.
+        substrate_xy_supercell_matrix (List[List[int]]): Supercell matrix for substrate slab xy plane.
+        film_xy_supercell_matrix (List[List[int]]): Supercell matrix for film slab xy plane.
+        gap (Optional[float]): Gap between the two materials, in Angstroms.
+        vacuum (float): Size of the vacuum layer in Angstroms.
+        xy_shift (List[float]): Shift in x and y directions, in Angstroms.
+        use_conventional_cell (bool): Whether to use conventional cell for crystals.
+        reduce_result_cell_to_primitive (bool): Whether to reduce result cell to primitive.
+
+    Returns:
+        Material: The interface material.
+    """
+    substrate_slab = create_slab(
+        crystal=substrate_crystal,
+        miller_indices=substrate_miller_indices,
+        number_of_layers=substrate_number_of_layers,
+        vacuum=0,
+        termination_formula=substrate_termination_formula,
+        xy_supercell_matrix=substrate_xy_supercell_matrix,
+        use_conventional_cell=use_conventional_cell,
+    )
+    film_slab = create_slab(
+        crystal=film_crystal,
+        miller_indices=film_miller_indices,
+        number_of_layers=film_number_of_layers,
+        vacuum=0,
+        termination_formula=film_termination_formula,
+        xy_supercell_matrix=film_xy_supercell_matrix,
+        use_conventional_cell=use_conventional_cell,
+    )
+
+    return create_interface_simple_between_slabs(
+        substrate_slab=substrate_slab,
+        film_slab=film_slab,
+        gap=gap,
+        vacuum=vacuum,
+        xy_shift=xy_shift,
+        reduce_result_cell_to_primitive=reduce_result_cell_to_primitive,
+    )
diff --git a/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/commensurate/__init__.py b/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/commensurate/__init__.py
@@ -1,6 +1,6 @@
-from .helpers import create_commensurate_interface, get_commensurate_strained_configurations
+from .helpers import create_interface_commensurate, get_commensurate_strained_configurations
 
 __all__ = [
-    "create_commensurate_interface",
+    "create_interface_commensurate",
     "get_commensurate_strained_configurations",
 ]
diff --git a/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/commensurate/helpers.py b/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/commensurate/helpers.py
@@ -80,7 +80,7 @@ def get_commensurate_strained_configurations(
     return [selected_config.substrate_configuration, selected_config.film_configuration], actual_angle
 
 
-def create_commensurate_interface(
+def create_interface_commensurate(
     material: Union[Material, MaterialWithBuildMetadata],
     target_angle: float = 0.0,
     angle_tolerance: float = 0.1,
diff --git a/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/twisted/__init__.py b/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/twisted/__init__.py
@@ -1,7 +1,7 @@
 from .configuration import TwistedNanoribbonsInterfaceConfiguration
-from .helpers import create_twisted_interface
+from .helpers import create_interface_twisted
 
 __all__ = [
     "TwistedNanoribbonsInterfaceConfiguration",
-    "create_twisted_interface",
+    "create_interface_twisted",
 ]
diff --git a/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/twisted/helpers.py b/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/twisted/helpers.py
@@ -11,7 +11,7 @@
 from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab.configuration import SlabConfiguration
 
 
-def create_twisted_interface(
+def create_interface_twisted(
     material1: Union[Material, MaterialWithBuildMetadata],
     material2: Union[Material, MaterialWithBuildMetadata],
     angle: float = 0.0,
diff --git a/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/zsl/__init__.py b/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/zsl/__init__.py
@@ -1,6 +1,6 @@
-from .helpers import create_zsl_interface, create_zsl_interface_between_slabs
+from .helpers import create_interface_zsl, create_interface_zsl_between_slabs
 
 __all__ = [
-    "create_zsl_interface",
-    "create_zsl_interface_between_slabs",
+    "create_interface_zsl",
+    "create_interface_zsl_between_slabs",
 ]
diff --git a/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/zsl/helpers.py b/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/zsl/helpers.py
@@ -16,7 +16,7 @@
 from ......build_components.entities.core.two_dimensional.vacuum.configuration import VacuumConfiguration
 
 
-def create_zsl_interface(
+def create_interface_zsl(
     substrate_crystal: Union[Material, MaterialWithBuildMetadata],
     film_crystal: Union[Material, MaterialWithBuildMetadata],
     substrate_miller_indices: Tuple[int, int, int] = (0, 0, 1),
@@ -58,7 +58,7 @@ def create_zsl_interface(
         use_conventional_cell=use_conventional_cell,
     )
 
-    return create_zsl_interface_between_slabs(
+    return create_interface_zsl_between_slabs(
         substrate_slab=substrate_slab,
         film_slab=film_slab,
         gap=gap,
@@ -74,7 +74,7 @@ def create_zsl_interface(
     )
 
 
-def create_zsl_interface_between_slabs(
+def create_interface_zsl_between_slabs(
     substrate_slab: MaterialWithBuildMetadata,
     film_slab: MaterialWithBuildMetadata,
     gap: Optional[float] = None,
diff --git a/src/py/mat3ra/made/tools/build/defective_structures/two_dimensional/adatom/helpers.py b/src/py/mat3ra/made/tools/build/defective_structures/two_dimensional/adatom/helpers.py
@@ -26,7 +26,7 @@ def get_adatom_defect_analyzer_cls(
         raise ValueError(f"Unsupported placement method: {placement_method}")
 
 
-def create_adatom_defect(
+def create_defect_adatom(
     slab: MaterialWithBuildMetadata,
     position_on_surface: List[float],
     distance_z: float = 1.0,
diff --git a/src/py/mat3ra/made/tools/build/defective_structures/two_dimensional/island/helpers.py b/src/py/mat3ra/made/tools/build/defective_structures/two_dimensional/island/helpers.py
@@ -25,7 +25,7 @@
 CoordinateConditionType = TypeVar("CoordinateConditionType", bound=CoordinateCondition)
 
 
-def create_island_defect(
+def create_defect_island(
     slab: MaterialWithBuildMetadata,
     condition: Union[
         CylinderCoordinateCondition,
diff --git a/src/py/mat3ra/made/tools/build/defective_structures/two_dimensional/terrace/helpers.py b/src/py/mat3ra/made/tools/build/defective_structures/two_dimensional/terrace/helpers.py
@@ -13,7 +13,7 @@
 from .....modify import filter_by_condition_on_coordinates
 
 
-def create_terrace(
+def create_defect_terrace(
     slab: MaterialWithBuildMetadata,
     cut_direction: Optional[List[int]] = None,
     pivot_coordinate: Optional[List[float]] = None,
diff --git a/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/pair_defect/helpers.py b/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/pair_defect/helpers.py
@@ -1,18 +1,20 @@
 from typing import List, Optional, Union
 
 from mat3ra.made.material import Material
-from ...build_components import MaterialWithBuildMetadata
 from .builder import PairDefectBuilder
 from .configuration import PairDefectConfiguration
-from ..point_defect_type_enum import PointDefectTypeEnum
-from ..vacancy_placement_method_enum import VacancyPlacementMethodEnum
-from ..substitution_placement_method_enum import SubstitutionPlacementMethodEnum
-from ..interstitial_placement_method_enum import InterstitialPlacementMethodEnum
-from ..atom_placement_method_enum import AtomPlacementMethodEnum
-from ..factories import create_defect_configuration
+from ..point_defect import (
+    PointDefectTypeEnum,
+    VacancyPlacementMethodEnum,
+    SubstitutionPlacementMethodEnum,
+    InterstitialPlacementMethodEnum,
+    AtomPlacementMethodEnum,
+    create_defect_configuration,
+)
+from .....build_components import MaterialWithBuildMetadata
 
 
-def create_pair_defect(
+def create_defect_pair(
     material: Union[Material, MaterialWithBuildMetadata],
     defect_type_1: Optional[PointDefectTypeEnum] = None,
     coordinate_1: Optional[List[float]] = None,
diff --git a/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/__init__.py b/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/__init__.py
@@ -5,14 +5,14 @@
 from .factories import PointDefectConfigurationFactory, create_defect_configuration, resolve_coordinate
 from .helpers import create_multiple_defects
 from .interstitial.configuration import InterstitialDefectConfiguration
-from .interstitial.helpers import create_point_defect_interstitial
+from .interstitial.helpers import create_defect_point_interstitial
 from .interstitial.interstitial_placement_method_enum import InterstitialPlacementMethodEnum
 from .point_defect_type_enum import PointDefectTypeEnum
 from .substitutional.configuration import SubstitutionalDefectConfiguration
-from .substitutional.helpers import create_point_defect_substitution
+from .substitutional.helpers import create_defect_point_substitution
 from .substitutional.substitution_placement_method_enum import SubstitutionPlacementMethodEnum
 from .vacancy.configuration import VacancyDefectConfiguration
-from .vacancy.helpers import create_point_defect_vacancy
+from .vacancy.helpers import create_defect_point_vacancy
 from .vacancy.vacancy_placement_method_enum import VacancyPlacementMethodEnum
 
 __all__ = [
@@ -34,7 +34,7 @@
     "create_defect_configuration",
     "resolve_coordinate",
     "create_multiple_defects",
-    "create_point_defect_interstitial",
-    "create_point_defect_substitution",
-    "create_point_defect_vacancy",
+    "create_defect_point_interstitial",
+    "create_defect_point_substitution",
+    "create_defect_point_vacancy",
 ]
diff --git a/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/helpers.py b/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/helpers.py
@@ -2,12 +2,12 @@
 from typing import List, Union
 
 from mat3ra.made.material import Material
-from .interstitial.helpers import create_point_defect_interstitial
+from .interstitial.helpers import create_defect_point_interstitial
 from .interstitial.interstitial_placement_method_enum import InterstitialPlacementMethodEnum
 from .point_defect_type_enum import PointDefectTypeEnum
-from .substitutional.helpers import create_point_defect_substitution
+from .substitutional.helpers import create_defect_point_substitution
 from .substitutional.substitution_placement_method_enum import SubstitutionPlacementMethodEnum
-from .vacancy.helpers import create_point_defect_vacancy
+from .vacancy.helpers import create_defect_point_vacancy
 from .vacancy.vacancy_placement_method_enum import VacancyPlacementMethodEnum
 from .....build_components import MaterialWithBuildMetadata
 
@@ -65,15 +65,15 @@ def create_multiple_defects(
         use_cartesian = getattr(defect_configuration, "use_cartesian_coordinates", False)
 
         if defect_type == "vacancy":
-            current_material = create_point_defect_vacancy(
+            current_material = create_defect_point_vacancy(
                 current_material,
                 coordinate=defect_configuration.coordinate,
                 placement_method=defect_configuration.placement_method or VacancyPlacementMethodEnum.CLOSEST_SITE.value,
                 use_cartesian_coordinates=use_cartesian,
             )
 
         elif defect_type == "substitution":
-            current_material = create_point_defect_substitution(
+            current_material = create_defect_point_substitution(
                 current_material,
                 coordinate=defect_configuration.coordinate,
                 element=defect_configuration.element,
@@ -83,7 +83,7 @@ def create_multiple_defects(
             )
 
         elif defect_type == "interstitial":
-            current_material = create_point_defect_interstitial(
+            current_material = create_defect_point_interstitial(
                 current_material,
                 coordinate=defect_configuration.coordinate,
                 element=defect_configuration.element,
diff --git a/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/interstitial/helpers.py b/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/interstitial/helpers.py
@@ -9,7 +9,7 @@
 from ......build_components import MaterialWithBuildMetadata
 
 
-def create_point_defect_interstitial(
+def create_defect_point_interstitial(
     material: Union[Material, MaterialWithBuildMetadata],
     coordinate: List[float],
     element: str,
diff --git a/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/substitutional/helpers.py b/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/substitutional/helpers.py
@@ -8,7 +8,7 @@
 from ......build_components import MaterialWithBuildMetadata
 
 
-def create_point_defect_substitution(
+def create_defect_point_substitution(
     material: Union[Material, MaterialWithBuildMetadata],
     coordinate: List[float],
     element: str,
diff --git a/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/vacancy/helpers.py b/src/py/mat3ra/made/tools/build/defective_structures/zero_dimensional/point_defect/vacancy/helpers.py
@@ -10,7 +10,7 @@
 from ......build_components import MaterialWithBuildMetadata
 
 
-def create_point_defect_vacancy(
+def create_defect_point_vacancy(
     material: Union[Material, MaterialWithBuildMetadata],
     coordinate: List[float],
     placement_method: str,
diff --git a/src/py/mat3ra/made/tools/helpers.py b/src/py/mat3ra/made/tools/helpers.py
diff --git a/tests/py/unit/test_tools_build_defect/test_adatom.py b/tests/py/unit/test_tools_build_defect/test_adatom.py
diff --git a/tests/py/unit/test_tools_build_defect/test_island.py b/tests/py/unit/test_tools_build_defect/test_island.py
diff --git a/tests/py/unit/test_tools_build_defect/test_point_defect.py b/tests/py/unit/test_tools_build_defect/test_point_defect.py
diff --git a/tests/py/unit/test_tools_build_defect/test_terrace.py b/tests/py/unit/test_tools_build_defect/test_terrace.py
diff --git a/tests/py/unit/test_tools_build_interface.py b/tests/py/unit/test_tools_build_interface.py
diff --git a/tests/py/unit/test_tools_build_interface_zsl.py b/tests/py/unit/test_tools_build_interface_zsl.py

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`		`-from .helpers import create_commensurate_interface, get_commensurate_strained_configurations`
	`1`	`+from .helpers import create_interface_commensurate, get_commensurate_strained_configurations`
`2`	`2`
`3`	`3`	`__all__ = [`
`4`		`- "create_commensurate_interface",`
	`4`	`+ "create_interface_commensurate",`
`5`	`5`	`"get_commensurate_strained_configurations",`
`6`	`6`	`]`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`from .configuration import TwistedNanoribbonsInterfaceConfiguration`
`2`		`-from .helpers import create_twisted_interface`
	`2`	`+from .helpers import create_interface_twisted`
`3`	`3`
`4`	`4`	`__all__ = [`
`5`	`5`	`"TwistedNanoribbonsInterfaceConfiguration",`
`6`		`- "create_twisted_interface",`
	`6`	`+ "create_interface_twisted",`
`7`	`7`	`]`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`		`-from .helpers import create_zsl_interface, create_zsl_interface_between_slabs`
	`1`	`+from .helpers import create_interface_zsl, create_interface_zsl_between_slabs`
`2`	`2`
`3`	`3`	`__all__ = [`
`4`		`- "create_zsl_interface",`
`5`		`- "create_zsl_interface_between_slabs",`
	`4`	`+ "create_interface_zsl",`
	`5`	`+ "create_interface_zsl_between_slabs",`
`6`	`6`	`]`