@mat3ra/made 2026.4.2-1 → 2026.5.21-1

package/package.json

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

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

@@ -4,7 +4,7 @@ from typing import Any, List, Optional, Union
 from mat3ra.code.constants import AtomicCoordinateUnits, Units
 from mat3ra.code.entity import HasDescriptionHasMetadataNamedDefaultableInMemoryEntityPydantic
 from mat3ra.esse.models.material import MaterialSchema
-from pydantic import ConfigDict, SkipValidation
+from pydantic import ConfigDict, SkipValidation, computed_field, field_serializer
 
 from .basis import Basis
 from .lattice import Lattice
@@ -120,10 +120,15 @@ class Material(MaterialSchema, HasDescriptionHasMetadataNamedDefaultableInMemory
         message = f"{self.basis.hash_string}#{self.lattice.get_hash_string(is_scaled)}#{salt}"
         return hashlib.md5(message.encode()).hexdigest()
 
+    @computed_field
     @property
     def hash(self) -> str:
         return self.calculate_hash()
 
+    @field_serializer("scaledHash")
+    def serialize_scaled_hash(self, _scaled_hash: Optional[str]) -> str:
+        return self.scaled_hash
+
     @property
     def scaled_hash(self) -> str:
         return self.calculate_hash(is_scaled=True)

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/pristine_structures/two_dimensional/slab/helpers.py

@@ -40,14 +40,6 @@ def create_slab(
     Returns:
         Material: The generated slab material.
     """
-    material_to_use = crystal
-
-    if use_conventional_cell:
-        crystal_lattice_planes_analyzer = CrystalLatticePlanesMaterialAnalyzer(
-            material=crystal, miller_indices=miller_indices
-        )
-        material_to_use = crystal_lattice_planes_analyzer.material_with_conventional_lattice
-
     if termination_top is not None:
         termination_top_formula = termination_top.formula
     if termination_bottom is not None:
@@ -58,7 +50,7 @@ def create_slab(
         use_orthogonal_c=use_orthogonal_c,
     )
     slab_configuration = SlabConfiguration.from_parameters(
-        material_or_dict=material_to_use,
+        material_or_dict=crystal,
         miller_indices=miller_indices,
         number_of_layers=number_of_layers,
         termination_top_formula=termination_top_formula,

package/tests/py/unit/test_material.py

@@ -12,6 +12,8 @@ from unit.fixtures.slab import BULK_Si_CONVENTIONAL
 from unit.utils import assert_two_entities_deep_almost_equal
 
 FIXTURES_DIR = Path(__file__).parents[2] / "fixtures"
+HASH_KEY = "hash"
+SCALED_HASH_KEY = "scaledHash"
 
 
 def load_fixture(name: str) -> dict:
@@ -136,3 +138,11 @@ def test_calculate_hash(fixture_file):
     material = Material.create(fixture)
     assert material.hash == fixture["hash"]
     assert material.scaled_hash == fixture["scaledHash"]
+
+
+def test_model_dump_includes_hashes():
+    material = Material.create_default()
+    serialized_material = material.model_dump()
+
+    assert serialized_material[HASH_KEY] == material.hash
+    assert serialized_material[SCALED_HASH_KEY] == material.scaled_hash

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_interface.py

@@ -5,6 +5,7 @@ import pytest
 from mat3ra.esse.models.core.reusable.axis_enum import AxisEnum
 from mat3ra.made.material import Material
 from mat3ra.made.tools.analyze.interface.simple import InterfaceAnalyzer
+from mat3ra.made.tools.analyze.lattice_planes import CrystalLatticePlanesMaterialAnalyzer
 from mat3ra.made.tools.build import MaterialWithBuildMetadata
 from mat3ra.made.tools.build.compound_pristine_structures.two_dimensional.interface.base.build_parameters import (
     InterfaceBuilderParameters,
@@ -39,6 +40,9 @@ from .fixtures.interface.twisted_nanoribbons import TWISTED_INTERFACE_GRAPHENE_G
 from .fixtures.monolayer import GRAPHENE
 from .utils import OSPlatform, assert_two_entities_deep_almost_equal
 
+HASH_KEY = "hash"
+SCALED_HASH_KEY = "scaledHash"
+
 Si_Ge_SIMPLE_INTERFACE_TEST_CASE = (
     SimpleNamespace(
         bulk_config=BULK_Si_CONVENTIONAL,
@@ -253,6 +257,29 @@ def test_commensurate_interface_creation(material_config, analyzer_params, direc
     assert_two_entities_deep_almost_equal(interface, expected_interface, atol=PRECISION)
 
 
+def test_create_slab_with_conventional_cell_stores_crystal_hashes_in_metadata():
+    miller_indices = (0, 0, 1)
+    material = Material.create(BULK_Ni_PRIMITIVE)
+    expected_crystal = CrystalLatticePlanesMaterialAnalyzer(
+        material=material, miller_indices=miller_indices
+    ).material_with_conventional_lattice
+
+    slab = create_slab(
+        crystal=material,
+        miller_indices=miller_indices,
+        use_conventional_cell=True,
+        use_orthogonal_c=True,
+        number_of_layers=1,
+        vacuum=0.0,
+    )
+    serialized_slab = slab.model_dump()
+    crystal = serialized_slab["metadata"]["build"][-1]["configuration"]["stack_components"][0]["crystal"]
+
+    assert crystal[HASH_KEY] == expected_crystal.hash
+    assert crystal[SCALED_HASH_KEY] == expected_crystal.scaled_hash
+    assert "bulkId" not in serialized_slab["metadata"]
+
+
 @pytest.mark.parametrize(
     "interface_config, expected_coordinate_level",
     [(GRAPHENE_NICKEL_INTERFACE_TOP_HCP, 12.048)],