@mat3ra/made 2024.7.2-0 → 2024.7.8-0

package/package.json

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

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

@@ -67,13 +67,13 @@ class Basis(RoundNumericValuesMixin, BaseModel):
     def to_cartesian(self):
         if self.is_in_cartesian_units:
             return
-        self.coordinates = self.coordinates.map_array_in_place(self.cell.convert_point_to_cartesian)
+        self.coordinates.map_array_in_place(self.cell.convert_point_to_cartesian)
         self.units = AtomicCoordinateUnits.cartesian
 
     def to_crystal(self):
         if self.is_in_crystal_units:
             return
-        self.coordinates = self.coordinates.map_array_in_place(self.cell.convert_point_to_crystal)
+        self.coordinates.map_array_in_place(self.cell.convert_point_to_crystal)
         self.units = AtomicCoordinateUnits.crystal
 
     def add_atom(self, element="Si", coordinate=[0.5, 0.5, 0.5]):

package/src/py/mat3ra/made/cell.py

@@ -44,7 +44,7 @@ class Cell(RoundNumericValuesMixin, BaseModel):
         np_vector = np.array(self.vectors_as_nested_array)
         return np.dot(point, np_vector)
 
-    def convert_point_to_fractional(self, point):
+    def convert_point_to_crystal(self, point):
         np_vector = np.array(self.vectors_as_nested_array)
         return np.dot(point, np.linalg.inv(np_vector))
 

package/src/py/mat3ra/made/tools/analyze.py

@@ -1,10 +1,10 @@
-from typing import Callable, List, Optional
+from typing import Callable, List, Literal, Optional
 
 import numpy as np
 
 from ..material import Material
 from .convert import decorator_convert_material_args_kwargs_to_atoms, to_pymatgen
-from .third_party import ASEAtoms, PymatgenIStructure
+from .third_party import ASEAtoms, PymatgenIStructure, PymatgenVoronoiNN
 
 
 @decorator_convert_material_args_kwargs_to_atoms
