@mat3ra/made 2024.8.16-0 → 2024.8.20-0

package/package.json

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

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

@@ -95,3 +95,16 @@ class Material(HasDescriptionHasMetadataNamedDefaultableInMemoryEntity):
         new_basis = self.basis.copy()
         new_basis.coordinates.values = coordinates
         self.basis = new_basis
+
+    def set_new_lattice_vectors(
+        self, lattice_vector1: List[float], lattice_vector2: List[float], lattice_vector3: List[float]
+    ) -> None:
+        new_basis = self.basis.copy()
+        new_basis.to_cartesian()
+        new_basis.cell.vector1 = lattice_vector1
+        new_basis.cell.vector2 = lattice_vector2
+        new_basis.cell.vector3 = lattice_vector3
+        new_basis.to_crystal()
+        self.basis = new_basis
+        lattice = Lattice.from_vectors_array([lattice_vector1, lattice_vector2, lattice_vector3])
+        self.lattice = lattice

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

@@ -1,10 +1,28 @@
 from typing import List, Optional, Any
 
+from mat3ra.code.entity import InMemoryEntity
 from pydantic import BaseModel
 
 from ...material import Material
 
 
+class BaseConfiguration(BaseModel, InMemoryEntity):
+    """
+    Base class for material build configurations.
+    This class provides an interface for defining the configuration parameters.
+
+    The class is designed to be subclassed and the subclass should define the following attributes:
+    - `_json`: The JSON representation of the configuration.
+    """
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    @property
+    def _json(self):
+        raise NotImplementedError
+
+
 class BaseBuilder(BaseModel):
     """
     Base class for material builders.

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

@@ -40,7 +40,8 @@ def safely_select_termination_pair(
 ) -> TerminationPair:
     """
     Attempt finding provided in generated terminations to find a complete match,
