@mat3ra/made 2026.5.7-0 → 2026.5.21-2

package/package.json

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

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

@@ -132,6 +132,7 @@ class Basis(BasisSchema, InMemoryEntityPydantic):
         coordinate: Optional[List[float]] = None,
         use_cartesian_coordinates: bool = False,
         force: bool = False,
+        label: Optional[Union[int, str]] = None,
     ):
         """
         Add an atom to the basis at a specified coordinate. Check that no other atom is overlapping with it.
@@ -141,6 +142,7 @@ class Basis(BasisSchema, InMemoryEntityPydantic):
             coordinate (List[float]): Coordinate of the atom to be added.
             use_cartesian_coordinates (bool): Whether the coordinate is in Cartesian units (or crystal by default).
             force (bool): Whether to force adding the atom even if it overlaps with another atom.
+            label (int|str|None): Per-atom label when the basis already uses labels; omit if the basis has none.
         """
         if coordinate is None:
             coordinate = [0, 0, 0]
@@ -162,6 +164,8 @@ class Basis(BasisSchema, InMemoryEntityPydantic):
                 return
         self.elements.add_item(element)
         self.coordinates.add_item(coordinate)
+        if label is not None:
+            self.labels.add_item(label)
 
     def add_atoms_from_another_basis(self, other_basis: "Basis"):
         """

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

@@ -4,6 +4,7 @@ from .simple import InterfaceAnalyzer
 from .twisted_nanoribbons import TwistedNanoribbonsInterfaceAnalyzer
 from .utils.holders import MatchedSubstrateFilmConfigurationHolder
 from .zsl import ZSLInterfaceAnalyzer, ZSLMatchHolder
+from .utils import calculate_interfacial_distance_from_rdf
 
 __all__ = [
     "InterfaceAnalyzer",
@@ -15,4 +16,5 @@ __all__ = [
     "GrainBoundaryPlanarMatchHolder",
     "TwistedNanoribbonsInterfaceAnalyzer",
     "MatchedSubstrateFilmConfigurationHolder",
+    "calculate_interfacial_distance_from_rdf",
 ]

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

@@ -1,5 +1,77 @@
+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/build/defective_structures/zero_dimensional/point_defect/substitutional/configuration.py

@@ -7,6 +7,7 @@ from mat3ra.esse.models.materials_category_components.entities.core.zero_dimensi
 from mat3ra.esse.models.materials_category_components.operations.core.combinations.merge import MergeMethodsEnum
 
 from mat3ra.made.material import Material
+from mat3ra.made.tools.analyze.other import get_closest_site_id_from_coordinate
 from ..base.configuration import PointDefectConfiguration
 from ......build_components import MaterialWithBuildMetadata
 from ......build_components.entities.auxiliary.zero_dimensional.point_defect_site.configuration import (
@@ -14,6 +15,16 @@ from ......build_components.entities.auxiliary.zero_dimensional.point_defect_sit
 )
 
 
+def _host_atom_label_at_coordinate(
+    crystal: Union[Material, MaterialWithBuildMetadata], coordinate: List[float]
+) -> Union[int, str, None]:
+    host_labels = crystal.basis.labels.values
+    if not host_labels:
+        return None
+    site_index = get_closest_site_id_from_coordinate(crystal, coordinate)
+    return host_labels[site_index]
+
+
 class SubstitutionalDefectConfiguration(PointDefectConfiguration, SubstitutionalPointDefectSchema):
     type: str = "SubstitutionalDefectConfiguration"
 
@@ -25,5 +36,6 @@ class SubstitutionalDefectConfiguration(PointDefectConfiguration, Substitutional
             crystal=crystal,
             element=AtomSchema(chemical_element=element),
             coordinate=coordinate,
+            host_atom_label=_host_atom_label_at_coordinate(crystal, coordinate),
         )
         return cls(merge_components=[crystal, substitution_site], merge_method=MergeMethodsEnum.REPLACE, **kwargs)

package/src/py/mat3ra/made/tools/build_components/entities/auxiliary/zero_dimensional/point_defect_site/builder.py

@@ -26,5 +26,6 @@ class PointDefectSiteBuilder(BaseSingleBuilder):
         new_material.basis.add_atom(
             element=configuration.element.chemical_element,
             coordinate=configuration.coordinate,
+            label=configuration.host_atom_label,
         )
         return new_material

package/src/py/mat3ra/made/tools/build_components/entities/auxiliary/zero_dimensional/point_defect_site/configuration.py

@@ -1,4 +1,4 @@
-from typing import Union
+from typing import Optional, Union
 
 from mat3ra.esse.models.materials_category.defective_structures.two_dimensional.adatom.configuration import (
     PointDefectSiteSchema,
@@ -11,3 +11,4 @@ from ..crystal_site import CrystalSite
 
 class PointDefectSiteConfiguration(CrystalSite, PointDefectSiteSchema):
     element: Union[VacancySchema, AtomSchema]
+    host_atom_label: Optional[Union[int, str]] = None

package/tests/py/unit/test_tools_analyze_interface.py

@@ -3,8 +3,10 @@ from typing import Final
 
 import numpy as np
 import pytest
+from mat3ra.made.material import Material
 from mat3ra.made.tools.analyze.interface import InterfaceAnalyzer
 from mat3ra.made.tools.analyze.interface.commensurate import CommensurateLatticeInterfaceAnalyzer
+from mat3ra.made.tools.analyze.interface.utils import calculate_interfacial_distance_from_rdf
 from mat3ra.made.tools.build.pristine_structures.two_dimensional.slab import SlabConfiguration
 from unit.fixtures.bulk import BULK_GRAPHENE, BULK_Ge_CONVENTIONAL, BULK_Si_CONVENTIONAL
 
@@ -195,3 +197,27 @@ def test_optimal_supercell_functions(substrate, film, expected_n, expected_m):
 
     assert optimal_n == expected_n
     assert optimal_m == expected_m
+
+
+@pytest.mark.parametrize(
+    "substrate_config, film_config, expected_distance_range",
+    [
+        (BULK_Si_CONVENTIONAL, BULK_Si_CONVENTIONAL, (3.8, 3.9)),
+        (BULK_Si_CONVENTIONAL, BULK_Ge_CONVENTIONAL, (3.1, 3.2)),
+    ],
+)
+def test_calculate_interfacial_distance_from_rdf(substrate_config, film_config, expected_distance_range):
+    """Test RDF-based interfacial distance calculation with different material types."""
+    substrate_material = Material.create(substrate_config)
+    film_material = Material.create(film_config)
+
+    distance = calculate_interfacial_distance_from_rdf(
+        substrate_material=substrate_material,
+        film_material=film_material,
+        rdf_cutoff=10.0,
+        rdf_bin_size=0.1,
+        supercell_size=(3, 3, 3),
+    )
+
+    assert isinstance(distance, float)
+    assert expected_distance_range[0] <= distance <= expected_distance_range[1]

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

@@ -16,6 +16,7 @@ from mat3ra.made.tools.build.defective_structures.zero_dimensional.point_defect.
 )
 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.interface.zsl import GRAPHENE_NICKEL_INTERFACE
 from unit.fixtures.point_defects import (
     INTERSTITIAL_DEFECT_BULK_PRIMITIVE_Si,
     INTERSTITIAL_VORONOI_DEFECT_BULK_PRIMITIVE_Si,
@@ -25,6 +26,19 @@ from unit.fixtures.point_defects import (
 )
 from unit.utils import assert_two_entities_deep_almost_equal, get_platform_specific_value
 
+FILM_LABEL = 1
+SUBSTRATE_LABEL = 0
+SUBSTITUTION_ELEMENT = "Ge"
+INTERFACE_SUBSTITUTION_PLACEMENT_METHOD = SubstitutionPlacementMethodEnum.CLOSEST_SITE.value
+
+
+def _film_atom_coordinate(material: Material) -> list:
+    labels_by_id = {entry["id"]: entry["value"] for entry in material.basis.labels.to_dict()}
+    for coordinate_entry in material.basis.coordinates.to_dict():
+        if labels_by_id.get(coordinate_entry["id"]) == FILM_LABEL:
+            return coordinate_entry["value"]
+    raise ValueError("No film atom found in fixture material")
+
 
 @pytest.mark.parametrize(
     "material_config, defect_params, expected_material_config",
@@ -91,6 +105,25 @@ def test_point_defect_helpers(material_config, defect_params, expected_material_
     assert_two_entities_deep_almost_equal(defect, expected_material_config)
 
 
+@pytest.mark.parametrize(
+    "expected_label_count, expected_unique_labels",
+    [(5, {SUBSTRATE_LABEL, FILM_LABEL})],
+)
+def test_create_defect_point_substitution_preserves_interface_labels(
+    expected_label_count, expected_unique_labels
+):
+    material = Material.create(GRAPHENE_NICKEL_INTERFACE)
+    coordinate = _film_atom_coordinate(material)
+
+    defect_material = create_defect_point_substitution(
+        material, coordinate, SUBSTITUTION_ELEMENT, INTERFACE_SUBSTITUTION_PLACEMENT_METHOD
+    )
+
+    assert len(defect_material.basis.elements.values) == expected_label_count
+    assert len(defect_material.basis.labels.values) == expected_label_count
+    assert set(defect_material.basis.labels.values) == expected_unique_labels
+
+
 @pytest.mark.parametrize(
     "material_config, defect_params_list, expected_material_config",
     [