@mat3ra/made 2026.5.21-1 → 2026.5.21-2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2026.5.21-1",
+    "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/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_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",
     [