@mat3ra/made 2025.12.16-0 → 2026.3.3-0

package/package.json

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

package/pyproject.toml

@@ -21,7 +21,6 @@ dependencies = [
     "mat3ra-utils",
     "mat3ra-esse",
     "mat3ra-code"
-
 ]
 
 [project.optional-dependencies]
@@ -31,6 +30,7 @@ tools = [
     "pymatgen==2024.4.13",
     "ase",
     "pymatgen-analysis-defects==2024.4.23",
+    "mat3ra-periodic-table>=2025.12.26",
 ]
 dev = [
     "pre-commit",

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

@@ -2,6 +2,7 @@ from typing import Any, Dict, List, Optional, Union
 
 import numpy as np
 from mat3ra.code.array_with_ids import ArrayWithIds
+from mat3ra.code.constants import HASH_TOLERANCE
 from mat3ra.code.entity import InMemoryEntityPydantic
 from mat3ra.esse.models.core.abstract.matrix_3x3 import Matrix3x3Schema
 from mat3ra.esse.models.material import BasisSchema, BasisUnitsEnum
@@ -87,6 +88,24 @@ class Basis(BasisSchema, InMemoryEntityPydantic):
             constraints=ArrayWithIds.from_list_of_dicts(constraints),
         )
 
+    @property
+    def hash_string(self) -> str:
+        """
+        Mirrors JS Basis.hashString (getAsSortedString in crystal units).
+        Converts to crystal, applies mod 1 to bring coords into [0,1), builds sorted atom strings.
+        """
+        original_is_in_cartesian = self.is_in_cartesian_units
+        self.to_crystal()
+        labels_map = {lbl["id"]: str(lbl["value"]) for lbl in self.labels.to_dict()}
+        parts = []
+        for elem, coord in zip(self.elements.to_dict(), self.coordinates.to_dict()):
+            label = labels_map.get(elem["id"], "")
+            rounded = [f"{round(v % 1, HASH_TOLERANCE):g}" for v in coord["value"]]
+            parts.append(f"{elem['value']}{label} {','.join(rounded)}")
+        if original_is_in_cartesian:
+            self.to_cartesian()
+        return ";".join(sorted(parts)) + ";"
+
     @property
     def is_in_crystal_units(self):
         return self.units == BasisUnitsEnum.crystal

package/src/py/mat3ra/made/lattice.py

@@ -2,6 +2,7 @@ import math
 from typing import List, Optional
 
 import numpy as np
