@mat3ra/made 2026.7.21-0 → 2026.8.7-0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2026.7.21-0",
+    "version": "2026.8.7-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/build/defective_structures/three_dimensional/solid_solution/builder.py

@@ -31,7 +31,7 @@ class SolidSolutionBuilder(MergeBuilder):
         source_element = configuration.source_element
         target_element = configuration.target_element
         material.name = (
-            f"{formula} - Solid Solution ({source_element}\u2192{target_element} "
+            f"{formula} - Solid Solution ({source_element}->{target_element} "
             f"{concentration_percentage:.4g}%)"
         )
         return material

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

@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import Optional, Tuple
 
 from ...material import Material
 from ..analyze.other import get_surface_area
@@ -88,6 +88,31 @@ def calculate_adhesion_energy(
     return (energy_substrate_slab + energy_film_slab - energy_interface) / area
 
 
+def _get_interface_with_build_metadata(interface: Material) -> MaterialWithBuildMetadata:
+    if isinstance(interface, MaterialWithBuildMetadata):
+        return interface
+    return MaterialWithBuildMetadata.create(interface.to_dict())
+
+
+def _resolve_interface_bulk_materials(
+    interface: Material,
+    substrate_bulk: Optional[Material],
+    film_bulk: Optional[Material],
+) -> Tuple[Optional[Material], Optional[Material]]:
+    """Resolve missing bulks from interface build metadata (handles BoundaryConditions metadata)."""
+    try:
+        interface_with_metadata = _get_interface_with_build_metadata(interface)
+        if substrate_bulk is None:
+            substrate_bulk = Material.create(get_interface_bulk_crystal(interface_with_metadata, part="substrate"))
+        if film_bulk is None:
+            film_bulk = Material.create(get_interface_bulk_crystal(interface_with_metadata, part="film"))
+    except (ValueError, TypeError) as exc:
+        raise ValueError(
+            "The substrate and film bulk materials must be provided or defined in the interface metadata."
+        ) from exc
+    return substrate_bulk, film_bulk
+
+
 def calculate_interfacial_energy(
     interface: Material,
     substrate_slab: Optional[Material] = None,
@@ -115,14 +140,9 @@ 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
 
-    try:
-        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
+    if substrate_bulk is None or film_bulk is None:
+        substrate_bulk, film_bulk = _resolve_interface_bulk_materials(interface, substrate_bulk, film_bulk)
+
     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/src/py/mat3ra/made/tools/operations/core/unary.py

@@ -17,14 +17,58 @@ def translate(material: Material, vector: Vector3D) -> Material:
     return translate_by_vector(material, vector, use_cartesian_coordinates=True)
 
 
+def translate_atoms(
+    material: Material,
+    atom_ids: List[int],
+    vector: Vector3D,
+    use_cartesian_coordinates: bool = True,
+) -> Material:
+    """
+    Translate the given atoms by a vector.
+
+    Basis order is preserved.
+
+    Args:
+        material (Material): The material to translate atoms in.
+        atom_ids (List[int]): Indices of the atoms to translate.
+        vector (Vector3D): The vector to translate the atoms by.
+        use_cartesian_coordinates (bool): Whether `vector` is in cartesian coordinates.
+
+    Returns:
+        Material: The material with the given atoms translated.
+
+    Raises:
+        IndexError: If any atom id is out of range for the basis.
+    """
+    new_material = material.clone()
+    if use_cartesian_coordinates:
+        new_material.to_cartesian()
+    coordinates: List[List[float]] = [list(coordinate) for coordinate in new_material.basis.coordinates.values]
+
+    out_of_range = [atom_id for atom_id in atom_ids if not -len(coordinates) <= atom_id < len(coordinates)]
+    if out_of_range:
+        raise IndexError(f"Atom ids {out_of_range} are out of range for a basis of {len(coordinates)} atoms.")
+
+    for atom_id in atom_ids:
+        coordinates[atom_id] = (np.array(coordinates[atom_id]) + np.array(vector)).tolist()
+
+    new_material.set_coordinates(coordinates)
+    if use_cartesian_coordinates:
+        new_material.to_crystal()
+    return new_material
+
+
 @decorator_convert_supercell_matrix_2x2_to_3x3
 def supercell(material: MaterialWithBuildMetadata, supercell_matrix) -> MaterialWithBuildMetadata:
     atoms = to_ase(material)
 
     supercell_atoms = ase_make_supercell(atoms, supercell_matrix)
-    new_material = MaterialWithBuildMetadata.create(from_ase(supercell_atoms))
-    # if material.metadata:
-    #     new_material.metadata.update(**material.metadata.to_dict())
+    material_config = from_ase(supercell_atoms)
+    # ASE make_supercell drops atoms.info; merge prior build/boundaryConditions when present.
+    source_metadata = material.to_dict().get("metadata") or {}
+    if source_metadata:
+        material_config["metadata"] = {**material_config.get("metadata", {}), **source_metadata}
+    new_material = MaterialWithBuildMetadata.create(material_config)
     new_material.name = material.name
     return new_material
 

package/tests/py/unit/fixtures/bulk.py

@@ -5,7 +5,7 @@ from mat3ra.standata.materials import Materials
 BULK_SrTiO3 = Materials.get_by_name_first_match("SrTiO3")
 BULK_GRAPHITE = Materials.get_by_name_first_match("Graphite")
 BULK_SiO2 = Materials.get_by_name_first_match("SiO2")
-BULK_Hf2O_MCL = Materials.get_by_name_first_match("Hafnium.*MCL")
+BULK_Hf2O_MCL = Materials.get_by_name_first_match("Hafnium IV Oxide, MCL")
 BULK_TiN = Materials.get_by_name_first_match("TiN")
 BULK_Ni_PRIMITIVE = Materials.get_by_name_first_match("Nickel")
 BULK_GRAPHENE = Materials.get_by_name_first_match("Graphene")

package/tests/py/unit/test_operations.py

@@ -5,9 +5,11 @@ import pytest
 from mat3ra.esse.models.core.abstract.matrix_3x3 import Matrix3x3Schema
 from mat3ra.esse.models.core.reusable.axis_enum import AxisEnum
 from mat3ra.made.material import Material
-from mat3ra.made.tools.build_components.operations.core.modifications.perturb import SineWavePerturbationFunctionHolder
+from mat3ra.made.tools.build_components.operations.core.modifications.perturb import (
+    SineWavePerturbationFunctionHolder,
+)
 from mat3ra.made.tools.operations.core.binary import stack_two_materials
-from mat3ra.made.tools.operations.core.unary import perturb, strain
+from mat3ra.made.tools.operations.core.unary import perturb, strain, translate_atoms
 from mat3ra.made.tools.operations.reusable.unary import transform_material_by_matrix
 from unit.fixtures.bulk import BULK_Si_CONVENTIONAL
 from unit.fixtures.strain import BULK_Si_CONVENTIONAL_STRAINED
@@ -100,3 +102,25 @@ def test_transform_material_by_matrix(matrix, expected_a, expected_b, expected_c
     assert transformed_material.lattice.a == pytest.approx(expected_a, abs=1e-6)
     assert transformed_material.lattice.b == pytest.approx(expected_b, abs=1e-6)
     assert transformed_material.lattice.c == pytest.approx(expected_c, abs=1e-6)
+
+
+@pytest.mark.parametrize(
+    "material_config, atom_ids, vector, expected_coord_change",
+    [
+        (SI_CONVENTIONAL_SLAB_001, [3], [0.0, 0.0, -1.5], [0.0, 0.0, -1.5]),
+    ],
+)
+def test_translate_atoms(material_config, atom_ids, vector, expected_coord_change):
+    material = Material.create(material_config)
+    original_coords = [coord[:] for coord in material.basis.coordinates.values]
+
+    translated_material = translate_atoms(material, atom_ids, vector)
+    lattice_vectors = np.array(material.lattice.vector_arrays)
+
+    actual_delta = (
+        np.array(translated_material.basis.coordinates.values[atom_ids[0]]) - np.array(original_coords[atom_ids[0]])
+    ) @ lattice_vectors
+    assert np.isclose(actual_delta, expected_coord_change, atol=1e-4).all()
+
+    untouched_id = atom_ids[0] - 1
+    assert np.allclose(translated_material.basis.coordinates.values[untouched_id], original_coords[untouched_id])

package/tests/py/unit/test_tools_build_supercell.py

@@ -2,18 +2,22 @@ import numpy as np
 import pytest
 from mat3ra.made.material import Material
 from mat3ra.made.tools.build_components.entities.reusable.three_dimensional.supercell.helpers import create_supercell
+from mat3ra.made.tools.build_components.metadata import MaterialWithBuildMetadata
+from unit.fixtures.interface.zsl import GRAPHENE_NICKEL_INTERFACE
 from unit.fixtures.supercell import SI_SUPERCELL_2X2X1
 
 from .fixtures.bulk import BULK_Si_PRIMITIVE
 from .utils import assert_two_entities_deep_almost_equal
 
+SUPERCELL_MATRIX_2X2X1 = [[2, 0, 0], [0, 2, 0], [0, 0, 1]]
+
 
 @pytest.mark.parametrize(
     "material_config, supercell_matrix, expected_material_config",
     [
         (
             BULK_Si_PRIMITIVE,
-            [[2, 0, 0], [0, 2, 0], [0, 0, 1]],
+            SUPERCELL_MATRIX_2X2X1,
             SI_SUPERCELL_2X2X1,
         ),
     ],
@@ -27,3 +31,17 @@ def test_create_supercell(material_config, supercell_matrix, expected_material_c
     expected_vectors = np.array(supercell_matrix) @ np.array(material.lattice.vector_arrays)
     actual_vectors = np.array(supercell_material.lattice.vector_arrays)
     assert np.allclose(actual_vectors, expected_vectors, atol=1e-6), "Supercell vectors do not match expected values."
+
+
+def test_create_supercell_preserves_prior_build_metadata():
+    material = MaterialWithBuildMetadata.create(GRAPHENE_NICKEL_INTERFACE)
+    prior_build_types = [step.configuration.get("type") for step in material.metadata.build]
+
+    supercell_material = create_supercell(material, SUPERCELL_MATRIX_2X2X1)
+
+    result_build_types = [step.configuration.get("type") for step in supercell_material.metadata.build]
+    assert result_build_types[:-1] == prior_build_types
+    assert result_build_types[-1] == "SupercellConfiguration"
+    assert supercell_material.metadata.to_dict().get("boundaryConditions") == material.metadata.to_dict().get(
+        "boundaryConditions"
+    )

package/tests/py/unit/test_tools_calculate.py

@@ -1,5 +1,4 @@
 import numpy as np
-import pytest
 from ase.build import add_adsorbate, bulk, fcc111, graphene, surface
 from ase.calculators import emt
 from mat3ra.made.material import Material
@@ -20,16 +19,15 @@ graphene_layer.cell = nickel_slab.cell
 interface = nickel_slab.copy()
 add_adsorbate(interface, graphene_layer, height=2, position="ontop")
 
-# Material objects setup
+# Material.create yields MaterialMetadataBoundaryConditions; bulks are resolved from nested build.
 interface_material = Material.create(GRAPHENE_NICKEL_INTERFACE)
 nickel_slab_material = Material.create(from_ase(nickel_slab))
-nickel_bulk_material = Material.create(from_ase(bulk("Ni", "fcc", a=3.52)))
-graphene_layer_material = Material.create(from_ase(graphene_layer))
-graphene_bulk_material = graphene_layer
 
 # Calculator setup
 calculator = emt.EMT()
 
+EXPECTED_INTERFACIAL_ENERGY = -0.78488
+
 
 def test_calculate_total_energy():
     atoms = bulk("C", cubic=True)
@@ -59,17 +57,11 @@ def test_calculate_adhesion_energy():
     assert np.isclose(adhesion_energy, 0.07345)
 
 
-@pytest.mark.skip(reason="This test is not working as expected")
 def test_calculate_interfacial_energy():
     interfacial_energy = calculate_interfacial_energy(
         interface_material,
-        nickel_slab_material,
-        nickel_bulk_material,
-        graphene_layer,
-        graphene_bulk_material,
-        calculator,
-    )
-    assert np.isclose(
-        interfacial_energy,
-        -0.78488,
+        substrate_slab=nickel_slab_material,
+        film_slab=graphene_layer,
+        calculator=calculator,
     )
+    assert np.isclose(interfacial_energy, EXPECTED_INTERFACIAL_ENERGY)