@mat3ra/made 2024.4.16-0 → 2024.4.25-0

package/package.json

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

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

@@ -5,7 +5,7 @@ from .convert import convert_material_args_kwargs_to_atoms
 
 
 @convert_material_args_kwargs_to_atoms
-def calculate_average_interlayer_distance(
+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)
+
+
+@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/calculate.py

@@ -2,6 +2,7 @@ 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
 
 
 @convert_material_args_kwargs_to_atoms
@@ -18,3 +19,94 @@ def calculate_total_energy(atoms: Atoms, calculator: Calculator):
     """
     atoms.set_calculator(calculator)
     return atoms.get_total_energy()
+
+
+@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()
+
+
+@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)
+
+
+@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
+
+
+@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/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/test_tools_analyze.py

@@ -1,6 +1,7 @@
 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
+from mat3ra.made.tools.analyze import get_surface_area
 
 
 def test_calculate_average_interlayer_distance():
@@ -8,5 +9,11 @@ def test_calculate_average_interlayer_distance():
     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_calculate.py

@@ -1,7 +1,29 @@
 import numpy as np
-from ase.build import bulk
+from ase.build import bulk, surface, fcc111, graphene, add_adsorbate
 from ase.calculators import emt
-from mat3ra.made.tools.calculate import calculate_total_energy
+from mat3ra.made.tools.calculate import (
+    calculate_total_energy,
+    calculate_total_energy_per_atom,
+    calculate_surface_energy,
+    calculate_adhesion_energy,
+    calculate_interfacial_energy,
+)
+
+# 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,
+    )