@@ -211,7 +211,7 @@ def get_atom_indices_with_condition_on_coordinates(
     Args:
         material (Material): Material object
         condition (Callable[List[float], bool]): Function that checks if coordinates satisfy the condition.
-        use_cartesian (bool): Whether to use Cartesian coordinates for the condition evaluation.
+        use_cartesian_coordinates (bool): Whether to use Cartesian coordinates for the condition evaluation.
 
     Returns:
         List[int]: List of indices of atoms whose coordinates satisfy the condition.
@@ -229,3 +229,65 @@ def get_atom_indices_with_condition_on_coordinates(
             selected_indices.append(coord.id)
 
     return selected_indices
+
+
+def get_nearest_neighbors_atom_indices(
+    material: Material,
+    position: Optional[List[float]] = None,
+) -> Optional[List[int]]:
+    """
+    Returns the indices of direct neighboring atoms to a specified position in the material using Voronoi tessellation.
+
+    Args:
+        material (Material): The material object to find neighbors in.
+        position (List[float]): The position to find neighbors for.
+
+    Returns:
+        List[int]: A list of indices of neighboring atoms, or an empty list if no neighbors are found.
+    """
+    if position is None:
+        position = [0, 0, 0]
+    structure = to_pymatgen(material)
+    voronoi_nn = PymatgenVoronoiNN(
+        tol=0.5,
+        cutoff=13.0,
+        allow_pathological=False,
+        weight="solid_angle",
+        extra_nn_info=True,
+        compute_adj_neighbors=True,
+    )
+    structure.append("X", position, validate_proximity=False)
+    neighbors = voronoi_nn.get_nn_info(structure, len(structure.sites) - 1)
+    neighboring_atoms_pymatgen_ids = [n["site_index"] for n in neighbors]
+    structure.remove_sites([-1])
+
+    all_coordinates = material.basis.coordinates
+    all_coordinates.filter_by_indices(neighboring_atoms_pymatgen_ids)
+    return all_coordinates.ids
+
+
+def get_atomic_coordinates_extremum(
+    material: Material,
+    extremum: Literal["max", "min"] = "max",
+    axis: Literal["x", "y", "z"] = "z",
+    use_cartesian_coordinates: bool = False,
+) -> float:
+    """
+    Return minimum or maximum of coordinates along the specified axis.
+
+    Args:
+        material (Material): Material object.
+        extremum (str): "min" or "max".
+        axis (str):  "x", "y", or "z".
+        use_cartesian_coordinates (bool): Whether to use Cartesian coordinates.
+    Returns:
+        float: Minimum or maximum of coordinates along the specified axis.
+    """
+    new_material = material.clone()
+    if use_cartesian_coordinates:
+        new_basis = new_material.basis
+        new_basis.to_cartesian()
+        new_material.basis = new_basis
+    coordinates = new_material.basis.coordinates.to_array_of_values_with_ids()
+    values = [coord.value[{"x": 0, "y": 1, "z": 2}[axis]] for coord in coordinates]
+    return getattr(np, extremum)(values)

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

@@ -65,6 +65,8 @@ class BaseBuilder(BaseModel):
     def _post_process(
         self, items: List[_GeneratedItemType], post_process_parameters: Optional[_PostProcessParametersType]
     ) -> List[Material]:
+        if self._GeneratedItemType == Material:
+            return items
         return [Material(self._convert_generated_item(item)) for item in items]
 
     @staticmethod

package/src/py/mat3ra/made/tools/build/defect/__init__.py

@@ -1,11 +1,16 @@
-from typing import Optional
+from typing import Optional, Union
 
 from mat3ra.utils.factory import BaseFactory
 from mat3ra.made.material import Material
 
-from .builders import PointDefectBuilderParameters
-from .configuration import PointDefectConfiguration
-from .enums import PointDefectTypeEnum
+from .builders import (
+    PointDefectBuilderParameters,
+    SlabDefectBuilderParameters,
+    AdatomSlabDefectBuilder,
+    EquidistantAdatomSlabDefectBuilder,
+)
+from .configuration import PointDefectConfiguration, AdatomSlabDefectConfiguration
+from .enums import PointDefectTypeEnum, SlabDefectTypeEnum
 
 
 class DefectBuilderFactory(BaseFactory):
@@ -17,8 +22,8 @@ class DefectBuilderFactory(BaseFactory):
 
 
 def create_defect(
-    configuration: PointDefectConfiguration,
-    builder_parameters: Optional[PointDefectBuilderParameters] = None,
+    configuration: Union[PointDefectConfiguration, AdatomSlabDefectConfiguration],
+    builder_parameters: Union[PointDefectBuilderParameters, SlabDefectBuilderParameters, None] = None,
 ) -> Material:
     """
     Return a material with a selected defect added.
@@ -34,3 +39,22 @@ def create_defect(
     builder = BuilderClass(builder_parameters)
 
     return builder.get_material(configuration) if builder else configuration.crystal
+
+
+def create_slab_defect(
+    configuration: Union[AdatomSlabDefectConfiguration],
+    builder: Optional[Union[AdatomSlabDefectBuilder, EquidistantAdatomSlabDefectBuilder]] = None,
+) -> Material:
+    """
+    Return a material with a selected slab defect added.
+
+    Args:
+        configuration: The configuration of the defect to be added.
+        builder: The builder to be used to create the defect.
+
+    Returns:
+        The material with the defect added.
+    """
+    if builder is None:
+        builder = AdatomSlabDefectBuilder(build_parameters=SlabDefectBuilderParameters())
+    return builder.get_material(configuration)

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

@@ -1,7 +1,10 @@
-from typing import List, Callable
+from typing import List, Callable, Optional
 
-from mat3ra.made.material import Material
+from mat3ra.made.tools.build.supercell import create_supercell
+from mat3ra.made.tools.modify import add_vacuum
 from pydantic import BaseModel
+from mat3ra.made.material import Material
+
 
 from ...third_party import (
     PymatgenStructure,
@@ -12,8 +15,10 @@ from ...third_party import (
 )
 from ...build import BaseBuilder
 from ...convert import to_pymatgen
+from ...analyze import get_nearest_neighbors_atom_indices, get_atomic_coordinates_extremum
+from ....utils import get_center_of_coordinates
 from ..mixins import ConvertGeneratedItemsPymatgenStructureMixin
-from .configuration import PointDefectConfiguration
+from .configuration import PointDefectConfiguration, AdatomSlabDefectConfiguration
 
 
 class PointDefectBuilderParameters(BaseModel):
@@ -67,3 +72,124 @@ class SubstitutionPointDefectBuilder(PointDefectBuilder):
 
 class InterstitialPointDefectBuilder(PointDefectBuilder):
     _generator: PymatgenInterstitial = PymatgenInterstitial
+
+
+class SlabDefectBuilderParameters(BaseModel):
+    auto_add_vacuum: bool = True
+    vacuum_thickness: float = 5.0
+
+
+class SlabDefectBuilder(BaseBuilder):
+    _BuildParametersType = SlabDefectBuilderParameters
+    _DefaultBuildParameters = SlabDefectBuilderParameters()
+
+
+class AdatomSlabDefectBuilder(SlabDefectBuilder):
+    _ConfigurationType: type(AdatomSlabDefectConfiguration) = AdatomSlabDefectConfiguration  # type: ignore
+    _GeneratedItemType: Material = Material
+
+    def create_adatom(
+        self,
+        material: Material,
+        chemical_element: str = "Si",
+        position_on_surface: Optional[List[float]] = None,
+        distance_z: float = 2.0,
+    ) -> List[Material]:
+        """
+        Create an adatom at the specified position on the surface of the material.
+
+        Args:
+            material: The material to add the adatom to.
+            chemical_element: The chemical element of the adatom.
+            position_on_surface: The position on the surface of the material.
+            distance_z: The distance of the adatom from the surface.
+
+        Returns:
+            The material with the adatom added.
+        """
+        if position_on_surface is None:
+            position_on_surface = [0.5, 0.5]
+        new_material = material.clone()
+        new_basis = new_material.basis
+        adatom_position = self._calculate_position_from_2d(material, position_on_surface, distance_z)
+        new_basis.add_atom(chemical_element, adatom_position)
+        new_material.basis = new_basis
+        return [new_material]
+
+    def _calculate_position_from_2d(
+        self, material: Material, position_on_surface: List[float], distance_z: float
+    ) -> List[float]:
+        max_z = get_atomic_coordinates_extremum(material)
+        distance_z = distance_z
+        distance_in_crystal_units = distance_z / material.lattice.c
+        position = position_on_surface.copy()
+        position = position[:2]
+        position.append(max_z + distance_in_crystal_units)
+        return position
+
+    def _generate(self, configuration: _ConfigurationType) -> List[_GeneratedItemType]:
+        return self.create_adatom(
+            material=configuration.crystal,
+            chemical_element=configuration.chemical_element,
+            position_on_surface=configuration.position_on_surface,
+            distance_z=configuration.distance_z,
+        )
+
+
+class EquidistantAdatomSlabDefectBuilder(AdatomSlabDefectBuilder):
+    def create_adatom(
+        self,
+        material: Material,
+        chemical_element: str = "Si",
+        position_on_surface: Optional[List[float]] = None,
+        distance_z: float = 2.0,
+    ) -> List[Material]:
+        """
+        Create an adatom with an equidistant XY position among the nearest neighbors
+        at the given distance from the surface.
+
+        Args:
+            material: The material to add the adatom to.
+            chemical_element: The chemical element of the adatom.
+            position_on_surface: The position on the surface of the material.
+            distance_z: The distance of the adatom from the surface.
+
+        Returns:
+            The material with the adatom added.
+        """
+        if position_on_surface is None:
+            position_on_surface = [0.5, 0.5]
+        equidistant_position = self.get_equidistant_position(material, position_on_surface, distance_z)
+        new_material = material.clone()
+        if equidistant_position[2] > 1:
+            if self.build_parameters.auto_add_vacuum:
+                new_material = add_vacuum(material, self.build_parameters.vacuum_thickness)
+                equidistant_position = self.get_equidistant_position(new_material, position_on_surface, distance_z)
+            else:
+                raise ValueError("Not enough vacuum space to place the adatom.")
+
+        return super().create_adatom(new_material, chemical_element, equidistant_position, distance_z)
+
+    def get_equidistant_position(
+        self, material: Material, position_on_surface: List[float], distance_z: float = 2.0
+    ) -> List[float]:
+        new_basis = material.basis
+        adatom_position = self._calculate_position_from_2d(material, position_on_surface, distance_z)
+        neighboring_atoms_ids = get_nearest_neighbors_atom_indices(material, adatom_position)
+        # We need to check if neighboring atoms number is the same in pbc
+        supercell_material = create_supercell(material, [[3, 0, 0], [0, 3, 0], [0, 0, 1]])
+        # Move the coordinate to the central unit cell of the supercell (crystal coordinates)
+        supercell_adatom_position = [1 / 3 + adatom_position[0] / 3, 1 / 3 + adatom_position[1] / 3, adatom_position[2]]
+        supercell_neighboring_atoms_ids = get_nearest_neighbors_atom_indices(
+            supercell_material, supercell_adatom_position
+        )
+        if neighboring_atoms_ids is None or supercell_neighboring_atoms_ids is None:
+            raise ValueError("No neighboring atoms found. Try reducing the distance_z.")
+        if len(supercell_neighboring_atoms_ids) != len(neighboring_atoms_ids):
+            raise ValueError("Number of neighboring atoms is not the same in PBC. Try increasing the supercell size.")
+        neighboring_atoms_coordinates = [new_basis.coordinates.values[atom_id] for atom_id in neighboring_atoms_ids]
+
+        equidistant_position = get_center_of_coordinates(neighboring_atoms_coordinates)
+        equidistant_position[2] = adatom_position[2]
+
+        return equidistant_position

package/src/py/mat3ra/made/tools/build/defect/configuration.py

@@ -5,7 +5,7 @@ from mat3ra.code.entity import InMemoryEntity
 from mat3ra.made.material import Material
 
 from ...analyze import get_closest_site_id_from_position
-from .enums import PointDefectTypeEnum
+from .enums import PointDefectTypeEnum, SlabDefectTypeEnum
 
 
 class BaseDefectConfiguration(BaseModel):
@@ -23,7 +23,7 @@ class PointDefectConfiguration(BaseDefectConfiguration, InMemoryEntity):
         cls, crystal: Material, defect_type: PointDefectTypeEnum, site_id: int, chemical_element: Optional[str] = None
     ):
         if not crystal:
-            RuntimeError("Crystal is not defined")
+            raise RuntimeError("Crystal is not defined")
         position = crystal.coordinates_array[site_id]
         return cls(crystal=crystal, defect_type=defect_type, position=position, chemical_element=chemical_element)
 
@@ -36,7 +36,7 @@ class PointDefectConfiguration(BaseDefectConfiguration, InMemoryEntity):
         chemical_element: Optional[str] = None,
     ):
         if not crystal:
-            RuntimeError("Crystal is not defined")
+            raise RuntimeError("Crystal is not defined")
         closest_site_id = get_closest_site_id_from_position(crystal, approximate_position)
         return cls.from_site_id(
             crystal=crystal, defect_type=defect_type, site_id=closest_site_id, chemical_element=chemical_element
@@ -50,3 +50,24 @@ class PointDefectConfiguration(BaseDefectConfiguration, InMemoryEntity):
             "position": self.position,
             "chemical_element": self.chemical_element,
         }
+
+
+class SlabDefectConfiguration(BaseDefectConfiguration, InMemoryEntity):
+    pass
+
+
+class AdatomSlabDefectConfiguration(SlabDefectConfiguration):
+    defect_type: SlabDefectTypeEnum = SlabDefectTypeEnum.ADATOM
+    position_on_surface: List[float] = [0.5, 0.5]
+    distance_z: float = 2.0
+    chemical_element: str = "Si"
+
+    @property
+    def _json(self):
+        return {
+            "type": "AdatomSlabDefectConfiguration",
+            "defect_type": self.defect_type.name,
+            "position_on_surface": self.position_on_surface,
+            "distance_z": self.distance_z,
+            "chemical_element": self.chemical_element,
+        }

package/src/py/mat3ra/made/tools/build/defect/enums.py

@@ -5,3 +5,7 @@ class PointDefectTypeEnum(str, Enum):
     VACANCY = "vacancy"
     SUBSTITUTION = "substitution"
     INTERSTITIAL = "interstitial"
+
+
+class SlabDefectTypeEnum(str, Enum):
+    ADATOM = "adatom"

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

@@ -184,6 +184,8 @@ def to_ase(material_or_material_data: Union[Material, Dict[str, Any]]) -> ASEAto
         atoms.set_tags(map_array_with_id_value_to_array(atomic_labels))
     if "metadata" in material_config:
         atoms.info.update({"metadata": material_config["metadata"]})
+
+    atoms.info.update({"name": material_config["name"]})
     return atoms
 
 
@@ -205,6 +207,7 @@ def from_ase(ase_atoms: ASEAtoms) -> Dict[str, Any]:
     ase_metadata = ase_atoms.info.get("metadata", {})
     if ase_metadata:
         material["metadata"].update(ase_metadata)
+    material["name"] = ase_atoms.info.get("name", "")
     return material
 
 

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

@@ -1,17 +1,19 @@
-from typing import Callable, List, Optional, Union
+from typing import Callable, List, Literal, Optional, Union
 
-import numpy as np
 from mat3ra.made.material import Material
 
-from .analyze import get_atom_indices_with_condition_on_coordinates, get_atom_indices_within_radius_pbc
-from .convert import decorator_convert_material_args_kwargs_to_structure
-from .third_party import PymatgenSpacegroupAnalyzer, PymatgenStructure
+from .analyze import (
+    get_atom_indices_with_condition_on_coordinates,
+    get_atom_indices_within_radius_pbc,
+    get_atomic_coordinates_extremum,
+)
+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 (
     is_coordinate_in_box,
     is_coordinate_in_cylinder,
     is_coordinate_in_triangular_prism,
     is_coordinate_within_layer,
-    translate_to_bottom_pymatgen_structure,
 )
 
 
@@ -35,22 +37,54 @@ def filter_by_label(material: Material, label: Union[int, str]) -> Material:
     return new_material
 
 
-@decorator_convert_material_args_kwargs_to_structure
-def translate_to_bottom(structure: PymatgenStructure, use_conventional_cell: bool = True):
+def translate_to_z_level(
+    material: Material, z_level: Optional[Literal["top", "bottom", "center"]] = "bottom"
+) -> Material:
     """
-    Translate atoms to the bottom of the cell (vacuum on top) to allow for the correct consecutive interface generation.
-    If use_conventional_cell is passed, conventional cell is used.
+    Translate atoms to the specified z-level.
 
     Args:
-        structure (Structure): The pymatgen Structure object to normalize.
-        use_conventional_cell: Whether to convert to the conventional cell.
+        material (Material): The material object to normalize.
+        z_level (str): The z-level to translate the atoms to (top, bottom, center)
     Returns:
-        Structure: The normalized pymatgen Structure object.
+        Material: The translated material object.
     """
-    if use_conventional_cell:
-        structure = PymatgenSpacegroupAnalyzer(structure).get_conventional_standard_structure()
-    structure = translate_to_bottom_pymatgen_structure(structure)
-    return structure
+    min_z = get_atomic_coordinates_extremum(material, "min")
+    max_z = get_atomic_coordinates_extremum(material)
+    if z_level == "top":
+        material = translate_by_vector(material, vector=[0, 0, 1 - max_z])
+    elif z_level == "bottom":
+        material = translate_by_vector(material, vector=[0, 0, -min_z])
+    elif z_level == "center":
+        material = translate_by_vector(material, vector=[0, 0, (1 - min_z - max_z) / 2])
+    return material
+
+
+def translate_by_vector(
+    material: Material,
+    vector: Optional[List[float]] = None,
+    use_cartesian_coordinates: bool = False,
+) -> Material:
+    """
+    Translate atoms by a vector.
+
+    Args:
+        material (Material): The material object to normalize.
+        vector (List[float]): The vector to translate the atoms by (in crystal coordinates by default).
+        use_cartesian_coordinates (bool): Whether to use cartesian coordinates.
+    Returns:
+        Material: The translated material object.
+    """
+    if not use_cartesian_coordinates:
+        vector = material.basis.cell.convert_point_to_cartesian(vector)
+
+    if vector is None:
+        vector = [0, 0, 0]
+
+    atoms = to_ase(material)
+    # ASE accepts cartesian coordinates for translation
+    atoms.translate(tuple(vector))
+    return Material(from_ase(atoms))
 
 
 @decorator_convert_material_args_kwargs_to_structure
@@ -140,7 +174,7 @@ def filter_by_layers(
     if central_atom_id is not None:
         center_coordinate = material.basis.coordinates.get_element_value_by_index(central_atom_id)
     vectors = material.lattice.vectors
-    direction_vector = np.array(vectors[2])
+    direction_vector = vectors[2]
 
     def condition(coordinate):
         return is_coordinate_within_layer(coordinate, center_coordinate, direction_vector, layer_thickness)
@@ -323,3 +357,61 @@ def filter_by_triangle_projection(
     return filter_by_condition_on_coordinates(
         material, condition, use_cartesian_coordinates=use_cartesian_coordinates, invert_selection=invert_selection
     )
+
+
+def add_vacuum(material: Material, vacuum: float = 5.0, on_top=True, to_bottom=False) -> Material:
+    """
+    Add vacuum to the material along the c-axis.
+    On top, on bottom, or both.
+
+    Args:
+        material (Material): The material object to add vacuum to.
+        vacuum (float): The thickness of the vacuum to add in angstroms.
+        on_top (bool): Whether to add vacuum on top.
+        to_bottom (bool): Whether to add vacuum on bottom.
+
+    Returns:
+        Material: The material object with vacuum added.
+    """
+    new_material_atoms = to_ase(material)
+    vacuum_amount = vacuum * 2 if on_top and to_bottom else vacuum
+    ase_add_vacuum(new_material_atoms, vacuum_amount)
+    new_material = Material(from_ase(new_material_atoms))
+    if to_bottom and not on_top:
+        new_material = translate_to_z_level(new_material, z_level="top")
+    elif on_top and to_bottom:
+        new_material = translate_to_z_level(new_material, z_level="center")
+    return new_material
+
+
+def remove_vacuum(material: Material, from_top=True, from_bottom=True, fixed_padding=1.0) -> Material:
+    """
+    Remove vacuum from the material along the c-axis.
+    From top, from bottom, or from both.
+
+    Args:
+        material (Material): The material object to set the vacuum thickness.
+        from_top (bool): Whether to remove vacuum from the top.
+        from_bottom (bool): Whether to remove vacuum from the bottom.
+        fixed_padding (float): The fixed padding of vacuum to add to avoid collisions in pbc (in angstroms).
+
+    Returns:
+        Material: The material object with the vacuum thickness set.
+    """
+    translated_material = translate_to_z_level(material, z_level="bottom")
+    new_basis = translated_material.basis
+    new_basis.to_cartesian()
+    new_lattice = translated_material.lattice
+    new_lattice.c = get_atomic_coordinates_extremum(translated_material, use_cartesian_coordinates=True) + fixed_padding
+    new_basis.cell.vector3 = new_lattice.vectors[2]
+    new_basis.to_crystal()
+    new_material = material.clone()
+
+    new_material.basis = new_basis
+    new_material.lattice = new_lattice
+
+    if from_top and not from_bottom:
+        new_material = translate_to_z_level(new_material, z_level="top")
+    if from_bottom and not from_top:
+        new_material = translate_to_z_level(new_material, z_level="bottom")
+    return new_material

package/src/py/mat3ra/made/tools/third_party.py

@@ -1,10 +1,12 @@
 from ase import Atoms as ASEAtoms
+from ase.build import add_vacuum as ase_add_vacuum
 from ase.build.supercells import make_supercell as ase_make_supercell
 from ase.calculators.calculator import Calculator as ASECalculator
 from ase.calculators.emt import EMT as ASECalculatorEMT
 from pymatgen.analysis.defects.core import Interstitial as PymatgenInterstitial
 from pymatgen.analysis.defects.core import Substitution as PymatgenSubstitution
 from pymatgen.analysis.defects.core import Vacancy as PymatgenVacancy
+from pymatgen.analysis.local_env import VoronoiNN as PymatgenVoronoiNN
 from pymatgen.core import IStructure as PymatgenIStructure
 from pymatgen.core import PeriodicSite as PymatgenPeriodicSite
 from pymatgen.core.interface import Interface as PymatgenInterface
@@ -36,6 +38,8 @@ __all__ = [
     "PymatgenInterstitial",
     "label_pymatgen_slab_termination",
     "ase_make_supercell",
+    "ase_add_vacuum",
     "PymatgenAseAtomsAdaptor",
     "PymatgenPoscar",
+    "PymatgenVoronoiNN",
 ]

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

@@ -1,6 +1,7 @@
 import json
 from typing import Any, Callable, Dict, List, Optional, Union
 
+import numpy as np
 from mat3ra.utils.array import convert_to_array_if_not
 from mat3ra.utils.mixins import RoundNumericValuesMixin
 from pydantic import BaseModel
@@ -44,6 +45,19 @@ def are_arrays_equal_by_id_value(array1: List[Dict[str, Any]], array2: List[Dict
     return map_array_with_id_value_to_array(array1) == map_array_with_id_value_to_array(array2)
 
 
+def get_center_of_coordinates(coordinates: List[List[float]]) -> List[float]:
+    """
+    Calculate the center of the coordinates.
+
+    Args:
+        coordinates (List[List[float]]): The list of coordinates.
+
+    Returns:
+        List[float]: The center of the coordinates.
+    """
+    return list(np.mean(np.array(coordinates), axis=0))
+
+
 class ValueWithId(RoundNumericValuesMixin, BaseModel):
     id: int = 0
     value: Any = None

package/tests/py/unit/fixtures.py

@@ -1,3 +1,6 @@
+import copy
+from typing import Any, Dict
+
 from ase.build import bulk
 from mat3ra.made.material import Material
 from mat3ra.made.tools.build.interface.termination_pair import TerminationPair
@@ -59,7 +62,7 @@ INTERFACE_STRUCTURE.interface_properties = INTERFACE_PROPERTIES_MOCK
 INTERFACE_NAME = "Cu4(001)-Si8(001), Interface, Strain 0.062pct"
 
 # TODO: Use fixtures package when available
-SI_CONVENTIONAL_CELL = {
+SI_CONVENTIONAL_CELL: Dict[str, Any] = {
     "name": "Si8",
     "basis": {
         "elements": [
@@ -110,7 +113,7 @@ SI_CONVENTIONAL_CELL = {
     "isUpdated": True,
 }
 
-SI_SUPERCELL_2X2X1 = {
+SI_SUPERCELL_2X2X1: Dict[str, Any] = {
     "name": "Si8",
     "basis": {
         "elements": [
@@ -162,7 +165,7 @@ SI_SUPERCELL_2X2X1 = {
 }
 
 
-SI_SLAB_CONFIGURATION = {
+SI_SLAB_CONFIGURATION: Dict[str, Any] = {
     "type": "SlabConfiguration",
     "bulk": SI_CONVENTIONAL_CELL,
     "miller_indices": (0, 0, 1),
@@ -173,9 +176,7 @@ SI_SLAB_CONFIGURATION = {
     "use_orthogonal_z": True,
 }
 
-
-SI_SLAB = {
-    "name": "Si8(001), termination Si_P4/mmm_1, Slab",
+SI_SLAB: Dict[str, Any] = {
     "basis": {
         "elements": [
             {"id": 0, "value": "Si"},
@@ -211,6 +212,7 @@ SI_SLAB = {
             "units": "angstrom",
         },
     },
+    "name": "Si8(001), termination Si_P4/mmm_1, Slab",
     "isNonPeriodic": False,
     "_id": "",
     "metadata": {
@@ -220,3 +222,14 @@ SI_SLAB = {
     },
     "isUpdated": True,
 }
+
+SI_SLAB_VACUUM = copy.deepcopy(SI_SLAB)
+SI_SLAB_VACUUM["basis"]["coordinates"] = [
+    {"id": 0, "value": [0.5, 0.5, 0.386029718]},
+    {"id": 1, "value": [0.5, 0.0, 0.4718141]},
+    {"id": 2, "value": [0.0, 0.0, 0.557598482]},
+    {"id": 3, "value": [-0.0, 0.5, 0.643382864]},
+]
+SI_SLAB_VACUUM["basis"]["cell"] = [[3.867, 0.0, 0.0], [-0.0, 3.867, 0.0], [0.0, 0.0, 15.937527692]]
+SI_SLAB_VACUUM["lattice"]["c"] = 15.937527692
+SI_SLAB_VACUUM["lattice"]["vectors"]["c"] = [0.0, 0.0, 15.937527692]

package/tests/py/unit/test_tools_build_defect.py

@@ -1,8 +1,28 @@
 from mat3ra.made.material import Material
-from mat3ra.made.tools.build.defect import PointDefectBuilderParameters, PointDefectConfiguration, create_defect
+from mat3ra.made.tools.build.defect import (
+    AdatomSlabDefectConfiguration,
+    EquidistantAdatomSlabDefectBuilder,
+    PointDefectBuilderParameters,
+    PointDefectConfiguration,
+    create_defect,
+    create_slab_defect,
+)
+from mat3ra.made.tools.build.slab import SlabConfiguration, create_slab, get_terminations
+from mat3ra.utils import assertion as assertion_utils
 
 clean_material = Material.create(Material.default_config)
 
+slab_config = SlabConfiguration(
+    clean_material,
+    (1, 1, 1),
+    thickness=3,
+    vacuum=6,
+    use_orthogonal_z=True,
+    xy_supercell_matrix=[[2, 0, 0], [0, 2, 0], [0, 0, 1]],
+)
+t = get_terminations(slab_config)[0]
+slab = create_slab(slab_config, t)
+
 
 def test_create_vacancy():
     # vacancy in place of 0 element
@@ -49,3 +69,26 @@ def test_create_defect_from_site_id():
         {"id": 0, "value": "Si"},
         {"id": 1, "value": "Ge"},
     ]
+
+
+def test_create_adatom():
+    # Adatom of Si at 0.5, 0.5 position
+    configuration = AdatomSlabDefectConfiguration(
+        crystal=slab, position_on_surface=[0.5, 0.5], distance_z=2, chemical_element="Si"
+    )
+    defect = create_slab_defect(configuration=configuration, builder=None)
+
+    assert defect.basis.elements.values[-1] == "Si"
+    assertion_utils.assert_deep_almost_equal([0.5, 0.5, 0.389826], defect.basis.coordinates.values[-1])
+
+
+def test_create_adatom_equidistant():
+    # Adatom of Si at approximate 0.5, 0.5 position
+    configuration = AdatomSlabDefectConfiguration(
+        crystal=slab, position_on_surface=[0.5, 0.5], distance_z=2, chemical_element="Si"
+    )
+    defect = create_slab_defect(configuration=configuration, builder=EquidistantAdatomSlabDefectBuilder())
+
+    assert defect.basis.elements.values[-1] == "Si"
+    # We expect adatom to shift from provided position
+    assertion_utils.assert_deep_almost_equal([0.4583333333, 0.541666667, 0.389826], defect.basis.coordinates.values[-1])

package/tests/py/unit/test_tools_modify.py

@@ -2,16 +2,19 @@ from ase.build import bulk
 from mat3ra.made.material import Material
 from mat3ra.made.tools.convert import from_ase
 from mat3ra.made.tools.modify import (
+    add_vacuum,
     filter_by_circle_projection,
     filter_by_label,
     filter_by_layers,
     filter_by_rectangle_projection,
     filter_by_sphere,
     filter_by_triangle_projection,
+    remove_vacuum,
+    translate_to_z_level,
 )
 from mat3ra.utils import assertion as assertion_utils
 
-from .fixtures import SI_CONVENTIONAL_CELL
+from .fixtures import SI_CONVENTIONAL_CELL, SI_SLAB, SI_SLAB_VACUUM
 
 COMMON_PART = {
     "units": "crystal",
@@ -136,3 +139,22 @@ def test_filter_by_triangle_projection():
     cavity = filter_by_triangle_projection(material, [0.4, 0.4], [0.4, 0.5], [0.5, 0.5], invert_selection=True)
     assertion_utils.assert_deep_almost_equal(expected_basis_sphere_cluster, section.basis.to_json())
     assertion_utils.assert_deep_almost_equal(expected_basis_sphere_cavity, cavity.basis.to_json())
+
+
+def test_add_vacuum():
+    material = Material(SI_SLAB)
+    material_with_vacuum = add_vacuum(material, 5.0)
+    assertion_utils.assert_deep_almost_equal(SI_SLAB_VACUUM, material_with_vacuum.to_json())
+
+
+def test_remove_vacuum():
+    material_with_vacuum = Material(SI_SLAB_VACUUM)
+    vacuum = 6.836
+    material_with_no_vacuum = remove_vacuum(material_with_vacuum, from_top=True, from_bottom=True, fixed_padding=0)
+    material_with_set_vacuum = add_vacuum(material_with_no_vacuum, vacuum)
+    # to compare correctly, we need to translate the expected material to the bottom
+    # as it down when setting vacuum to 0
+    material = Material(SI_SLAB)
+    material_down = translate_to_z_level(material, z_level="bottom")
+
+    assertion_utils.assert_deep_almost_equal(material_down.to_json(), material_with_set_vacuum.to_json())