feature/SOF 7397

src/py/mat3ra/made/basis.py

@@ -31,7 +31,7 @@ def from_dict(
             elements=ArrayWithIds.from_list_of_dicts(elements),
             coordinates=ArrayWithIds.from_list_of_dicts(coordinates),
             units=units,
-            cell=Cell.from_nested_array(cell),
+            cell=Cell.from_vectors_array(cell),
             labels=ArrayWithIds.from_list_of_dicts(labels) if labels else ArrayWithIds(values=[]),
             constraints=ArrayWithIds.from_list_of_dicts(constraints) if constraints else ArrayWithIds(values=[]),
         )

src/py/mat3ra/made/cell.py

@@ -13,13 +13,13 @@ class Cell(RoundNumericValuesMixin, BaseModel):
     __round_precision__ = 6
 
     @classmethod
-    def from_nested_array(cls, nested_array):
-        if nested_array is None:
-            nested_array = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
-        return cls(vector1=nested_array[0], vector2=nested_array[1], vector3=nested_array[2])
+    def from_vectors_array(cls, vectors_array):
+        if vectors_array is None:
+            vectors_array = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
+        return cls(vector1=vectors_array[0], vector2=vectors_array[1], vector3=vectors_array[2])
 
     @property
-    def vectors_as_nested_array(self, skip_rounding=False) -> List[List[float]]:
+    def vectors_as_array(self, skip_rounding=False) -> List[List[float]]:
         if skip_rounding:
             return [self.vector1, self.vector2, self.vector3]
         return self.round_array_or_number([self.vector1, self.vector2, self.vector3])
@@ -33,21 +33,21 @@ def to_json(self, skip_rounding=False):
         ]
 
     def clone(self):
-        return self.from_nested_array(self.vectors_as_nested_array)
+        return self.from_vectors_array(self.vectors_as_array)
 
     def clone_and_scale_by_matrix(self, matrix):
         new_cell = self.clone()
         new_cell.scale_by_matrix(matrix)
         return new_cell
 
     def convert_point_to_cartesian(self, point):
-        np_vector = np.array(self.vectors_as_nested_array)
+        np_vector = np.array(self.vectors_as_array)
         return np.dot(point, np_vector)
 
     def convert_point_to_crystal(self, point):
-        np_vector = np.array(self.vectors_as_nested_array)
+        np_vector = np.array(self.vectors_as_array)
         return np.dot(point, np.linalg.inv(np_vector))
 
     def scale_by_matrix(self, matrix):
-        np_vector = np.array(self.vectors_as_nested_array)
+        np_vector = np.array(self.vectors_as_array)
         self.vector1, self.vector2, self.vector3 = np.dot(matrix, np_vector).tolist()

src/py/mat3ra/made/lattice.py

@@ -8,6 +8,8 @@
 from .cell import Cell
 
 HASH_TOLERANCE = 3
+DEFAULT_UNITS = {"length": "angstrom", "angle": "degree"}
+DEFAULT_TYPE = "TRI"
 
 
 class Lattice(RoundNumericValuesMixin, BaseModel):
@@ -17,11 +19,8 @@ class Lattice(RoundNumericValuesMixin, BaseModel):
     alpha: float = 90.0
     beta: float = 90.0
     gamma: float = 90.0
-    units: Dict[str, str] = {
-        "length": "angstrom",
-        "angle": "degree",
-    }
-    type: str = "TRI"
+    units: Dict[str, str] = DEFAULT_UNITS
+    type: str = DEFAULT_TYPE
 
     @property
     def vectors(self) -> List[List[float]]:
@@ -52,6 +51,29 @@ def vectors(self) -> List[List[float]]:
             [0.0, 0.0, c],
         ]
 
+    @classmethod
+    def from_vectors_array(
+        cls, vectors: List[List[float]], units: Optional[Dict[str, str]] = None, type: Optional[str] = None
+    ) -> "Lattice":
+        """
+        Create a Lattice object from a nested array of vectors.
+        Args:
+            vectors (List[List[float]]): A nested array of vectors.
+        Returns:
+            Lattice: A Lattice object.
+        """
+        a = np.linalg.norm(vectors[0])
+        b = np.linalg.norm(vectors[1])
+        c = np.linalg.norm(vectors[2])
+        alpha = np.degrees(np.arccos(np.dot(vectors[1], vectors[2]) / (b * c)))
+        beta = np.degrees(np.arccos(np.dot(vectors[0], vectors[2]) / (a * c)))
+        gamma = np.degrees(np.arccos(np.dot(vectors[0], vectors[1]) / (a * b)))
+        if units is None:
+            units = DEFAULT_UNITS
+        if type is None:
+            type = DEFAULT_TYPE
+        return cls(a=float(a), b=float(b), c=float(c), alpha=alpha, beta=beta, gamma=gamma, units=units, type=type)
+
     def to_json(self, skip_rounding: bool = False) -> Dict[str, Any]:
         __round__ = RoundNumericValuesMixin.round_array_or_number
         round_func = __round__ if not skip_rounding else lambda x: x
@@ -78,7 +100,7 @@ def vector_arrays(self) -> List[List[float]]:
 
     @property
     def cell(self) -> Cell:
-        return Cell.from_nested_array(self.vector_arrays)
+        return Cell.from_vectors_array(self.vector_arrays)
 
     def volume(self) -> float:
         np_vector = np.array(self.vector_arrays)

src/py/mat3ra/made/tools/build/defect/builders.py

