@mat3ra/made 2025.11.24-0 → 2025.12.29-0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2025.11.24-0",
+    "version": "2025.12.29-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/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/convert/__init__.py

@@ -2,10 +2,19 @@ import inspect
 from functools import wraps
 from typing import Any, Callable, Dict, Union
 
-from mat3ra.made.material import Material
-from mat3ra.made.utils import map_array_to_array_with_id_value, map_array_with_id_value_to_array
 from mat3ra.utils.mixins import RoundNumericValuesMixin
 
+from mat3ra.made.material import Material
+from mat3ra.made.utils import (
+    map_array_to_array_with_id_value,
+    map_array_with_id_value_to_array,
+)
+from .utils import (
+    extract_labels_from_pymatgen_structure,
+    extract_metadata_from_pymatgen_structure,
+    extract_tags_from_ase_atoms,
+    calculate_padded_cell_simple_cubic,
+)
 from ..third_party import (
     ASEAtoms,
     PymatgenAseAtomsAdaptor,
@@ -14,11 +23,6 @@ from ..third_party import (
     PymatgenPoscar,
     PymatgenStructure,
 )
-from .utils import (
-    extract_labels_from_pymatgen_structure,
-    extract_metadata_from_pymatgen_structure,
-    extract_tags_from_ase_atoms,
-)
 
 
 def to_pymatgen(material_or_material_data: Union[Material, Dict[str, Any]]) -> PymatgenStructure:
@@ -198,15 +202,27 @@ def from_ase(ase_atoms: ASEAtoms) -> Dict[str, Any]:
     Returns:
         dict: A dictionary containing the material information in ESSE format.
     """
+    is_molecule = not any(ase_atoms.pbc)
+
+    if is_molecule:
+        lattice_vectors = calculate_padded_cell_simple_cubic(ase_atoms.get_positions())
+        ase_atoms.set_cell(lattice_vectors)
+        ase_atoms.center()
+
     # TODO: check that atomic labels/tags are properly handled
     structure = PymatgenAseAtomsAdaptor.get_structure(ase_atoms)
+
     material = from_pymatgen(structure)
+    material["isNonPeriodic"] = is_molecule
+    if is_molecule:
+        material["lattice"]["type"] = "CUB"
+
     ase_tags = extract_tags_from_ase_atoms(ase_atoms)
     material["basis"]["labels"] = ase_tags
     ase_metadata = ase_atoms.info.get("metadata", {})
     if ase_metadata:
         material["metadata"].update(ase_metadata)
-    material["name"] = ase_atoms.info.get("name", "")
+    material["name"] = ase_atoms.info.get("name", ase_atoms.get_chemical_formula())
     return material
 
 

package/src/py/mat3ra/made/tools/convert/utils.py

@@ -1,11 +1,13 @@
 import json
 from typing import Any, Dict, List, Union
 
-from mat3ra.made.utils import map_array_to_array_with_id_value
+import numpy as np
 from mat3ra.utils.object import NumpyNDArrayRoundEncoder
+from scipy.spatial.distance import pdist
 
-from ..third_party import ASEAtoms, PymatgenInterface, PymatgenStructure
+from mat3ra.made.utils import map_array_to_array_with_id_value, get_center_of_coordinates
 from .interface_parts_enum import INTERFACE_LABELS_MAP
+from ..third_party import ASEAtoms, PymatgenInterface, PymatgenStructure
 
 
 def extract_labels_from_pymatgen_structure(structure: PymatgenStructure) -> List[int]:
@@ -37,3 +39,27 @@ def extract_tags_from_ase_atoms(atoms: ASEAtoms) -> List[Union[str, int]]:
         int_tags = [int(tag) for tag in atoms.arrays["tags"] if tag is not None]
         result = map_array_to_array_with_id_value(int_tags, remove_none=True)
     return result
+
+
+def calculate_padded_cell_simple_cubic(
+    coordinates: List[List[float]], padding_factor: float = 2.0
+) -> List[List[float]]:
+    """
+    Calculate values for a padded cell for a molecule based on its coordinates.
+    Args:
+        coordinates (Array[Array[float]]): A list of atomic coordinates.
+        padding_factor (float): The factor by which to multiply the maximum distance for padding.
+    Returns:
+        Array[float]: A list containing the final cell latice vectors with padding applied.
+    """
+    positions = np.array(coordinates)
+    center = get_center_of_coordinates(positions)
+    shifted_positions = positions - center
+    max_distance = np.max(pdist(shifted_positions)) if len(positions) >= 2 else 10.0
+    padding_value = padding_factor * max_distance
+
+    return [
+        [padding_value, 0.0, 0.0],
+        [0.0, padding_value, 0.0],
+        [0.0, 0.0, padding_value],
+    ]

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/py/unit/fixtures/thrid_party/ase_atoms.py

@@ -0,0 +1,14 @@
+from ase.build import bulk, molecule
+
+
+BULK_SI_LATTICE_A = 3.8395
+BULK_SI_LATTICE_ALPHA = 60
+BULK_SI_LABELS = [{"id": 0, "value": 0}, {"id": 1, "value": 1}]
+
+atoms = bulk("Si")
+atoms.set_tags([0, 1])
+ASE_BULK_Si = atoms
+
+atoms = molecule("H2O")
+atoms.set_pbc(False)
+ASE_MOLECULE_H2O = atoms

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

package/tests/py/unit/test_tools_build_metadata.py

@@ -1,22 +1,13 @@
 import pytest
-from mat3ra.code.entity import InMemoryEntity, InMemoryEntityPydantic
+from mat3ra.code.entity import InMemoryEntityPydantic
+
 from mat3ra.made.tools.build_components.metadata import BuildMetadata, MaterialBuildMetadata
-from pydantic import BaseModel
 
 
 class ConfigWithToDict(InMemoryEntityPydantic):
     value: str = "test_dict"
 
 
-# TODO: Remove this class when all configurations moved to Pydantic
-class ConfigWithToJsonReturnsDict(BaseModel, InMemoryEntity):
-    value: str = "test_json_dict"
-
-    @property
-    def _json(self):
-        return {"value": self.value}
-
-
 class ConfigWithToJsonReturnsStr(InMemoryEntityPydantic):
     value: str = "test_json_str"
 
@@ -42,7 +33,6 @@ def test_metadata_empty_initialization():
     "config_object, expected_dict",
     [
         (ConfigWithToDict(), {"value": "test_dict"}),
-        (ConfigWithToJsonReturnsDict(), {"value": "test_json_dict"}),
         (ConfigWithToJsonReturnsStr(), {"value": "test_json_str"}),
     ],
 )

package/tests/py/unit/test_tools_convert.py

@@ -1,14 +1,20 @@
 import numpy as np
 import pytest
 from ase import Atoms
-from ase.build import bulk
 from mat3ra.code.array_with_ids import ArrayWithIds
-from mat3ra.made.material import Material
-from mat3ra.made.tools.convert import from_ase, from_poscar, from_pymatgen, to_ase, to_poscar, to_pymatgen
 from mat3ra.utils import assertion as assertion_utils
 from pymatgen.core.structure import Element, Lattice, Structure
 
+from mat3ra.made.material import Material
+from mat3ra.made.tools.convert import from_ase, from_poscar, from_pymatgen, to_ase, to_poscar, to_pymatgen
 from .fixtures.monolayer import GRAPHENE
+from .fixtures.thrid_party.ase_atoms import (
+    ASE_BULK_Si,
+    ASE_MOLECULE_H2O,
+    BULK_SI_LATTICE_A,
+    BULK_SI_LATTICE_ALPHA,
+    BULK_SI_LABELS,
+)
 
 PYMATGEN_LATTICE = Lattice.from_parameters(a=3.84, b=3.84, c=3.84, alpha=120, beta=90, gamma=60)
 PYMATGEN_STRUCTURE = Structure(PYMATGEN_LATTICE, ["Si", "Si"], [[0, 0, 0], [0.75, 0.5, 0.75]])
@@ -98,10 +104,42 @@ def test_to_ase():
     assert ase_atoms.get_tags().tolist() == [0, 1]
 
 
-def test_from_ase():
-    ase_atoms = bulk("Si")
-    ase_atoms.set_tags([0, 1])
+@pytest.mark.parametrize(
+    "ase_atoms, expected_lattice_a, expected_lattice_alpha, expected_labels,"
+    + " expected_is_non_periodic, expected_lattice_type",
+    [
+        (
+            ASE_BULK_Si,
+            BULK_SI_LATTICE_A,
+            BULK_SI_LATTICE_ALPHA,
+            BULK_SI_LABELS,
+            False,
+            None,
+        ),
+        (
+            ASE_MOLECULE_H2O,
+            None,
+            None,
+            [],
+            True,
+            "CUB",
+        ),
+    ],
+)
+def test_from_ase(
+    ase_atoms,
+    expected_lattice_a,
+    expected_lattice_alpha,
+    expected_labels,
+    expected_is_non_periodic,
+    expected_lattice_type,
+):
     material_data = from_ase(ase_atoms)
-    assert material_data["lattice"]["a"] == 3.839589822
-    assert material_data["lattice"]["alpha"] == 60
-    assert material_data["basis"]["labels"] == [{"id": 0, "value": 0}, {"id": 1, "value": 1}]
+    if expected_lattice_a is not None:
+        assertion_utils.assert_almost_equal_numbers(material_data["lattice"]["a"], expected_lattice_a, atol=1e-4)
+    if expected_lattice_alpha is not None:
+        assert material_data["lattice"]["alpha"] == expected_lattice_alpha
+    assert material_data["basis"]["labels"] == expected_labels
+    assert material_data["isNonPeriodic"] == expected_is_non_periodic
+    if expected_lattice_type is not None:
+        assert material_data["lattice"]["type"] == expected_lattice_type