-    if match isn't found, get terminations with equivalent chemical elements.
+    if match isn't found, get terminations with equivalent chemical elements,
+    if that fails, return the first generated termination pair.
     """
     provided_film_termination = provided_termination_pair.film_termination
     provided_substrate_termination = provided_termination_pair.substrate_termination
@@ -55,5 +56,8 @@ def safely_select_termination_pair(
                 == provided_substrate_termination.chemical_elements
             ):
                 hotfix_termination_pair = termination_pair
-                print("Interface will be built with terminations: ", hotfix_termination_pair)
+            else:
+                hotfix_termination_pair = generated_termination_pairs[0]
+            print("Interface will be built with terminations: ", hotfix_termination_pair)
+
     return hotfix_termination_pair

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

@@ -0,0 +1,9 @@
+from mat3ra.made.material import Material
+
+from .builders import NanoribbonBuilder
+from .configuration import NanoribbonConfiguration
+
+
+def create_nanoribbon(configuration: NanoribbonConfiguration) -> Material:
+    builder = NanoribbonBuilder()
+    return builder.get_material(configuration)

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

@@ -0,0 +1,149 @@
+from typing import List, Optional, Any, Tuple
+
+import numpy as np
+
+from mat3ra.made.material import Material
+from mat3ra.made.tools.build import BaseBuilder
+from mat3ra.made.tools.build.supercell import create_supercell
+from mat3ra.made.tools.modify import filter_by_rectangle_projection, wrap_to_unit_cell
+
+from ...modify import translate_to_center
+from .configuration import NanoribbonConfiguration
+from .enums import EdgeTypes
+
+
+class NanoribbonBuilder(BaseBuilder):
+    """
+    Builder class for creating a nanoribbon from a material.
+
+    The process creates a supercell with large enough dimensions to contain the nanoribbon and then
+    filters the supercell to only include the nanoribbon. The supercell is then centered and returned as the nanoribbon.
+    The nanoribbon can have either Armchair or Zigzag edge. The edge is defined along the vector 1 of the material cell,
+    which corresponds to [1,0,0] direction.
+    """
+
+    _ConfigurationType: type(NanoribbonConfiguration) = NanoribbonConfiguration  # type: ignore
+    _GeneratedItemType: Material = Material
+    _PostProcessParametersType: Any = None
+
+    def create_nanoribbon(self, config: NanoribbonConfiguration) -> Material:
+        material = config.material
+        (
+            length_cartesian,
+            width_cartesian,
+            height_cartesian,
+            vacuum_length_cartesian,
+            vacuum_width_cartesian,
+        ) = self._calculate_cartesian_dimensions(config, material)
+        length_lattice_vector, width_lattice_vector, height_lattice_vector = self._get_new_lattice_vectors(
+            length_cartesian,
+            width_cartesian,
+            height_cartesian,
+            vacuum_length_cartesian,
+            vacuum_width_cartesian,
+            config.edge_type,
+        )
+        n = max(config.length, config.width)
+        large_supercell_to_cut = create_supercell(material, np.diag([2 * n, 2 * n, 1]))
+
+        min_coordinate, max_coordinate = self._calculate_coordinates_of_cut(
+            length_cartesian, width_cartesian, height_cartesian, config.edge_type
+        )
+        nanoribbon = filter_by_rectangle_projection(
+            large_supercell_to_cut,
+            min_coordinate=min_coordinate,
+            max_coordinate=max_coordinate,
+            use_cartesian_coordinates=True,
+        )
+        nanoribbon.set_new_lattice_vectors(length_lattice_vector, width_lattice_vector, height_lattice_vector)
+        return translate_to_center(nanoribbon)
+
+    @staticmethod
+    def _calculate_cartesian_dimensions(config: NanoribbonConfiguration, material: Material):
+        """
+        Calculate the dimensions of the nanoribbon in the cartesian coordinate system.
+        """
+        nanoribbon_width = config.width
+        nanoribbon_length = config.length
+        vacuum_width = config.vacuum_width
+        vacuum_length = config.vacuum_length
+        edge_type = config.edge_type
+
+        if edge_type == EdgeTypes.armchair:
+            nanoribbon_length, nanoribbon_width = nanoribbon_width, nanoribbon_length
+            vacuum_width, vacuum_length = vacuum_length, vacuum_width
+
+        length_cartesian = nanoribbon_length * np.dot(np.array(material.basis.cell.vector1), np.array([1, 0, 0]))
+        width_cartesian = nanoribbon_width * np.dot(np.array(material.basis.cell.vector2), np.array([0, 1, 0]))
+        height_cartesian = np.dot(np.array(material.basis.cell.vector3), np.array([0, 0, 1]))
+        vacuum_length_cartesian = vacuum_length * np.dot(np.array(material.basis.cell.vector1), np.array([1, 0, 0]))
+        vacuum_width_cartesian = vacuum_width * np.dot(np.array(material.basis.cell.vector2), np.array([0, 1, 0]))
+
+        return length_cartesian, width_cartesian, height_cartesian, vacuum_length_cartesian, vacuum_width_cartesian
+
+    @staticmethod
+    def _get_new_lattice_vectors(
+        length: float, width: float, height: float, vacuum_length: float, vacuum_width: float, edge_type: EdgeTypes
+    ) -> Tuple[List[float], List[float], List[float]]:
+        """
+        Calculate the new lattice vectors for the nanoribbon.
+
+        Args:
+            length: Length of the nanoribbon.
+            width: Width of the nanoribbon.
+            height: Height of the nanoribbon.
+            vacuum_length: Length of the vacuum region.
+            vacuum_width: Width of the vacuum region.
+            edge_type: Type of the edge of the nanoribbon.
+
+        Returns:
+            Tuple of the new lattice vectors.
+        """
+        length_lattice_vector = [length + vacuum_length, 0, 0]
+        width_lattice_vector = [0, width + vacuum_width, 0]
+        height_lattice_vector = [0, 0, height]
+
+        if edge_type == EdgeTypes.armchair:
+            length_lattice_vector, width_lattice_vector = width_lattice_vector, length_lattice_vector
+
+        return length_lattice_vector, width_lattice_vector, height_lattice_vector
+
+    @staticmethod
+    def _calculate_coordinates_of_cut(
+        length: float, width: float, height: float, edge_type: EdgeTypes
+    ) -> Tuple[List[float], List[float]]:
+        """
+        Calculate the coordinates of the rectangular nanoribbon cut from the supercell.
+
+        Args:
+            length: Length of the nanoribbon.
+            width: Width of the nanoribbon.
+            height: Height of the nanoribbon.
+            edge_type: Type of the edge of the nanoribbon.
+
+        Returns:
+            Tuple of the minimum and maximum coordinates of the cut.
+        """
+        edge_nudge_value = 0.01
+        conditional_nudge_value = edge_nudge_value * (
+            -1 * (edge_type == EdgeTypes.armchair) + 1 * (edge_type == EdgeTypes.zigzag)
+        )
+        min_coordinate = [-edge_nudge_value, conditional_nudge_value, 0]
+        max_coordinate = [length - edge_nudge_value, width + conditional_nudge_value, height]
+        return min_coordinate, max_coordinate
+
+    def _generate(self, configuration: NanoribbonConfiguration) -> List[_GeneratedItemType]:
+        nanoribbon = self.create_nanoribbon(configuration)
+        return [nanoribbon]
+
+    def _post_process(
+        self,
+        items: List[_GeneratedItemType],
+        post_process_parameters: Optional[_PostProcessParametersType],
+    ) -> List[Material]:
+        return [wrap_to_unit_cell(item) for item in items]
+
+    def _update_material_name(self, material: Material, configuration: NanoribbonConfiguration) -> Material:
+        edge_type = configuration.edge_type.capitalize()
+        material.name = f"{material.name} ({edge_type} nanoribbon)"
+        return material

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

@@ -0,0 +1,37 @@
+from mat3ra.made.material import Material
+from mat3ra.made.tools.build.nanoribbon.enums import EdgeTypes
+
+from ...build import BaseConfiguration
+
+
+class NanoribbonConfiguration(BaseConfiguration):
+    """
+    Configuration for building a nanoribbon from a material.
+
+
+    Attributes:
+        material (Material): The material to build the nanoribbon from.
+        width (int): The width of the nanoribbon in number of unit cells.
+        length (int): The length of the nanoribbon in number of unit cells.
+        vacuum_width (int): The width of the vacuum region in number of unit cells.
+        vacuum_length (int): The length of the vacuum region in number of unit cells.
+        edge_type (EdgeTypes): The type of edge to use for the nanoribbon, either zigzag or armchair.
+    """
+
+    material: Material
+    width: int  # in number of unit cells
+    length: int  # in number of unit cells
+    vacuum_width: int = 3  # in number of unit cells
+    vacuum_length: int = 0  # in number of unit cells
+    edge_type: EdgeTypes = EdgeTypes.zigzag
+
+    @property
+    def _json(self):
+        return {
+            "material": self.material.to_json(),
+            "width": self.width,
+            "length": self.length,
+            "vacuum_width": self.vacuum_width,
+            "vacuum_length": self.vacuum_length,
+            "edge_type": self.edge_type,
+        }

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

@@ -0,0 +1,10 @@
+from enum import Enum
+
+
+class EdgeTypes(str, Enum):
+    """
+    Enum for nanoribbon edge types.
+    """
+
+    zigzag = "zigzag"
+    armchair = "armchair"

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

@@ -87,6 +87,31 @@ def translate_by_vector(
     return Material(from_ase(atoms))
 
 
+def translate_to_center(material: Material, axes: Optional[List[str]] = None) -> Material:
+    """
+    Center the material in the unit cell.
+
+    Args:
+        material (Material): The material object to center.
+        axes (List[str]): The axes to center the material along.
+    Returns:
+        Material: The centered material object.
+    """
+    new_material = material.clone()
+    new_material.to_crystal()
+    if axes is None:
+        axes = ["x", "y", "z"]
+    min_x = get_atomic_coordinates_extremum(material, axis="x", extremum="min") if "x" in axes else 0
+    max_x = get_atomic_coordinates_extremum(material, axis="x", extremum="max") if "x" in axes else 1
+    min_y = get_atomic_coordinates_extremum(material, axis="y", extremum="min") if "y" in axes else 0
+    max_y = get_atomic_coordinates_extremum(material, axis="y", extremum="max") if "y" in axes else 1
+    if "z" in axes:
+        material = translate_to_z_level(material, z_level="center")
+
+    material = translate_by_vector(material, vector=[(1 - min_x - max_x) / 2, (1 - min_y - max_y) / 2, 0])
+    return material
+
+
 def wrap_to_unit_cell(material: Material) -> Material:
     """
     Wrap the material to the unit cell.

