@mat3ra/made 2025.8.23-0 → 2025.8.24-0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/made",
-    "version": "2025.8.23-0",
+    "version": "2025.8.24-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/lattice/__init__.py

@@ -0,0 +1,2 @@
+from .analyzer import LatticeMaterialAnalyzer
+from .helpers import get_lattice_type, get_material_with_conventional_lattice, get_material_with_primitive_lattice

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

@@ -0,0 +1,120 @@
+from ....lattice import LatticeTypeEnum
+from ...build_components.metadata import MaterialWithBuildMetadata
+from ...convert import from_pymatgen, to_pymatgen
+from ...operations.core.unary import rotate
+from ...third_party import PymatgenSpacegroupAnalyzer
+from .. import BaseMaterialAnalyzer
+from ..basis import BasisMaterialAnalyzer
+
+
+class LatticeMaterialAnalyzer(BaseMaterialAnalyzer):
+    precision: float = 0.1
+    angle_tolerance: float = 5.0
+
+    @property
+    def spacegroup_analyzer(self):
+        return PymatgenSpacegroupAnalyzer(
+            to_pymatgen(self.material), symprec=self.precision, angle_tolerance=self.angle_tolerance
+        )
+
+    def detect_lattice_type(self, precision=0.1, angle_tolerance=5) -> LatticeTypeEnum:
+        """
+        Detects the lattice type of the material.
+
+        Args:
+            precision (float): Tolerance for lattice parameter comparison, in Angstroms.
+            angle_tolerance (float): Tolerance for angle comparisons, in degrees.
+
+        Returns:
+            LatticeTypeEnum: The detected lattice type.
+        """
+        self.precision = precision
+        self.angle_tolerance = angle_tolerance
+        try:
+            lattice_type = self.spacegroup_analyzer.get_lattice_type()
+            spg_symbol = self.spacegroup_analyzer.get_space_group_symbol()
+
+            # Enhanced detection using space group symbol
+            if lattice_type == "cubic":
+                if "P" in spg_symbol:
+                    return LatticeTypeEnum.CUB
+                elif "F" in spg_symbol:
+                    return LatticeTypeEnum.FCC
+                elif "I" in spg_symbol:
+                    return LatticeTypeEnum.BCC
+            elif lattice_type == "tetragonal":
+                if "P" in spg_symbol:
+                    return LatticeTypeEnum.TET
+                elif "I" in spg_symbol:
+                    return LatticeTypeEnum.BCT
+            elif lattice_type == "orthorhombic":
+                if "P" in spg_symbol:
+                    return LatticeTypeEnum.ORC
+                elif "F" in spg_symbol:
+                    return LatticeTypeEnum.ORCF
+                elif "I" in spg_symbol:
+                    return LatticeTypeEnum.ORCI
+                elif "C" in spg_symbol:
+                    return LatticeTypeEnum.ORCC
+            elif lattice_type == "hexagonal":
+                return LatticeTypeEnum.HEX
+            elif lattice_type == "rhombohedral":
+                return LatticeTypeEnum.RHL
+            elif lattice_type == "monoclinic":
+                if "P" in spg_symbol:
+                    return LatticeTypeEnum.MCL
+                elif "C" in spg_symbol:
+                    return LatticeTypeEnum.MCLC
+
+        except Exception:
+            return LatticeTypeEnum.TRI
+
+    @property
+    def material_with_primitive_lattice(self: MaterialWithBuildMetadata) -> MaterialWithBuildMetadata:
+        """
+        Convert a structure to its primitive cell.
+        """
+        return MaterialWithBuildMetadata.create(
+            from_pymatgen(self.spacegroup_analyzer.get_primitive_standard_structure())
+        )
+
+    @property
+    def material_with_conventional_lattice(self: MaterialWithBuildMetadata) -> MaterialWithBuildMetadata:
+        """
+        Convert a structure to its conventional cell.
+        """
+        return MaterialWithBuildMetadata.create(
+            from_pymatgen(self.spacegroup_analyzer.get_conventional_standard_structure())
+        )
+
+    def get_material_with_primitive_lattice_standard(
+        self, return_original_if_not_reduced: bool = False, keep_orientation: bool = True, layer_thickness: float = 1.0
+    ) -> MaterialWithBuildMetadata:
+        """
+        Get material with primitive lattice and optional orientation correction to be standardized.
+
+        Args:
+            return_original_if_not_reduced: If True, return original material when no reduction occurs
+            keep_orientation: If True, correct orientation after primitive conversion
+            layer_thickness: Thickness of layers for orientation detection
+
+        Returns:
+            MaterialWithBuildMetadata: Material with primitive lattice
+        """
+        material_with_primitive_lattice = self.material_with_primitive_lattice
+        original_number_of_atoms = self.material.basis.number_of_atoms
+        primitive_structure_number_of_atoms = material_with_primitive_lattice.basis.number_of_atoms
+
+        if original_number_of_atoms == primitive_structure_number_of_atoms:
+            if return_original_if_not_reduced:
+                return self.material
+
+        if keep_orientation:
+            basis_analyzer = BasisMaterialAnalyzer(material=material_with_primitive_lattice)
+            if basis_analyzer.is_orientation_flipped(self.material, layer_thickness):
+                material_with_primitive_lattice = rotate(
+                    material_with_primitive_lattice, axis=[1, 0, 0], angle=180, rotate_cell=False
+                )
+                print("Orientation corrected after primitive conversion.")
+
+        return material_with_primitive_lattice

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

