@mat3ra/made 2025.7.15-0 → 2025.8.1-0

package/README.md

@@ -178,6 +178,13 @@ pip install ".[tests]"
 pytest tests/py
 ```
 
+To visualize material from a debugger, run the following command in the "Evaluate expression" console:
+
+```python
+from mat3ra.debug_utils import debug_visualize_material; debug_visualize_material(material)
+```
+
+
 #### 5.2.2. Important Notes
 
 Conventions:

package/dist/js/material.d.ts

@@ -1,8 +1,13 @@
-import { HasConsistencyChecksHasMetadataNamedDefaultableInMemoryEntity } from "@mat3ra/code/dist/js/entity";
 import type { ConsistencyCheck, MaterialSchema } from "@mat3ra/esse/dist/js/types";
 import { type MaterialMixinConstructor, defaultMaterialConfig } from "./materialMixin";
 export { defaultMaterialConfig };
-declare const BaseInMemoryEntity: typeof HasConsistencyChecksHasMetadataNamedDefaultableInMemoryEntity;
+declare const BaseInMemoryEntity: typeof import("@mat3ra/code/dist/js/entity").InMemoryEntity & import("@mat3ra/code/dist/js/entity/mixins/DefaultableMixin").DefaultableInMemoryEntityConstructor & {
+    createDefault<T extends import("@mat3ra/code/dist/js/utils/types").Constructor<import("@mat3ra/code/dist/js/entity").InMemoryEntity> & {
+        defaultConfig?: object | null | undefined;
+    }>(this: T): InstanceType<T> & {
+        isDefault: boolean;
+    };
+} & import("@mat3ra/code/dist/js/entity/mixins/NamedEntityMixin").NamedInMemoryEntityConstructor & import("@mat3ra/code/dist/js/entity/mixins/HasMetadataMixin").HasMetadataInMemoryEntityConstructor & import("@mat3ra/code/dist/js/entity/mixins/HasConsistencyChecksMixin").HasConsistencyChecksInMemoryEntityConstructor;
 type BaseMaterial = MaterialMixinConstructor & typeof BaseInMemoryEntity;
 type MaterialSchemaWithConsistencyChecksAsString = Omit<MaterialSchema, "consistencyChecks"> & {
     consistencyChecks?: ConsistencyCheck[];

package/package.json

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

package/pyproject.toml

@@ -19,8 +19,9 @@ dependencies = [
     # new verison of numpy==2.0.0 is not handled by pymatgen yet
     "numpy<=1.26.4",
     "mat3ra-utils",
-    "mat3ra-esse==2025.5.16post0",
-    "mat3ra-code==2025.4.27.post0",
+    "mat3ra-esse @ git+https://github.com/Exabyte-io/esse.git@090fe8b4271d449c8329f53b2a7da35ea9965062",
+    "mat3ra-code"
+
 ]
 
 [project.optional-dependencies]
@@ -47,6 +48,7 @@ tests = [
     "gradio",
     "pydantic",
     "mat3ra-made[tools]",
+    "mat3ra-standata"
 ]
 all = [
     "mat3ra-made[tests]",

package/src/py/mat3ra/made/basis/__init__.py

@@ -1,12 +1,33 @@
 from typing import Any, Dict, List, Optional, Union
 
+import numpy as np
 from mat3ra.code.array_with_ids import ArrayWithIds
 from mat3ra.code.entity import InMemoryEntityPydantic
+from mat3ra.esse.models.core.abstract.matrix_3x3 import Matrix3x3Schema
 from mat3ra.esse.models.material import BasisSchema, BasisUnitsEnum
 from mat3ra.made.basis.coordinates import Coordinates
 from mat3ra.made.cell import Cell
-from mat3ra.made.utils import get_overlapping_coordinates
 from pydantic import Field
+from scipy.spatial import cKDTree
+
+
+def get_overlapping_coordinates(
+    coordinate: List[float],
+    coordinates: List[List[float]],
+    threshold: float = 0.01,
+) -> List[List[float]]:
+    """
+    Find coordinates that are within a certain threshold of a given coordinate.
+
+    Args:
+        coordinate (List[float]): The coordinate.
+        coordinates (List[List[float]]): The list of coordinates.
+        threshold (float): The threshold for the distance, in the units of the coordinates.
+
+    Returns:
+        List[List[float]]: The list of overlapping coordinates.
+    """
+    return [c for c in coordinates if np.linalg.norm(np.array(c) - np.array(coordinate)) < threshold]
 
 
 class Basis(BasisSchema, InMemoryEntityPydantic):
@@ -15,6 +36,9 @@ class Basis(BasisSchema, InMemoryEntityPydantic):
     cell: Cell = Field(Cell(), exclude=True)
     labels: ArrayWithIds = Field(ArrayWithIds.from_values([]))
     constraints: ArrayWithIds = Field(ArrayWithIds.from_values([]))
+    DEFAULT_COORDINATE_PROXIMITY_TOLERANCE: float = Field(
+        0.1, exclude=True
+    )  # Angstroms, used for checking overlapping coordinates
 
     def __convert_kwargs__(self, **kwargs: Any) -> Dict[str, Any]:
         if isinstance(kwargs.get("elements"), list):
@@ -33,6 +57,17 @@ class Basis(BasisSchema, InMemoryEntityPydantic):
         kwargs = self.__convert_kwargs__(**kwargs)
         super().__init__(*args, **kwargs)
 
+    @property
+    def coordinates_as_kdtree(self):
+        return cKDTree(np.array(self.coordinates.values))
+
+    def get_coordinates_colliding_pairs(self, tolerance=DEFAULT_COORDINATE_PROXIMITY_TOLERANCE):
+        return self.coordinates_as_kdtree.query_pairs(r=tolerance)
+
+    @property
+    def number_of_atoms(self) -> int:
+        return len(self.elements.values)
+
     @classmethod
     def from_dict(
         cls,
@@ -80,9 +115,7 @@ class Basis(BasisSchema, InMemoryEntityPydantic):
         force: bool = False,
     ):
         """
-        Add an atom to the basis.
-
-        Before adding the atom at the specified coordinate, checks that no other atom is overlapping within a threshold.
+        Add an atom to the basis at a specified coordinate. Check that no other atom is overlapping with it.
 
         Args:
             element (str): Element symbol of the atom to be added.
@@ -128,15 +161,61 @@ class Basis(BasisSchema, InMemoryEntityPydantic):
         self.coordinates.remove_item(id)
         self.labels.remove_item(id)
 
-    def filter_atoms_by_ids(self, ids: Union[List[int], int], invert: bool = False) -> "Basis":
-        self.elements.filter_by_ids(ids, invert)
-        self.coordinates.filter_by_ids(ids, invert)
-        self.labels.filter_by_ids(ids, invert)
+    def remove_atoms_by_elements(self, values: Union[List[str], str]) -> "Basis":
+        if isinstance(values, str):
+            values = [values]
+        ids_to_remove = [
+            id_ for value in values for id_, v in zip(self.elements.ids, self.elements.values) if v == value
+        ]
+        self.filter_atoms_by_ids(ids_to_remove, invert=True)
+        return self
+
+    def filter_atoms_by_ids(self, ids: Union[List[int], int], invert: bool = False, reset_ids=False) -> "Basis":
+        self.elements.filter_by_ids(ids, invert, reset_ids=reset_ids)
+        self.coordinates.filter_by_ids(ids, invert, reset_ids=reset_ids)
+        self.labels.filter_by_ids(ids, invert, reset_ids=reset_ids)
         return self
 
     def filter_atoms_by_labels(self, labels: Union[List[str], str]) -> "Basis":
+        labels = [int(label) if isinstance(label, str) else label for label in labels]
         self.labels.filter_by_values(labels)
         ids = self.labels.ids
         self.elements.filter_by_ids(ids)
         self.coordinates.filter_by_ids(ids)
         return self
+
+    def set_labels_from_list(self, labels: List[Union[int, str]]) -> None:
+        num_atoms = len(self.elements.values)
+
+        if len(labels) != num_atoms:
+            raise ValueError(f"Number of labels ({len(labels)}) must match number of atoms ({num_atoms})")
+
+        self.labels = ArrayWithIds.from_values(values=list(labels))
+
+    def transform_by_matrix(self, matrix: Matrix3x3Schema) -> None:
+        original_is_in_crystal_units = self.is_in_crystal_units
+        self.to_crystal()
+        matrix_np = np.array(matrix)
+        new_coordinates = np.dot(self.coordinates.values, matrix_np)
+        self.coordinates.values = new_coordinates.tolist()
+        if not original_is_in_crystal_units:
+            self.to_cartesian()
+
+    # TODO: add/update test for this method
+    def resolve_colliding_coordinates(self, tolerance=DEFAULT_COORDINATE_PROXIMITY_TOLERANCE):
+        """
+        Find all atoms that are within distance tolerance and only keep the last one, remove other sites.
+
+        Args:
+            tolerance (float): The distance tolerance in angstroms.
+        """
+        original_is_in_crystal = self.is_in_crystal_units
+        self.to_cartesian()
+        ids_to_remove = set()
+        atom_ids = self.coordinates.ids
+        for index_1, index_2 in self.get_coordinates_colliding_pairs(tolerance):
+            ids_to_remove.add(atom_ids[index_1])  # Keep the last one in the pair
+
+        self.filter_atoms_by_ids(list(ids_to_remove), invert=True, reset_ids=True)
+        if original_is_in_crystal:
+            self.to_crystal()

package/src/py/mat3ra/made/lattice.py

@@ -3,14 +3,13 @@ from typing import List, Optional
 
 import numpy as np
 from mat3ra.code.entity import InMemoryEntityPydantic
-from mat3ra.esse.models.properties_directory.structural.lattice.lattice_bravais import (
-    LatticeImplicitSchema as LatticeBravaisSchema,
-)
-from mat3ra.esse.models.properties_directory.structural.lattice.lattice_bravais import (
+from mat3ra.esse.models.properties_directory.structural.lattice import (
+    LatticeSchema,
     LatticeTypeEnum,
     LatticeUnitsSchema,
 )
 from mat3ra.utils.mixins import RoundNumericValuesMixin
+from pydantic import BaseModel
 
 from .cell import Cell
 
@@ -21,10 +20,23 @@ class LatticeVectors(Cell):
     pass
 
 
-class Lattice(RoundNumericValuesMixin, LatticeBravaisSchema, InMemoryEntityPydantic):
+class LatticeSchemaVectorless(BaseModel):
+    """LatticeSchema without the vectors field to avoid conflicts."""
+
+    a: float
+    b: float
+    c: float
+    alpha: float
+    beta: float
+    gamma: float
+    units: LatticeUnitsSchema = LatticeSchema.model_fields["units"].default_factory()
+    type: LatticeTypeEnum = LatticeSchema.model_fields["type"].default
+
+
+class Lattice(RoundNumericValuesMixin, LatticeSchemaVectorless, InMemoryEntityPydantic):
     __types__ = LatticeTypeEnum
-    __type_default__ = LatticeBravaisSchema.model_fields["type"].default
-    __units_default__ = LatticeBravaisSchema.model_fields["units"].default_factory()
+    __type_default__ = LatticeSchema.model_fields["type"].default
+    __units_default__ = LatticeSchema.model_fields["units"].default_factory()
 
     a: float = 1.0
     b: float = a

package/src/py/mat3ra/made/material.py

@@ -1,4 +1,4 @@
-from typing import Any, List
+from typing import Any, List, Union
 
 from mat3ra.code.constants import AtomicCoordinateUnits, Units
 from mat3ra.code.entity import HasDescriptionHasMetadataNamedDefaultableInMemoryEntityPydantic
@@ -63,6 +63,12 @@ class Material(MaterialSchema, HasDescriptionHasMetadataNamedDefaultableInMemory
             self.name: str = self.formula
         self.basis.cell = self.lattice.vectors
 
+    @classmethod
+    def create_from_config_or_class_instance(cls, config_or_instance: Union[dict, "Material"]) -> "Material":
+        if isinstance(config_or_instance, cls):
+            return config_or_instance
+        return cls.create(config_or_instance)
+
     @property
     def coordinates_array(self) -> List[List[float]]:
         return self.basis.coordinates.values
@@ -76,7 +82,7 @@ class Material(MaterialSchema, HasDescriptionHasMetadataNamedDefaultableInMemory
     def set_coordinates(self, coordinates: List[List[float]]) -> None:
         self.basis.coordinates.values = coordinates
 
-    def set_new_lattice_vectors(
+    def set_lattice_vectors(
         self, lattice_vector1: List[float], lattice_vector2: List[float], lattice_vector3: List[float]
     ) -> None:
         original_is_in_crystal_units = self.basis.is_in_crystal_units
@@ -86,8 +92,19 @@ class Material(MaterialSchema, HasDescriptionHasMetadataNamedDefaultableInMemory
         if original_is_in_crystal_units:
             self.to_crystal()
 
+    def set_lattice_vectors_from_array(self, lattice_vectors: List[List[float]]) -> None:
+        if len(lattice_vectors) != 3:
+            raise ValueError("Lattice vectors array must contain exactly three vectors.")
+        self.set_lattice_vectors(*lattice_vectors)
+
     def set_lattice(self, lattice: Lattice) -> None:
-        self.set_new_lattice_vectors(*lattice.vector_arrays)
+        self.set_lattice_vectors(*lattice.vector_arrays)
 
     def add_atom(self, element: str, coordinate: List[float], use_cartesian_coordinates: bool = False) -> None:
         self.basis.add_atom(element, coordinate, use_cartesian_coordinates)
+
+    def set_labels_from_list(self, labels: List[Union[int, str]]) -> None:
+        self.basis.set_labels_from_list(labels)
+
+    def set_labels_from_value(self, value: Union[int, str]) -> None:
+        self.basis.set_labels_from_list([value] * self.basis.number_of_atoms)

package/src/py/mat3ra/made/metadata.py

@@ -0,0 +1,45 @@
+import json
+from typing import Any
+
+from mat3ra.code.entity import InMemoryEntityPydantic
+from pydantic import model_validator
+
+
+def to_dict(obj: Any) -> dict:
+    if isinstance(obj, dict):
+        return obj
+    if hasattr(obj, "to_dict") and callable(obj.to_dict):
+        return obj.to_dict()
+    # TODO: remove conditional checks below when all configurations moved to Pydantic
+    if hasattr(obj, "to_json") and callable(obj.to_json):
+        data = obj.to_json()
+        if isinstance(data, str):
+            return json.loads(data)
+        return data
+    return {}
+
+
+class BaseMetadata(InMemoryEntityPydantic):
+    model_config = {"arbitrary_types_allowed": True, "extra": "allow"}
+
+    @model_validator(mode="before")
+    def convert_fields_to_dict(cls, values):
+        for key, value in values.items():
+            field = cls.model_fields.get(key)
+            if field and field.annotation is dict and value is None:
+                values[key] = {}
+            elif field and field.annotation is dict and value is not None and not isinstance(value, dict):
+                values[key] = to_dict(value)
+            elif isinstance(value, InMemoryEntityPydantic):
+                values[key] = to_dict(value)
+            elif hasattr(value, "to_dict") and callable(value.to_dict):
+                values[key] = to_dict(value)
+            # TODO: remove when Pydantic configurations are fully implemented
+            elif hasattr(value, "to_json") and callable(value.to_json):
+                values[key] = to_dict(value)
+        return values
+
+    def update(self, **kwargs: Any):
+        for key, value in kwargs.items():
+            if hasattr(self, key) and isinstance(getattr(self, key), dict):
+                getattr(self, key).update(to_dict(value))

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

@@ -1,12 +1,17 @@
+from typing import Union
+
 import numpy as np
 from mat3ra.made.material import Material
+from pydantic import BaseModel
 from scipy.spatial.distance import pdist
 
+from ..build import MaterialWithBuildMetadata
+from .other import get_chemical_formula_empirical
+from .utils import decorator_perform_operation_in_cartesian_coordinates
+
 
-class BaseMaterialAnalyzer:
-    def __init__(self, material: Material):
-        self.material = material.clone()
-        self.material.to_cartesian()
+class BaseMaterialAnalyzer(BaseModel):
+    material: Union[Material, MaterialWithBuildMetadata]
 
     @property
     def volume(self):
@@ -17,5 +22,10 @@ class BaseMaterialAnalyzer:
         return len(self.material.coordinates_array) / self.volume
 
     @property
+    @decorator_perform_operation_in_cartesian_coordinates
     def pairwise_distances(self):
         return pdist(np.array(self.material.coordinates_array))
+
+    @property
+    def formula(self):
+        return get_chemical_formula_empirical(self.material)

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

@@ -0,0 +1,75 @@
+from typing import List
+
+from mat3ra.esse.models.materials_category_components.entities.core.zero_dimensional.atom import AtomSchema
+from mat3ra.made.material import Material
+from mat3ra.made.tools.analyze.crystal_site import CrystalSiteAnalyzer
+from mat3ra.made.tools.analyze.slab import SlabMaterialAnalyzer
+from mat3ra.made.tools.build import MaterialWithBuildMetadata
+from mat3ra.made.tools.build.defect.point.builders import AtomAtCoordinateBuilder, AtomAtCoordinateConfiguration
+from mat3ra.made.tools.build.defect.slab.helpers import recreate_slab_with_fractional_layers
+from mat3ra.made.tools.build.slab.builders import SlabBuilder
+from mat3ra.made.tools.build.vacuum.builders import VacuumBuilder
+from mat3ra.made.tools.build.vacuum.configuration import VacuumConfiguration
+
+
+class AdatomMaterialAnalyzer(SlabMaterialAnalyzer):
+    distance_z: float
+    coordinate_2d: List[float]  # Add coordinate property
+    element: str
+
+    @property
+    def added_component_height(self) -> float:
+        return self.layer_thickness
+
+    @property
+    def added_component_prototype(self) -> MaterialWithBuildMetadata:
+        vacuum_configuration = VacuumConfiguration(crystal=self.material, size=self.added_component_height)
+        vacuum_material = VacuumBuilder().get_material(vacuum_configuration)
+        return vacuum_material
+
+    @property
+    def coordinate_in_added_component(self) -> List[float]:
+        coordinate_3d = self.coordinate_2d + [0]
+        coordinate_3d_cartesian = self.material.basis.cell.convert_point_to_cartesian(coordinate_3d)
+        coordinate_3d_cartesian[2] = self.distance_z
+        coordinate_3d_crystal = self.added_component_prototype.basis.cell.convert_point_to_crystal(
+            coordinate_3d_cartesian
+        )
+        return coordinate_3d_crystal
+
+    @property
+    def added_component(self) -> MaterialWithBuildMetadata:
+        atom_configuration = AtomAtCoordinateConfiguration(
+            crystal=self.added_component_prototype,
+            element=AtomSchema(chemical_element=self.element),
+            coordinate=self.coordinate_in_added_component,
+        )
+        return AtomAtCoordinateBuilder().get_material(atom_configuration)
+
+    @property
+    def slab_material_or_configuration_for_stacking(self) -> MaterialWithBuildMetadata:
+        return self._slab_with_no_gap
+
+
+class AdatomCrystalSiteMaterialAnalyzer(AdatomMaterialAnalyzer):
+    DEFAULT_NUMBER_OF_LAYERS: float = 1
+
+    @property
+    def added_component_prototype(self) -> Material:
+        # Recreate the slab with a single layer to ensure the adatom is placed correctly
+        return recreate_slab_with_fractional_layers(self.material, self.DEFAULT_NUMBER_OF_LAYERS)
+
+    @property
+    def coordinate_in_added_component(self) -> List[float]:
+        approximate_coordinate_3d = super().coordinate_in_added_component
+        crystal_site_analyzer = CrystalSiteAnalyzer(
+            material=self.added_component_prototype,
+            coordinate=approximate_coordinate_3d,
+        )
+        return crystal_site_analyzer.closest_site_coordinate
+
+    @property
+    def slab_material_or_configuration_for_stacking(self) -> MaterialWithBuildMetadata:
+        config = self.slab_configuration_with_no_vacuum
+        params = self.build_parameters
+        return SlabBuilder(build_parameters=params).get_material(config)

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

@@ -0,0 +1,108 @@
+from typing import List
+
+from ...utils import get_center_of_coordinates
+from ..build.supercell import create_supercell
+from ..convert import to_pymatgen
+from ..modify import filter_by_condition_on_coordinates
+from ..third_party import PymatgenVoronoiInterstitialGenerator
+from ..utils import get_distance_between_coordinates, transform_coordinate_to_supercell
+from . import BaseMaterialAnalyzer
+from .coordination import get_voronoi_nearest_neighbors_atom_indices
+from .other import get_closest_site_id_from_coordinate
+
+
+class CrystalSiteAnalyzer(BaseMaterialAnalyzer):
+    coordinate: List[float] = [0.0, 0.0, 0.0]
+
+    @property
+    def exact_coordinate(self) -> List[float]:
+        return self.coordinate
+
+    @property
+    def closest_site_coordinate(self) -> List[float]:
+        site_id = get_closest_site_id_from_coordinate(self.material, self.coordinate)
+        return self.material.coordinates_array[site_id]
+
+    def get_equidistant_coordinate(self, coordinate=None) -> List[float]:
+        """
+        Compute a coordinate that is equidistant from the nearest atoms to the target coordinate. Useful for adatom.
+
+        This method works by:
+        1. Creating a 3x3x1 supercell of the original material to include atoms in PBC.
+        2. Transforming the target coordinate into the supercell's coordinate system.
+        3. Using Voronoi tessellation to find the indices of the nearest atoms in the supercell.
+        4. Taking the geometric center (average) of these neighboring atoms' coordinates as the equidistant point.
+        5. Setting the z-coordinate to the original value (useful for 2D/slab systems).
+        6. Transforming the equidistant coordinate back to the original cell's coordinate system.
+
+        The [3, 3, 1] supercell ensures robust neighbor search in x and y, but not in z (for 2D/slab systems).
+        """
+        if coordinate is None:
+            coordinate = self.coordinate
+        scaling_factor = [3, 3, 1]
+        translation_vector = [1 / 3, 1 / 3, 0]
+        supercell_material = create_supercell(self.material, scaling_factor=scaling_factor)
+
+        coordinate_in_supercell = transform_coordinate_to_supercell(
+            coordinate=coordinate, scaling_factor=scaling_factor, translation_vector=translation_vector
+        )
+
+        neighboring_atoms_ids_in_supercell = get_voronoi_nearest_neighbors_atom_indices(
+            material=supercell_material, coordinate=coordinate_in_supercell
+        )
+
+        if neighboring_atoms_ids_in_supercell is None:
+            raise ValueError("No neighboring atoms found for equidistant calculation.")
+
+        # Filter out atoms that are too close to the z boundaries of the supercell
+        supercell_material = filter_by_condition_on_coordinates(supercell_material, lambda c: 1e-2 < c[2] < 1 - 1e-2)
+        isolated_neighboring_atoms_basis = supercell_material.basis.model_copy()
+        isolated_neighboring_atoms_basis.coordinates.filter_by_ids(neighboring_atoms_ids_in_supercell)
+        equidistant_coordinate_in_supercell = get_center_of_coordinates(
+            isolated_neighboring_atoms_basis.coordinates.values
+        )
+
+        return transform_coordinate_to_supercell(
+            equidistant_coordinate_in_supercell, scaling_factor, translation_vector, reverse=True
+        )
+
+
+class VoronoiCrystalSiteAnalyzer(CrystalSiteAnalyzer):
+    """
+    Attributes:
+       clustering_tol: Tolerance for clustering the Voronoi nodes.
+       min_dist: Minimum distance between an interstitial and the nearest atom.
+       ltol: Tolerance for lattice matching.
+       stol: Tolerance for structure matching.
+       angle_tol: Angle tolerance for structure matching.
+    """
+
+    clustering_tol: float = 0.5
+    min_dist: float = 0.9
+    ltol: float = 0.2
+    stol: float = 0.3
+    angle_tol: float = 5
+
+    @property
+    def voronoi_site_coordinate(self) -> List[float]:
+        pymatgen_structure = to_pymatgen(self.material)
+
+        voronoi_gen = PymatgenVoronoiInterstitialGenerator(
+            clustering_tol=self.clustering_tol,
+            min_dist=self.min_dist,
+            ltol=self.ltol,
+            stol=self.stol,
+            angle_tol=self.angle_tol,
+        )
+
+        interstitials = list(voronoi_gen.generate(structure=pymatgen_structure, insert_species=["Si"]))
+
+        if not interstitials:
+            raise ValueError("No Voronoi interstitial sites found.")
+
+        closest_interstitial = min(
+            interstitials,
+            key=lambda interstitial: get_distance_between_coordinates(interstitial.site.frac_coords, self.coordinate),
+        )
+
+        return closest_interstitial.site.frac_coords.tolist()

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

@@ -0,0 +1,24 @@
+from mat3ra.made.tools.analyze.interface.commensurate import (
+    CommensurateLatticeInterfaceAnalyzer,
+    CommensurateLatticeMatchHolder,
+)
+from mat3ra.made.tools.analyze.interface.grain_boundary import (
+    GrainBoundaryPlanarAnalyzer,
+    GrainBoundaryPlanarMatchHolder,
+)
+from mat3ra.made.tools.analyze.interface.simple import InterfaceAnalyzer
+from mat3ra.made.tools.analyze.interface.twisted_nanoribbons import TwistedNanoribbonsInterfaceAnalyzer
+from mat3ra.made.tools.analyze.interface.utils.holders import MatchedSubstrateFilmConfigurationHolder
+from mat3ra.made.tools.analyze.interface.zsl import ZSLInterfaceAnalyzer, ZSLMatchHolder
+
+__all__ = [
+    "InterfaceAnalyzer",
+    "ZSLInterfaceAnalyzer",
+    "ZSLMatchHolder",
+    "CommensurateLatticeInterfaceAnalyzer",
+    "CommensurateLatticeMatchHolder",
+    "GrainBoundaryPlanarAnalyzer",
+    "GrainBoundaryPlanarMatchHolder",
+    "TwistedNanoribbonsInterfaceAnalyzer",
+    "MatchedSubstrateFilmConfigurationHolder",
+]