package/tests/py/unit/fixtures.py

@@ -289,3 +289,161 @@ GRAPHENE = {
     },
     "isNonPeriodic": False,
 }
+
+GRAPHENE_ZIGZAG_NANORIBBON = {
+    "name": "Graphene (Zigzag nanoribbon)",
+    "basis": {
+        "elements": [
+            {"id": 0, "value": "C"},
+            {"id": 1, "value": "C"},
+            {"id": 2, "value": "C"},
+            {"id": 3, "value": "C"},
+            {"id": 4, "value": "C"},
+            {"id": 5, "value": "C"},
+            {"id": 6, "value": "C"},
+            {"id": 7, "value": "C"},
+            {"id": 8, "value": "C"},
+            {"id": 9, "value": "C"},
+            {"id": 10, "value": "C"},
+            {"id": 11, "value": "C"},
+            {"id": 12, "value": "C"},
+            {"id": 13, "value": "C"},
+            {"id": 14, "value": "C"},
+            {"id": 15, "value": "C"},
+        ],
+        "coordinates": [
+            {"id": 0, "value": [0.062499937, 0.366666681, 0.5]},
+            {"id": 1, "value": [0.312499937, 0.366666681, 0.5]},
+            {"id": 2, "value": [0.187500062, 0.433333286, 0.5]},
+            {"id": 3, "value": [0.187499937, 0.566666695, 0.5]},
+            {"id": 4, "value": [0.062500062, 0.6333333, 0.5]},
+            {"id": 5, "value": [0.562499937, 0.366666681, 0.5]},
+            {"id": 6, "value": [0.437500062, 0.433333286, 0.5]},
+            {"id": 7, "value": [0.437499937, 0.566666695, 0.5]},
+            {"id": 8, "value": [0.312500062, 0.6333333, 0.5]},
+            {"id": 9, "value": [0.812499938, 0.366666681, 0.5]},
+            {"id": 10, "value": [0.687500062, 0.433333286, 0.5]},
+            {"id": 11, "value": [0.687499937, 0.566666695, 0.5]},
+            {"id": 12, "value": [0.562500062, 0.6333333, 0.5]},
+            {"id": 13, "value": [0.937500063, 0.433333286, 0.5]},
+            {"id": 14, "value": [0.937499937, 0.566666695, 0.5]},
+            {"id": 15, "value": [0.812500063, 0.6333333, 0.5]},
+        ],
+        "units": "crystal",
+        "cell": [[9.869164, 0.0, 0.0], [-0.0, 10.683683422, 0.0], [0.0, 0.0, 20.0]],
+        "constraints": [],
+        "labels": [],
+    },
+    "lattice": {
+        "a": 9.869164,
+        "b": 10.683683422,
+        "c": 20.0,
+        "alpha": 90.0,
+        "beta": 90.0,
+        "gamma": 90.0,
+        "units": {"length": "angstrom", "angle": "degree"},
+        "type": "TRI",
+        "vectors": {
+            "a": [9.869164, 0.0, 0.0],
+            "b": [-0.0, 10.683683422, 0.0],
+            "c": [0.0, 0.0, 20.0],
+            "alat": 1,
+            "units": "angstrom",
+        },
+    },
+    "isNonPeriodic": False,
+    "_id": "",
+    "metadata": {
+        "boundaryConditions": {"type": "pbc", "offset": 0},
+        "build": {
+            "configuration": {
+                "material": GRAPHENE,
+                "width": 2,
+                "length": 4,
+                "vacuum_width": 3,
+                "vacuum_length": 0,
+                "edge_type": "zigzag",
+            }
+        },
+    },
+    "isUpdated": True,
+}
+
+GRAPHENE_ARMCHAIR_NANORIBBON = {
+    "name": "Graphene (Armchair nanoribbon)",
+    "basis": {
+        "elements": [
+            {"id": 0, "value": "C"},
+            {"id": 1, "value": "C"},
+            {"id": 2, "value": "C"},
+            {"id": 3, "value": "C"},
+            {"id": 4, "value": "C"},
+            {"id": 5, "value": "C"},
+            {"id": 6, "value": "C"},
+            {"id": 7, "value": "C"},
+            {"id": 8, "value": "C"},
+            {"id": 9, "value": "C"},
+            {"id": 10, "value": "C"},
+            {"id": 11, "value": "C"},
+            {"id": 12, "value": "C"},
+            {"id": 13, "value": "C"},
+            {"id": 14, "value": "C"},
+            {"id": 15, "value": "C"},
+        ],
+        "coordinates": [
+            {"id": 0, "value": [0.041666626, 0.35000005, 0.5]},
+            {"id": 1, "value": [0.208333376, 0.34999995, 0.5]},
+            {"id": 2, "value": [0.041666626, 0.55000005, 0.5]},
+            {"id": 3, "value": [0.208333376, 0.54999995, 0.5]},
+            {"id": 4, "value": [0.291666626, 0.45000005, 0.5]},
+            {"id": 5, "value": [0.458333376, 0.44999995, 0.5]},
+            {"id": 6, "value": [0.541666626, 0.35000005, 0.5]},
+            {"id": 7, "value": [0.708333376, 0.34999995, 0.5]},
+            {"id": 8, "value": [0.291666626, 0.65000005, 0.5]},
+            {"id": 9, "value": [0.458333376, 0.64999995, 0.5]},
+            {"id": 10, "value": [0.541666626, 0.55000005, 0.5]},
+            {"id": 11, "value": [0.708333376, 0.54999995, 0.5]},
+            {"id": 12, "value": [0.791666626, 0.45000005, 0.5]},
+            {"id": 13, "value": [0.958333376, 0.44999995, 0.5]},
+            {"id": 14, "value": [0.791666626, 0.65000005, 0.5]},
+            {"id": 15, "value": [0.958333376, 0.64999995, 0.5]},
+        ],
+        "units": "crystal",
+        "cell": [[8.546946738, 0.0, 0.0], [-0.0, 12.336455, 0.0], [0.0, 0.0, 20.0]],
+        "constraints": [],
+        "labels": [],
+    },
+    "lattice": {
+        "a": 8.546946738,
+        "b": 12.336455,
+        "c": 20.0,
+        "alpha": 90.0,
+        "beta": 90.0,
+        "gamma": 90.0,
+        "units": {"length": "angstrom", "angle": "degree"},
+        "type": "TRI",
+        "vectors": {
+            "a": [8.546946738, 0.0, 0.0],
+            "b": [-0.0, 12.336455, 0.0],
+            "c": [0.0, 0.0, 20.0],
+            "alat": 1,
+            "units": "angstrom",
+        },
+    },
+    "isNonPeriodic": False,
+    "_id": "",
+    "metadata": {
+        "boundaryConditions": {"type": "pbc", "offset": 0},
+        "build": {
+            "configuration": {
+                "material": GRAPHENE,
+                "width": 2,
+                "length": 4,
+                "vacuum_width": 3,
+                "vacuum_length": 0,
+                "edge_type": "armchair",
+            }
+        },
+    },
+    "isUpdated": True,
+}

