@mat3ra/made 2024.6.11-0 → 2024.6.12-0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2024.6.11-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/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/utils.py

@@ -15,6 +15,10 @@ 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]]:

package/tests/py/unit/fixtures.py

@@ -56,7 +56,7 @@ 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 = {

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"},
+    ]