@mat3ra/made 2024.7.31-0 → 2024.7.31-1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2024.7.31-0",
+    "version": "2024.7.31-1",
     "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

@@ -246,10 +246,12 @@ def get_atom_indices_with_condition_on_coordinates(
         List[int]: List of indices of atoms whose coordinates satisfy the condition.
     """
     new_material = material.clone()
+    new_basis = new_material.basis
     if use_cartesian_coordinates:
-        new_basis = new_material.basis
         new_basis.to_cartesian()
-        new_material.basis = new_basis
+    else:
+        new_basis.to_crystal()
+    new_material.basis = new_basis
     coordinates = new_material.basis.coordinates.to_array_of_values_with_ids()
 
     selected_indices = []
@@ -313,10 +315,12 @@ def get_atomic_coordinates_extremum(
         float: Minimum or maximum of coordinates along the specified axis.
     """
     new_material = material.clone()
+    new_basis = new_material.basis
     if use_cartesian_coordinates:
-        new_basis = new_material.basis
         new_basis.to_cartesian()
-        new_material.basis = new_basis
+    else:
+        new_basis.to_crystal()
+    new_material.basis = new_basis
     coordinates = new_material.basis.coordinates.to_array_of_values_with_ids()
     values = [coord.value[{"x": 0, "y": 1, "z": 2}[axis]] for coord in coordinates]
     return getattr(np, extremum)(values)

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

@@ -1,6 +1,5 @@
 from typing import Optional, Union
 
-from mat3ra.utils.factory import BaseFactory
 from mat3ra.made.material import Material
 
 from .builders import (
@@ -14,14 +13,7 @@ from .builders import (
 )
 from .configuration import PointDefectConfiguration, AdatomSlabPointDefectConfiguration, IslandSlabDefectConfiguration
 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",
-    }
+from .factories import DefectBuilderFactory
 
 
 def create_defect(

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

@@ -1,9 +1,10 @@
-from typing import List, Callable, Optional
+from typing import List, Callable, Optional, Union
 
 import numpy as np
 from pydantic import BaseModel
 from mat3ra.made.material import Material
 
+
 from ...third_party import (
     PymatgenStructure,
     PymatgenPeriodicSite,
@@ -39,7 +40,9 @@ from .configuration import (
     AdatomSlabPointDefectConfiguration,
     IslandSlabDefectConfiguration,
     TerraceSlabDefectConfiguration,
+    PointDefectPairConfiguration,
 )
+from .factories import DefectBuilderFactory
 
 
 class PointDefectBuilderParameters(BaseModel):
@@ -47,7 +50,7 @@ class PointDefectBuilderParameters(BaseModel):
 
 
 class DefectBuilder(BaseBuilder):
-    def create_isolated_defect(self, material: Material, defect_configuration: PointDefectConfiguration) -> Material:
+    def create_isolated_defect(self, defect_configuration: PointDefectConfiguration) -> Material:
         raise NotImplementedError
 
 
@@ -171,8 +174,7 @@ class AdatomSlabDefectBuilder(SlabDefectBuilder):
     def _calculate_coordinate_from_position_and_distance(
         self, material: Material, position_on_surface: List[float], distance_z: float
     ) -> List[float]:
-        max_z = get_atomic_coordinates_extremum(material)
-        distance_z = distance_z
+        max_z = get_atomic_coordinates_extremum(material, use_cartesian_coordinates=False)
         distance_in_crystal_units = distance_z / material.lattice.c
         return [position_on_surface[0], position_on_surface[1], max_z + distance_in_crystal_units]
 
@@ -272,12 +274,16 @@ class CrystalSiteAdatomSlabDefectBuilder(AdatomSlabDefectBuilder):
         )
         return approximate_adatom_coordinate_cartesian
 
-    def create_isolated_defect(
+    def create_isolated_adatom(
         self,
-        material: Material,
-        approximate_adatom_coordinate_cartesian: List[float],
-        chemical_element: Optional[str] = None,
+        original_material: Material,
+        configuration: AdatomSlabPointDefectConfiguration,
     ) -> Material:
+        material: Material = configuration.crystal
+        approximate_adatom_coordinate_cartesian: List[float] = self.calculate_approximate_adatom_coordinate(
+            original_material, configuration.position_on_surface, configuration.distance_z
+        )
+        chemical_element: Optional[str] = configuration.chemical_element or None
         if chemical_element is None:
             closest_site_id = get_closest_site_id_from_coordinate(material, approximate_adatom_coordinate_cartesian)
         else:
@@ -310,21 +316,77 @@ class CrystalSiteAdatomSlabDefectBuilder(AdatomSlabDefectBuilder):
             position_on_surface = [0.5, 0.5]
 
         new_material = material.clone()
-
-        approximate_adatom_coordinate_cartesian = self.calculate_approximate_adatom_coordinate(
-            new_material, position_on_surface, distance_z
-        )
-
         material_with_additional_layer = self.create_material_with_additional_layers(new_material)
         material_with_additional_layer.to_cartesian()
 
-        only_adatom_material = self.create_isolated_defect(
-            material_with_additional_layer, approximate_adatom_coordinate_cartesian, chemical_element
+        only_adatom_material = self.create_isolated_adatom(
+            original_material=new_material,
+            configuration=AdatomSlabPointDefectConfiguration(
+                crystal=material_with_additional_layer,
+                chemical_element=chemical_element,
+                position_on_surface=position_on_surface,
+                distance_z=distance_z,
+            ),
         )
 
         return self.merge_slab_and_defect(new_material, only_adatom_material)
 
 
+class DefectPairBuilder(DefectBuilder):
+    def create_defect_pair(
+        self,
+        primary_defect_configuration: Union[PointDefectConfiguration, AdatomSlabPointDefectConfiguration],
+        secondary_defect_configuration: Union[PointDefectConfiguration, AdatomSlabPointDefectConfiguration],
+    ) -> Material:
+        """
+        Create a pair of point defects in the material.
+
+        Args:
+            primary_defect_configuration: The configuration of the first defect.
+            secondary_defect_configuration: The configuration of the second defect.
+
+        Returns:
+            Material: The material with both defects added.
+        """
+        primary_material = self.create_isolated_defect(primary_defect_configuration)
+        # Remove metadata to allow for independent defect creation
+        primary_material.metadata["build"] = primary_defect_configuration.crystal.metadata["build"]
+        primary_material.name = primary_defect_configuration.crystal.name
+        secondary_defect_configuration.crystal = primary_material
+        secondary_material = self.create_isolated_defect(secondary_defect_configuration)
+
+        return secondary_material
+
+
+class PointDefectPairBuilder(PointDefectBuilder, DefectPairBuilder):
+    _ConfigurationType: type(PointDefectPairConfiguration) = PointDefectPairConfiguration  # type: ignore
+    _GeneratedItemType: Material = Material
+
+    def create_isolated_defect(self, defect_configuration: PointDefectConfiguration) -> Material:
+        key = defect_configuration.defect_type.value
+        if hasattr(defect_configuration, "placement_method") and defect_configuration.placement_method is not None:
+            key += f":{defect_configuration.placement_method.name}".lower()
+        builder_class = DefectBuilderFactory.get_class_by_name(key)
+        defect_builder = builder_class()
+        return defect_builder.get_material(defect_configuration)
+
+    def _generate(self, configuration: _ConfigurationType) -> List[_GeneratedItemType]:
+        return [
+            self.create_defect_pair(
+                primary_defect_configuration=configuration.primary_defect_configuration,
+                secondary_defect_configuration=configuration.secondary_defect_configuration,
+            )
+        ]
+
+    def _update_material_name(self, material: Material, configuration: _ConfigurationType) -> Material:
+        updated_material = super()._update_material_name(material, configuration)
+        name_1 = configuration.primary_defect_configuration.defect_type.name.capitalize()
+        name_2 = configuration.secondary_defect_configuration.defect_type.name.capitalize()
+        new_name = f"{updated_material.name}, {name_1} and {name_2} Defect Pair"
+        updated_material.name = new_name
+        return updated_material
+
+
 class IslandSlabDefectBuilder(SlabDefectBuilder):
     _ConfigurationType: type(IslandSlabDefectConfiguration) = IslandSlabDefectConfiguration  # type: ignore
     _GeneratedItemType: Material = Material

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

@@ -1,4 +1,4 @@
-from typing import Optional, List, Any, Callable, Dict, Tuple
+from typing import Optional, List, Any, Callable, Dict, Tuple, Union
 from pydantic import BaseModel
 
 from mat3ra.code.entity import InMemoryEntity
@@ -6,7 +6,7 @@ from mat3ra.made.material import Material
 
 from ...analyze import get_closest_site_id_from_coordinate, get_atomic_coordinates_extremum
 from ...utils import CoordinateConditionBuilder
-from .enums import PointDefectTypeEnum, SlabDefectTypeEnum
+from .enums import PointDefectTypeEnum, SlabDefectTypeEnum, AtomPlacementMethodEnum, ComplexDefectTypeEnum
 
 
 class BaseDefectConfiguration(BaseModel):
@@ -144,12 +144,15 @@ class AdatomSlabPointDefectConfiguration(SlabPointDefectConfiguration):
     """
 
     defect_type: PointDefectTypeEnum = PointDefectTypeEnum.ADATOM
+    placement_method: AtomPlacementMethodEnum = AtomPlacementMethodEnum.COORDINATE
 
     @property
     def _json(self):
         return {
             **super()._json,
             "type": self.get_cls_name(),
+            "defect_type": self.defect_type.name,
+            "placement_method": self.placement_method.name,
         }
 
 
@@ -212,3 +215,26 @@ class TerraceSlabDefectConfiguration(SlabDefectConfiguration):
             "use_cartesian_coordinates": self.use_cartesian_coordinates,
             "rotate_to_match_pbc": self.rotate_to_match_pbc,
         }
+
+
+class PointDefectPairConfiguration(BaseDefectConfiguration, InMemoryEntity):
+    """
+    Configuration for a pair of point defects.
+
+    Args:
+        primary_defect_configuration: The first defect configuration.
+        secondary_defect_configuration: The second defect configuration. Material is used from the primary defect.
+    """
+
+    defect_type: ComplexDefectTypeEnum = ComplexDefectTypeEnum.PAIR
+    primary_defect_configuration: Union[PointDefectConfiguration, AdatomSlabPointDefectConfiguration]
+    secondary_defect_configuration: Union[PointDefectConfiguration, AdatomSlabPointDefectConfiguration]
+
+    @property
+    def _json(self):
+        return {
+            "type": self.get_cls_name(),
+            "defect_type": self.defect_type.name,
+            "primary_defect_configuration": self.primary_defect_configuration.to_json(),
+            "secondary_defect_configuration": self.secondary_defect_configuration.to_json(),
+        }

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

@@ -11,3 +11,18 @@ class PointDefectTypeEnum(str, Enum):
 class SlabDefectTypeEnum(str, Enum):
     ISLAND = "island"
     TERRACE = "terrace"
+
+
+class ComplexDefectTypeEnum(str, Enum):
+    PAIR = "pair"
+
+
+class AtomPlacementMethodEnum(str, Enum):
+    # Places the atom at the exact given coordinate.
+    COORDINATE = "coordinate"
+    # Among existing atoms, selects the closest one to the given coordinate.
+    CLOSEST_SITE = "closest_site"
+    # Places the atom at the equal distance from the closest atoms to the given coordinate.
+    EQUIDISTANT = "equidistant"
+    # Places the atom at the existing or extrapolated crystal site closest to the given coordinate.
+    CRYSTAL_SITE = "crystal_site"

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

@@ -0,0 +1,12 @@
+from mat3ra.utils.factory import BaseFactory
+
+
+class DefectBuilderFactory(BaseFactory):
+    __class_registry__ = {
+        "vacancy": "mat3ra.made.tools.build.defect.builders.VacancyPointDefectBuilder",
+        "substitution": "mat3ra.made.tools.build.defect.builders.SubstitutionPointDefectBuilder",
+        "interstitial": "mat3ra.made.tools.build.defect.builders.InterstitialPointDefectBuilder",
+        "adatom:coordinate": "mat3ra.made.tools.build.defect.builders.AdatomSlabDefectBuilder",
+        "adatom:crystal_site": "mat3ra.made.tools.build.defect.builders.CrystalSiteAdatomSlabDefectBuilder",
+        "adatom:equidistant": "mat3ra.made.tools.build.defect.builders.EquidistantAdatomSlabDefectBuilder",
+    }

package/tests/py/unit/fixtures.py

@@ -4,7 +4,7 @@ from typing import Any, Dict
 from ase.build import bulk
 from mat3ra.made.material import Material
 from mat3ra.made.tools.build.interface.termination_pair import TerminationPair
-from mat3ra.made.tools.build.slab import SlabConfiguration, get_terminations
+from mat3ra.made.tools.build.slab import SlabConfiguration, create_slab, get_terminations
 from mat3ra.made.tools.convert import from_ase
 from pymatgen.analysis.elasticity.strain import Strain
 from pymatgen.core.interface import Interface
@@ -236,3 +236,27 @@ SI_SLAB_VACUUM["basis"]["coordinates"] = [
 SI_SLAB_VACUUM["basis"]["cell"] = [[3.867, 0.0, 0.0], [-0.0, 3.867, 0.0], [0.0, 0.0, 15.937527692]]
 SI_SLAB_VACUUM["lattice"]["c"] = 15.937527692
 SI_SLAB_VACUUM["lattice"]["vectors"]["c"] = [0.0, 0.0, 15.937527692]
+
+
+clean_material = Material.create(Material.default_config)
+slab_111_config = SlabConfiguration(
+    bulk=clean_material,
+    miller_indices=(1, 1, 1),
+    thickness=4,
+    vacuum=6,
+    xy_supercell_matrix=[[1, 0], [0, 1]],
+    use_orthogonal_z=True,
+)
+t_111 = get_terminations(slab_111_config)[0]
+SLAB_111 = create_slab(slab_111_config, t_111)
+
+slab_001_config = SlabConfiguration(
+    bulk=clean_material,
+    miller_indices=(0, 0, 1),
+    thickness=3,
+    vacuum=3,
+    xy_supercell_matrix=[[2, 0], [0, 1]],
+    use_orthogonal_z=True,
+)
+t_001 = get_terminations(slab_001_config)[0]
+SLAB_001 = create_slab(slab_001_config, t_001)

package/tests/py/unit/test_tools_build_defect.py

@@ -5,27 +5,26 @@ from mat3ra.made.tools.build.defect import (
     EquidistantAdatomSlabDefectBuilder,
     PointDefectBuilderParameters,
     PointDefectConfiguration,
+    PointDefectTypeEnum,
     create_defect,
     create_slab_defect,
 )
-from mat3ra.made.tools.build.defect.builders import IslandSlabDefectBuilder, TerraceSlabDefectBuilder
-from mat3ra.made.tools.build.defect.configuration import IslandSlabDefectConfiguration, TerraceSlabDefectConfiguration
-from mat3ra.made.tools.build.slab import SlabConfiguration, create_slab, get_terminations
+from mat3ra.made.tools.build.defect.builders import (
+    IslandSlabDefectBuilder,
+    PointDefectPairBuilder,
+    TerraceSlabDefectBuilder,
+)
+from mat3ra.made.tools.build.defect.configuration import (
+    IslandSlabDefectConfiguration,
+    PointDefectPairConfiguration,
+    TerraceSlabDefectConfiguration,
+)
 from mat3ra.made.tools.utils import CoordinateConditionBuilder
 from mat3ra.utils import assertion as assertion_utils
 
-clean_material = Material.create(Material.default_config)
+from .fixtures import SLAB_001, SLAB_111
 
-slab_config = SlabConfiguration(
-    bulk=clean_material,
-    miller_indices=(1, 1, 1),
-    thickness=4,
-    vacuum=6,
-    xy_supercell_matrix=[[1, 0], [0, 1]],
-    use_orthogonal_z=True,
-)
-t = get_terminations(slab_config)[0]
-slab = create_slab(slab_config, t)
+clean_material = Material.create(Material.default_config)
 
 
 def test_create_vacancy():
@@ -78,7 +77,7 @@ def test_create_defect_from_site_id():
 def test_create_adatom():
     # Adatom of Si at 0.5, 0.5 position
     configuration = AdatomSlabPointDefectConfiguration(
-        crystal=slab, position_on_surface=[0.5, 0.5], distance_z=2, chemical_element="Si"
+        crystal=SLAB_111, position_on_surface=[0.5, 0.5], distance_z=2, chemical_element="Si"
     )
     defect = create_slab_defect(configuration=configuration, builder=None)
 
@@ -89,7 +88,7 @@ def test_create_adatom():
 def test_create_adatom_equidistant():
     # Adatom of Si at approximate 0.5, 0.5 position
     configuration = AdatomSlabPointDefectConfiguration(
-        crystal=slab, position_on_surface=[0.5, 0.5], distance_z=2, chemical_element="Si"
+        crystal=SLAB_111, position_on_surface=[0.5, 0.5], distance_z=2, chemical_element="Si"
     )
     defect = create_slab_defect(configuration=configuration, builder=EquidistantAdatomSlabDefectBuilder())
 
@@ -103,7 +102,7 @@ def test_create_adatom_equidistant():
 def test_create_crystal_site_adatom():
     # Adatom of Si (autodetect) at approximate 0.5, 0.5 position
     configuration = AdatomSlabPointDefectConfiguration(
-        crystal=slab, position_on_surface=[0.5, 0.5], distance_z=2, chemical_element=None
+        crystal=SLAB_111, position_on_surface=[0.5, 0.5], distance_z=2, chemical_element=None
     )
     builder = CrystalSiteAdatomSlabDefectBuilder()
     defect = create_slab_defect(configuration=configuration, builder=builder)
@@ -117,7 +116,7 @@ def test_create_crystal_site_adatom():
 def test_create_island():
     condition = CoordinateConditionBuilder.cylinder(center_position=[0.625, 0.5], radius=0.25, min_z=0, max_z=1)
     island_config = IslandSlabDefectConfiguration(
-        crystal=slab,
+        crystal=SLAB_111,
         defect_type="island",
         condition=condition,
         thickness=1,
@@ -126,27 +125,35 @@ def test_create_island():
     defect = create_slab_defect(configuration=island_config, builder=IslandSlabDefectBuilder())
 
     # Only one atom is in the island for this configuration
-    assert len(defect.basis.elements.values) == len(slab.basis.elements.values) + 1
+    assert len(defect.basis.elements.values) == len(SLAB_111.basis.elements.values) + 1
     assert defect.basis.elements.values[-1] == "Si"
 
 
 def test_create_terrace():
-    slab_config = SlabConfiguration(
-        bulk=clean_material,
-        miller_indices=(0, 0, 1),
-        thickness=3,
-        vacuum=3,
-        xy_supercell_matrix=[[2, 0], [0, 1]],
-        use_orthogonal_z=True,
-    )
-    t = get_terminations(slab_config)[0]
-    slab = create_slab(slab_config, t)
-
     config = TerraceSlabDefectConfiguration(
-        crystal=slab,
+        crystal=SLAB_001,
         cut_direction=[1, 0, 0],
         pivot_coordinate=[0.5, 0.5, 0.5],
         number_of_added_layers=1,
     )
     new_slab = TerraceSlabDefectBuilder().get_material(configuration=config)
     assertion_utils.assert_deep_almost_equal([0.720082355, 0.5, 0.461401798], new_slab.basis.coordinates.values[42])
+
+
+def test_create_defect_pair():
+    defect1_config = PointDefectConfiguration.from_approximate_position(
+        crystal=SLAB_001,
+        defect_type=PointDefectTypeEnum.VACANCY,
+        approximate_coordinate=[0.5, 0.5, 0.25],
+    )
+    defect2_config = PointDefectConfiguration(
+        defect_type=PointDefectTypeEnum.INTERSTITIAL, coordinate=[0.5, 0.55, 0.35], chemical_element="P"
+    )
+    defect_pair_config = PointDefectPairConfiguration(
+        primary_defect_configuration=defect1_config,
+        secondary_defect_configuration=defect2_config,
+    )
+    defect_material = PointDefectPairBuilder().get_material(defect_pair_config)
+
+    assertion_utils.assert_deep_almost_equal("P", defect_material.basis.elements.values[0])
+    assertion_utils.assert_deep_almost_equal([0.5, 0.55, 0.35], defect_material.basis.coordinates.values[0])