@mat3ra/made 2026.7.29-0 → 2026.8.7-0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2026.7.29-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/operations/core/unary.py

@@ -17,6 +17,47 @@ 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)

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])