package/tests/py/unit/test_tools_build_nanoribbon.py

@@ -0,0 +1,32 @@
+from mat3ra.made.material import Material
+from mat3ra.made.tools.build.nanoribbon import NanoribbonConfiguration, create_nanoribbon
+from mat3ra.made.tools.build.nanoribbon.enums import EdgeTypes
+from mat3ra.utils import assertion as assertion_utils
+
+from .fixtures import GRAPHENE, GRAPHENE_ARMCHAIR_NANORIBBON, GRAPHENE_ZIGZAG_NANORIBBON
+
+
+def test_build_zigzag_nanoribbon():
+    config = NanoribbonConfiguration(
+        material=Material(GRAPHENE),
+        width=2,
+        length=4,
+        vacuum_width=3,
+        edge_type=EdgeTypes.zigzag,
+    )
+
+    nanoribbon = create_nanoribbon(config)
+    assertion_utils.assert_deep_almost_equal(GRAPHENE_ZIGZAG_NANORIBBON, nanoribbon.to_json())
+
+
+def test_build_armchair_nanoribbon():
+    config = NanoribbonConfiguration(
+        material=Material(GRAPHENE),
+        width=2,
+        length=4,
+        vacuum_width=3,
+        edge_type=EdgeTypes.armchair,
+    )
+
+    nanoribbon = create_nanoribbon(config)
+    assertion_utils.assert_deep_almost_equal(GRAPHENE_ARMCHAIR_NANORIBBON, nanoribbon.to_json())