@@ -0,0 +1,31 @@
+from ....lattice import LatticeTypeEnum
+from ...build_components.metadata import MaterialWithBuildMetadata
+from .analyzer import LatticeMaterialAnalyzer
+
+
+def get_material_with_conventional_lattice(material: MaterialWithBuildMetadata) -> MaterialWithBuildMetadata:
+    analyzer = LatticeMaterialAnalyzer(material=material)
+    return analyzer.material_with_conventional_lattice
+
+
+def get_material_with_primitive_lattice(
+    material: MaterialWithBuildMetadata, return_original_if_not_reduced=False, keep_orientation=True
+) -> MaterialWithBuildMetadata:
+    analyzer = LatticeMaterialAnalyzer(material=material)
+    return analyzer.get_material_with_primitive_lattice_standard(return_original_if_not_reduced, keep_orientation)
+
+
+def get_lattice_type(material: MaterialWithBuildMetadata, tolerance=0.2, angle_tolerance=5) -> LatticeTypeEnum:
+    """
+    Detects the lattice type of the material.
+
+    Args:
+        material (MaterialWithBuildMetadata): The material to analyze.
+        tolerance (float): Tolerance for lattice parameter comparisons.
+        angle_tolerance (float): Tolerance for angle comparisons.
+
+    Returns:
+        LatticeTypeEnum: The detected lattice type.
+    """
+    analyzer = LatticeMaterialAnalyzer(material=material)
+    return analyzer.detect_lattice_type(precision=tolerance, angle_tolerance=angle_tolerance)

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

@@ -1,3 +1,6 @@
+# Analyzers
+from .analyze.lattice import get_material_with_conventional_lattice, get_material_with_primitive_lattice
+
 # Defective Structures
 from .build.compound_pristine_structures.two_dimensional.heterostructure import create_heterostructure
 from .build.compound_pristine_structures.two_dimensional.heterostructure.types import StackComponentDict