@@ -463,7 +463,7 @@ def _calculate_cut_direction_vector(self, material: Material, cut_direction: Lis
             The normalized cut direction vector in Cartesian coordinates.
         """
         np_cut_direction = np.array(cut_direction)
-        direction_vector = np.dot(np.array(material.basis.cell.vectors_as_nested_array), np_cut_direction)
+        direction_vector = np.dot(np.array(material.basis.cell.vectors_as_array), np_cut_direction)
         normalized_direction_vector = direction_vector / np.linalg.norm(direction_vector)
         return normalized_direction_vector
 
@@ -499,7 +499,7 @@ def _calculate_rotation_parameters(
         """
         height_cartesian = self._calculate_height_cartesian(original_material, new_material)
         cut_direction_xy_proj_cart = np.linalg.norm(
-            np.dot(np.array(new_material.basis.cell.vectors_as_nested_array), normalized_direction_vector)
+            np.dot(np.array(new_material.basis.cell.vectors_as_array), normalized_direction_vector)
         )
         # Slope of the terrace along the cut direction
         hypotenuse = np.linalg.norm([height_cartesian, cut_direction_xy_proj_cart])

src/py/mat3ra/made/tools/build/interface/builders.py

@@ -1,6 +1,7 @@
 from typing import Any, List, Optional
 
 import numpy as np
+from mat3ra.made.tools.modify import translate_to_z_level
 from pydantic import BaseModel
 from ase.build.tools import niggli_reduce
 from pymatgen.analysis.interfaces.coherent_interfaces import (
@@ -144,9 +145,11 @@ class ZSLStrainMatchingInterfaceBuilder(ConvertGeneratedItemsPymatgenStructureMi
 
     def _generate(self, configuration: InterfaceConfiguration) -> List[PymatgenInterface]:
         generator = ZSLGenerator(**self.build_parameters.strain_matching_parameters.dict())
+        substrate_down = translate_to_z_level(configuration.substrate_configuration.bulk, "bottom")
+        film_down = translate_to_z_level(configuration.film_configuration.bulk, "bottom")
         builder = CoherentInterfaceBuilder(
-            substrate_structure=to_pymatgen(configuration.substrate_configuration.bulk),
-            film_structure=to_pymatgen(configuration.film_configuration.bulk),
+            substrate_structure=to_pymatgen(substrate_down),
+            film_structure=to_pymatgen(film_down),
             substrate_miller=configuration.substrate_configuration.miller_indices,
             film_miller=configuration.film_configuration.miller_indices,
             zslgen=generator,

src/py/mat3ra/made/tools/build/perturbation/__init__.py

@@ -0,0 +1,38 @@
+from typing import Union, Optional
+
+from mat3ra.made.material import Material
+from .builders import (
+    SlabPerturbationBuilder,
+    DistancePreservingSlabPerturbationBuilder,
+    CellMatchingDistancePreservingSlabPerturbationBuilder,
+)
+from .configuration import PerturbationConfiguration
+from .builders import PerturbationFunctionHolder  # type: ignore
+
+
+def create_perturbation(
+    configuration: PerturbationConfiguration,
+    preserve_distance: Optional[bool] = False,
+    builder: Union[
+        SlabPerturbationBuilder,
+        DistancePreservingSlabPerturbationBuilder,
+        CellMatchingDistancePreservingSlabPerturbationBuilder,
+        None,
+    ] = None,
+) -> Material:
+    """
+    Return a material with a perturbation applied.
+
+    Args:
+        configuration: The configuration of the perturbation to be applied.
+        preserve_distance: If True, the builder that preserves the distance between atoms is used.
+        builder: The builder to be used to create the perturbation.
+
+    Returns:
+        The material with the perturbation applied.
+    """
+    if builder is None:
+        builder = SlabPerturbationBuilder()
+    if preserve_distance:
+        builder = CellMatchingDistancePreservingSlabPerturbationBuilder()
+    return builder.get_material(configuration)

src/py/mat3ra/made/tools/build/perturbation/builders.py

@@ -0,0 +1,91 @@
+from typing import List, Optional, Any
+
+from mat3ra.made.material import Material
+from mat3ra.made.tools.build import BaseBuilder
+
+from .configuration import PerturbationConfiguration
+from ...modify import wrap_material, translate_to_z_level
+from ...utils import PerturbationFunctionHolder
+
+
+class PerturbationBuilder(BaseBuilder):
+    _ConfigurationType: type(PerturbationConfiguration) = PerturbationConfiguration  # type: ignore
+    _GeneratedItemType: Material = Material
+    _PostProcessParametersType: Any = None
+
+    @staticmethod
+    def _prepare_material(configuration):
+        new_material = configuration.material.clone()
+        new_material = translate_to_z_level(new_material, "center")
+        if configuration.use_cartesian_coordinates:
+            new_material.to_cartesian()
+        return new_material
+
+    @staticmethod
+    def _set_new_coordinates(new_material, new_coordinates):
+        new_basis = new_material.basis.copy()
+        new_basis.coordinates.values = new_coordinates
+        new_basis.to_crystal()
+        new_material.basis = new_basis
+        return new_material
+
+    def _generate(self, configuration: _ConfigurationType) -> List[_GeneratedItemType]:
+        """Generate materials with applied continuous perturbation based on the given configuration."""
+        new_material = self.create_perturbed_slab(configuration)
+        return [new_material]
+
+    def _post_process(
+        self,
+        items: List[_GeneratedItemType],
+        post_process_parameters: Optional[_PostProcessParametersType],
+    ) -> List[Material]:
+        return [wrap_material(item) for item in items]
+
+    def _update_material_name(self, material: Material, configuration: _ConfigurationType) -> Material:
+        perturbation_details = f"Perturbation: {configuration.perturbation_function[1].get('type')}"
+        material.name = f"{material.name} ({perturbation_details})"
+        return material
+
+
+class SlabPerturbationBuilder(PerturbationBuilder):
+    def create_perturbed_slab(self, configuration):
+        new_material = self._prepare_material(configuration)
+        perturbation_function, _ = configuration.perturbation_function
+        new_coordinates = [perturbation_function(coord) for coord in new_material.basis.coordinates.values]
+        new_material = self._set_new_coordinates(new_material, new_coordinates)
+        return new_material
+
+
+class DistancePreservingSlabPerturbationBuilder(SlabPerturbationBuilder):
+    def create_perturbed_slab(self, configuration):
+        new_material = self._prepare_material(configuration)
+        perturbation_function, perturbation_json = configuration.perturbation_function
+        coord_transformation_function = PerturbationFunctionHolder.get_coord_transformation(perturbation_json)
+        new_coordinates = [
+            perturbation_function(coord_transformation_function(coord))
+            for coord in new_material.basis.coordinates.values
+        ]
+        new_material = self._set_new_coordinates(new_material, new_coordinates)
+        return new_material
+
+
+class CellMatchingDistancePreservingSlabPerturbationBuilder(DistancePreservingSlabPerturbationBuilder):
+    def _transform_cell_vectors(self, configuration: PerturbationConfiguration) -> List[List[float]]:
+        perturbation_function, perturbation_json = configuration.perturbation_function
+        coord_transformation_function = PerturbationFunctionHolder.get_coord_transformation(perturbation_json)
+        cell_vectors = configuration.material.basis.cell.vectors_as_array
+        return [perturbation_function(coord_transformation_function(coord)) for coord in cell_vectors]
+
+    def create_perturbed_slab(self, configuration: PerturbationConfiguration):
+        new_material = super().create_perturbed_slab(configuration)
+        new_lattice_vectors = self._transform_cell_vectors(configuration)
+        new_lattice = new_material.lattice.copy()
+        new_lattice = new_lattice.from_vectors_array(new_lattice_vectors)
+        new_material.lattice = new_lattice
+
+        new_basis = new_material.basis.copy()
+        new_basis.to_cartesian()
+        new_basis.cell = new_basis.cell.from_vectors_array(new_lattice_vectors)
+        new_basis.to_crystal()
+        new_material.basis = new_basis
+        return new_material

src/py/mat3ra/made/tools/build/perturbation/configuration.py

@@ -0,0 +1,26 @@
+from typing import Callable, Dict, Tuple
+
+from mat3ra.code.entity import InMemoryEntity
+from mat3ra.made.material import Material
+from pydantic import BaseModel
+
+from ...utils import PerturbationFunctionHolder
+
+
+class PerturbationConfiguration(BaseModel, InMemoryEntity):
+    material: Material
+    perturbation_function: Tuple[Callable, Dict] = PerturbationFunctionHolder.sine_wave()
+    use_cartesian_coordinates: bool = True
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    @property
+    def _json(self):
+        _, perturbation_function_json = self.perturbation_function
+        return {
+            "type": self.get_cls_name(),
+            "material": self.material.to_json(),
+            "perturbation_function": perturbation_function_json,
+            "use_cartesian_coordinates": self.use_cartesian_coordinates,
+        }

src/py/mat3ra/made/tools/build/supercell.py

@@ -2,28 +2,32 @@
 
 import numpy as np
 from mat3ra.made.material import Material
-from ..third_party import ASEAtoms, ase_make_supercell
+from ..third_party import ase_make_supercell
 from ..utils import decorator_convert_2x2_to_3x3
-from ..convert import from_ase, decorator_convert_material_args_kwargs_to_atoms
+from ..convert import from_ase, to_ase
 
 
 @decorator_convert_2x2_to_3x3
-@decorator_convert_material_args_kwargs_to_atoms
 def create_supercell(
-    atoms: ASEAtoms, supercell_matrix: Optional[List[List[int]]] = None, scaling_factor: Optional[List[int]] = None
+    material: Material, supercell_matrix: Optional[List[List[int]]] = None, scaling_factor: Optional[List[int]] = None
 ) -> Material:
     """
     Create a supercell of the atoms.
 
     Args:
-        atoms (Material): The atoms to create a supercell of.
+        material (Material): The atoms to create a supercell of.
         supercell_matrix (List[List[int]]): The supercell matrix (e.g. [[3,0,0],[0,3,0],[0,0,1]]).
         scaling_factor (List[int], optional): The scaling factor instead of matrix (e.g. [3,3,1]).
 
     Returns:
         Material: The supercell of the atoms.
     """
+    atoms = to_ase(material)
     if scaling_factor is not None:
         supercell_matrix = np.multiply(scaling_factor, np.eye(3)).tolist()
     supercell_atoms = ase_make_supercell(atoms, supercell_matrix)
-    return Material(from_ase(supercell_atoms))
+    new_material = Material(from_ase(supercell_atoms))
+    if material.metadata:
+        new_material.metadata = material.metadata
+    new_material.name = material.name
+    return new_material

src/py/mat3ra/made/tools/modify.py

@@ -9,7 +9,7 @@
 )
 from .convert import decorator_convert_material_args_kwargs_to_structure, from_ase, to_ase
 from .third_party import PymatgenStructure, ase_add_vacuum
-from .utils import (
+from .utils.coordinate import (
     is_coordinate_in_box,
     is_coordinate_in_cylinder,
     is_coordinate_in_triangular_prism,
@@ -437,3 +437,17 @@ def rotate_material(material: Material, axis: List[int], angle: float) -> Materi
     atoms.wrap()
 
     return Material(from_ase(atoms))
+
+
+def wrap_material(material: Material) -> Material:
+    """
+    Wrap the material to the unit cell.
+
+    Args:
+        material (Material): The material to wrap.
+    Returns:
+        Material: The wrapped material.
+    """
+    atoms = to_ase(material)
+    atoms.wrap()
+    return Material(from_ase(atoms))