@mat3ra/made 2026.8.7-0 → 2026.8.18-0

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

@@ -1,80 +0,0 @@
-from typing import List, Tuple
-
-from mat3ra.code.entity import InMemoryEntityPydantic
-from mat3ra.esse.models.core.abstract.matrix_3x3 import Matrix3x3Schema
-from mat3ra.esse.models.materials_category_components.entities.auxiliary.two_dimensional.supercell_matrix_2d import (
-    SupercellMatrix2DSchema,
-)
-from mat3ra.made.material import Material
-from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab.configuration import SlabConfiguration
-from pydantic import model_validator
-
-from .utils.holders import MatchedSubstrateFilmConfigurationHolder
-from .zsl import ZSLInterfaceAnalyzer
-
-
-class GrainBoundaryPlanarMatchHolder(InMemoryEntityPydantic):
-    match_id: int
-    substrate_transformation_matrix: SupercellMatrix2DSchema
-    film_transformation_matrix: SupercellMatrix2DSchema
-    match_area: float
-    strain_transformation_matrix: Matrix3x3Schema
-    total_strain_percentage: float
-
-
-class GrainBoundaryPlanarAnalyzer(ZSLInterfaceAnalyzer):
-    """
-    Analyzer for creating grain boundaries between two orientations of the same material.
-
-    Uses ZSL to find matching supercells between two phases with different
-    orientations, then stacks them in x/y direction to create a grain boundary configuration.
-    """
-
-    phase_1_material: Material
-    phase_2_material: Material
-    phase_1_miller_indices: Tuple[int, int, int]
-    phase_2_miller_indices: Tuple[int, int, int]
-    phase_1_thickness: int = 1
-    phase_2_thickness: int = 1
-
-    @model_validator(mode="before")
-    @classmethod
-    def _setup_slab_configurations(cls, values):
-        # we need to create slab configurations for both phases for InterfaceAnalyzer to use
-        values["substrate_slab_configuration"] = SlabConfiguration.from_parameters(
-            material_or_dict=values["phase_1_material"],
-            miller_indices=values["phase_1_miller_indices"],
-            number_of_layers=values.get("phase_1_thickness", 1),
-            vacuum=0.0,
-        )
-        values["film_slab_configuration"] = SlabConfiguration.from_parameters(
-            material_or_dict=values["phase_2_material"],
-            miller_indices=values["phase_2_miller_indices"],
-            number_of_layers=values.get("phase_2_thickness", 1),
-            vacuum=0.0,
-        )
-        return values
-
-    @property
-    def grain_boundary_match_holders(self) -> List[GrainBoundaryPlanarMatchHolder]:
-        zsl_matches = self.zsl_match_holders
-        match_holders = []
-
-        for idx, zsl_match in enumerate(zsl_matches):
-            match_holder = GrainBoundaryPlanarMatchHolder(
-                match_id=idx,
-                substrate_transformation_matrix=zsl_match.substrate_supercell_matrix,
-                film_transformation_matrix=zsl_match.film_supercell_matrix,
-                match_area=zsl_match.match_area,
-                strain_transformation_matrix=zsl_match.strain_transformation_matrix,
-                total_strain_percentage=zsl_match.total_strain_percentage,
-            )
-            match_holders.append(match_holder)
-
-        return match_holders
-
-    def get_grain_boundary_configuration_by_match_id(self, match_id: int) -> MatchedSubstrateFilmConfigurationHolder:
-        return self.get_strained_configuration_by_match_id(match_id)
-
-    def get_grain_boundary_configurations(self) -> List[MatchedSubstrateFilmConfigurationHolder]:
-        return self.get_strained_configurations()

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

