@mat3ra/made 2026.6.15-0 → 2026.6.29-0

package/src/js/lattice/reciprocal/paths.ts

@@ -1,3 +1,12 @@
+/**
+ * Default k-point paths according to:
+ *  [AFLOW](https://arxiv.org/abs/1004.2974) methodology.
+ *  Paths are split in parts for clarity.
+ *
+ * Raw segment data is stored in data/reciprocal_paths.json (shared with Python).
+ */
+import points from "../../data/reciprocal_paths.json";
+
 interface KPointStep {
     point: string;
     steps: number;
@@ -7,123 +16,6 @@ interface PathsType {
     [key: string]: KPointStep[];
 }
 
-/**
- * Default kpoing paths according to:
- *  [AFLOW](https://arxiv.org/abs/1004.2974) methodology.
- *  Paths are split in parts for clarity.
- */
-const points: Record<string, string[][]> = {
-    CUB: [
-        ["Г", "X", "M", "Г", "R", "X"],
-        ["M", "R"],
-    ],
-    BCC: [
-        ["Г", "H", "N", "Г", "P", "H"],
-        ["P", "N"],
-    ],
-    FCC: [
-        ["Г", "X", "W", "K", "Г", "L", "U", "W", "L"],
-        ["U", "X"],
-    ],
-    TET: [
-        ["Г", "X", "M", "Г", "Z", "R", "A", "Z"],
-        ["X", "R"],
-        ["M", "A"],
-    ],
-    "BCT-1": [
-        ["Г", "X", "M", "Г", "Z", "P", "N", "Z1", "M"],
-        ["X", "P"],
-    ],
-    "BCT-2": [
-        ["Г", "X", "Y", "∑", "Г", "Z", "∑1", "N", "P", "Y1", "Z"],
-        ["X", "P"],
-    ],
-    ORC: [
-        ["Г", "X", "S", "Y", "Г", "Z", "U", "R", "T", "Z"],
-        ["Y", "T"],
-        ["U", "X"],
-        ["S", "R"],
-    ],
-    "ORCF-1": [
-        ["Г", "Y", "T", "Z", "Г", "X", "A1", "Y"],
-        ["T", "X1"],
-        ["X", "A", "Z"],
-        ["L", "Г"],
-    ],
-    "ORCF-2": [
-        ["Г", "Y", "C", "D", "X", "Г", "Z", "D1", "H", "C"],
-        ["C1", "Z"],
-        ["X", "H1"],
-        ["H", "Y"],
-        ["L", "Г"],
-    ],
-    "ORCF-3": [
-        ["Г", "Y", "T", "Z", "Г", "X", "A1", "Y"],
-        ["X", "A", "Z"],
-        ["L", "Г"],
-    ],
-    ORCI: [
-        ["Г", "X", "L", "T", "W", "R", "X1", "Z", "Г", "Y", "S", "W"],
-        ["L1", "Y"],
-        ["Y1", "Z"],
-    ],
-    ORCC: [
-        ["Г", "X", "S", "R", "A", "Z", "Г", "Y", "X1", "A1", "T", "Y"],
-        ["Z", "T"],
-    ],
-    HEX: [
-        ["Г", "M", "K", "Г", "A", "L", "H", "A"],
-        ["L", "M"],
-        ["K", "H"],
-    ],
-    "RHL-1": [
-        ["Г", "L", "B1"],
-        ["B", "Z", "Г", "X"],
-        ["Q", "F", "P1", "Z"],
-        ["L", "P"],
-    ],
-    "RHL-2": [["Г", "P", "Z", "Q", "Г", "F", "P1", "Q1", "L", "Z"]],
-    MCL: [
-        ["Г", "Y", "H", "C", "E", "M1", "A", "X", "H1"],
-        ["M", "D", "Z"],
-        ["Y", "D"],
-    ],
-    "MCLC-1": [
-        ["Г", "Y", "Г", "L", "I"],
-        ["I1", "Z", "F1"],
-        ["Y", "X1"],
-        ["X", "Г", "N"],
-        ["M", "Г"],
-    ],
-    "MCLC-2": [
-        ["Г", "Y", "F", "L", "I"],
-        ["I1", "Z", "F1"],
-        ["N", "Г", "M"],
-    ],
-    "MCLC-3": [
-        ["Г", "Y", "F", "H", "Z", "I", "F1"],
-        ["H1", "Y1", "X", "Г", "N"],
-        ["M", "Г"],
-    ],
-    "MCLC-4": [
-        ["Г", "Y", "F", "H", "Z", "I"],
-        ["H1", "Y1", "X", "Г", "N"],
-        ["M", "Г"],
-    ],
-    "MCLC-5": [
-        ["Г", "Y", "F", "L", "I"],
-        ["I1", "Z", "H", "F1"],
-        ["H1", "Y1", "X", "Г", "N"],
-        ["M", "Г"],
-    ],
-    TRI: [
-        ["X", "Г", "Y"],
-        ["L", "Г", "Z"],
-        ["N", "Г", "M"],
-        ["R", "Г"],
-    ],
-};
-
 // Export a processed version of the paths
 export const paths: PathsType = (() => {
     const result: PathsType = {};
@@ -132,7 +24,7 @@ export const paths: PathsType = (() => {
         // Flatten arrays of path segments into a single array
         const flattenedPath: string[] = pathSegments.reduce(
             (acc, segment) => [...acc, ...segment],
-            [],
+            [] as string[],
         );
 
         // Convert to KPointStep array

package/src/js/made.ts

@@ -3,9 +3,9 @@ import { Cell } from "./cell/cell";
 import { ATOMIC_COORD_UNITS, coefficients, tolerance, units } from "./constants";
 import { AtomicConstraints } from "./constraints/constraints";
 import {
-    Lattice,
     defaultNonPeriodicMinimumLatticeSize,
     diatomicLatticePaddingFactor,
+    Lattice,
     molecularLatticePaddingFactor,
 } from "./lattice/lattice";
 import { DEFAULT_LATTICE_UNITS, LATTICE_TYPE_CONFIGS } from "./lattice/lattice_types";

package/src/py/mat3ra/made/data_helper.py

@@ -0,0 +1,5 @@
+"""Resolve the shared data/ directory at the repository root."""
+
+from pathlib import Path
+
+DATA_DIR = Path(__file__).parent / "data"

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

@@ -142,6 +142,40 @@ class Lattice(RoundNumericValuesMixin, LatticeSchemaVectorless, InMemoryEntityPy
         max_norm = max(norms)
         return [round(float(value / max_norm), 3) for value in norms]
 
+    @property
+    def type_extended(self) -> str:
+        """Get the extended lattice type classification.
+
+        For lattice types with subtypes (BCT, ORCF, RHL, MCLC, TRI),
+        returns the specific subtype based on lattice parameters.
+        For other types, returns the base type string.
+        """
+        a, b, c = self.a, self.b, self.c
+        alpha, beta, gamma = self.alpha, self.beta, self.gamma
+        cos_alpha = math.cos(math.radians(alpha))
+        lattice_type = self.type.value if hasattr(self.type, "value") else str(self.type)
+
+        if lattice_type == "BCT":
+            return "BCT-1" if c < a else "BCT-2"
+        elif lattice_type == "ORCF":
+            if 1 / (a * a) >= 1 / (b * b) + 1 / (c * c):
+                return "ORCF-1"
+            return "ORCF-2"
+        elif lattice_type == "RHL":
+            return "RHL-1" if cos_alpha > 0 else "RHL-2"
+        elif lattice_type == "MCLC":
+            if gamma >= 90:
+                return "MCLC-1"
+            if (b / c) * cos_alpha + (b * b / (a * a)) * (1 - cos_alpha * cos_alpha) <= 1:
+                return "MCLC-3"
+            return "MCLC-5"
+        elif lattice_type == "TRI":
+            if alpha > 90 and beta > 90 and gamma >= 90:
+                return "TRI_1a"
+            return "TRI_1b"
+        else:
+            return lattice_type
+
     def get_hash_string(self, is_scaled: bool = False) -> str:
         """Mirrors JS Lattice.getHashString(isScaled). Rounds to HASH_TOLERANCE decimal places."""
         scale = self.a if is_scaled else 1

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

@@ -55,7 +55,7 @@ defaultMaterialConfig = {
 # TODO: replace `-Pydantic` with actual class in the next PR
 class Material(MaterialSchema, HasDescriptionHasMetadataNamedDefaultableInMemoryEntityPydantic):
     model_config = ConfigDict(arbitrary_types_allowed=True, populate_by_name=True)
-    
+
     __default_config__ = defaultMaterialConfig
     __schema__ = MaterialSchema
 
@@ -132,4 +132,3 @@ class Material(MaterialSchema, HasDescriptionHasMetadataNamedDefaultableInMemory
     @property
     def scaled_hash(self) -> str:
         return self.calculate_hash(is_scaled=True)
-

package/src/py/mat3ra/made/reciprocal/__init__.py

@@ -0,0 +1,5 @@
+"""Reciprocal lattice module with symmetry points and k-point path utilities."""
+
+from .lattice_reciprocal import ReciprocalLattice
+from .paths import RECIPROCAL_PATHS
+from .symmetry_points import get_symmetry_points

package/src/py/mat3ra/made/reciprocal/lattice_reciprocal.py

@@ -0,0 +1,147 @@
+"""
+Reciprocal lattice class with k-point path and symmetry point utilities.
+
+Extends the base Lattice class with reciprocal-space functionality
+for Brillouin zone analysis.
+"""
+
+from typing import List, Optional
+
+import numpy as np
+
+from ..lattice import Lattice
+from .paths import RECIPROCAL_PATHS
+from .symmetry_points import get_symmetry_points
+
+
+class ReciprocalLattice(Lattice):
+    """Lattice with reciprocal-space utilities.
+
+    Provides methods for working with reciprocal lattice vectors,
+    high-symmetry points, k-point paths, and k-grid dimensions.
+    """
+
+    def cartesian_coordinates(self, point: List[float]) -> List[float]:
+        """Convert a point in crystal (fractional) coordinates to Cartesian coordinates.
+
+        The Cartesian coordinates are in units of 2π/a.
+
+        Args:
+            point: A 3D point in fractional reciprocal-space coordinates.
+
+        Returns:
+            The point in Cartesian coordinates.
+        """
+        return np.dot(point, self.reciprocal_vectors).tolist()
+
+    @property
+    def symmetry_points(self) -> List[dict]:
+        """Get the list of high-symmetry points for the current lattice.
+
+        Returns:
+            List of dicts with 'point' (str) and 'coordinates' ([float, float, float]).
+        """
+        return get_symmetry_points(self)
+
+    @property
+    def default_kpoint_path(self) -> List[dict]:
+        """Get the default path in reciprocal space for the current lattice.
+
+        Looks up the path by extended type first (e.g., 'BCT-1'), falling back
+        to the base type (e.g., 'BCT').
+
+        Returns:
+            List of dicts with 'point' (str) and 'steps' (int).
+        """
+        path = RECIPROCAL_PATHS.get(self.type_extended)
+        if path is None:
+            lattice_type = self.type.value if hasattr(self.type, "value") else str(self.type)
+            path = RECIPROCAL_PATHS.get(lattice_type, [])
+        return path
+
+    def extract_kpoint_path(self, data_points: Optional[List[List[float]]] = None) -> List[dict]:
+        """Find and label high-symmetry points in a list of raw k-point coordinates.
+
+        Scans through the provided data points and identifies any that match
+        known symmetry points (within tolerance).
+
+        Args:
+            data_points: List of 3D k-point coordinates.
+
+        Returns:
+            List of dicts with 'point' (str), 'steps' (int), and
+            'coordinates' ([float, float, float]) for each matched symmetry point.
+        """
+        if data_points is None:
+            data_points = []
+
+        kpoint_path: List[dict] = []
+        symm_points = self.symmetry_points
+
+        for index, point in enumerate(data_points):
+            for sp in symm_points:
+                if np.allclose(sp["coordinates"], point, atol=1e-4):
+                    kpoint_path.append(
+                        {
+                            "point": sp["point"],
+                            "steps": index,
+                            "coordinates": sp["coordinates"],
+                        }
+                    )
+                    break
+
+        return kpoint_path
+
+    def calculate_dimension(self, n_points: int, index: int) -> int:
+        """Calculate k-grid dimension for one reciprocal direction.
+
+        Args:
+            n_points: Total number of k-points.
+            index: Index of the reciprocal vector direction (0, 1, or 2).
+
+        Returns:
+            Grid dimension in the specified direction.
+        """
+        norms = self.reciprocal_vector_norms
+        others = [i for i in range(3) if i != index]
+        j, k = others[0], others[1]
+        n = np.cbrt((n_points * norms[index] ** 2) / (norms[j] * norms[k]))
+        return max(1, int(np.ceil(n)))
+
+    def get_dimensions_from_points_count(self, n_kpoints: int) -> List[int]:
+        """Calculate 3D grid dimensions from total number of k-points.
+
+        Args:
+            n_kpoints: Total number of k-points.
+
+        Returns:
+            List of three grid dimensions [n1, n2, n3].
+        """
+        return [self.calculate_dimension(n_kpoints, i) for i in range(3)]
+
+    def get_dimensions_from_spacing(self, spacing: float) -> List[int]:
+        """Calculate grid dimensions from k-point spacing.
+
+        The spacing is in Cartesian (2π/a) units.
+
+        Args:
+            spacing: Maximum spacing between k-points.
+
+        Returns:
+            List of three grid dimensions [n1, n2, n3].
+        """
+        norms = self.reciprocal_vector_norms
+        return [max(1, int(np.ceil(round(norm / spacing, 4)))) for norm in norms]
+
+    def get_spacing_from_dimensions(self, dimensions: List[int]) -> float:
+        """Calculate average k-point spacing from grid dimensions.
+
+        Args:
+            dimensions: List of three grid dimensions [n1, n2, n3].
+
+        Returns:
+            Average spacing in Cartesian (2π/a) units.
+        """
+        norms = self.reciprocal_vector_norms
+        spacings = [norms[i] / max(1, dimensions[i]) for i in range(3)]
+        return float(np.mean(spacings))

package/src/py/mat3ra/made/reciprocal/paths.py

@@ -0,0 +1,30 @@
+"""
+Default k-point paths according to AFLOW methodology.
+
+Reference: https://arxiv.org/abs/1004.2974
+Paths are split in parts for clarity.
+
+Raw segment data is stored in reciprocal_paths.json (shared with JS/TS).
+"""
+
+import json
+from typing import Dict, List
+
+from mat3ra.made.data_helper import DATA_DIR
+
+_JSON_FILE = DATA_DIR / "reciprocal_paths.json"
+with open(_JSON_FILE) as f:
+    _POINTS: Dict[str, List[List[str]]] = json.load(f)
+
+
+def _build_reciprocal_paths() -> Dict[str, List[dict]]:
+    """Flatten path segments and assign default step count to each point."""
+    result: Dict[str, List[dict]] = {}
+    for key, path_segments in _POINTS.items():
+        flattened = [point for segment in path_segments for point in segment]
+        # TODO: calculate number of steps based on distance in k-space
+        result[key] = [{"point": point, "steps": 10} for point in flattened]
+    return result
+
+
+RECIPROCAL_PATHS: Dict[str, List[dict]] = _build_reciprocal_paths()