@@ -87,6 +90,9 @@ from .build_components.operations.core.modifications.perturb.helpers import crea
 from .entities.coordinate import CoordinateCondition
 
 __all__ = [
+    # Crystal and related analyzer functions
+    "get_material_with_primitive_lattice",
+    "get_material_with_conventional_lattice",
     # Slab and related Functions
     "create_slab",
     "create_slab_if_not",

package/tests/py/unit/test_tools_analyze.py

@@ -7,7 +7,6 @@ from mat3ra.made.tools.analyze.crystal_site.adatom_crystal_site_material_analyze
 from mat3ra.made.tools.analyze.crystal_site.adatom_material_analyzer import AdatomMaterialAnalyzer
 from mat3ra.made.tools.analyze.crystal_site.crystal_site_analyzer import CrystalSiteAnalyzer
 from mat3ra.made.tools.analyze.crystal_site.voronoi_crystal_site_analyzer import VoronoiCrystalSiteAnalyzer
-from mat3ra.made.tools.analyze.lattice import LatticeMaterialAnalyzer
 from mat3ra.made.tools.analyze.other import (
     SurfaceTypesEnum,
     get_average_interlayer_distance,
@@ -23,10 +22,9 @@ from mat3ra.made.tools.build_components.operations.core.combinations.enums impor
 from unit.fixtures.nanoribbon.nanoribbon import GRAPHENE_ZIGZAG_NANORIBBON
 from unit.utils import OSPlatform, get_platform_specific_value
 
-from .fixtures.bulk import BULK_Si_CONVENTIONAL, BULK_Si_PRIMITIVE, BULK_Si_PRIMITIVIZED
+from .fixtures.bulk import BULK_Si_CONVENTIONAL, BULK_Si_PRIMITIVE
 from .fixtures.interface.zsl import GRAPHENE_NICKEL_INTERFACE
 from .fixtures.slab import SI_CONVENTIONAL_SLAB_001
-from .utils import assert_two_entities_deep_almost_equal
 
 COMPARISON_PRECISION = 1e-4
 
@@ -88,23 +86,6 @@ def test_radial_distribution_function(material_config, rdf_params, expected_firs
     assert np.isclose(rdf.first_peak_distance, expected_first_peak_distance, atol=0.1)
 
 
-@pytest.mark.parametrize(
-    "primitive_material_config, expected_conventional_material_config, expected_primitive_material_config",
-    [(BULK_Si_PRIMITIVE, BULK_Si_CONVENTIONAL, BULK_Si_PRIMITIVIZED)],
-)
-def test_lattice_material_analyzer(
-    primitive_material_config, expected_conventional_material_config, expected_primitive_material_config
-):
-    primitive_cell = Material.create(primitive_material_config)
-    lattice_material_analyzer = LatticeMaterialAnalyzer(material=primitive_cell)
-
-    conventional_cell = lattice_material_analyzer.material_with_conventional_lattice
-    assert_two_entities_deep_almost_equal(conventional_cell, expected_conventional_material_config)
-
-    primitive_cell_generated = lattice_material_analyzer.material_with_primitive_lattice
-    assert_two_entities_deep_almost_equal(primitive_cell_generated, expected_primitive_material_config)
-
-
 VORONOI_SITE_EXPECTED = {OSPlatform.DARWIN: [0.625, 0.625, 0.125], OSPlatform.OTHER: [0.5, 0.5, 0.5]}
 
 

package/tests/py/unit/test_tools_analyze_lattice.py

@@ -0,0 +1,38 @@
+import pytest
+from mat3ra.made.material import Material
+from mat3ra.made.tools.analyze.lattice import LatticeMaterialAnalyzer, get_lattice_type
+
+from .fixtures.bulk import BULK_GRAPHITE, BULK_Hf2O_MCL, BULK_Si_CONVENTIONAL, BULK_Si_PRIMITIVE, BULK_Si_PRIMITIVIZED
+from .fixtures.interface.gr_ni_111_top_hcp import GRAPHENE_NICKEL_INTERFACE_TOP_HCP
+from .utils import assert_two_entities_deep_almost_equal
+
+
+@pytest.mark.parametrize(
+    "primitive_material_config, expected_conventional_material_config, expected_primitive_material_config",
+    [(BULK_Si_PRIMITIVE, BULK_Si_CONVENTIONAL, BULK_Si_PRIMITIVIZED)],
+)
+def test_lattice_material_analyzer(
+    primitive_material_config, expected_conventional_material_config, expected_primitive_material_config
+):
+    primitive_cell = Material.create(primitive_material_config)
+    lattice_material_analyzer = LatticeMaterialAnalyzer(material=primitive_cell)
+    conventional_cell = lattice_material_analyzer.material_with_conventional_lattice
+    assert_two_entities_deep_almost_equal(conventional_cell, expected_conventional_material_config)
+
+    primitive_cell_generated = lattice_material_analyzer.material_with_primitive_lattice
+    assert_two_entities_deep_almost_equal(primitive_cell_generated, expected_primitive_material_config)
+
+
+@pytest.mark.parametrize(
+    "material, expected_lattice_type",
+    [
+        (BULK_Si_PRIMITIVE, "FCC"),
+        (BULK_Si_CONVENTIONAL, "FCC"),
+        (GRAPHENE_NICKEL_INTERFACE_TOP_HCP, "HEX"),
+        (BULK_Hf2O_MCL, "MCL"),
+        (BULK_GRAPHITE, "HEX"),
+    ],
+)
+def test_analyze_lattice_type(material, expected_lattice_type):
+    result = get_lattice_type(material)
+    assert result.value == expected_lattice_type

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

@@ -1,82 +0,0 @@
-from ..build_components.metadata import MaterialWithBuildMetadata
-from ..convert import from_pymatgen, to_pymatgen
-from ..operations.core.unary import rotate
-from ..third_party import PymatgenSpacegroupAnalyzer
-from . import BaseMaterialAnalyzer
-from .basis import BasisMaterialAnalyzer
-
-
-class LatticeMaterialAnalyzer(BaseMaterialAnalyzer):
-    @property
-    def spacegroup_analyzer(self):
-        return PymatgenSpacegroupAnalyzer(to_pymatgen(self.material))
-
-    @property
-    def material_with_primitive_lattice(self: MaterialWithBuildMetadata) -> MaterialWithBuildMetadata:
-        """
-        Convert a structure to its primitive cell.
-        """
-        return MaterialWithBuildMetadata.create(
-            from_pymatgen(self.spacegroup_analyzer.get_primitive_standard_structure())
-        )
-
-    @property
-    def material_with_primitive_lattice_standard(self) -> MaterialWithBuildMetadata:
-        """
-        Get material with primitive lattice and standard orientation correction.
-        Uses default parameters: return_original_if_not_reduced=False, keep_orientation=True
-        """
-        return self.get_material_with_primitive_lattice_standard()
-
-    @property
-    def material_with_conventional_lattice(self: MaterialWithBuildMetadata) -> MaterialWithBuildMetadata:
-        """
-        Convert a structure to its conventional cell.
-        """
-        return MaterialWithBuildMetadata.create(
-            from_pymatgen(self.spacegroup_analyzer.get_conventional_standard_structure())
-        )
-
-    def get_material_with_primitive_lattice_standard(
-        self, return_original_if_not_reduced: bool = False, keep_orientation: bool = True, layer_thickness: float = 1.0
-    ) -> MaterialWithBuildMetadata:
-        """
-        Get material with primitive lattice and optional orientation correction to be standardized.
-
-        Args:
-            return_original_if_not_reduced: If True, return original material when no reduction occurs
-            keep_orientation: If True, correct orientation after primitive conversion
-            layer_thickness: Thickness of layers for orientation detection
-
-        Returns:
-            MaterialWithBuildMetadata: Material with primitive lattice
-        """
-        material_with_primitive_lattice = self.material_with_primitive_lattice
-        original_number_of_atoms = self.material.basis.number_of_atoms
-        primitive_structure_number_of_atoms = material_with_primitive_lattice.basis.number_of_atoms
-
-        if original_number_of_atoms == primitive_structure_number_of_atoms:
-            if return_original_if_not_reduced:
-                return self.material
-
-        if keep_orientation:
-            basis_analyzer = BasisMaterialAnalyzer(material=material_with_primitive_lattice)
-            if basis_analyzer.is_orientation_flipped(self.material, layer_thickness):
-                material_with_primitive_lattice = rotate(
-                    material_with_primitive_lattice, axis=[1, 0, 0], angle=180, rotate_cell=False
-                )
-                print("Orientation corrected after primitive conversion.")
-
-        return material_with_primitive_lattice
-
-
-def get_material_with_conventional_lattice(material: MaterialWithBuildMetadata) -> MaterialWithBuildMetadata:
-    analyzer = LatticeMaterialAnalyzer(material=material)
-    return analyzer.material_with_conventional_lattice
-
-
-def get_material_with_primitive_lattice(
-    material: MaterialWithBuildMetadata, return_original_if_not_reduced=False, keep_orientation=True
-) -> MaterialWithBuildMetadata:
-    analyzer = LatticeMaterialAnalyzer(material=material)
-    return analyzer.get_material_with_primitive_lattice_standard(return_original_if_not_reduced, keep_orientation)