@mat3ra/made 2024.6.4-0 → 2024.6.12-0

package/.husky/pre-commit

@@ -1,6 +1,6 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
-npx lint-staged
+npx lint-staged --allow-empty
 npm run transpile
 git add dist

package/.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
       - id: end-of-file-fixer
         exclude: ^tests/fixtures*
       - id: trailing-whitespace
-        exclude: ^tests/fixtures*
+        exclude: ^tests/fixtures*|^dist*
   - repo: local
     hooks:
       - id: lint-staged

package/package.json

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

package/pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
 tools = [
     "pymatgen",
     "ase",
+    "pymatgen-analysis-defects"
 ]
 dev = [
     "pre-commit",

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

@@ -3,6 +3,7 @@ from typing import Any, Dict, List, Union
 from mat3ra.code.constants import AtomicCoordinateUnits, Units
 from mat3ra.code.entity import HasDescriptionHasMetadataNamedDefaultableInMemoryEntity
 from mat3ra.esse.models.material import MaterialSchema
+from mat3ra.made.utils import map_array_with_id_value_to_array
 
 defaultMaterialConfig = {
     "name": "Silicon FCC",
@@ -57,3 +58,7 @@ class Material(HasDescriptionHasMetadataNamedDefaultableInMemoryEntity):
 
     def to_json(self, exclude: List[str] = []) -> MaterialSchemaJSON:
         return {**super().to_json()}
+
+    @property
+    def coordinates_array(self) -> List[List[float]]:
+        return map_array_with_id_value_to_array(self.basis["coordinates"])

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

@@ -1,6 +1,9 @@
+from typing import List
+
 import numpy as np
 from ase import Atoms
 
+from ..material import Material
 from .convert import decorator_convert_material_args_kwargs_to_atoms
 
 
@@ -69,3 +72,20 @@ def get_chemical_formula(atoms: Atoms):
         str: The formula of the atoms.
     """
     return atoms.get_chemical_formula()
+
+
+def get_closest_site_id_from_position(material: Material, position: List[float]) -> int:
+    """
+    Get the site ID of the closest site to a given position in the crystal.
+
+    Args:
+        material (Material): The material object to find the closest site in.
+        position (List[float]): The position to find the closest site to.
+
+    Returns:
+        int: The site ID of the closest site.
+    """
+    coordinates = np.array(material.coordinates_array)
+    position = np.array(position)  # type: ignore
+    distances = np.linalg.norm(coordinates - position, axis=1)
+    return int(np.argmin(distances))

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

@@ -73,7 +73,8 @@ class BaseBuilder(BaseModel):
         return material_config
 
     def _finalize(self, materials: List[Material], configuration: _ConfigurationType) -> List[Material]:
-        return [self._update_material_name(material, configuration) for material in materials]
+        materials_with_metadata = [self._update_material_metadata(material, configuration) for material in materials]
+        return [self._update_material_name(material, configuration) for material in materials_with_metadata]
 
     def get_materials(
         self,
@@ -99,3 +100,7 @@ class BaseBuilder(BaseModel):
     def _update_material_name(self, material, configuration):
         # Do nothing by default
         return material
+
+    def _update_material_metadata(self, material, configuration):
+        material.metadata["build"] = {"configuration": configuration.to_json()}
+        return material

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

@@ -0,0 +1,36 @@
+from typing import Optional
+
+from mat3ra.utils.factory import BaseFactory
+from mat3ra.made.material import Material
+
+from .builders import PointDefectBuilderParameters
+from .configuration import PointDefectConfiguration
+from .enums import PointDefectTypeEnum
+
+
+class DefectBuilderFactory(BaseFactory):
+    __class_registry__ = {
+        PointDefectTypeEnum.VACANCY: "mat3ra.made.tools.build.defect.builders.VacancyPointDefectBuilder",
+        PointDefectTypeEnum.SUBSTITUTION: "mat3ra.made.tools.build.defect.builders.SubstitutionPointDefectBuilder",
+        PointDefectTypeEnum.INTERSTITIAL: "mat3ra.made.tools.build.defect.builders.InterstitialPointDefectBuilder",
+    }
+
+
+def create_defect(
+    configuration: PointDefectConfiguration,
+    builder_parameters: Optional[PointDefectBuilderParameters] = None,
+) -> Material:
+    """
+    Return a material with a selected defect added.
+
+    Args:
+        configuration: The configuration of the defect to be added.
+        builder_parameters: The parameters to be used by the defect builder.
+
+    Returns:
+        The material with the defect added.
+    """
+    BuilderClass = DefectBuilderFactory.get_class_by_name(configuration.defect_type)
+    builder = BuilderClass(builder_parameters)
+
+    return builder.get_material(configuration) if builder else configuration.crystal

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

@@ -0,0 +1,69 @@
+from typing import List, Callable
+
+from mat3ra.made.material import Material
+from pydantic import BaseModel
+from pymatgen.analysis.defects.core import (
+    Substitution as PymatgenSubstitution,
+    Vacancy as PymatgenVacancy,
+    Interstitial as PymatgenInterstitial,
+)
+from pymatgen.core import PeriodicSite as PymatgenPeriodicSite
+
+from ...build import BaseBuilder
+from ...convert import PymatgenStructure, to_pymatgen
+from ..mixins import ConvertGeneratedItemsPymatgenStructureMixin
+from .configuration import PointDefectConfiguration
+from mat3ra.made.utils import get_array_with_id_value_element_value_by_index
+
+
+class PointDefectBuilderParameters(BaseModel):
+    center_defect: bool = False
+
+
+class PointDefectBuilder(ConvertGeneratedItemsPymatgenStructureMixin, BaseBuilder):
+    """
+    Builder class for generating point defects.
+    """
+
+    _BuildParametersType = PointDefectBuilderParameters
+    _DefaultBuildParameters = PointDefectBuilderParameters()
+    _GeneratedItemType: PymatgenStructure = PymatgenStructure
+    _ConfigurationType = PointDefectConfiguration
+    _generator: Callable
+
+    def _get_species(self, configuration: BaseBuilder._ConfigurationType):
+        crystal_elements = configuration.crystal.basis["elements"]
+        placeholder_specie = get_array_with_id_value_element_value_by_index(crystal_elements, 0)
+        return configuration.chemical_element or placeholder_specie
+
+    def _generate(self, configuration: BaseBuilder._ConfigurationType) -> List[_GeneratedItemType]:
+        pymatgen_structure = to_pymatgen(configuration.crystal)
+        pymatgen_periodic_site = PymatgenPeriodicSite(
+            species=self._get_species(configuration),
+            coords=configuration.position,
+            lattice=pymatgen_structure.lattice,
+        )
+        defect = self._generator(pymatgen_structure, pymatgen_periodic_site)
+        defect_structure = defect.defect_structure.copy()
+        defect_structure.remove_oxidation_states()
+        return [defect_structure]
+
+    def _update_material_name(self, material: Material, configuration: BaseBuilder._ConfigurationType) -> Material:
+        updated_material = super()._update_material_name(material, configuration)
+        capitalized_defect_type = configuration.defect_type.name.capitalize()
+        chemical_element = configuration.chemical_element if configuration.chemical_element else ""
+        new_name = f"{updated_material.name}, {capitalized_defect_type} {chemical_element} Defect"
+        updated_material.name = new_name
+        return updated_material
+
+
+class VacancyPointDefectBuilder(PointDefectBuilder):
+    _generator: PymatgenVacancy = PymatgenVacancy
+
+
+class SubstitutionPointDefectBuilder(PointDefectBuilder):
+    _generator: PymatgenSubstitution = PymatgenSubstitution
+
+
+class InterstitialPointDefectBuilder(PointDefectBuilder):
+    _generator: PymatgenInterstitial = PymatgenInterstitial

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

@@ -0,0 +1,44 @@
+from typing import Optional, List, Any
+from pydantic import BaseModel
+
+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
+
+
+class BaseDefectConfiguration(BaseModel):
+    # TODO: fix arbitrary_types_allowed error and set Material class type
+    crystal: Any = None
+
+
+class PointDefectConfiguration(BaseDefectConfiguration, InMemoryEntity):
+    defect_type: PointDefectTypeEnum
+    position: Optional[List[float]] = [0, 0, 0]  # fractional coordinates
+    site_id: Optional[int] = None
+    chemical_element: Optional[str] = None
+
+    def __init__(self, position=position, site_id=None, **data):
+        super().__init__(**data)
+        if site_id is not None:
+            self.position = self.crystal.coordinates_array[site_id]
+        else:
+            self.site_id = get_closest_site_id_from_position(self.crystal, position)
+
+    @classmethod
+    def from_site_id(cls, site_id: int, crystal: Material, **data):
+        if crystal:
+            position = crystal.coordinates_array[site_id]
+        else:
+            RuntimeError("Crystal is not defined")
+        return cls(crystal=crystal, position=position, site_id=site_id, **data)
+
+    @property
+    def _json(self):
+        return {
+            "type": "PointDefectConfiguration",
+            "defect_type": self.defect_type.name,
+            "position": self.position,
+            "chemical_element": self.chemical_element,
+        }

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

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class PointDefectTypeEnum(str, Enum):
+    VACANCY = "vacancy"
+    SUBSTITUTION = "substitution"
+    INTERSTITIAL = "interstitial"

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

@@ -54,7 +54,7 @@ class SimpleInterfaceBuilder(ConvertGeneratedItemsASEAtomsMixin, InterfaceBuilde
     Creates matching interface between substrate and film by straining the film to match the substrate.
     """
 
-    _BuildParametersType = Optional[SimpleInterfaceBuilderParameters]
+    _BuildParametersType = SimpleInterfaceBuilderParameters
     _DefaultBuildParameters = SimpleInterfaceBuilderParameters(scale_film=True)
     _GeneratedItemType: type(ASEAtoms) = ASEAtoms  # type: ignore
 
@@ -116,9 +116,9 @@ class StrainMatchingInterfaceBuilder(InterfaceBuilder):
         updated_material = super()._update_material_name(material, configuration)
         if StrainModes.mean_abs_strain in material.metadata:
             strain = material.metadata[StrainModes.mean_abs_strain]
-            new_name = f"{updated_material.name}, Strain {strain*100:.3f}%"
+            new_name = f"{updated_material.name}, Strain {strain*100:.3f}pct"
             updated_material.name = new_name
-        return material
+        return updated_material
 
 
 class ZSLStrainMatchingParameters(BaseModel):

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

@@ -1,3 +1,4 @@
+from mat3ra.code.entity import InMemoryEntity
 from pydantic import BaseModel
 
 from .termination_pair import TerminationPair
@@ -5,7 +6,7 @@ from ..slab import Termination
 from ..slab.configuration import SlabConfiguration
 
 
-class InterfaceConfiguration(BaseModel):
+class InterfaceConfiguration(BaseModel, InMemoryEntity):
     film_configuration: SlabConfiguration
     substrate_configuration: SlabConfiguration
     film_termination: Termination
@@ -16,3 +17,15 @@ class InterfaceConfiguration(BaseModel):
     @property
     def termination_pair(self):
         return TerminationPair(self.film_termination, self.substrate_termination)
+
+    @property
+    def _json(self):
+        return {
+            "type": "InterfaceConfiguration",
+            "film_configuration": self.film_configuration.to_json(),
+            "substrate_configuration": self.substrate_configuration.to_json(),
+            "film_termination": str(self.film_termination),
+            "substrate_termination": str(self.substrate_termination),
+            "distance_z": self.distance_z,
+            "vacuum": self.vacuum,
+        }

package/src/py/mat3ra/made/tools/build/interface/utils.py

@@ -1,8 +1,11 @@
 import types
 from typing import List
 import numpy as np
+from mat3ra.made.material import Material
+
+from ...modify import filter_by_label
+from ...convert import PymatgenInterface, INTERFACE_LABELS_MAP
 from .enums import StrainModes
-from ...convert import PymatgenInterface
 
 
 def interface_patch_with_mean_abs_strain(target: PymatgenInterface, tolerance: float = 10e-6):
@@ -34,3 +37,10 @@ def remove_duplicate_interfaces(
         if not any(are_interfaces_duplicate(interface, unique_interface) for unique_interface in filtered_interfaces):
             filtered_interfaces.append(interface)
     return filtered_interfaces
+
+
+def get_slab(interface: Material, part: str = "film"):
+    try:
+        return filter_by_label(interface, INTERFACE_LABELS_MAP[part])
+    except ValueError:
+        raise ValueError(f"Material does not contain label for {part}.")

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

@@ -1,4 +1,6 @@
 from typing import List, Tuple, Any
+
+from mat3ra.code.entity import InMemoryEntity
 from pymatgen.symmetry.analyzer import SpacegroupAnalyzer as PymatgenSpacegroupAnalyzer
 from pydantic import BaseModel
 
@@ -6,7 +8,7 @@ from mat3ra.made.material import Material
 from ...convert import to_pymatgen, from_pymatgen
 
 
-class SlabConfiguration(BaseModel):
+class SlabConfiguration(BaseModel, InMemoryEntity):
     """
     Configuration for building a slab.
 
@@ -54,3 +56,16 @@ class SlabConfiguration(BaseModel):
             xy_supercell_matrix=xy_supercell_matrix,
             use_orthogonal_z=use_orthogonal_z,
         )
+
+    @property
+    def _json(self):
+        return {
+            "type": "SlabConfiguration",
+            "bulk": self.bulk.to_json(),
+            "miller_indices": self.miller_indices,
+            "thickness": self.thickness,
+            "vacuum": self.vacuum,
+            "xy_supercell_matrix": self.xy_supercell_matrix,
+            "use_conventional_cell": self.use_conventional_cell,
+            "use_orthogonal_z": self.use_orthogonal_z,
+        }

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

@@ -1,7 +1,12 @@
+from typing import Optional
+
 from ase import Atoms
 from ase.calculators.calculator import Calculator
+from ase.calculators.emt import EMT
 
+from ..material import Material
 from .analyze import get_surface_area
+from .build.interface.utils import get_slab
 from .convert import decorator_convert_material_args_kwargs_to_atoms
 
 
@@ -57,56 +62,67 @@ def calculate_surface_energy(slab: Atoms, bulk: Atoms, calculator: Calculator):
 
 
 @decorator_convert_material_args_kwargs_to_atoms
-def calculate_adhesion_energy(interface: Atoms, substrate_slab: Atoms, layer_slab: Atoms, calculator: Calculator):
+def calculate_adhesion_energy(interface: Atoms, substrate_slab: Atoms, film_slab: Atoms, calculator: Calculator):
     """
     Calculate the adhesion energy.
     The adhesion energy is the difference between the energy of the interface and
-    the sum of the energies of the substrate and layer.
+    the sum of the energies of the substrate and film.
     According to: 10.1088/0953-8984/27/30/305004
 
     Args:
         interface (ase.Atoms): The interface Atoms object to calculate the adhesion energy of.
         substrate_slab (ase.Atoms): The substrate slab Atoms object to calculate the adhesion energy of.
-        layer_slab (ase.Atoms): The layer slab Atoms object to calculate the adhesion energy of.
+        film_slab (ase.Atoms): The film slab Atoms object to calculate the adhesion energy of.
         calculator (ase.calculators.calculator.Calculator): The calculator to use for the energy calculation.
 
     Returns:
         float: The adhesion energy of the interface.
     """
     energy_substrate_slab = calculate_total_energy(substrate_slab, calculator)
-    energy_layer_slab = calculate_total_energy(layer_slab, calculator)
+    energy_film_slab = calculate_total_energy(film_slab, calculator)
     energy_interface = calculate_total_energy(interface, calculator)
     area = get_surface_area(interface)
-    return (energy_substrate_slab + energy_layer_slab - energy_interface) / area
+    return (energy_substrate_slab + energy_film_slab - energy_interface) / area
 
 
-@decorator_convert_material_args_kwargs_to_atoms
 def calculate_interfacial_energy(
-    interface: Atoms,
-    substrate_slab: Atoms,
-    substrate_bulk: Atoms,
-    layer_slab: Atoms,
-    layer_bulk: Atoms,
-    calculator: Calculator,
+    interface: Material,
+    substrate_slab: Optional[Material] = None,
+    substrate_bulk: Optional[Material] = None,
+    film_slab: Optional[Material] = None,
+    film_bulk: Optional[Material] = None,
+    calculator: Calculator = EMT(),
 ):
     """
     Calculate the interfacial energy.
-    The interfacial energy is the sum of the surface energies of the substrate and layer minus the adhesion energy.
+    The interfacial energy is the sum of the surface energies of the substrate and film minus the adhesion energy.
     According to Dupré's formula
 
     Args:
-        interface (ase.Atoms): The interface Atoms object to calculate the interfacial energy of.
-        substrate_slab (ase.Atoms): The substrate slab Atoms object to calculate the interfacial energy of.
-        substrate_bulk (ase.Atoms): The substrate bulk Atoms object to calculate the interfacial energy of.
-        layer_slab (ase.Atoms): The layer slab Atoms object to calculate the interfacial energy of.
-        layer_bulk (ase.Atoms): The layer bulk Atoms object to calculate the interfacial energy of.
-        calculator (ase.calculators.calculator.Calculator): The calculator to use for the energy calculation.
+        interface (Material): The interface Material object to calculate the interfacial energy of.
+        substrate_slab (Material): The substrate slab Material object to calculate the interfacial energy of.
+        substrate_bulk (Material): The substrate bulk Material object to calculate the interfacial energy of.
+        film_slab (Material): The film slab Material object to calculate the interfacial energy of.
+        film_bulk (Material): The film bulk Material object to calculate the interfacial energy of.
+        calculator (ase.calculators.calculator.Calculator): The calculator to use for the energy calculation
 
     Returns:
         float: The interfacial energy of the interface.
     """
-
+    substrate_slab = get_slab(interface, part="substrate") if substrate_slab is None else substrate_slab
+    film_slab = get_slab(interface, part="film") if film_slab is None else film_slab
+
+    build_configuration = interface.metadata["build"]["configuration"] if "build" in interface.metadata else {}
+    try:
+        substrate_bulk = (
+            Material(build_configuration["substrate_configuration"]["bulk"])
+            if substrate_bulk is None
+            else substrate_bulk
+        )
+        film_bulk = Material(build_configuration["film_configuration"]["bulk"]) if film_bulk is None else film_bulk
+    except KeyError:
+        raise ValueError("The substrate and film bulk materials must be provided or defined in the interface metadata.")
     surface_energy_substrate = calculate_surface_energy(substrate_slab, substrate_bulk, calculator)
-    surface_energy_layer = calculate_surface_energy(layer_slab, layer_bulk, calculator)
-    adhesion_energy = calculate_adhesion_energy(interface, substrate_slab, layer_slab, calculator)
-    return surface_energy_layer + surface_energy_substrate - adhesion_energy
+    surface_energy_film = calculate_surface_energy(film_slab, film_bulk, calculator)
+    adhesion_energy = calculate_adhesion_energy(interface, substrate_slab, film_slab, calculator)
+    return surface_energy_film + surface_energy_substrate - adhesion_energy

package/src/py/mat3ra/made/tools/{convert.py → convert/__init__.py}

@@ -1,27 +1,29 @@
 import inspect
-import json
 from functools import wraps
 from typing import Any, Callable, Dict, Union
 
-from ase import Atoms
+from mat3ra.made.material import Material
+from mat3ra.made.utils import map_array_with_id_value_to_array
 from mat3ra.utils.mixins import RoundNumericValuesMixin
-from mat3ra.utils.object import NumpyNDArrayRoundEncoder
-from pymatgen.core.interface import Interface, label_termination
-from pymatgen.core.structure import Lattice, Structure
-from pymatgen.core.surface import Slab
 from pymatgen.io.ase import AseAtomsAdaptor
 from pymatgen.io.vasp.inputs import Poscar
 
-from ..material import Material
+from .utils import (
+    INTERFACE_LABELS_MAP,
+    ASEAtoms,
+    PymatgenInterface,
+    PymatgenLattice,
+    PymatgenSlab,
+    PymatgenStructure,
+    extract_labels_from_pymatgen_structure,
+    extract_metadata_from_pymatgen_structure,
+    extract_tags_from_ase_atoms,
+    label_pymatgen_slab_termination,
+    map_array_to_array_with_id_value,
+)
 
-PymatgenStructure = Structure
-PymatgenSlab = Slab
-PymatgenInterface = Interface
-ASEAtoms = Atoms
-label_pymatgen_slab_termination = label_termination
 
-
-def to_pymatgen(material_or_material_data: Union[Material, Dict[str, Any]]) -> Structure:
+def to_pymatgen(material_or_material_data: Union[Material, Dict[str, Any]]) -> PymatgenStructure:
     """
     Converts material object in ESSE format to a pymatgen Structure object.
 
@@ -43,27 +45,28 @@ def to_pymatgen(material_or_material_data: Union[Material, Dict[str, Any]]) -> S
     alpha = lattice_params["alpha"]
     beta = lattice_params["beta"]
     gamma = lattice_params["gamma"]
-    lattice = Lattice.from_parameters(a, b, c, alpha, beta, gamma)
+    lattice = PymatgenLattice.from_parameters(a, b, c, alpha, beta, gamma)
 
     basis = material_data["basis"]
     elements = [element["value"] for element in basis["elements"]]
     coordinates = [coord["value"] for coord in basis["coordinates"]]
     labels = [label["value"] for label in basis.get("labels", [])]
-
     # Assuming that the basis units are fractional since it's a crystal basis
     coords_are_cartesian = "units" in basis and basis["units"].lower() == "angstrom"
 
-    if "labels" in inspect.signature(Structure.__init__).parameters:
-        structure = Structure(lattice, elements, coordinates, coords_are_cartesian=coords_are_cartesian, labels=labels)
+    if "labels" in inspect.signature(PymatgenStructure.__init__).parameters:
+        structure = PymatgenStructure(
+            lattice, elements, coordinates, coords_are_cartesian=coords_are_cartesian, labels=labels
+        )
     else:
         # Passing labels does not work for pymatgen `2023.6.23` supporting py3.8
         print(f"labels: {labels}. Not passing labels to pymatgen.")
-        structure = Structure(lattice, elements, coordinates, coords_are_cartesian=coords_are_cartesian)
+        structure = PymatgenStructure(lattice, elements, coordinates, coords_are_cartesian=coords_are_cartesian)
 
     return structure
 
 
-def from_pymatgen(structure: Union[Structure, Interface]) -> Dict[str, Any]:
+def from_pymatgen(structure: Union[PymatgenStructure, PymatgenInterface]) -> Dict[str, Any]:
     """
     Converts a pymatgen Structure object to a material object in ESSE format.
 
@@ -102,18 +105,14 @@ def from_pymatgen(structure: Union[Structure, Interface]) -> Dict[str, Any]:
         },
     }
 
-    metadata = {"boundaryConditions": {"type": "pbc", "offset": 0}}
+    metadata = {
+        **extract_metadata_from_pymatgen_structure(structure),
+        "boundaryConditions": {"type": "pbc", "offset": 0},
+    }
 
-    # TODO: consider using Interface JSONSchema from ESSE when such created and adapt interface_properties accordingly.
-    # Add interface properties to metadata according to pymatgen Interface as a JSON object
-    if hasattr(structure, "interface_properties"):
-        interface_props = structure.interface_properties
-        # TODO: figure out how to round the values and stringify terminations tuple
-        #  in the interface properties with Encoder
-        for key, value in interface_props.items():
-            if isinstance(value, tuple):
-                interface_props[key] = str(value)
-        metadata["interface_properties"] = json.loads(json.dumps(interface_props, cls=NumpyNDArrayRoundEncoder))
+    basis["labels"] = map_array_to_array_with_id_value(
+        extract_labels_from_pymatgen_structure(structure), remove_none=True
+    )
 
     material_data = {
         "name": structure.formula,
@@ -157,11 +156,11 @@ def from_poscar(poscar: str) -> Dict[str, Any]:
     Returns:
         dict: A dictionary containing the material information in ESSE format.
     """
-    structure = Structure.from_str(poscar, "poscar")
+    structure = PymatgenStructure.from_str(poscar, "poscar")
     return from_pymatgen(structure)
 
 
-def to_ase(material_or_material_data: Union[Material, Dict[str, Any]]) -> Atoms:
+def to_ase(material_or_material_data: Union[Material, Dict[str, Any]]) -> ASEAtoms:
     """
     Converts material object in ESSE format to an ASE Atoms object.
 
@@ -171,12 +170,22 @@ def to_ase(material_or_material_data: Union[Material, Dict[str, Any]]) -> Atoms:
     Returns:
         Any: An ASE Atoms object.
     """
-    # TODO: check that atomic labels are properly handled
-    structure = to_pymatgen(material_or_material_data)
-    return AseAtomsAdaptor.get_atoms(structure)
+    if isinstance(material_or_material_data, Material):
+        material_config = material_or_material_data.to_json()
+    else:
+        material_config = material_or_material_data
+    structure = to_pymatgen(material_config)
+    atoms = AseAtomsAdaptor.get_atoms(structure)
 
+    atomic_labels = material_config["basis"].get("labels", [])
+    if atomic_labels:
+        atoms.set_tags(map_array_with_id_value_to_array(atomic_labels))
+    if "metadata" in material_config:
+        atoms.info.update({"metadata": material_config["metadata"]})
+    return atoms
 
-def from_ase(ase_atoms: Atoms) -> Dict[str, Any]:
+
+def from_ase(ase_atoms: ASEAtoms) -> Dict[str, Any]:
     """
     Converts an ASE Atoms object to a material object in ESSE format.
 
@@ -188,7 +197,13 @@ def from_ase(ase_atoms: Atoms) -> Dict[str, Any]:
     """
     # TODO: check that atomic labels/tags are properly handled
     structure = AseAtomsAdaptor.get_structure(ase_atoms)
-    return from_pymatgen(structure)
+    material = from_pymatgen(structure)
+    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)
+    return material
 
 
 def decorator_convert_material_args_kwargs_to_atoms(func: Callable) -> Callable:
@@ -230,8 +245,8 @@ def decorator_convert_material_args_kwargs_to_structure(func: Callable) -> Calla
 
 
 def convert_atoms_or_structure_to_material(item):
-    if isinstance(item, Structure):
+    if isinstance(item, PymatgenStructure):
         return from_pymatgen(item)
-    elif isinstance(item, Atoms):
+    elif isinstance(item, ASEAtoms):
         return from_ase(item)
     return item

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

@@ -0,0 +1,52 @@
+import json
+from typing import Any, Dict, List, Union
+
+from ase import Atoms as ASEAtoms
+from mat3ra.made.utils import map_array_to_array_with_id_value
+from mat3ra.utils.object import NumpyNDArrayRoundEncoder
+from pymatgen.core.interface import Interface as PymatgenInterface
+from pymatgen.core.interface import label_termination
+from pymatgen.core.structure import Lattice as PymatgenLattice
+from pymatgen.core.structure import Structure as PymatgenStructure
+from pymatgen.core.surface import Slab as PymatgenSlab
+
+# Re-exported imports to allow for both use in type hints and instantiation
+PymatgenLattice = PymatgenLattice
+PymatgenStructure = PymatgenStructure
+PymatgenSlab = PymatgenSlab
+PymatgenInterface = PymatgenInterface
+ASEAtoms = ASEAtoms
+label_pymatgen_slab_termination = label_termination
+
+INTERFACE_LABELS_MAP = {"substrate": 0, "film": 1}
+
+
+def extract_labels_from_pymatgen_structure(structure: PymatgenStructure) -> List[int]:
+    labels = []
+    if isinstance(structure, PymatgenInterface):
+        labels = list(map(lambda s: INTERFACE_LABELS_MAP[s.properties["interface_label"]], structure.sites))
+    return labels
+
+
+def extract_metadata_from_pymatgen_structure(structure: PymatgenStructure) -> Dict[str, Any]:
+    metadata = {}
+    # TODO: consider using Interface JSONSchema from ESSE when such created and adapt interface_properties accordingly.
+    # Add interface properties to metadata according to pymatgen Interface as a JSON object
+    if hasattr(structure, "interface_properties"):
+        interface_props = structure.interface_properties
+        # TODO: figure out how to round the values and stringify terminations tuple
+        #  in the interface properties with Encoder
+        for key, value in interface_props.items():
+            if isinstance(value, tuple):
+                interface_props[key] = str(value)
+        metadata["interface_properties"] = json.loads(json.dumps(interface_props, cls=NumpyNDArrayRoundEncoder))
+
+    return metadata
+
+
+def extract_tags_from_ase_atoms(atoms: ASEAtoms) -> List[Union[str, int]]:
+    result = []
+    if "tags" in atoms.arrays:
+        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

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

@@ -1,29 +1,32 @@
 from typing import Union
 
-from ase import Atoms
+from mat3ra.made.material import Material
+from mat3ra.made.utils import filter_array_with_id_value_by_ids, filter_array_with_id_value_by_values
 from pymatgen.analysis.structure_analyzer import SpacegroupAnalyzer
 from pymatgen.core.structure import Structure
 
-from .convert import (
-    decorator_convert_material_args_kwargs_to_atoms,
-    decorator_convert_material_args_kwargs_to_structure,
-)
+from .convert import decorator_convert_material_args_kwargs_to_structure
 from .utils import translate_to_bottom_pymatgen_structure
 
 
-@decorator_convert_material_args_kwargs_to_atoms
-def filter_by_label(atoms: Atoms, label: Union[int, str]):
+def filter_by_label(material: Material, label: Union[int, str]) -> Material:
     """
-    Filter out only atoms corresponding to the label/tag.
+    Filter out only atoms corresponding to the label.
 
     Args:
-        atoms (ase.Atoms): The Atoms object to filter.
+        material (Material): The material object to filter.
         label (int|str): The tag/label to filter by.
 
     Returns:
-        ase.Atoms: The filtered Atoms object.
+        Material: The filtered material object.
     """
-    return atoms[atoms.get_tags() == label]
+    new_material = material.clone()
+    labels = material.basis["labels"]
+    filtered_labels = filter_array_with_id_value_by_values(labels, label)
+    filtered_label_ids = [item["id"] for item in filtered_labels]
+    for key in ["coordinates", "elements", "labels"]:
+        new_material.basis[key] = filter_array_with_id_value_by_ids(new_material.basis[key], filtered_label_ids)
+    return new_material
 
 
 @decorator_convert_material_args_kwargs_to_structure

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

@@ -0,0 +1,41 @@
+from typing import Any, Dict, List, Union
+
+from mat3ra.utils.array import convert_to_array_if_not
+
+
+# TODO: move to a more general location
+def map_array_to_array_with_id_value(array: List[Any], remove_none: bool = False) -> List[Any]:
+    full_array = [{"id": i, "value": item} for i, item in enumerate(array)]
+    if remove_none:
+        return list(filter(lambda x: x["value"] is not None, full_array))
+    return full_array
+
+
+def map_array_with_id_value_to_array(array: List[Dict[str, Any]]) -> List[Any]:
+    return [item["value"] for item in array]
+
+
+def get_array_with_id_value_element_value_by_index(array: List[Dict[str, Any]], index: int = 0) -> List[Any]:
+    return map_array_with_id_value_to_array(array)[index]
+
+
+def filter_array_with_id_value_by_values(
+    array: List[Dict[str, Any]], values: Union[List[Any], Any]
+) -> List[Dict[str, Any]]:
+    values = convert_to_array_if_not(values)
+    return [item for item in array if item["value"] in values]
+    # Alternative implementation:
+    # return list(filter(lambda x: x["value"] in values, array))
+
+
+def filter_array_with_id_value_by_ids(
+    array: List[Dict[str, Any]], ids: Union[List[int], List[str], int, str]
+) -> List[Dict[str, Any]]:
+    int_ids = list(map(lambda i: int(i), convert_to_array_if_not(ids)))
+    return [item for item in array if item["id"] in int_ids]
+    # Alternative implementation:
+    # return list(filter(lambda x: x["id"] in ids, array))
+
+
+def are_arrays_equal_by_id_value(array1: List[Dict[str, Any]], array2: List[Dict[str, Any]]) -> bool:
+    return map_array_with_id_value_to_array(array1) == map_array_with_id_value_to_array(array2)

package/tests/py/unit/fixtures.py

@@ -56,9 +56,60 @@ INTERFACE_PROPERTIES_JSON = {
 
 # Add properties to interface structure
 INTERFACE_STRUCTURE.interface_properties = INTERFACE_PROPERTIES_MOCK
-INTERFACE_NAME = "Cu4(001)-Si8(001), Interface, Strain 0.062%"
+INTERFACE_NAME = "Cu4(001)-Si8(001), Interface, Strain 0.062pct"
 
 # TODO: Use fixtures package when available
+SI_CONVENTIONAL_CELL = {
+    "name": "Si8",
+    "basis": {
+        "elements": [
+            {"id": 0, "value": "Si"},
+            {"id": 1, "value": "Si"},
+            {"id": 2, "value": "Si"},
+            {"id": 3, "value": "Si"},
+            {"id": 4, "value": "Si"},
+            {"id": 5, "value": "Si"},
+            {"id": 6, "value": "Si"},
+            {"id": 7, "value": "Si"},
+        ],
+        "coordinates": [
+            {"id": 0, "value": [0.5, 0.0, 0.0]},
+            {"id": 1, "value": [0.25, 0.25, 0.75]},
+            {"id": 2, "value": [0.5, 0.5, 0.5]},
+            {"id": 3, "value": [0.25, 0.75, 0.25]},
+            {"id": 4, "value": [0.0, 0.0, 0.5]},
+            {"id": 5, "value": [0.75, 0.25, 0.25]},
+            {"id": 6, "value": [0.0, 0.5, 0.0]},
+            {"id": 7, "value": [0.75, 0.75, 0.75]},
+        ],
+        "units": "crystal",
+        "cell": [[5.468763846, 0.0, 0.0], [-0.0, 5.468763846, 0.0], [0.0, 0.0, 5.468763846]],
+        "constraints": [],
+        "labels": [],
+    },
+    "lattice": {
+        "a": 5.468763846,
+        "b": 5.468763846,
+        "c": 5.468763846,
+        "alpha": 90.0,
+        "beta": 90.0,
+        "gamma": 90.0,
+        "units": {"length": "angstrom", "angle": "degree"},
+        "type": "TRI",
+        "vectors": {
+            "a": [5.468763846, 0.0, 0.0],
+            "b": [-0.0, 5.468763846, 0.0],
+            "c": [0.0, 0.0, 5.468763846],
+            "alat": 1,
+            "units": "angstrom",
+        },
+    },
+    "isNonPeriodic": False,
+    "_id": "",
+    "metadata": {"boundaryConditions": {"type": "pbc", "offset": 0}},
+    "isUpdated": True,
+}
+
 SI_SUPERCELL_2X2X1 = {
     "name": "Si8",
     "basis": {
@@ -85,6 +136,7 @@ SI_SUPERCELL_2X2X1 = {
         "units": "crystal",
         "cell": [[6.697840473, 0.0, 3.867], [2.232613491, 6.314784557, 3.867], [0.0, 0.0, 3.867]],
         "constraints": [],
+        "labels": [],
     },
     "lattice": {
         "a": 7.734,
@@ -109,6 +161,19 @@ SI_SUPERCELL_2X2X1 = {
     "isUpdated": True,
 }
 
+
+SI_SLAB_CONFIGURATION = {
+    "type": "SlabConfiguration",
+    "bulk": SI_CONVENTIONAL_CELL,
+    "miller_indices": (0, 0, 1),
+    "thickness": 1,
+    "vacuum": 1,
+    "xy_supercell_matrix": [[1, 0], [0, 1]],
+    "use_conventional_cell": True,
+    "use_orthogonal_z": True,
+}
+
+
 SI_SLAB = {
     "name": "Si8(001), termination Si_P4/mmm_1, Slab",
     "basis": {
@@ -127,6 +192,7 @@ SI_SLAB = {
         "units": "crystal",
         "cell": [[3.867, 0.0, 0.0], [0.0, 3.867, 0.0], [0.0, 0.0, 10.937527692]],
         "constraints": [],
+        "labels": [],
     },
     "lattice": {
         "a": 3.867,
@@ -150,6 +216,7 @@ SI_SLAB = {
     "metadata": {
         "boundaryConditions": {"type": "pbc", "offset": 0},
         "termination": "Si_P4/mmm_1",
+        "build": {"configuration": SI_SLAB_CONFIGURATION},
     },
     "isUpdated": True,
 }

package/tests/py/unit/test_tools_build_defect.py

@@ -0,0 +1,51 @@
+from mat3ra.made.material import Material
+from mat3ra.made.tools.build.defect import PointDefectBuilderParameters, PointDefectConfiguration, create_defect
+
+clean_material = Material.create(Material.default_config)
+
+
+def test_create_vacancy():
+    # vacancy in place of 0 element
+    configuration = PointDefectConfiguration(crystal=clean_material, defect_type="vacancy", site_id=0)
+    defect = create_defect(configuration)
+
+    assert len(defect.basis["elements"]) == 1
+
+
+def test_create_substitution():
+    # Substitution of Ge in place of Si at default site_id=0
+    configuration = PointDefectConfiguration(crystal=clean_material, defect_type="substitution", chemical_element="Ge")
+    defect = create_defect(configuration)
+
+    assert defect.basis["elements"] == [{"id": 0, "value": "Ge"}, {"id": 1, "value": "Si"}]
+    assert defect.basis["coordinates"][0] == {"id": 0, "value": [0.0, 0.0, 0.0]}
+
+
+def test_create_interstitial():
+    # Interstitial Ge at 0.5, 0.5, 0.5 position
+    configuration = PointDefectConfiguration(
+        crystal=clean_material, defect_type="interstitial", chemical_element="Ge", position=[0.5, 0.5, 0.5]
+    )
+    defect = create_defect(configuration)
+
+    assert defect.basis["elements"] == [
+        {"id": 0, "value": "Ge"},
+        {"id": 1, "value": "Si"},
+        {"id": 2, "value": "Si"},
+    ]
+
+
+def test_create_defect_from_site_id():
+    # Substitution of Ge in place of Si at site_id=1
+    defect_configuration = PointDefectConfiguration.from_site_id(
+        crystal=clean_material, defect_type="substitution", chemical_element="Ge", site_id=1
+    )
+    defect_builder_parameters = PointDefectBuilderParameters(center_defect=False)
+    material_with_defect = create_defect(
+        builder_parameters=defect_builder_parameters, configuration=defect_configuration
+    )
+
+    assert material_with_defect.basis["elements"] == [
+        {"id": 0, "value": "Si"},
+        {"id": 1, "value": "Ge"},
+    ]

package/tests/py/unit/test_tools_build_slab.py

@@ -18,4 +18,4 @@ def test_build_slab():
     )
     termination = get_terminations(slab_config)[0]
     slab = create_slab(slab_config, termination)
-    assertion_utils.assert_deep_almost_equal(slab.to_json(), SI_SLAB)
+    assertion_utils.assert_deep_almost_equal(SI_SLAB, slab.to_json())

package/tests/py/unit/test_tools_calculate.py

@@ -1,6 +1,7 @@
 import numpy as np
 from ase.build import add_adsorbate, bulk, fcc111, graphene, surface
 from ase.calculators import emt
+from mat3ra.made.material import Material
 from mat3ra.made.tools.calculate import (
     calculate_adhesion_energy,
     calculate_interfacial_energy,
@@ -8,6 +9,7 @@ from mat3ra.made.tools.calculate import (
     calculate_total_energy,
     calculate_total_energy_per_atom,
 )
+from mat3ra.made.tools.convert import from_ase
 
 # Interface and its constituents structures setup
 nickel_slab = fcc111("Ni", size=(2, 2, 3), vacuum=10, a=3.52)
@@ -16,14 +18,15 @@ graphene_layer.cell = nickel_slab.cell
 interface = nickel_slab.copy()
 add_adsorbate(interface, graphene_layer, height=2, position="ontop")
 
-# Assign calculators
-calculator = emt.EMT()
-nickel_slab.set_calculator(calculator)
-graphene_layer.set_calculator(calculator)
-interface.set_calculator(calculator)
+# Material objects setup
+interface_material = Material(from_ase(interface))
+nickel_slab_material = Material(from_ase(nickel_slab))
+nickel_bulk_material = Material(from_ase(bulk("Ni", "fcc", a=3.52)))
+graphene_layer_material = Material(from_ase(graphene_layer))
+graphene_bulk_material = graphene_layer
 
-nickel_bulk = bulk("Ni", "fcc", a=3.52)
-graphene_bulk = graphene_layer
+# Calculator setup
+calculator = emt.EMT()
 
 
 def test_calculate_total_energy():
@@ -56,7 +59,12 @@ def test_calculate_adhesion_energy():
 
 def test_calculate_interfacial_energy():
     interfacial_energy = calculate_interfacial_energy(
-        interface, nickel_slab, nickel_bulk, graphene_layer, graphene_bulk, calculator
+        interface_material,
+        nickel_slab_material,
+        nickel_bulk_material,
+        graphene_layer,
+        graphene_bulk_material,
+        calculator,
     )
     assert np.isclose(
         interfacial_energy,

package/tests/py/unit/test_tools_convert.py

@@ -56,6 +56,7 @@ def test_from_poscar():
 
 def test_to_ase():
     material = Material.create(Material.default_config)
+    material.basis["labels"] = [{"id": 0, "value": 0}, {"id": 1, "value": 1}]
     ase_atoms = to_ase(material)
     assert isinstance(ase_atoms, Atoms)
     assert np.allclose(
@@ -68,10 +69,13 @@ def test_to_ase():
     )
     assert ase_atoms.get_chemical_symbols() == ["Si", "Si"]
     assert np.allclose(ase_atoms.get_scaled_positions().tolist(), [[0.0, 0.0, 0.0], [0.25, 0.25, 0.25]])
+    assert ase_atoms.get_tags().tolist() == [0, 1]
 
 
 def test_from_ase():
     ase_atoms = bulk("Si")
+    ase_atoms.set_tags([0, 1])
     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}]

package/tests/py/unit/test_tools_modify.py

@@ -1,4 +1,6 @@
 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 filter_by_label
 
 
@@ -7,5 +9,11 @@ def test_filter_by_label():
     film = bulk("Cu", cubic=True)
     interface_atoms = substrate + film
     interface_atoms.set_tags([1] * len(substrate) + [2] * len(film))
-    film_extracted = filter_by_label(interface_atoms, 2)
-    assert (film.symbols == film_extracted.symbols).all()
+    material_interface = Material(from_ase(interface_atoms))
+    film_extracted = filter_by_label(material_interface, 2)
+    film_material = Material(from_ase(film))
+
+    # Ids of filtered elements will be missing, comparing the resulting values
+    assert [el["value"] for el in film_material.basis["elements"]] == [
+        el["value"] for el in film_extracted.basis["elements"]
+    ]