@mat3ra/made 2024.4.16-0 → 2024.5.3-0

package/package.json

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

package/pyproject.toml

@@ -17,6 +17,7 @@ classifiers = [
 dependencies = [
     # add requirements here
     "numpy",
+    "mat3ra-utils",
     "mat3ra-esse",
     "mat3ra-code",
 ]

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

@@ -1,11 +1,11 @@
 import numpy as np
 from ase import Atoms
 
-from .convert import convert_material_args_kwargs_to_atoms
+from .convert import decorator_convert_material_args_kwargs_to_atoms
 
 
-@convert_material_args_kwargs_to_atoms
-def calculate_average_interlayer_distance(
+@decorator_convert_material_args_kwargs_to_atoms
+def get_average_interlayer_distance(
     interface_atoms: Atoms, tag_substrate: str, tag_film: str, threshold: float = 0.5
 ) -> float:
     """
@@ -39,3 +39,19 @@ def calculate_average_interlayer_distance(
     # Calculate the average distance between the top layer of substrate and the bottom layer of film
     average_interlayer_distance = avg_z_bottom_film - avg_z_top_substrate
     return abs(average_interlayer_distance)
+
+
+@decorator_convert_material_args_kwargs_to_atoms
+def get_surface_area(atoms: Atoms):
+    """
+    Calculate the area of the surface perpendicular to the z-axis of the atoms structure.
+
+    Args:
+        atoms (ase.Atoms): The Atoms object to calculate the surface area of.
+
+    Returns:
+        float: The surface area of the atoms.
+    """
+    matrix = atoms.cell
+    cross_product = np.cross(matrix[0], matrix[1])
+    return np.linalg.norm(cross_product)

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

@@ -0,0 +1,66 @@
+from ...material import Material
+from .interface import InterfaceDataHolder
+from .interface import InterfaceSettings as Settings
+from .interface import interface_init_zsl_builder, interface_patch_with_mean_abs_strain
+from ..convert import decorator_convert_material_args_kwargs_to_structure
+from ..modify import translate_to_bottom, wrap_to_unit_cell
+
+
+@decorator_convert_material_args_kwargs_to_structure
+def create_interfaces(
+    substrate: Material,
+    layer: Material,
+    settings: Settings,
+    sort_by_strain_and_size: bool = True,
+    remove_duplicates: bool = True,
+    is_logging_enabled: bool = True,
+) -> InterfaceDataHolder:
+    """
+    Create all interfaces between the substrate and layer structures using ZSL algorithm provided by pymatgen.
+
+    Args:
+        substrate (Material): The substrate structure.
+        layer (Material): The layer structure.
+        settings: The settings for the interface generation.
+        sort_by_strain_and_size (bool): Whether to sort the interfaces by strain and size.
+        remove_duplicates (bool): Whether to remove duplicate interfaces.
+        is_logging_enabled (bool): Whether to enable debug print.
+    Returns:
+        InterfaceDataHolder.
+    """
+    substrate = translate_to_bottom(substrate, settings["USE_CONVENTIONAL_CELL"])
+    layer = translate_to_bottom(layer, settings["USE_CONVENTIONAL_CELL"])
+
+    if is_logging_enabled:
+        print("Creating interfaces...")
+
+    builder = interface_init_zsl_builder(substrate, layer, settings)
+    interfaces_data = InterfaceDataHolder()
+
+    for termination in builder.terminations:
+        all_interfaces_for_termination = builder.get_interfaces(
+            termination,
+            gap=settings["INTERFACE_PARAMETERS"]["DISTANCE_Z"],
+            film_thickness=settings["LAYER_PARAMETERS"]["THICKNESS"],
+            substrate_thickness=settings["SUBSTRATE_PARAMETERS"]["THICKNESS"],
+            in_layers=True,
+        )
+
+        all_interfaces_for_termination_patched_wrapped = list(
+            map(
+                lambda i: wrap_to_unit_cell(interface_patch_with_mean_abs_strain(i)),
+                all_interfaces_for_termination,
+            )
+        )
+
+        interfaces_data.add_data_entries(
+            all_interfaces_for_termination_patched_wrapped,
+            sort_interfaces_by_strain_and_size=sort_by_strain_and_size,
+            remove_duplicates=remove_duplicates,
+        )
+
+    if is_logging_enabled:
+        unique_str = "unique" if remove_duplicates else ""
+        print(f"Found {len(interfaces_data.get_interfaces_for_termination(0))} {unique_str} interfaces.")
+
+    return interfaces_data

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

@@ -0,0 +1,237 @@
+import functools
+import types
+import numpy as np
+from typing import Union, List, Tuple, Dict, TypedDict
+from enum import Enum
+from mat3ra.utils import array as array_utils
+from pymatgen.core.structure import Structure
+from pymatgen.analysis.interfaces.coherent_interfaces import CoherentInterfaceBuilder, ZSLGenerator
+from pymatgen.analysis.interfaces.coherent_interfaces import Interface
+from ..convert import convert_atoms_or_structure_to_material, decorator_convert_material_args_kwargs_to_structure
+
+
+class SlabParameters(TypedDict):
+    MILLER_INDICES: Tuple[int, int, int]
+    THICKNESS: int
+
+
+class ZSLParameters(TypedDict):
+    MAX_AREA_TOL: float
+    MAX_AREA: float
+    MAX_LENGTH_TOL: float
+    MAX_ANGLE_TOL: float
+
+
+class InterfaceParameters(TypedDict):
+    DISTANCE_Z: float
+    MAX_AREA: float
+
+
+class InterfaceSettings(TypedDict):
+    SUBSTRATE_PARAMETERS: SlabParameters
+    LAYER_PARAMETERS: SlabParameters
+    USE_CONVENTIONAL_CELL: bool
+    ZSL_PARAMETERS: ZSLParameters
+    INTERFACE_PARAMETERS: InterfaceParameters
+
+
+class StrainModes(Enum):
+    strain = "strain"
+    von_mises_strain = "von_mises_strain"
+    mean_abs_strain = "mean_abs_strain"
+
+
+def interface_patch_with_mean_abs_strain(target: Interface, tolerance: float = 10e-6):
+    def get_mean_abs_strain(target):
+        return target.interface_properties[StrainModes.mean_abs_strain]
+
+    target.get_mean_abs_strain = types.MethodType(get_mean_abs_strain, target)
+    target.interface_properties[StrainModes.mean_abs_strain] = (
+        round(np.mean(np.abs(target.interface_properties["strain"])) / tolerance) * tolerance
+    )
+    return target
+
+
+@decorator_convert_material_args_kwargs_to_structure
+def interface_init_zsl_builder(
+    substrate: Structure, layer: Structure, settings: InterfaceSettings
+) -> CoherentInterfaceBuilder:
+    generator: ZSLGenerator = ZSLGenerator(
+        max_area_ratio_tol=settings["ZSL_PARAMETERS"]["MAX_AREA_TOL"],
+        max_area=settings["ZSL_PARAMETERS"]["MAX_AREA"],
+        max_length_tol=settings["ZSL_PARAMETERS"]["MAX_LENGTH_TOL"],
+        max_angle_tol=settings["ZSL_PARAMETERS"]["MAX_ANGLE_TOL"],
+    )
+
+    builder = CoherentInterfaceBuilder(
+        substrate_structure=substrate,
+        film_structure=layer,
+        substrate_miller=settings["SUBSTRATE_PARAMETERS"]["MILLER_INDICES"],
+        film_miller=settings["LAYER_PARAMETERS"]["MILLER_INDICES"],
+        zslgen=generator,
+    )
+
+    return builder
+
+
+TerminationType = Tuple[str, str]
+InterfacesType = List[Interface]
+InterfacesDataType = Dict[Tuple, List[Interface]]
+
+
+class InterfaceDataHolder(object):
+    """
+    A class to hold data for interfaces generated by pymatgen.
+    Structures are stored in a dictionary with the termination as the key.
+    Example data structure:
+        {
+            "('C_P6/mmm_2', 'Si_R-3m_1')": [
+                { ...interface for ('C_P6/mmm_2', 'Si_R-3m_1') at index 0...},
+                { ...interface for ('C_P6/mmm_2', 'Si_R-3m_1') at index 1...},
+                ...
+            ],
+            "<termination at index 1>": [
+                { ...interface for 'termination at index 1' at index 0...},
+                { ...interface for 'termination at index 1' at index 1...},
+                ...
+            ]
+        }
+    """
+
+    def __init__(self, entries: Union[InterfacesType, None] = None) -> None:
+        if entries is None:
+            entries = []
+        self.data: InterfacesDataType = {}
+        self.terminations: List[TerminationType] = []
+        self.add_data_entries(entries)
+
+    def __str__(self):
+        terminations_list = f"There are {len(self.terminations)} terminations:" + ", ".join(
+            f"\n{idx}: ({a}, {b})" for idx, (a, b) in enumerate(self.terminations)
+        )
+        interfaces_list = "\n".join(
+            [
+                f"There are {len(self.data[termination])} interfaces for termination {termination}:\n{idx}: "
+                + f"{self.data[termination]}"
+                for idx, termination in enumerate(self.terminations)
+            ]
+        )
+        return f"{terminations_list}\n{interfaces_list}"
+
+    def add_termination(self, termination: Tuple[str, str]):
+        if termination not in self.terminations:
+            self.terminations.append(termination)
+            self.set_interfaces_for_termination(termination, [])
+
+    def add_interfaces_for_termination(
+        self, termination: TerminationType, interfaces: Union[InterfacesType, Interface]
+    ):
+        self.add_termination(termination)
+        self.set_interfaces_for_termination(termination, self.get_interfaces_for_termination(termination) + interfaces)
+
+    def add_data_entries(
+        self,
+        entries: List[Interface] = [],
+        sort_interfaces_by_strain_and_size: bool = True,
+        remove_duplicates: bool = True,
+    ):
+        entries = array_utils.convert_to_array_if_not(entries)
+        all_terminations = [e.interface_properties["termination"] for e in entries]
+        unique_terminations = list(set(all_terminations))
+        for termination in unique_terminations:
+            entries_for_termination = [
+                entry for entry in entries if entry.interface_properties["termination"] == termination
+            ]
+            self.add_interfaces_for_termination(termination, entries_for_termination)
+        if sort_interfaces_by_strain_and_size:
+            self.sort_interfaces_for_all_terminations_by_strain_and_size()
+        if remove_duplicates:
+            self.remove_duplicate_interfaces()
+
+    def set_interfaces_for_termination(self, termination: TerminationType, interfaces: List[Interface]):
+        self.data[termination] = interfaces
+
+    def get_termination(self, termination: Union[int, TerminationType]) -> TerminationType:
+        if isinstance(termination, int):
+            termination = self.terminations[termination]
+        return termination
+
+    def get_interfaces_for_termination_or_its_index(
+        self, termination_or_its_index: Union[int, TerminationType]
+    ) -> List[Interface]:
+        termination = self.get_termination(termination_or_its_index)
+        return self.data[termination]
+
+    def get_interfaces_for_termination(
+        self,
+        termination_or_its_index: Union[int, TerminationType],
+        slice_or_index_or_indices: Union[int, slice, List[int], None] = None,
+    ) -> List[Interface]:
+        interfaces = self.get_interfaces_for_termination_or_its_index(termination_or_its_index)
+        return array_utils.filter_by_slice_or_index_or_indices(interfaces, slice_or_index_or_indices)
+
+    def remove_duplicate_interfaces(self, strain_mode: StrainModes = StrainModes.mean_abs_strain):
+        for termination in self.terminations:
+            self.remove_duplicate_interfaces_for_termination(termination, strain_mode)
+
+    def remove_duplicate_interfaces_for_termination(
+        self, termination, strain_mode: StrainModes = StrainModes.mean_abs_strain
+    ):
+        def are_interfaces_duplicate(interface1: Interface, interface2: Interface):
+            return interface1.num_sites == interface2.num_sites and np.allclose(
+                interface1.interface_properties[strain_mode], interface2.interface_properties[strain_mode]
+            )
+
+        sorted_interfaces = self.get_interfaces_for_termination_sorted_by_size(termination)
+        filtered_interfaces = [sorted_interfaces[0]] if sorted_interfaces else []
+
+        for interface in sorted_interfaces[1:]:
+            if not any(
+                are_interfaces_duplicate(interface, unique_interface) for unique_interface in filtered_interfaces
+            ):
+                filtered_interfaces.append(interface)
+
+        self.set_interfaces_for_termination(termination, filtered_interfaces)
+
+    def get_interfaces_for_termination_sorted_by_strain(
+        self, termination: Union[int, TerminationType], strain_mode: StrainModes = StrainModes.mean_abs_strain
+    ) -> List[Interface]:
+        return sorted(
+            self.get_interfaces_for_termination(termination),
+            key=lambda x: np.mean(np.abs(x.interface_properties[strain_mode])),
+        )
+
+    def get_interfaces_for_termination_sorted_by_size(
+        self, termination: Union[int, TerminationType]
+    ) -> List[Interface]:
+        return sorted(
+            self.get_interfaces_for_termination(termination),
+            key=lambda x: x.num_sites,
+        )
+
+    def get_interfaces_for_termination_sorted_by_strain_and_size(
+        self, termination: Union[int, TerminationType], strain_mode: StrainModes = StrainModes.mean_abs_strain
+    ) -> List[Interface]:
+        return sorted(
+            self.get_interfaces_for_termination_sorted_by_strain(termination, strain_mode),
+            key=lambda x: x.num_sites,
+        )
+
+    def sort_interfaces_for_all_terminations_by_strain_and_size(self):
+        for termination in self.terminations:
+            self.set_interfaces_for_termination(
+                termination, self.get_interfaces_for_termination_sorted_by_strain_and_size(termination)
+            )
+
+    def get_all_interfaces(self) -> List[Interface]:
+        return functools.reduce(lambda a, b: a + b, self.data.values())
+
+    def get_interfaces_as_materials(
+        self, termination: Union[int, TerminationType], slice_range_or_index: Union[int, slice]
+    ) -> List[Interface]:
+        return list(
+            map(
+                convert_atoms_or_structure_to_material,
+                self.get_interfaces_for_termination(termination, slice_range_or_index),
+            )
+        )

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

@@ -1,10 +1,11 @@
 from ase import Atoms
 from ase.calculators.calculator import Calculator
 
-from .convert import convert_material_args_kwargs_to_atoms
+from .analyze import get_surface_area
+from .convert import decorator_convert_material_args_kwargs_to_atoms
 
 
-@convert_material_args_kwargs_to_atoms
+@decorator_convert_material_args_kwargs_to_atoms
 def calculate_total_energy(atoms: Atoms, calculator: Calculator):
     """
     Set calculator for ASE Atoms and calculate the total energy.
@@ -18,3 +19,94 @@ def calculate_total_energy(atoms: Atoms, calculator: Calculator):
     """
     atoms.set_calculator(calculator)
     return atoms.get_total_energy()
+
+
+@decorator_convert_material_args_kwargs_to_atoms
+def calculate_total_energy_per_atom(atoms: Atoms, calculator: Calculator):
+    """
+    Set calculator for ASE Atoms and calculate the total energy per atom.
+
+    Args:
+            atoms (ase.Atoms): The Atoms object to calculate the energy of.
+            calculator (ase.calculators.calculator.Calculator): The calculator to use for the energy calculation.
+
+    Returns:
+            float: The energy per atom of the atoms.
+    """
+    return calculate_total_energy(atoms, calculator) / atoms.get_global_number_of_atoms()
+
+
+@decorator_convert_material_args_kwargs_to_atoms
+def calculate_surface_energy(slab: Atoms, bulk: Atoms, calculator: Calculator):
+    """
+    Calculate the surface energy by subtracting the weighted bulk energy from the slab energy.
+
+    Args:
+        slab (ase.Atoms): The slab Atoms object to calculate the surface energy of.
+        bulk (ase.Atoms): The bulk Atoms object to calculate the surface energy of.
+        calculator (ase.calculators.calculator.Calculator): The calculator to use for the energy calculation.
+
+    Returns:
+        float: The surface energy of the slab.
+    """
+    number_of_atoms = slab.get_global_number_of_atoms()
+    area = get_surface_area(slab)
+    return (
+        calculate_total_energy(slab, calculator) - calculate_total_energy_per_atom(bulk, calculator) * number_of_atoms
+    ) / (2 * area)
+
+
+@decorator_convert_material_args_kwargs_to_atoms
+def calculate_adhesion_energy(interface: Atoms, substrate_slab: Atoms, layer_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.
+    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.
+        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_interface = calculate_total_energy(interface, calculator)
+    area = get_surface_area(interface)
+    return (energy_substrate_slab + energy_layer_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,
+):
+    """
+    Calculate the interfacial energy.
+    The interfacial energy is the sum of the surface energies of the substrate and layer 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.
+
+    Returns:
+        float: The interfacial energy of the interface.
+    """
+
+    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

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

@@ -167,7 +167,7 @@ def from_ase(ase_atoms: Atoms) -> Dict[str, Any]:
     return from_pymatgen(structure)
 
 
-def convert_material_args_kwargs_to_atoms(func: Callable) -> Callable:
+def decorator_convert_material_args_kwargs_to_atoms(func: Callable) -> Callable:
     """
     Decorator that converts ESSE Material objects to ASE Atoms objects.
     """
@@ -184,3 +184,30 @@ def convert_material_args_kwargs_to_atoms(func: Callable) -> Callable:
         return func(*new_args, **new_kwargs)
 
     return wrapper
+
+
+def decorator_convert_material_args_kwargs_to_structure(func: Callable) -> Callable:
+    """
+    Decorator that converts ESSE Material objects to pymatgen Structure objects.
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        # Convert args if they are of type ESSE Material
+        new_args = [to_pymatgen(arg) if isinstance(arg, Material) else arg for arg in args]
+
+        # Convert kwargs if they are of type ESSE Material
+        new_kwargs = {k: to_pymatgen(v) if isinstance(v, Material) else v for k, v in kwargs.items()}
+
+        # Call the original function with the converted arguments
+        return func(*new_args, **new_kwargs)
+
+    return wrapper
+
+
+def convert_atoms_or_structure_to_material(item):
+    if isinstance(item, Structure):
+        return from_pymatgen(item)
+    elif isinstance(item, Atoms):
+        return from_ase(item)
+    return item

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

@@ -1,11 +1,17 @@
 from typing import Union
 
 from ase import Atoms
+from pymatgen.analysis.structure_analyzer import SpacegroupAnalyzer
+from pymatgen.core.structure import Structure
 
-from .convert import convert_material_args_kwargs_to_atoms
+from .convert import (
+    decorator_convert_material_args_kwargs_to_atoms,
+    decorator_convert_material_args_kwargs_to_structure,
+)
+from .utils import translate_to_bottom_pymatgen_structure
 
 
-@convert_material_args_kwargs_to_atoms
+@decorator_convert_material_args_kwargs_to_atoms
 def filter_by_label(atoms: Atoms, label: Union[int, str]):
     """
     Filter out only atoms corresponding to the label/tag.
@@ -18,3 +24,35 @@ def filter_by_label(atoms: Atoms, label: Union[int, str]):
         ase.Atoms: The filtered Atoms object.
     """
     return atoms[atoms.get_tags() == label]
+
+
+@decorator_convert_material_args_kwargs_to_structure
+def translate_to_bottom(structure: Structure, use_conventional_cell: bool = True):
+    """
+    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.
+
+    Args:
+        structure (Structure): The pymatgen Structure object to normalize.
+        use_conventional_cell: Whether to convert to the conventional cell.
+    Returns:
+        Structure: The normalized pymatgen Structure object.
+    """
+    if use_conventional_cell:
+        structure = SpacegroupAnalyzer(structure).get_conventional_standard_structure()
+    structure = translate_to_bottom_pymatgen_structure(structure)
+    return structure
+
+
+@decorator_convert_material_args_kwargs_to_structure
+def wrap_to_unit_cell(structure: Structure):
+    """
+    Wrap atoms to the cell
+
+    Args:
+        structure (Structure): The pymatgen Structure object to normalize.
+    Returns:
+        Structure: The wrapped pymatgen Structure object.
+    """
+    structure.make_supercell((1, 1, 1), to_unit_cell=True)
+    return structure

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

@@ -0,0 +1,19 @@
+from pymatgen.core.structure import Structure
+
+
+# TODO: convert to accept ASE Atoms object
+def translate_to_bottom_pymatgen_structure(structure: Structure):
+    """
+    Translate the structure to the bottom of the cell.
+    Args:
+        structure (Structure): The pymatgen Structure object to translate.
+
+    Returns:
+        Structure: The translated pymatgen Structure object.
+    """
+    min_c = min(site.c for site in structure)
+    translation_vector = [0, 0, -min_c]
+    translated_structure = structure.copy()
+    for site in translated_structure:
+        site.coords += translation_vector
+    return translated_structure

package/tests/py/unit/fixtures.py

@@ -0,0 +1,31 @@
+from typing import Tuple
+
+from ase.build import bulk
+from mat3ra.made.material import Material
+from mat3ra.made.tools.build.interface import interface_patch_with_mean_abs_strain
+from mat3ra.made.tools.convert import from_ase
+from pymatgen.core.interface import Interface
+
+from .utils import atoms_to_interface_structure
+
+# ASE Atoms fixtures
+substrate = bulk("Si", cubic=True)
+film = bulk("Cu", cubic=True)
+INTERFACE_ATOMS = substrate + film
+INTERFACE_ATOMS.set_tags([1] * len(substrate) + [2] * len(film))
+
+# Material fixtures
+SUBSTRATE_MATERIAL = Material(from_ase(substrate))
+LAYER_MATERIAL = Material(from_ase(film))
+
+# Pymatgen Interface fixtures
+INTERFACE_TERMINATION: Tuple = ("Si_termination", "Cu_termination")
+
+interface_structure = atoms_to_interface_structure(INTERFACE_ATOMS)
+dict = interface_structure.as_dict()
+
+INTERFACE_STRUCTURE = Interface.from_dict(dict)
+# Add properties that are assigned during interface creation in ZSL algorithm
+INTERFACE_STRUCTURE.interface_properties["termination"] = INTERFACE_TERMINATION
+INTERFACE_STRUCTURE.interface_properties["strain"] = 0.1
+INTERFACE_STRUCTURE = interface_patch_with_mean_abs_strain(INTERFACE_STRUCTURE)

package/tests/py/unit/test_tools_analyze.py

@@ -1,12 +1,16 @@
 import numpy as np
 from ase.build import bulk
-from mat3ra.made.tools.analyze import calculate_average_interlayer_distance
+from mat3ra.made.tools.analyze import get_average_interlayer_distance, get_surface_area
+
+from .fixtures import INTERFACE_ATOMS
 
 
 def test_calculate_average_interlayer_distance():
-    substrate = bulk("Si", cubic=True)
-    film = bulk("Cu", cubic=True)
-    interface_atoms = substrate + film
-    interface_atoms.set_tags([1] * len(substrate) + [2] * len(film))
-    distance = calculate_average_interlayer_distance(interface_atoms, 1, 2)
+    distance = get_average_interlayer_distance(INTERFACE_ATOMS, 1, 2)
     assert np.isclose(distance, 4.0725)
+
+
+def test_calculate_surface_area():
+    atoms = bulk("Si", cubic=False)
+    area = get_surface_area(atoms)
+    assert np.isclose(area, 12.7673)

package/tests/py/unit/test_tools_build.py

@@ -0,0 +1,22 @@
+import platform
+
+from mat3ra.made.tools.build import create_interfaces
+from mat3ra.made.tools.build.interface import InterfaceSettings
+
+from .fixtures import LAYER_MATERIAL, SUBSTRATE_MATERIAL
+
+MAX_AREA = 200
+# pymatgen `2023.6.23` supporting py3.8 returns 1 interface instead of 2
+EXPECTED_NUMBER_OF_INTERFACES = 1 if platform.python_version().startswith("3.8") else 2
+settings = InterfaceSettings(
+    USE_CONVENTIONAL_CELL=True,
+    INTERFACE_PARAMETERS={"DISTANCE_Z": 3.0, "MAX_AREA": MAX_AREA},
+    ZSL_PARAMETERS={"MAX_AREA": MAX_AREA, "MAX_AREA_TOL": 0.09, "MAX_LENGTH_TOL": 0.03, "MAX_ANGLE_TOL": 0.01},
+    SUBSTRATE_PARAMETERS={"MILLER_INDICES": (1, 1, 1), "THICKNESS": 3},
+    LAYER_PARAMETERS={"MILLER_INDICES": (0, 0, 1), "THICKNESS": 1},
+)
+
+
+def test_create_interfaces():
+    interfaces = create_interfaces(substrate=SUBSTRATE_MATERIAL, layer=LAYER_MATERIAL, settings=settings)
+    assert len(interfaces.get_interfaces_for_termination(0)) == EXPECTED_NUMBER_OF_INTERFACES

package/tests/py/unit/test_tools_build_interface.py

@@ -0,0 +1,24 @@
+from mat3ra.made.tools.build.interface import InterfaceDataHolder
+
+from .fixtures import INTERFACE_STRUCTURE, INTERFACE_TERMINATION
+
+
+def test_add_data_entries():
+    interfaces_data = InterfaceDataHolder()
+    interfaces_data.add_data_entries(INTERFACE_STRUCTURE)
+    assert len(interfaces_data.get_interfaces_for_termination(0)) == 1
+    assert len(interfaces_data.get_interfaces_for_termination(INTERFACE_TERMINATION)) == 1
+
+
+def test_get_interfaces_for_termination():
+    interfaces_data = InterfaceDataHolder()
+    interfaces_data.add_data_entries([INTERFACE_STRUCTURE])
+    assert interfaces_data.get_interfaces_for_termination(0)[0] == INTERFACE_STRUCTURE
+
+
+def test_remove_duplicate_interfaces():
+    interfaces_data = InterfaceDataHolder()
+    interfaces_data.add_data_entries([INTERFACE_STRUCTURE, INTERFACE_STRUCTURE], remove_duplicates=False)
+    assert len(interfaces_data.get_interfaces_for_termination(INTERFACE_TERMINATION)) == 2
+    interfaces_data.remove_duplicate_interfaces()
+    assert len(interfaces_data.get_interfaces_for_termination(INTERFACE_TERMINATION)) == 1

package/tests/py/unit/test_tools_calculate.py

@@ -1,7 +1,29 @@
 import numpy as np
-from ase.build import bulk
+from ase.build import add_adsorbate, bulk, fcc111, graphene, surface
 from ase.calculators import emt
-from mat3ra.made.tools.calculate import calculate_total_energy
+from mat3ra.made.tools.calculate import (
+    calculate_adhesion_energy,
+    calculate_interfacial_energy,
+    calculate_surface_energy,
+    calculate_total_energy,
+    calculate_total_energy_per_atom,
+)
+
+# Interface and its constituents structures setup
+nickel_slab = fcc111("Ni", size=(2, 2, 3), vacuum=10, a=3.52)
+graphene_layer = graphene(size=(1, 1, 1), vacuum=10)
+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)
+
+nickel_bulk = bulk("Ni", "fcc", a=3.52)
+graphene_bulk = graphene_layer
 
 
 def test_calculate_total_energy():
@@ -9,3 +31,34 @@ def test_calculate_total_energy():
     calculator = emt.EMT()
     energy = calculate_total_energy(atoms, calculator)
     assert np.isclose(energy, 1.3612647524769237)
+
+
+def test_calculate_total_energy_per_atom():
+    atoms = bulk("C", cubic=True)
+    calculator = emt.EMT()
+    print(atoms.get_global_number_of_atoms())
+    energy_per_atom = calculate_total_energy_per_atom(atoms, calculator)
+    assert np.isclose(energy_per_atom, 0.1701580940596)
+
+
+def test_calculate_surface_energy():
+    atoms_slab = surface("C", (1, 1, 1), 3, vacuum=10)
+    atoms_bulk = bulk("C", cubic=True)
+    calculator = emt.EMT()
+    surface_energy = calculate_surface_energy(atoms_slab, atoms_bulk, calculator)
+    assert np.isclose(surface_energy, 0.148845)
+
+
+def test_calculate_adhesion_energy():
+    adhesion_energy = calculate_adhesion_energy(interface, nickel_slab, graphene_layer, calculator)
+    assert np.isclose(adhesion_energy, 0.07345)
+
+
+def test_calculate_interfacial_energy():
+    interfacial_energy = calculate_interfacial_energy(
+        interface, nickel_slab, nickel_bulk, graphene_layer, graphene_bulk, calculator
+    )
+    assert np.isclose(
+        interfacial_energy,
+        0.030331590159230523,
+    )

package/tests/py/unit/utils.py

@@ -0,0 +1,25 @@
+from typing import Dict
+
+from pymatgen.core.structure import Structure
+from pymatgen.io.ase import AseAtomsAdaptor
+
+ATOMS_TAGS_TO_INTERFACE_STRUCTURE_LABELS: Dict = {1: "substrate", 2: "film"}
+INTERFACE_STRUCTURE_LABELS_TO_ATOMS_TAGS: Dict = {v: k for k, v in ATOMS_TAGS_TO_INTERFACE_STRUCTURE_LABELS.items()}
+
+
+def atoms_to_interface_structure(atoms) -> Structure:
+    """
+    Converts ASE Atoms object to pymatgen Interface object.
+    Args:
+        atoms (Atoms): The ASE Atoms object.
+    Returns:
+        Interface: The pymatgen Interface object.
+    """
+
+    adaptor = AseAtomsAdaptor()
+    interface_structure = adaptor.get_structure(atoms)
+    interface_structure.add_site_property(
+        "interface_label",
+        [ATOMS_TAGS_TO_INTERFACE_STRUCTURE_LABELS[tag] for tag in interface_structure.site_properties["tags"]],
+    )
+    return interface_structure