+from mat3ra.code.constants import HASH_TOLERANCE
 from mat3ra.code.entity import InMemoryEntityPydantic
 from mat3ra.esse.models.properties_directory.structural.lattice import (
     LatticeSchema,
@@ -127,6 +128,12 @@ class Lattice(RoundNumericValuesMixin, LatticeSchemaVectorless, InMemoryEntityPy
     def cell_volume_rounded(self) -> float:
         return self.vectors.volume_rounded
 
+    def get_hash_string(self, is_scaled: bool = False) -> str:
+        """Mirrors JS Lattice.getHashString(isScaled). Rounds to HASH_TOLERANCE decimal places."""
+        scale = self.a if is_scaled else 1
+        values = [self.a / scale, self.b / scale, self.c / scale, self.alpha, self.beta, self.gamma]
+        return ";".join(f"{round(v, HASH_TOLERANCE):g}" for v in values) + ";"
+
     def get_scaled_by_matrix(self, matrix: List[List[float]]):
         """
         Scale the lattice by a matrix.

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

@@ -1,3 +1,4 @@
+import hashlib
 from typing import Any, List, Optional, Union
 
 from mat3ra.code.constants import AtomicCoordinateUnits, Units
@@ -111,3 +112,17 @@ class Material(MaterialSchema, HasDescriptionHasMetadataNamedDefaultableInMemory
 
     def set_labels_from_value(self, value: Union[int, str]) -> None:
         self.basis.set_labels_from_list([value] * self.basis.number_of_atoms)
+
+    def calculate_hash(self, salt: str = "", is_scaled: bool = False) -> str:
+        """Mirrors JS materialMixin.calculateHash(). MD5 of basis + lattice hash strings."""
+        message = f"{self.basis.hash_string}#{self.lattice.get_hash_string(is_scaled)}#{salt}"
+        return hashlib.md5(message.encode()).hexdigest()
+
+    @property
+    def hash(self) -> str:
+        return self.calculate_hash()
+
+    @property
+    def scaled_hash(self) -> str:
+        return self.calculate_hash(is_scaled=True)
+

package/src/py/mat3ra/made/tools/build_components/operations/core/modifications/perturb/__init__.py

@@ -1,7 +1,15 @@
-from .functions import FunctionHolder, PerturbationFunctionHolder, SineWavePerturbationFunctionHolder
+from .functions import (
+    AtomicMassDependentFunctionHolder,
+    FunctionHolder,
+    MaxwellBoltzmannDisplacementHolder,
+    PerturbationFunctionHolder,
+    SineWavePerturbationFunctionHolder,
+)
 
 __all__ = [
+    "AtomicMassDependentFunctionHolder",
     "FunctionHolder",
+    "MaxwellBoltzmannDisplacementHolder",
     "PerturbationFunctionHolder",
     "SineWavePerturbationFunctionHolder",
 ]

package/src/py/mat3ra/made/tools/build_components/operations/core/modifications/perturb/functions/__init__.py

@@ -1,9 +1,13 @@
+from .atomic_mass_dependent_function_holder import AtomicMassDependentFunctionHolder
 from .function_holder import FunctionHolder
+from .maxwell_boltzmann import MaxwellBoltzmannDisplacementHolder
 from .perturbation_function_holder import PerturbationFunctionHolder
 from .sine_wave_perturbation_function_holder import SineWavePerturbationFunctionHolder
 
 __all__ = [
+    "AtomicMassDependentFunctionHolder",
     "FunctionHolder",
+    "MaxwellBoltzmannDisplacementHolder",
     "PerturbationFunctionHolder",
     "SineWavePerturbationFunctionHolder",
 ]

package/src/py/mat3ra/made/tools/build_components/operations/core/modifications/perturb/functions/atomic_mass_dependent_function_holder.py

@@ -0,0 +1,32 @@
+from typing import Any, List, Optional, Union
+
+import sympy as sp
+from mat3ra.periodic_table.helpers import get_atomic_mass_from_element
+
+from .function_holder import FunctionHolder
+
+
+class AtomicMassDependentFunctionHolder(FunctionHolder):
+    variables: List[str] = ["x", "y", "z", "m"]
+
+    def __init__(
+        self,
+        function: Union[sp.Expr, str] = sp.Symbol("f"),
+        variables: Optional[List[str]] = None,
+        **data: Any,
+    ):
+        if variables is None:
+            expr = self._to_expr(function)
+            vs = sorted(expr.free_symbols, key=lambda s: s.name)
+            variables = [str(v) for v in vs] or ["x", "y", "z", "m"]
+
+        super().__init__(function=function, variables=variables, **data)
+
+    @staticmethod
+    def get_atomic_mass(coordinate: List[float], material) -> float:
+        if material is None:
+            raise ValueError("Material is required to extract atomic mass")
+
+        atom_id = material.basis.coordinates.get_element_id_by_value(coordinate)
+        element = material.basis.elements.get_element_value_by_index(atom_id)
+        return get_atomic_mass_from_element(element)

package/src/py/mat3ra/made/tools/build_components/operations/core/modifications/perturb/functions/function_holder.py

@@ -52,7 +52,7 @@ class FunctionHolder(InMemoryEntityPydantic):
     def function_str(self) -> str:
         return str(self.function)
 
-    def apply_function(self, coordinate: List[float]) -> float:
+    def apply_function(self, coordinate: List[float], **kwargs: Any) -> float:
         values = [coordinate[AXIS_TO_INDEX_MAP[var]] for var in self.variables]
         return self.function_numeric(*values)
 

package/src/py/mat3ra/made/tools/build_components/operations/core/modifications/perturb/functions/maxwell_boltzmann.py

@@ -0,0 +1,39 @@
+from typing import Any, List, Optional
+
+import numpy as np
+from pydantic import Field, model_validator
+
+from .atomic_mass_dependent_function_holder import AtomicMassDependentFunctionHolder
+
+DEFAULT_DISORDER_PARAMETER = 1.0
+
+
+class MaxwellBoltzmannDisplacementHolder(AtomicMassDependentFunctionHolder):
+    disorder_parameter: float = Field(
+        default=DEFAULT_DISORDER_PARAMETER,
+        exclude=True,
+        description="Disorder parameter. Can be viewed as effective temperature in eV.",
+    )
+    random_seed: Optional[int] = Field(default=None, exclude=True)
+    random_state: Any = Field(default=None, exclude=True)
+    is_mass_used: bool = Field(default=True, exclude=True)
+
+    @model_validator(mode="after")
+    def setup_random_state(self):
+        if self.random_state is None:
+            self.random_state = np.random.RandomState(self.random_seed) if self.random_seed is not None else np.random
+        return self
+
+    def apply_function(self, coordinate, material=None) -> List[float]:
+        if material is None:
+            raise ValueError("MaxwellBoltzmannDisplacementHolder requires 'material' kwargs")
+
+        if self.is_mass_used:
+            mass = self.get_atomic_mass(coordinate, material)
+            variance = self.disorder_parameter / mass
+        else:
+            variance = self.disorder_parameter
+
+        std_dev = np.sqrt(variance)
+        displacement = self.random_state.normal(0.0, std_dev, size=3)
+        return displacement.tolist()

package/src/py/mat3ra/made/tools/build_components/operations/core/modifications/perturb/helpers.py

@@ -1,13 +1,14 @@
-from typing import Union
+from typing import Optional, Union
 
 import sympy as sp
-from mat3ra.made.material import Material
 
-from ..... import MaterialWithBuildMetadata
+from mat3ra.made.material import Material
 from .builders.base import PerturbationBuilder
 from .builders.isometric import IsometricPerturbationBuilder
 from .configuration import PerturbationConfiguration
 from .functions import PerturbationFunctionHolder
+from .functions.maxwell_boltzmann import MaxwellBoltzmannDisplacementHolder
+from ..... import MaterialWithBuildMetadata
 
 
 def create_perturbation(
@@ -39,3 +40,44 @@ def create_perturbation(
     else:
         builder = PerturbationBuilder()
     return builder.get_material(configuration)
+
+
+def create_maxwell_displacement(
+    material: Union[Material, MaterialWithBuildMetadata],
+    disorder_parameter: float,
+    random_seed: Optional[int] = None,
+    is_mass_used: bool = True,
+) -> Material:
+    """
+    Apply Maxwell-Boltzmann random displacements to a material.
+
+    Generates random 3D displacement vectors where each component follows a normal
+    distribution with variance proportional to disorder_parameter/m (if is_mass_used=True)
+    or disorder_parameter (if is_mass_used=False), where m is atomic mass.
+
+    Args:
+        material: The material to be perturbed.
+        disorder_parameter: Disorder parameter controlling displacement magnitude,
+                            can be viewed as effective temperature in eV.
+        random_seed: Optional random seed for reproducibility for the same material and parameters.
+        is_mass_used: If True, displacement variance is disorder_parameter/m (mass-dependent).
+                     If False, displacement variance is disorder_parameter (mass-independent).
+
+    Returns:
+        Material with applied Maxwell-Boltzmann displacements.
+    """
+    displacement_holder = MaxwellBoltzmannDisplacementHolder(
+        disorder_parameter=disorder_parameter,
+        random_seed=random_seed,
+        is_mass_used=is_mass_used,
+    )
+
+    configuration = PerturbationConfiguration(
+        material=material,
+        perturbation_function_holder=displacement_holder,
+        use_cartesian_coordinates=True,
+    )
+
+    builder = PerturbationBuilder()
+
+    return builder.get_material(configuration)

package/src/py/mat3ra/made/tools/operations/core/unary.py

@@ -84,12 +84,11 @@ def perturb(
     perturbed_coordinates: List[List[float]] = []
 
     for coordinate in original_coordinates:
-        # If func_holder returns a scalar, assume z-axis; otherwise vector
-        displacement = perturbation_function.apply_function(coordinate)
+        displacement = perturbation_function.apply_function(coordinate, material=new_material)
+
         if isinstance(displacement, (list, tuple, np.ndarray)):
             delta = np.array(displacement)
         else:
-            # scalar: apply to z-axis
             delta = np.array([0.0, 0.0, displacement])
 
         new_coordinate = np.array(coordinate) + delta

package/tests/fixtures/Graphene.json

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:3fbf76a64fe44dccbad8e5cbd625e7b3a0fe3f0496c0fd447622632dca0fde62
-size 1733
+oid sha256:43712ea8ada9350751be35d18f0ef92880a095be6536615f86b0c9ffd3b10dae
+size 1835

package/tests/fixtures/si-standata.json

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:d096e1c2598dee0e809902646b28b38be4e2be1b40a2fc0b40f23fbf8b9f158e
-size 1031
+oid sha256:62175309558d4a75da4fd723ccb47dc558cdbb89fa224e61921c4ee2d5b48094
+size 1133

package/tests/js/material.test.ts

@@ -1,7 +1,7 @@
 import { expect } from "chai";
 
 import { Material } from "../../src/js/material";
-import { Na4Cl4, Silicon } from "./fixtures";
+import { Graphene, Na4Cl4, Silicon } from "./fixtures";
 
 const newBasisXYZ = `Si     0.000000    0.000000    0.000000
 Ge     0.250000    0.250000    0.250000
@@ -19,4 +19,17 @@ describe("Material", () => {
         clonedMaterial.setBasis(newBasisXYZ, "xyz", clonedMaterial.Basis.units);
         expect(clonedMaterial.Basis.elements).to.have.lengthOf(2);
     });
+
+    describe("calculateHash", () => {
+        [
+            { name: "Silicon", fixture: Silicon },
+            { name: "Graphene", fixture: Graphene },
+        ].forEach(({ name, fixture }) => {
+            it(`should match expected hash for ${name}`, () => {
+                const material = new Material(fixture);
+                expect(material.calculateHash()).to.equal((fixture as any).hash);
+                expect(material.scaledHash).to.equal((fixture as any).scaledHash);
+            });
+        });
+    });
 });

package/tests/py/unit/test_material.py

@@ -1,3 +1,6 @@
+import json
+from pathlib import Path
+
 import numpy as np
 import pytest
 from mat3ra.made.basis import Basis, Coordinates
@@ -8,6 +11,13 @@ from unit.fixtures.bulk import BULK_Si_PRIMITIVE
 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"
+
+
+def load_fixture(name: str) -> dict:
+    with open(FIXTURES_DIR / name) as f:
+        return json.load(f)
+
 
 def test_create_default():
     material = Material.create_default()
@@ -118,3 +128,11 @@ def test_set_labels_from_list(initial_labels, reset_labels, expected_final):
 
     assert len(material.basis.labels.values) == len(expected_final)
     assert material.basis.labels.values == expected_final
+
+
+@pytest.mark.parametrize("fixture_file", ["si-standata.json", "Graphene.json"])
+def test_calculate_hash(fixture_file):
+    fixture = load_fixture(fixture_file)
+    material = Material.create(fixture)
+    assert material.hash == fixture["hash"]
+    assert material.scaled_hash == fixture["scaledHash"]

package/tests/py/unit/test_tools_build_maxwell_disorder.py

@@ -0,0 +1,123 @@
+import numpy as np
+import pytest
+from mat3ra.made.material import Material
+from mat3ra.made.tools.build_components.operations.core.modifications.perturb.functions.maxwell_boltzmann import (
+    MaxwellBoltzmannDisplacementHolder,
+)
+from mat3ra.made.tools.build_components.operations.core.modifications.perturb.helpers import create_maxwell_displacement
+from mat3ra.made.tools.helpers import create_supercell
+from mat3ra.periodic_table.helpers import get_atomic_mass_from_element
+
+from .fixtures.bulk import BULK_Si_PRIMITIVE
+from .fixtures.slab import SI_CONVENTIONAL_SLAB_001
+
+DISORDER_PARAMETER = 1.0  # Temperature-like
+RANDOM_SEED = 42
+NUM_SAMPLES_FOR_MSD = 1000
+
+
+@pytest.mark.parametrize("random_seed", [None, 42, 123])
+def test_maxwell_displacement_deterministic(random_seed):
+    material = Material.create(BULK_Si_PRIMITIVE)
+    displacement_func1 = MaxwellBoltzmannDisplacementHolder(
+        disorder_parameter=DISORDER_PARAMETER, random_seed=random_seed
+    )
+    displacement_func2 = MaxwellBoltzmannDisplacementHolder(
+        disorder_parameter=DISORDER_PARAMETER, random_seed=random_seed
+    )
+
+    coord = [0.0, 0.0, 0.0]
+
+    if random_seed is not None:
+        disp1 = displacement_func1.apply_function(coord, material=material)
+        disp2 = displacement_func2.apply_function(coord, material=material)
+        assert np.allclose(disp1, disp2)
+
+        # Different seed should give different results
+        displacement_func3 = MaxwellBoltzmannDisplacementHolder(
+            disorder_parameter=DISORDER_PARAMETER, random_seed=random_seed + 1
+        )
+        disp3 = displacement_func3.apply_function(coord, material=material)
+        assert not np.allclose(disp1, disp3) or np.allclose(disp1, [0, 0, 0], atol=1e-10)
+    else:
+        # No seed: different instances should give different results (non-deterministic)
+        disp1 = displacement_func1.apply_function(coord, material=material)
+        disp2 = displacement_func2.apply_function(coord, material=material)
+        assert not np.allclose(disp1, disp2) or np.allclose(disp1, [0, 0, 0], atol=1e-10)
+
+
+def test_maxwell_displacement_perturb_integration():
+    material = Material.create(BULK_Si_PRIMITIVE)
+    original_coords = [coord[:] for coord in material.basis.coordinates.values]
+
+    perturbed_material = create_maxwell_displacement(
+        material, disorder_parameter=DISORDER_PARAMETER, random_seed=RANDOM_SEED
+    )
+
+    assert len(perturbed_material.basis.coordinates.values) == len(original_coords)
+    for i, (orig, pert) in enumerate(zip(original_coords, perturbed_material.basis.coordinates.values)):
+        delta = np.array(pert) - np.array(orig)
+        assert np.linalg.norm(delta) > 0 or np.allclose(delta, 0, atol=1e-10)
+
+
+def test_maxwell_displacement_msd_expectation():
+    material = Material.create(BULK_Si_PRIMITIVE)
+    si_mass = get_atomic_mass_from_element("Si")
+    disorder_parameter = DISORDER_PARAMETER
+    expected_variance = disorder_parameter / si_mass
+    expected_msd = 3 * expected_variance
+
+    displacements = []
+    coord = [0.0, 0.0, 0.0]
+    for _ in range(NUM_SAMPLES_FOR_MSD):
+        displacement_func = MaxwellBoltzmannDisplacementHolder(disorder_parameter=disorder_parameter, random_seed=None)
+        disp = displacement_func.apply_function(coord, material=material)
+        displacements.append(disp)
+
+    displacements_array = np.array(displacements)
+    msd = np.mean(np.sum(displacements_array**2, axis=1))
+
+    assert abs(msd - expected_msd) / expected_msd < 0.3
+
+
+@pytest.mark.parametrize(
+    "slab_config, temperature_k, random_seed",
+    [
+        (SI_CONVENTIONAL_SLAB_001, 1300.0, 42),
+        (SI_CONVENTIONAL_SLAB_001, 1300.0, 42),
+    ],
+)
+def test_maxwell_boltzmann_on_slab(slab_config, temperature_k, random_seed):
+    material = Material.create(slab_config)
+    material = create_supercell(material, scaling_factor=[4, 4, 1])
+    original_coords = [coord[:] for coord in material.basis.coordinates.values]
+    original_lattice = material.lattice.vector_arrays.copy()
+
+    perturbed_material = create_maxwell_displacement(
+        material, disorder_parameter=temperature_k, random_seed=random_seed
+    )
+
+    assert len(perturbed_material.basis.coordinates.values) == len(original_coords)
+    assert len(perturbed_material.basis.elements.values) == len(material.basis.elements.values)
+
+    coordinate_changes = []
+    for i, (orig, pert) in enumerate(zip(original_coords, perturbed_material.basis.coordinates.values)):
+        delta = np.array(pert) - np.array(orig)
+        displacement_magnitude = np.linalg.norm(delta)
+        coordinate_changes.append(displacement_magnitude)
+
+    max_displacement = max(coordinate_changes)
+    mean_displacement = np.mean(coordinate_changes)
+
+    assert max_displacement > 0
+    assert mean_displacement > 0
+
+    si_mass = get_atomic_mass_from_element("Si")
+    expected_std = np.sqrt(temperature_k / si_mass)
+
+    assert mean_displacement < 5 * expected_std
+
+    assert np.allclose(perturbed_material.lattice.vector_arrays, original_lattice, atol=1e-10)
+
+    for i, element in enumerate(material.basis.elements.values):
+        assert perturbed_material.basis.elements.values[i] == element