@@ -1,251 +0,0 @@
-from functools import cached_property
-from typing import Optional, Tuple
-
-import numpy as np
-from mat3ra.code.entity import InMemoryEntityPydantic
-from mat3ra.esse.models.core.abstract.matrix_3x3 import Matrix3x3Schema
-from mat3ra.esse.models.materials_category_components.entities.auxiliary.two_dimensional.supercell_matrix_2d import (
-    SupercellMatrix2DSchema,
-)
-from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab.build_parameters import SlabBuilderParameters
-from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab.builder import SlabBuilder
-from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab.configuration import SlabConfiguration
-
-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):
-    """
-    Analyzes the interface between two slabs, calculating strain matrices and strained configurations.
-    This class is used to prepare the configurations for the substrate and film materials, ensuring that the film
-    material's lattice vectors match the substrate material's lattice vectors.
-
-    `substrate_strained_configuration` and `film_strained_configuration` properties provide the strained configurations.
-    """
-
-    substrate_slab_configuration: SlabConfiguration
-    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)
-
-    @cached_property
-    def substrate_material(self):
-        return self.get_component_material(self.substrate_slab_configuration)
-
-    @cached_property
-    def film_material(self):
-        return self.get_component_material(self.film_slab_configuration)
-
-    @property
-    def identity_supercell(self) -> SupercellMatrix2DSchema:
-        return SupercellMatrix2DSchema(root=[[1, 0], [0, 1]])
-
-    @property
-    def _no_strain_matrix(self) -> Matrix3x3Schema:
-        return Matrix3x3Schema(root=np.eye(3).tolist())
-
-    def get_film_strain_matrix(
-        self,
-        substrate_lattice_vector_arrays: np.ndarray,
-        film_lattice_vector_arrays: np.ndarray,
-    ) -> Matrix3x3Schema:
-        """Calculate film strain to match substrate using ZSL approach.
-
-        This function calculates the 2D strain matrix needed to transform the film
-        lattice vectors to match the substrate lattice vectors.
-
-        Args:
-            substrate_lattice_vector_arrays: 3x3 array of substrate lattice vectors
-            film_lattice_vector_arrays: 3x3 array of film lattice vectors
-
-        Returns:
-            2x2 strain matrix that transforms film vectors to substrate vectors
-        """
-        substrate_vectors = np.array(substrate_lattice_vector_arrays)
-        film_vectors = np.array(film_lattice_vector_arrays)
-
-        substrate_2d_vectors = substrate_vectors[:2, :2]
-        film_2d_vectors = film_vectors[:2, :2]
-
-        try:
-            strain_2d = np.linalg.solve(film_2d_vectors, substrate_2d_vectors)
-        except np.linalg.LinAlgError:
-            raise ValueError("Film lattice vectors are not linearly independent.")
-
-        strain_3d = np.eye(3)
-        strain_3d[:2, :2] = strain_2d
-        return Matrix3x3Schema(root=strain_3d.tolist())
-
-    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,
-        strain_matrix: Matrix3x3Schema,
-        xy_supercell_matrix: SupercellMatrix2DSchema = None,
-    ) -> SlabStrainedSupercellConfiguration:
-        if xy_supercell_matrix is not None:
-            matrix_list = [[item.root[0], item.root[1]] for item in xy_supercell_matrix.root]
-        else:
-            matrix_list = [[1, 0], [0, 1]]
-
-        return SlabStrainedSupercellConfiguration(
-            stack_components=configuration.stack_components,
-            direction=configuration.direction,
-            strain_matrix=strain_matrix,
-            xy_supercell_matrix=matrix_list,
-        )
-
-    def create_matched_configuration_holder(
-        self,
-        substrate_slab_config: SlabConfiguration,
-        film_slab_config: SlabConfiguration,
-        match_id: int = 0,
-        substrate_xy_supercell_matrix: SupercellMatrix2DSchema = None,
-        film_xy_supercell_matrix: SupercellMatrix2DSchema = None,
-        substrate_strain_matrix: Matrix3x3Schema = None,
-        film_strain_matrix: Matrix3x3Schema = None,
-        total_strain_percentage: Optional[float] = None,
-    ) -> MatchedSubstrateFilmConfigurationHolder:
-        if substrate_strain_matrix is None:
-            substrate_strain_matrix = self._no_strain_matrix
-        if film_strain_matrix is None:
-            film_strain_matrix = self._no_strain_matrix
-
-        substrate_config = self.get_component_strained_configuration(
-            substrate_slab_config,
-            substrate_strain_matrix,
-            xy_supercell_matrix=substrate_xy_supercell_matrix,
-        )
-
-        film_config = self.get_component_strained_configuration(
-            film_slab_config, film_strain_matrix, xy_supercell_matrix=film_xy_supercell_matrix
-        )
-
-        return MatchedSubstrateFilmConfigurationHolder(
-            match_id=match_id,
-            substrate_configuration=substrate_config,
-            film_configuration=film_config,
-            total_strain_percentage=total_strain_percentage,
-        )
-
-    @property
-    def substrate_supercell_matrix(self) -> SupercellMatrix2DSchema:
-        if self.substrate_build_parameters and self.substrate_build_parameters.xy_supercell_matrix:
-            return SupercellMatrix2DSchema(root=self.substrate_build_parameters.xy_supercell_matrix)
-        return self.identity_supercell
-
-    @property
-    def film_supercell_matrix(self) -> SupercellMatrix2DSchema:
-        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
-
-    @cached_property
-    def substrate_strained_configuration(self) -> SlabStrainedSupercellConfiguration:
-        return self.get_component_strained_configuration(
-            self.substrate_slab_configuration,
-            self._no_strain_matrix,
-            xy_supercell_matrix=self.substrate_supercell_matrix,
-        )
-
-    @cached_property
-    def film_strained_configuration(self) -> SlabStrainedSupercellConfiguration:
-        return self.get_component_strained_configuration(
-            self.film_slab_configuration,
-            self.get_film_strain_matrix(
-                self.substrate_material.lattice.vector_arrays, self.film_material.lattice.vector_arrays
-            ),
-            xy_supercell_matrix=self.film_supercell_matrix,
-        )

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

