@mat3ra/made 2025.11.4-0 → 2025.11.22-0

package/dist/js/materialMixin.d.ts

@@ -108,6 +108,14 @@ export declare function materialMixin<T extends Base = Base>(item: T): {
      * Calculates hash from basis and lattice as above + scales lattice properties to make lattice.a = 1
      */
     readonly scaledHash: string;
+    external: {
+        id: string | number;
+        source: string;
+        origin: boolean;
+        data?: {} | undefined;
+        doi?: string | undefined;
+        url?: string | undefined;
+    } | undefined;
     /**
      * Converts basis to crystal/fractional coordinates.
      */

package/dist/js/materialMixin.js

@@ -232,6 +232,12 @@ function materialMixin(item) {
         get scaledHash() {
             return this.calculateHash("", true);
         },
+        get external() {
+            return item.prop("external");
+        },
+        set external(external) {
+            item.setProp("external", external);
+        },
         /**
          * Converts basis to crystal/fractional coordinates.
          */

package/package.json

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

package/pyproject.toml

@@ -90,7 +90,8 @@ extend-exclude = '''
 # Exclude a variety of commonly ignored directories.
 extend-exclude = [
     "src/js",
-    "tests/fixtures"
+    "tests/fixtures",
+    "tests/py/unit/fixtures"
 ]
 line-length = 120
 target-version = "py38"

package/src/js/materialMixin.ts

@@ -290,6 +290,13 @@ export function materialMixin<T extends Base = Base>(item: T) {
             return this.calculateHash("", true);
         },
 
+        get external() {
+            return item.prop<MaterialSchema["external"]>("external");
+        },
+        set external(external: MaterialSchema["external"]) {
+            item.setProp("external", external);
+        },
+
         /**
          * Converts basis to crystal/fractional coordinates.
          */

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

@@ -1,4 +1,3 @@
 from .analyzer import BasisMaterialAnalyzer
-from .fingerprint import LayeredFingerprintAlongAxis
 
-__all__ = ["BasisMaterialAnalyzer", "LayeredFingerprintAlongAxis"]
+__all__ = ["BasisMaterialAnalyzer"]

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

@@ -1,9 +1,8 @@
 from mat3ra.esse.models.core.reusable.axis_enum import AxisEnum
 from mat3ra.made.utils import AXIS_TO_INDEX_MAP
 
-from ...build_components.metadata import MaterialWithBuildMetadata
 from .. import BaseMaterialAnalyzer
-from .fingerprint import LayeredFingerprintAlongAxis, LayerFingerprint
+from ..fingerprint import LayeredFingerprintAlongAxis, UniqueElementStringsPerLayer
 
 
 class BasisMaterialAnalyzer(BaseMaterialAnalyzer):
@@ -43,40 +42,9 @@ class BasisMaterialAnalyzer(BaseMaterialAnalyzer):
                     layer_elements.append(elements[i])
 
             unique_elements = sorted(list(set(layer_elements))) if layer_elements else []
-            layer = LayerFingerprint(min_coord=layer_min, max_coord=layer_max, elements=unique_elements)
+            layer = UniqueElementStringsPerLayer(min_coord=layer_min, max_coord=layer_max, elements=unique_elements)
             fingerprint.layers.append(layer)
 
             current_coord += layer_thickness
 
         return fingerprint
-
-    def is_orientation_flipped(
-        self, original_material: MaterialWithBuildMetadata, layer_thickness: float = 1.0
-    ) -> bool:
-        """
-        Detect if the material orientation is flipped compared to the original.
-        Uses Jaccard similarity to compare fingerprints in normal and flipped orientations.
-
-        Args:
-            original_material: The original material before primitivization
-            layer_thickness: Thickness of layers for fingerprint comparison
-
-        Returns:
-            bool: True if orientation is flipped, False otherwise
-        """
-        original_analyzer = BasisMaterialAnalyzer(material=original_material)
-        original_fingerprint = original_analyzer.get_layer_fingerprint(layer_thickness)
-        current_fingerprint = self.get_layer_fingerprint(layer_thickness)
-
-        normal_score = original_fingerprint.get_similarity_score(current_fingerprint)
-        flipped_score = original_fingerprint.get_similarity_score(self._reverse_fingerprint(current_fingerprint))
-
-        # If flipped orientation has significantly higher similarity, material is flipped
-        threshold = 0.1
-        return flipped_score > normal_score + threshold
-
-    def _reverse_fingerprint(self, fingerprint: LayeredFingerprintAlongAxis) -> LayeredFingerprintAlongAxis:
-        reversed_layers = list(reversed(fingerprint.layers))
-        return LayeredFingerprintAlongAxis(
-            layers=reversed_layers, axis=fingerprint.axis, layer_thickness=fingerprint.layer_thickness
-        )

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

@@ -0,0 +1,33 @@
+POSSIBLE_TRANSFORMATION_MATRICES = [
+    [[1, 0, 0], [0, 1, 0], [0, 0, 1]],  # Identity - no transformation
+    # Direct swaps: new[i] = old[j]
+    [[0, 1, 0], [1, 0, 0], [0, 0, 1]],
+    [[0, 0, 1], [0, 1, 0], [1, 0, 0]],
+    [[1, 0, 0], [0, 0, 1], [0, 1, 0]],
+    # Swaps with sign flips
+    [[0, 0, 1], [1, 0, 0], [0, -1, 0]],
+    [[0, 0, -1], [1, 0, 0], [0, 1, 0]],
+    [[0, 1, 0], [0, 0, 1], [-1, 0, 0]],
+    [[0, -1, 0], [0, 0, 1], [1, 0, 0]],
+    # Inverted swaps
+    [[0, -1, 0], [-1, 0, 0], [0, 0, 1]],
+    [[0, 0, -1], [0, 1, 0], [-1, 0, 0]],
+    [[1, 0, 0], [0, 0, -1], [0, -1, 0]],
+    # Rotations around x-axis: -90 and +90 degrees
+    [[1, 0, 0], [0, 0, 1], [0, -1, 0]],  # -90° around x
+    [[1, 0, 0], [0, 0, -1], [0, 1, 0]],  # +90° around x
+    # Rotations around y-axis: -90 and +90 degrees
+    [[0, 0, -1], [0, 1, 0], [1, 0, 0]],  # -90° around y
+    [[0, 0, 1], [0, 1, 0], [-1, 0, 0]],  # +90° around y
+    # Rotations around z-axis: -90 and +90 degrees
+    [[0, 1, 0], [-1, 0, 0], [0, 0, 1]],  # -90° around z
+    [[0, -1, 0], [1, 0, 0], [0, 0, 1]],  # +90° around z
+    # 180° rotations around axes
+    [[1, 0, 0], [0, -1, 0], [0, 0, -1]],  # 180° around x
+    [[-1, 0, 0], [0, 1, 0], [0, 0, -1]],  # 180° around y
+    [[-1, 0, 0], [0, -1, 0], [0, 0, 1]],  # 180° around z
+    # Mirrors (reflections)
+    [[1, 0, 0], [0, 1, 0], [0, 0, -1]],  # Mirror along z
+    [[1, 0, 0], [0, -1, 0], [0, 0, 1]],  # Mirror along y
+    [[-1, 0, 0], [0, 1, 0], [0, 0, 1]],  # Mirror along x
+]

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

@@ -0,0 +1,4 @@
+from mat3ra.made.tools.analyze.fingerprint.layers.unique_element_string_per_layer import UniqueElementStringsPerLayer
+from mat3ra.made.tools.analyze.fingerprint.layers.layered_fingerprint_along_axis import LayeredFingerprintAlongAxis
+
+__all__ = ["UniqueElementStringsPerLayer", "LayeredFingerprintAlongAxis"]

package/src/py/mat3ra/made/tools/analyze/fingerprint/layers/layered_fingerprint_along_axis.py

@@ -0,0 +1,84 @@
+from itertools import cycle, islice
+from typing import List
+
+from mat3ra.utils.array import jaccard_similarity_for_strings
+from mat3ra.esse.models.core.reusable.axis_enum import AxisEnum
+from pydantic import BaseModel, Field
+
+from mat3ra.made.tools.analyze.fingerprint.layers.unique_element_string_per_layer import UniqueElementStringsPerLayer
+
+
+class LayeredFingerprintAlongAxis(BaseModel):
+    layers: List[UniqueElementStringsPerLayer] = Field(default_factory=list, description="List of layer fingerprints")
+    axis: AxisEnum = Field(default=AxisEnum.z, description="Axis along which the fingerprint is computed")
+    layer_thickness: float = Field(default=1.0, gt=0, description="Thickness of each layer in Angstroms")
+
+    @property
+    def non_empty_layers(self) -> List[UniqueElementStringsPerLayer]:
+        return [layer for layer in self.layers if layer.elements]
+
+    @property
+    def element_sequence(self) -> List[List[str]]:
+        return [layer.elements for layer in self.layers]
+
+    def get_similarity_score(self, other: "LayeredFingerprintAlongAxis") -> float:
+        """
+        Calculate Jaccard similarity score between this and another fingerprint.
+
+        The Jaccard similarity coefficient measures the similarity between two sets by comparing
+        the size of their intersection to the size of their union: J(A, B) = |A ∩ B| / |A ∪ B|.
+        In this implementation, we compare the sets of chemical elements in corresponding layers
+        between two fingerprints. For example, if layer 1 contains {Si, O} and the corresponding
+        layer contains {Si, Ge}, the Jaccard score is 1/3 (one common element divided by three
+        unique elements total). The final score is the average across all layers, providing a
+        measure of compositional similarity along the axis (0.0 = completely different,
+        1.0 = identical composition in all layers).
+
+        Args:
+            other: Another LayeredFingerprintAlongAxis to compare with
+
+        Returns:
+            float: Average Jaccard similarity score (0.0 to 1.0). Returns 0.0 if the number of layers doesn't match.
+        """
+        if not self.layers or not other.layers:
+            return 0.0
+        if len(self.layers) != len(other.layers):
+            return 0.0
+
+        seq1, seq2 = self.element_sequence, other.element_sequence
+        return sum(jaccard_similarity_for_strings(a, b) for a, b in zip(seq1, seq2)) / len(seq1)
+
+    def get_similarity_score_ignore_periodicity(self, other: "LayeredFingerprintAlongAxis") -> float:
+        """
+        Calculate Jaccard similarity score ignoring periodicity differences.
+
+        Handles cases where one fingerprint is a periodic repetition of another.
+        For example, if self has 6 layers and other has 2 layers, this method checks if
+        self.layers is a 3× repetition of other.layers (i.e., layers 0–1 match other,
+        layers 2–3 match other, etc.).
+
+        Args:
+            other: Another LayeredFingerprintAlongAxis to compare with
+
+        Returns:
+            float: Average Jaccard similarity score (0.0 to 1.0). Returns 0.0 if the number
+                   of layers is not a multiple relationship or if fingerprints don't match.
+        """
+        if not self.layers or not other.layers:
+            return 0.0
+
+        len_a, len_b = len(self.layers), len(other.layers)
+        if len_a == len_b:
+            return self.get_similarity_score(other)
+
+        # Identify shorter/longer and ensure multiplicity
+        if len_a < len_b:
+            short_seq, long_seq = self.element_sequence, other.element_sequence
+        else:
+            short_seq, long_seq = other.element_sequence, self.element_sequence
+
+        if len(long_seq) % len(short_seq) != 0:
+            return 0.0
+
+        cycled_short = islice(cycle(short_seq), len(long_seq))
+        return sum(jaccard_similarity_for_strings(a, b) for a, b in zip(cycled_short, long_seq)) / len(short_seq)

package/src/py/mat3ra/made/tools/analyze/fingerprint/layers/unique_element_string_per_layer.py

@@ -0,0 +1,9 @@
+from typing import List
+
+from pydantic import BaseModel, Field
+
+
+class UniqueElementStringsPerLayer(BaseModel):
+    min_coord: float = Field(..., description="Minimum coordinate value for the layer")
+    max_coord: float = Field(..., description="Maximum coordinate value for the layer")
+    elements: List[str] = Field(default_factory=list, description="Sorted unique chemical elements in the layer")

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

@@ -1,10 +1,9 @@
-from ....lattice import LatticeTypeEnum
+from .. import BaseMaterialAnalyzer
+from ..lattice_swap_analyzer import MaterialLatticeSwapAnalyzer
 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
+from ....lattice import LatticeTypeEnum
 
 
 class LatticeMaterialAnalyzer(BaseMaterialAnalyzer):
@@ -88,15 +87,20 @@ class LatticeMaterialAnalyzer(BaseMaterialAnalyzer):
         )
 
     def get_material_with_primitive_lattice_standard(
-        self, return_original_if_not_reduced: bool = False, keep_orientation: bool = True, layer_thickness: float = 1.0
+        self,
+        return_original_if_not_reduced: bool = False,
+        keep_orientation: bool = True,
+        layer_thickness: float = 1.0,
+        rotation_detection_threshold: float = 0.05,
     ) -> MaterialWithBuildMetadata:
         """
-        Get material with primitive lattice and optional orientation correction to be standardized.
+        Get material with primitive lattice standardized according to IUCr conventions.
 
         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
+            keep_orientation: If True, detect and reverse lattice parameter swaps to preserve original orientation
+            layer_thickness: Unused (kept for compatibility)
+            rotation_detection_threshold: Unused (kept for compatibility)
 
         Returns:
             MaterialWithBuildMetadata: Material with primitive lattice
@@ -110,11 +114,11 @@ class LatticeMaterialAnalyzer(BaseMaterialAnalyzer):
                 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.")
+            swap_analyzer = MaterialLatticeSwapAnalyzer(material=material_with_primitive_lattice)
+            material_with_primitive_lattice = swap_analyzer.get_corrected_material(
+                self.material, layer_thickness=layer_thickness, threshold=rotation_detection_threshold
+            )
+
+        material_with_primitive_lattice.metadata = self.material.metadata
 
         return material_with_primitive_lattice

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

@@ -0,0 +1,104 @@
+from typing import Union
+
+import numpy as np
+from mat3ra.esse.models.core.abstract.matrix_3x3 import Matrix3x3Schema
+from pydantic import BaseModel, Field
+
+from mat3ra.made.material import Material
+from .basis import BasisMaterialAnalyzer
+from .enums import POSSIBLE_TRANSFORMATION_MATRICES
+from ..build_components.metadata.material_with_build_metadata import MaterialWithBuildMetadata
+from ..operations.reusable.unary import transform_material_by_matrix
+
+
+class LatticeSwapDetectionResult(BaseModel):
+    model_config = {"arbitrary_types_allowed": True}
+    is_swapped: bool = Field(..., description="Whether a lattice swap was detected")
+    permutation: Matrix3x3Schema = Field(..., description="Transformation matrix representing the swap")
+    confidence: float = Field(..., description="Confidence score (0.0 to 1.0)")
+
+
+class MaterialLatticeSwapAnalyzer(BaseModel):
+    """
+    Analyzer to detect lattice vector swaps/permutations between materials.
+
+    This detects when lattice vectors have been reoriented (e.g., a->a, b->c, c->-b)
+    rather than the basis being rotated within the lattice.
+    """
+
+    material: Union[Material, MaterialWithBuildMetadata]
+    tolerance: float = 0.01
+
+    def _compute_transformation_score(self, matrix: np.ndarray, target_fingerprint) -> float:
+        transformed_material = transform_material_by_matrix(self.material, matrix)
+        new_analyzer = BasisMaterialAnalyzer(material=transformed_material)
+        new_fingerprint = new_analyzer.get_layer_fingerprint(target_fingerprint.layer_thickness)
+        return target_fingerprint.get_similarity_score(new_fingerprint)
+
+    def _create_detection_result(self, matrix: np.ndarray, score: float) -> LatticeSwapDetectionResult:
+        is_identity = np.allclose(matrix, np.eye(3), atol=self.tolerance)
+        return LatticeSwapDetectionResult(
+            is_swapped=not is_identity,
+            permutation=Matrix3x3Schema(root=matrix.tolist()),
+            confidence=score,
+        )
+
+    def detect_swap_from_original(
+        self, original_material: MaterialWithBuildMetadata, layer_thickness: float = 1.0, threshold: float = 0.1
+    ) -> LatticeSwapDetectionResult:
+        """
+        Detect lattice swap from the original material.
+
+        We apply every transformation matrix to lattice and basis, compute the fingerprint along z, then compare
+        to the original material's fingerprint. The best matching transformation (if above threshold) is considered
+        a detected swap.
+
+
+        Args:
+            original_material: The original material before transformation
+            layer_thickness: Thickness of layers for fingerprint comparison
+            threshold: Minimum improvement threshold to consider a swap detected
+
+        Returns:
+            LatticeSwapDetectionResult: Swap detection results with permutation and new lattice
+        """
+        target_analyzer = BasisMaterialAnalyzer(material=original_material)
+        target_fingerprint = target_analyzer.get_layer_fingerprint(layer_thickness)
+        possible_matrices = list(map(np.array, POSSIBLE_TRANSFORMATION_MATRICES))
+
+        best_match = None
+        max_score = 0
+
+        for matrix in possible_matrices:
+            score = self._compute_transformation_score(matrix, target_fingerprint)
+            if score > max_score:
+                best_match = self._create_detection_result(matrix, score)
+                max_score = score
+
+        if best_match and best_match.is_swapped and best_match.confidence >= threshold:
+            return best_match
+        return best_match
+
+    def get_corrected_material(
+        self,
+        target: MaterialWithBuildMetadata,
+        layer_thickness: float = 1.0,
+        threshold: float = 0.1,
+    ) -> MaterialWithBuildMetadata:
+        """
+        Correct the material's lattice to match the target material's orientation if a swap is detected.
+
+        Args:
+            target: The target material to match
+            layer_thickness: Thickness of layers for fingerprint comparison
+            threshold: Minimum improvement threshold to consider a swap detected
+
+        Returns:
+            MaterialWithBuildMetadata: Corrected material with lattice matching the target orientation
+        """
+        swap_info = self.detect_swap_from_original(target, layer_thickness, threshold)
+        if swap_info.is_swapped:
+            matrix_list = [list(row.root) if hasattr(row, "root") else row for row in swap_info.permutation.root]
+            matrix_array = np.array(matrix_list)
+            return transform_material_by_matrix(self.material, matrix_array)
+        return self.material

package/src/py/mat3ra/made/tools/operations/core/unary.py

@@ -101,23 +101,24 @@ def perturb(
     return new_material
 
 
-def rotate(material: Material, axis: List[int], angle: float, wrap: bool = True, rotate_cell=False) -> Material:
+def rotate(material: Material, axis: List[int], angle: float, wrap: bool = True) -> Material:
     """
-    Rotate the material around a given axis by a specified angle.
+    Rotate the basis of the material relative to the lattice.
+    This operation breaks symmetry and does not modify lattice vectors.
 
     Args:
         material (Material): The material to rotate.
         axis (List[int]): The axis to rotate around, expressed as [x, y, z].
         angle (float): The angle of rotation in degrees.
         wrap (bool): Whether to wrap the material to the unit cell.
-        rotate_cell (bool): Whether to rotate the cell.
     Returns:
         Atoms: The rotated material.
     """
-    original_is_in_cartesian_units = material.basis.is_in_cartesian_units
-    material.to_crystal()
-    atoms = to_ase(material)
-    atoms.rotate(v=axis, a=angle, center="COU", rotate_cell=rotate_cell)
+    new_material = material.clone()
+    original_is_in_cartesian_units = new_material.basis.is_in_cartesian_units
+    new_material.to_crystal()
+    atoms = to_ase(new_material)
+    atoms.rotate(v=axis, a=angle, center="COU", rotate_cell=False)
     if wrap:
         atoms.wrap()
     new_material = MaterialWithBuildMetadata.create(from_ase(atoms))

package/src/py/mat3ra/made/tools/operations/reusable/unary.py

@@ -1,8 +1,32 @@
 import numpy as np
 from mat3ra.esse.models.core.abstract.matrix_3x3 import Matrix3x3Schema
-from mat3ra.made.material import Material
 
+from mat3ra.made.material import Material
 from ..core.unary import strain
+from ...modify import wrap_to_unit_cell
+
+
+def transform_material_by_matrix(material: Material, matrix: np.ndarray) -> Material:
+    """
+    Transforms a material by applying a transformation matrix to lattice vectors and coordinates.
+
+    Args:
+        material: The material to be transformed.
+        matrix: The 3x3 transformation matrix as a numpy array.
+
+    Returns:
+        A new material instance with transformed lattice and coordinates, wrapped to unit cell.
+    """
+    current_lattice_vectors = np.array(material.lattice.vector_arrays)
+    current_coordinates = material.basis.coordinates.values
+
+    new_lattice_vectors = (matrix @ current_lattice_vectors.T).tolist()
+    new_coordinates = (np.linalg.inv(matrix) @ np.array(current_coordinates).T).T.tolist()
+
+    transformed_material = material.clone()
+    transformed_material.set_lattice_vectors_from_array(new_lattice_vectors)
+    transformed_material.basis.coordinates.values = new_coordinates
+    return wrap_to_unit_cell(transformed_material)
 
 
 def strain_to_match_lattice(material_to_strain: Material, target_material: Material) -> Material: