@mat3ra/made 2026.7.13-0 → 2026.7.18-0

package/package.json

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

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

@@ -16,6 +16,8 @@ class BuildMetadataAnalyzer(BaseMaterialAnalyzer, Generic[TypeConfiguration, Typ
 
     @property
     def build_metadata(self) -> BuildMetadata:
+        if not self.material.metadata.build:
+            raise ValueError("No metadata.build on the material.")
         metadata = self.material.metadata.get_build_metadata_of_type(self.configuration_cls.__name__)
         if not metadata:
             raise ValueError(f"Build metadata for {self.configuration_cls.__name__} not found.")

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

@@ -0,0 +1,31 @@
+from typing import Dict, Type
+
+from ..build_components.metadata import MaterialWithBuildMetadata
+from .build_metadata_analyzer import BuildMetadataAnalyzer
+from .interface_material import (
+    InterfaceMaterialAnalyzer,
+)
+from .slab import SlabMaterialAnalyzer
+
+BUILD_METADATA_ANALYZER_REGISTRY: Dict[str, Type[BuildMetadataAnalyzer]] = {
+    "SlabConfiguration": SlabMaterialAnalyzer,
+    "InterfaceConfiguration": InterfaceMaterialAnalyzer,
+}
+
+
+def create_build_metadata_analyzer(
+    material: MaterialWithBuildMetadata,
+    **analyzer_kwargs,
+) -> BuildMetadataAnalyzer:
+    build_metadata = material.metadata.get_latest_build_metadata()
+    configuration_type = build_metadata.configuration.get("type")
+    if not configuration_type:
+        raise ValueError("Latest build step has no configuration type.")
+    analyzer_cls = BUILD_METADATA_ANALYZER_REGISTRY.get(configuration_type)
+    if analyzer_cls is None:
+        registered_types = ", ".join(sorted(BUILD_METADATA_ANALYZER_REGISTRY))
+        raise ValueError(
+            f"No build metadata analyzer registered for '{configuration_type}'. "
+            f"Registered types: {registered_types}."
+        )
+    return analyzer_cls(material=material, **analyzer_kwargs)

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

@@ -0,0 +1,45 @@
+from typing import Type, Union
+
+from ..build.compound_pristine_structures.two_dimensional.interface.base.build_parameters import (
+    InterfaceBuilderParameters,
+)
+from ..build.compound_pristine_structures.two_dimensional.interface.base.configuration import InterfaceConfiguration
+from ..build.pristine_structures.two_dimensional.slab.configuration import SlabConfiguration
+from ..build.pristine_structures.two_dimensional.slab_strained_supercell.configuration import (
+    SlabStrainedSupercellConfiguration,
+)
+from ..build_components.metadata import MaterialWithBuildMetadata
+from ..convert.interface_parts_enum import INTERFACE_LABELS_MAP
+from .build_metadata_analyzer import BuildMetadataAnalyzer
+
+
+class InterfaceMaterialAnalyzer(
+    BuildMetadataAnalyzer[InterfaceConfiguration, InterfaceBuilderParameters],
+):
+    configuration_cls: Type[InterfaceConfiguration] = InterfaceConfiguration
+    build_parameters_cls: Type[InterfaceBuilderParameters] = InterfaceBuilderParameters
+
+    @property
+    def substrate_slab_configuration(self) -> Union[SlabStrainedSupercellConfiguration, SlabConfiguration]:
+        return self.build_configuration.substrate_configuration
+
+    @property
+    def film_slab_configuration(self) -> Union[SlabStrainedSupercellConfiguration, SlabConfiguration]:
+        return self.build_configuration.film_configuration
+
+    def get_bulk_crystal(self, part: str = "substrate") -> dict:
+        if part not in INTERFACE_LABELS_MAP:
+            raise ValueError(f"Unknown interface part '{part}'. Use 'substrate' or 'film'.")
+        slab_configuration = self.substrate_slab_configuration if part == "substrate" else self.film_slab_configuration
+        crystal = slab_configuration.atomic_layers.crystal
+        if crystal is None:
+            raise ValueError(f"No bulk crystal for {part} in interface build metadata.")
+        return crystal if isinstance(crystal, dict) else crystal.to_dict()
+
+
+def get_interface_configuration(interface: MaterialWithBuildMetadata) -> InterfaceConfiguration:
+    return InterfaceMaterialAnalyzer(material=interface).build_configuration
+
+
+def get_interface_bulk_crystal(interface: MaterialWithBuildMetadata, part: str = "substrate") -> dict:
+    return InterfaceMaterialAnalyzer(material=interface).get_bulk_crystal(part=part)

package/src/py/mat3ra/made/tools/build/compound_pristine_structures/two_dimensional/interface/__init__.py

@@ -13,7 +13,11 @@ from .twisted import (
     TwistedNanoribbonsInterfaceConfiguration,
     create_interface_twisted,
 )
-from .utils import get_optimal_film_displacement, get_slab, remove_duplicate_interfaces
+from .utils import (
+    get_optimal_film_displacement,
+    get_slab,
+    remove_duplicate_interfaces,
+)
 from .zsl import (
     create_interface_zsl,
     create_interface_zsl_between_slabs,

package/src/py/mat3ra/made/tools/build_components/metadata/material_build_metadata.py

@@ -10,6 +10,11 @@ class MaterialBuildMetadata(BaseMetadata):
     # Other metadata fields can be added as needed
     build: List[BuildMetadata] = Field([])
 
+    def get_latest_build_metadata(self) -> BuildMetadata:
+        if not self.build:
+            raise ValueError("No metadata.build on the material.")
+        return self.build[-1]
+
     def get_build_metadata_of_type(self, configuration_type: str) -> Optional[BuildMetadata]:
         """
         Returns the first build configuration of the specified type.

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

@@ -2,8 +2,9 @@ from typing import Optional
 
 from ...material import Material
 from ..analyze.other import get_surface_area
-from ..build.compound_pristine_structures.two_dimensional.interface import InterfaceConfiguration, get_slab
-from ..build_components import MaterialBuildMetadata, MaterialWithBuildMetadata
+from ..analyze.interface_material import get_interface_bulk_crystal
+from ..build.compound_pristine_structures.two_dimensional.interface import get_slab
+from ..build_components.metadata import MaterialWithBuildMetadata
 from ..convert import decorator_convert_material_args_kwargs_to_atoms
 from ..third_party import ASEAtoms, ASECalculator, ASECalculatorEMT
 from .calculators import InterfaceMaterialCalculatorParameters
@@ -114,19 +115,14 @@ def calculate_interfacial_energy(
     substrate_slab = get_slab(interface, part="substrate") if substrate_slab is None else substrate_slab
     film_slab = get_slab(interface, part="film") if film_slab is None else film_slab
 
-    metadata = (
-        interface.metadata
-        if isinstance(interface, MaterialWithBuildMetadata)
-        else MaterialBuildMetadata(**interface.metadata)
-    )
-    build_configuration = metadata.build[-1].configuration if metadata.build else {}
-    config = InterfaceConfiguration(**build_configuration)
-
     try:
-        substrate_bulk = config.substrate_configuration.atomic_layers.crystal
-        film_bulk = config.film_configuration.atomic_layers.crystal
-    except KeyError:
-        raise ValueError("The substrate and film bulk materials must be provided or defined in the interface metadata.")
+        interface_with_metadata = MaterialWithBuildMetadata.create(interface.to_dict())
+        substrate_bulk = Material.create(get_interface_bulk_crystal(interface_with_metadata, part="substrate"))
+        film_bulk = Material.create(get_interface_bulk_crystal(interface_with_metadata, part="film"))
+    except ValueError as exc:
+        raise ValueError(
+            "The substrate and film bulk materials must be provided or defined in the interface metadata."
+        ) from exc
     surface_energy_substrate = calculate_surface_energy(substrate_slab, substrate_bulk, calculator)
     surface_energy_film = calculate_surface_energy(film_slab, film_bulk, calculator)
     adhesion_energy = calculate_adhesion_energy(interface, substrate_slab, film_slab, calculator)

package/tests/py/unit/test_primitive_cell.py

@@ -3,7 +3,7 @@ import pytest
 
 from mat3ra.made.cell.primitive_cell import get_primitive_lattice_vectors_from_config
 from mat3ra.made.lattice import Lattice, LatticeTypeEnum
-from tests.py.unit.utils import assert_two_entities_deep_almost_equal
+from unit.utils import assert_two_entities_deep_almost_equal
 
 EXPECTED_PRIMITIVE_CELL_NA4CL4 = [
     [5.691694, 0.0, 0.0],

package/tests/py/unit/test_tools_analyze_interface_material.py

@@ -0,0 +1,63 @@
+from typing import Final, Type
+
+import pytest
+from mat3ra.made.tools.analyze.build_metadata_analyzer import BuildMetadataAnalyzer
+from mat3ra.made.tools.analyze.build_metadata_analyzer_factory import create_build_metadata_analyzer
+from mat3ra.made.tools.analyze.interface_material import (
+    InterfaceMaterialAnalyzer,
+    get_interface_bulk_crystal,
+    get_interface_configuration,
+)
+from mat3ra.made.tools.analyze.slab import SlabMaterialAnalyzer
+from mat3ra.made.tools.build import MaterialWithBuildMetadata
+from mat3ra.made.tools.build.compound_pristine_structures.two_dimensional.interface import InterfaceConfiguration
+from unit.fixtures.interface.zsl import GRAPHENE_NICKEL_INTERFACE
+from unit.fixtures.slab import SI_CONVENTIONAL_SLAB_001
+
+INTERFACE_MATERIAL: Final = MaterialWithBuildMetadata.create(GRAPHENE_NICKEL_INTERFACE)
+SLAB_MATERIAL: Final = MaterialWithBuildMetadata.create(SI_CONVENTIONAL_SLAB_001)
+SUBSTRATE_CRYSTAL_NAME: Final = "Ni, Nickel, FCC (Fm-3m) 3D (Bulk), mp-23"
+FILM_CRYSTAL_NAME: Final = "Graphene"
+
+GET_BULK_CRYSTAL_CASES = [
+    ("substrate", SUBSTRATE_CRYSTAL_NAME),
+    ("film", FILM_CRYSTAL_NAME),
+]
+
+CREATE_BUILD_METADATA_ANALYZER_CASES = [
+    (INTERFACE_MATERIAL, InterfaceMaterialAnalyzer),
+    (SLAB_MATERIAL, SlabMaterialAnalyzer),
+]
+
+
+def test_build_configuration():
+    configuration = InterfaceMaterialAnalyzer(material=INTERFACE_MATERIAL).build_configuration
+    assert isinstance(configuration, InterfaceConfiguration)
+    assert configuration.type == "InterfaceConfiguration"
+
+
+@pytest.mark.parametrize("part,expected_name", GET_BULK_CRYSTAL_CASES)
+def test_get_bulk_crystal(part, expected_name):
+    crystal = InterfaceMaterialAnalyzer(material=INTERFACE_MATERIAL).get_bulk_crystal(part=part)
+    assert crystal["name"] == expected_name
+
+
+def test_get_interface_configuration():
+    configuration = get_interface_configuration(INTERFACE_MATERIAL)
+    assert isinstance(configuration, InterfaceConfiguration)
+    assert configuration.type == "InterfaceConfiguration"
+
+
+@pytest.mark.parametrize("part,expected_name", GET_BULK_CRYSTAL_CASES)
+def test_get_interface_bulk_crystal(part, expected_name):
+    crystal = get_interface_bulk_crystal(INTERFACE_MATERIAL, part=part)
+    assert crystal["name"] == expected_name
+
+
+@pytest.mark.parametrize("material,expected_analyzer_cls", CREATE_BUILD_METADATA_ANALYZER_CASES)
+def test_create_build_metadata_analyzer(
+    material: MaterialWithBuildMetadata,
+    expected_analyzer_cls: Type[BuildMetadataAnalyzer],
+):
+    analyzer = create_build_metadata_analyzer(material)
+    assert isinstance(analyzer, expected_analyzer_cls)

package/tests/py/unit/test_tools_build_metadata.py

@@ -28,6 +28,16 @@ def test_metadata_empty_initialization():
     assert metadata.model_dump(exclude_none=True) == {"build": []}
 
 
+def test_get_latest_build_metadata():
+    metadata = MaterialBuildMetadata(build=[BuildMetadata(configuration={"type": "SlabConfiguration"})])
+    assert metadata.get_latest_build_metadata().configuration["type"] == "SlabConfiguration"
+
+
+def test_get_latest_build_metadata_raises_when_empty():
+    with pytest.raises(ValueError, match="No metadata.build"):
+        MaterialBuildMetadata().get_latest_build_metadata()
+
+
 @pytest.mark.parametrize(
     "config_object, expected_dict",
     [