@@ -1,91 +0,0 @@
-from typing import Tuple
-
-from mat3ra.made.material import Material
-from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab.configuration import SlabConfiguration
-
-from ...modify import translate_to_center
-from ...operations.core.unary import rotate
-from ..other import get_surface_area
-from . import InterfaceAnalyzer
-from .utils.holders import MatchedSubstrateFilmConfigurationHolder
-
-
-class TwistedNanoribbonsInterfaceAnalyzer(InterfaceAnalyzer):
-    """
-    Analyzer for creating twisted interfaces between two nanoribbons.
-
-    Takes two nanoribbons (or any 0D materials) and returns them with:
-    - Same lattice vectors
-    - One rotated by the specified angle
-    - Nanoribbons centered
-    - Gap handled separately through vacuum configuration
-
-    Args:
-
-        angle (float): Twist angle in degrees.
-        vacuum_x (float): Vacuum along x on both sides, in Angstroms.
-        vacuum_y (float): Vacuum along y on both sides, in Angstroms.
-    """
-
-    angle: float = 0.0
-    vacuum_x: float = 5.0
-    vacuum_y: float = 5.0
-
-    @property
-    def nanoribbon1(self):
-        return self.substrate_slab_configuration.atomic_layers.crystal
-
-    @property
-    def nanoribbon2(self):
-        return self.film_slab_configuration.atomic_layers.crystal
-
-    def _create_default_slab_from_nanoribbon(self, nanoribbon: Material) -> SlabConfiguration:
-        return SlabConfiguration.from_parameters(
-            material_or_dict=nanoribbon,
-            miller_indices=(0, 0, 1),
-            number_of_layers=1,
-            vacuum=0.0,
-            use_conventional_cell=False,
-        )
-
-    def _match_lattice_vectors(self, material1: Material, material2: Material) -> Tuple[Material, Material]:
-        """
-        Matches the lattice vectors of two nanoribbons with vacuum on the sides to assume the size of the larger one.
-        Before stacking, two materials must have the same lattice vectors.
-        """
-        area1 = get_surface_area(material1)
-        area2 = get_surface_area(material2)
-
-        if area1 >= area2:
-            material1_matched = material1
-            material2_matched = material2.clone()
-            material2_matched.set_lattice(material1.lattice)
-        else:
-            material1_matched = material1.clone()
-            material1_matched.set_lattice(material2.lattice)
-            material2_matched = material2
-
-        return material1_matched, material2_matched
-
-    def get_strained_configuration(self) -> MatchedSubstrateFilmConfigurationHolder:
-        centered_nanoribbon1 = translate_to_center(self.nanoribbon1, axes=["x", "y"])
-        centered_nanoribbon2 = translate_to_center(self.nanoribbon2, axes=["x", "y"])
-
-        matched_nanoribbon1, matched_nanoribbon2 = self._match_lattice_vectors(
-            centered_nanoribbon1, centered_nanoribbon2
-        )
-
-        rotated_nanoribbon2 = rotate(matched_nanoribbon2, [0, 0, 1], self.angle, wrap=False)
-
-        substrate_slab_config = self._create_default_slab_from_nanoribbon(matched_nanoribbon1)
-        film_slab_config = self._create_default_slab_from_nanoribbon(rotated_nanoribbon2)
-
-        return self.create_matched_configuration_holder(substrate_slab_config, film_slab_config, match_id=0)
-
-    @property
-    def substrate_nanoribbon_configuration(self):
-        return self.get_strained_configuration().substrate_configuration
-
-    @property
-    def film_nanoribbon_configuration(self):
-        return self.get_strained_configuration().film_configuration

package/src/py/mat3ra/made/tools/analyze/interface/utils/__init__.py

@@ -1,77 +0,0 @@
-from typing import Union
-
-from mat3ra.made.material import Material
-
-from ....build.pristine_structures.two_dimensional.slab import SlabConfiguration
-from ....build_components.entities.reusable.three_dimensional.supercell.helpers import create_supercell
-from ...rdf import RadialDistributionFunction
-from .holders import MatchedSubstrateFilmConfigurationHolder
-
-
-def calculate_interfacial_distance_from_rdf(
-    substrate_material: Union[Material, dict, "SlabConfiguration"],
-    film_material: Union[Material, dict, "SlabConfiguration"],
-    rdf_cutoff: float = 10.0,
-    rdf_bin_size: float = 0.1,
-    supercell_size: tuple = (3, 3, 3),
-) -> float:
-    """
-    Calculate interfacial distance based on RDF analysis of bulk materials.
-
-    Creates temporary supercells of substrate and film bulk materials,
-    calculates their RDFs to find the first peak (nearest neighbor distance),
-    and returns the average of these distances as the initial guess for interfacial distance.
-
-    Args:
-        substrate_material: Material, dict, or SlabConfiguration for the substrate
-        film_material: Material, dict, or SlabConfiguration for the film
-        rdf_cutoff: Maximum distance for RDF calculation in Angstroms
-        rdf_bin_size: Bin size for RDF histogram in Angstroms
-        supercell_size: Size of supercell for RDF analysis (default: 3x3x3)
-
-    Returns:
-        float: Calculated interfacial distance in Angstroms
-    """
-
-    if isinstance(substrate_material, SlabConfiguration):
-        substrate_bulk = substrate_material.atomic_layers.crystal
-    elif isinstance(substrate_material, dict):
-        substrate_bulk = Material.create(substrate_material)
-    else:
-        substrate_bulk = substrate_material
-
-    if isinstance(film_material, SlabConfiguration):
-        film_bulk = film_material.atomic_layers.crystal
-    elif isinstance(film_material, dict):
-        film_bulk = Material.create(film_material)
-    else:
-        film_bulk = film_material
-
-    substrate_supercell = create_supercell(material=substrate_bulk, scaling_factor=list(supercell_size))
-
-    film_supercell = create_supercell(material=film_bulk, scaling_factor=list(supercell_size))
-
-    substrate_rdf = RadialDistributionFunction.from_material(
-        substrate_supercell,
-        cutoff=rdf_cutoff,
-        bin_size=rdf_bin_size,
-    )
-
-    film_rdf = RadialDistributionFunction.from_material(
-        film_supercell,
-        cutoff=rdf_cutoff,
-        bin_size=rdf_bin_size,
-    )
-
-    substrate_first_peak = substrate_rdf.first_peak_distance
-    film_first_peak = film_rdf.first_peak_distance
-
-    interfacial_distance = (substrate_first_peak + film_first_peak) / 2.0
-
-    return interfacial_distance
-
-
-__all__ = [
-    "MatchedSubstrateFilmConfigurationHolder",
-    "calculate_interfacial_distance_from_rdf",
-]

package/src/py/mat3ra/made/tools/analyze/interface/utils/holders.py

@@ -1,14 +0,0 @@
-from typing import Optional
-
-from mat3ra.code.entity import InMemoryEntityPydantic
-
-from ....build.pristine_structures.two_dimensional.slab_strained_supercell.configuration import (
-    SlabStrainedSupercellConfiguration,
-)
-
-
-class MatchedSubstrateFilmConfigurationHolder(InMemoryEntityPydantic):
-    match_id: int
-    substrate_configuration: SlabStrainedSupercellConfiguration
-    film_configuration: SlabStrainedSupercellConfiguration
-    total_strain_percentage: Optional[float] = None

package/src/py/mat3ra/made/tools/analyze/interface/utils/vector.py

@@ -1,56 +0,0 @@
-from functools import reduce
-from typing import List
-
-import numpy as np
-from mat3ra.esse.models.core.abstract.vector_2d import Vector2dSchema
-from mat3ra.esse.models.materials_category_components.entities.auxiliary.two_dimensional.supercell_matrix_2d import (
-    SupercellMatrix2DSchema,
-)
-
-
-def are_vectors_colinear(v1: Vector2dSchema, v2: Vector2dSchema, tol=1e-3):
-    v1 = np.array(v1)
-    v2 = np.array(v2)
-    norm1 = np.linalg.norm(v1)
-    norm2 = np.linalg.norm(v2)
-    if norm1 < tol or norm2 < tol:
-        return False
-    cos_angle = np.dot(v1, v2) / (norm1 * norm2)
-    # Colinear if |cos_angle| close to 1
-    return np.abs(np.abs(cos_angle) - 1) < tol
-
-
-def align_first_vector_to_x_2d_right_handed(vectors: List[Vector2dSchema]):
-    """
-    Rotates a set of 2D lattice vectors so that the first vector is aligned with the x-axis,
-    and makes the cell right-handed.
-    vectors: (2, 2) array
-    Returns: rotated (2, 2) array
-    """
-    vectors_np = np.array(vectors)
-    if vectors_np.shape != (2, 2):
-        raise ValueError("Input must be two 2D vectors (shape (2, 2)).")
-    v = vectors_np[0]
-    a = np.linalg.norm(v)
-    if a == 0:
-        raise ValueError("First lattice vector has zero length.")
-    # Angle to x-axis
-    angle = np.arctan2(v[1], v[0])
-    # 2D rotation matrix to align v with x-axis
-    R = np.array([[np.cos(-angle), -np.sin(-angle)], [np.sin(-angle), np.cos(-angle)]])
-    rotated_vectors = vectors_np @ R.T
-    # Set first vector to [a, 0]
-    rotated_vectors[0] = np.array([a, 0])
-
-    # Check handedness: z-component of cross product should be positive
-    cross_z = np.cross(rotated_vectors[0], rotated_vectors[1])
-    if cross_z < 0:
-        rotated_vectors[1] = -rotated_vectors[1]
-
-    return rotated_vectors
-
-
-def get_global_gcd(A: SupercellMatrix2DSchema, B: SupercellMatrix2DSchema) -> int:
-    # flatten all entries, compute gcd over them
-    vals = np.hstack((A.ravel(), B.ravel())).astype(int)
-    return reduce(np.gcd, vals.tolist())