@mat3ra/made 2025.1.18-0 → 2025.4.4-0

package/package.json

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

package/pyproject.toml

@@ -6,7 +6,7 @@ readme = "README.md"
 requires-python = ">=3.8"
 license = {file = "LICENSE.md"}
 authors = [
-    {name = "Exabyte Inc.", email = "info@mat3ra.com"}
+    { name = "Exabyte Inc.", email = "info@mat3ra.com" }
 ]
 classifiers = [
     "Programming Language :: Python",
@@ -99,3 +99,11 @@ target-version = "py38"
 profile = "black"
 multi_line_output = 3
 include_trailing_comma = true
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src/py",
+]
+testpaths = [
+    "tests/py"
+]

package/src/py/mat3ra/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

package/src/py/mat3ra/made/{basis.py → basis/__init__.py}

@@ -1,21 +1,36 @@
-import json
-from typing import Dict, List, Optional, Union
-
-from mat3ra.code.constants import AtomicCoordinateUnits
-from mat3ra.utils.mixins import RoundNumericValuesMixin
-from pydantic import BaseModel
-
-from .cell import Cell
-from .utils import ArrayWithIds, get_overlapping_coordinates
-
-
-class Basis(RoundNumericValuesMixin, BaseModel):
-    elements: ArrayWithIds = ArrayWithIds(values=["Si"])
-    coordinates: ArrayWithIds = ArrayWithIds(values=[0, 0, 0])
-    units: str = AtomicCoordinateUnits.crystal
-    cell: Cell = Cell()
-    labels: Optional[ArrayWithIds] = ArrayWithIds(values=[])
-    constraints: Optional[ArrayWithIds] = ArrayWithIds(values=[])
+from typing import Any, Dict, List, Optional, Union
+
+from mat3ra.code.array_with_ids import ArrayWithIds
+from mat3ra.code.entity import InMemoryEntityPydantic
+from mat3ra.esse.models.material import BasisSchema
+from mat3ra.esse.models.material import Units as UnitsEnum
+from mat3ra.made.basis.coordinates import Coordinates
+from mat3ra.made.cell import Cell
+from mat3ra.made.utils import get_overlapping_coordinates
+from pydantic import Field
+
+
+class Basis(BasisSchema, InMemoryEntityPydantic):
+    elements: ArrayWithIds
+    coordinates: Coordinates
+    cell: Cell = Field(Cell(), exclude=True)
+    labels: ArrayWithIds = Field(ArrayWithIds.from_values([]))
+    constraints: ArrayWithIds = Field(ArrayWithIds.from_values([]))
+
+    def __convert_kwargs__(self, **kwargs: Any) -> Dict[str, Any]:
+        if isinstance(kwargs.get("elements"), list):
+            kwargs["elements"] = ArrayWithIds.from_list_of_dicts(kwargs["elements"])
+        if isinstance(kwargs.get("coordinates"), list):
+            kwargs["coordinates"] = Coordinates.from_list_of_dicts(kwargs["coordinates"])
+        if isinstance(kwargs.get("labels"), list):
+            kwargs["labels"] = ArrayWithIds.from_list_of_dicts(kwargs["labels"])
+        if isinstance(kwargs.get("constraints"), list):
+            kwargs["constraints"] = ArrayWithIds.from_list_of_dicts(kwargs["constraints"])
+        return kwargs
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        kwargs = self.__convert_kwargs__(**kwargs)
+        super().__init__(*args, **kwargs)
 
     @classmethod
     def from_dict(
@@ -23,57 +38,38 @@ class Basis(RoundNumericValuesMixin, BaseModel):
         elements: List[Dict],
         coordinates: List[Dict],
         units: str,
-        labels: Optional[List[Dict]] = None,
-        cell: Optional[List[List[float]]] = None,
-        constraints: Optional[List[Dict]] = None,
+        cell: List[List[float]],
+        labels: Optional[List[Dict]] = ArrayWithIds.from_list_of_dicts([]),
+        constraints: Optional[List[Dict]] = ArrayWithIds.from_list_of_dicts([]),
     ) -> "Basis":
         return Basis(
             elements=ArrayWithIds.from_list_of_dicts(elements),
-            coordinates=ArrayWithIds.from_list_of_dicts(coordinates),
+            coordinates=Coordinates.from_list_of_dicts(coordinates),
             units=units,
             cell=Cell.from_vectors_array(cell),
-            labels=ArrayWithIds.from_list_of_dicts(labels) if labels else ArrayWithIds(values=[]),
-            constraints=ArrayWithIds.from_list_of_dicts(constraints) if constraints else ArrayWithIds(values=[]),
-        )
-
-    def to_json(self, skip_rounding=False):
-        json_value = {
-            "elements": self.elements.to_json(),
-            "coordinates": self.coordinates.to_json(skip_rounding=skip_rounding),
-            "units": self.units,
-            "labels": self.labels.to_json(),
-        }
-        return json.loads(json.dumps(json_value))
-
-    def clone(self):
-        return Basis(
-            elements=self.elements,
-            coordinates=self.coordinates,
-            units=self.units,
-            cell=self.cell,
-            isEmpty=False,
-            labels=self.labels,
+            labels=ArrayWithIds.from_list_of_dicts(labels),
+            constraints=ArrayWithIds.from_list_of_dicts(constraints),
         )
 
     @property
     def is_in_crystal_units(self):
-        return self.units == AtomicCoordinateUnits.crystal
+        return self.units == UnitsEnum.crystal
 
     @property
     def is_in_cartesian_units(self):
-        return self.units == AtomicCoordinateUnits.cartesian
+        return self.units == UnitsEnum.cartesian
 
     def to_cartesian(self):
         if self.is_in_cartesian_units:
             return
         self.coordinates.map_array_in_place(self.cell.convert_point_to_cartesian)
-        self.units = AtomicCoordinateUnits.cartesian
+        self.units = UnitsEnum.cartesian
 
     def to_crystal(self):
         if self.is_in_crystal_units:
             return
         self.coordinates.map_array_in_place(self.cell.convert_point_to_crystal)
-        self.units = AtomicCoordinateUnits.crystal
+        self.units = UnitsEnum.crystal
 
     def add_atom(
         self,
@@ -117,19 +113,15 @@ class Basis(RoundNumericValuesMixin, BaseModel):
     def remove_atom_by_id(self, id: int):
         self.elements.remove_item(id)
         self.coordinates.remove_item(id)
-        if self.labels is not None:
-            self.labels.remove_item(id)
+        self.labels.remove_item(id)
 
-    def filter_atoms_by_ids(self, ids: Union[List[int], int]) -> "Basis":
-        self.elements.filter_by_ids(ids)
-        self.coordinates.filter_by_ids(ids)
-        if self.labels is not None:
-            self.labels.filter_by_ids(ids)
+    def filter_atoms_by_ids(self, ids: Union[List[int], int], invert: bool = False) -> "Basis":
+        self.elements.filter_by_ids(ids, invert)
+        self.coordinates.filter_by_ids(ids, invert)
+        self.labels.filter_by_ids(ids, invert)
         return self
 
     def filter_atoms_by_labels(self, labels: Union[List[str], str]) -> "Basis":
-        if self.labels is None:
-            return self
         self.labels.filter_by_values(labels)
         ids = self.labels.ids
         self.elements.filter_by_ids(ids)

package/src/py/mat3ra/made/basis/coordinates.py

@@ -0,0 +1,43 @@
+from typing import Literal
+
+import numpy as np
+from mat3ra.code.array_with_ids import RoundedArrayWithIds
+from mat3ra.code.value_with_id import RoundedValueWithId
+from mat3ra.code.vector import RoundedVector3D as RoundedPoint3D
+
+
+class Coordinate(RoundedValueWithId):
+    value: RoundedPoint3D
+
+    def get_value_along_axis(self, axis: Literal["x", "y", "z"] = "z"):
+        return self.value.root[{"x": 0, "y": 1, "z": 2}[axis]]
+
+
+class Coordinates(RoundedArrayWithIds):
+    def get_values_along_axis(
+        self,
+        axis: Literal["x", "y", "z"] = "z",
+    ):
+        values_along_axis = [Coordinate(value=coord).get_value_along_axis(axis) for coord in self.values]
+        return values_along_axis
+
+    def get_max_value_along_axis(
+        self,
+        axis: Literal["x", "y", "z"] = "z",
+    ):
+        return np.max(self.get_values_along_axis(axis))
+
+    def get_min_value_along_axis(
+        self,
+        axis: Literal["x", "y", "z"] = "z",
+    ):
+        return np.min(self.get_values_along_axis(axis))
+
+    def get_extremum_value_along_axis(
+        self,
+        extremum: Literal["max", "min"] = "max",
+        axis: Literal["x", "y", "z"] = "z",
+    ):
+        if extremum == "max":
+            return self.get_max_value_along_axis(axis)
+        return self.get_min_value_along_axis(axis)

package/src/py/mat3ra/made/cell.py

@@ -7,16 +7,23 @@ from pydantic import BaseModel, Field
 
 class Cell(RoundNumericValuesMixin, BaseModel):
     # TODO: figure out how to use ArrayOf3NumberElementsSchema
-    vector1: List[float] = Field(default_factory=lambda: [1, 0, 0])
-    vector2: List[float] = Field(default_factory=lambda: [0, 1, 0])
-    vector3: List[float] = Field(default_factory=lambda: [0, 0, 1])
+    vector1: List[float] = Field(default_factory=lambda: [1.0, 0.0, 0.0])
+    vector2: List[float] = Field(default_factory=lambda: [0.0, 1.0, 0.0])
+    vector3: List[float] = Field(default_factory=lambda: [0.0, 0.0, 1.0])
     __round_precision__ = 6
 
     @classmethod
     def from_vectors_array(cls, vectors_array: Optional[List[List[float]]] = None) -> "Cell":
         if vectors_array is None:
-            vectors_array = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
-        return cls(vector1=vectors_array[0], vector2=vectors_array[1], vector3=vectors_array[2])
+            vectors_array = [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]
+
+        # Ensure vectors are properly converted to lists of floats
+        processed_vectors = []
+        for vector in vectors_array:
+            processed_vector = [float(v) for v in vector]
+            processed_vectors.append(processed_vector)
+
+        return cls(vector1=processed_vectors[0], vector2=processed_vectors[1], vector3=processed_vectors[2])
 
     @property
     def vectors_as_array(self, skip_rounding=False) -> List[List[float]]:
@@ -24,7 +31,7 @@ class Cell(RoundNumericValuesMixin, BaseModel):
             return [self.vector1, self.vector2, self.vector3]
         return self.round_array_or_number([self.vector1, self.vector2, self.vector3])
 
-    def to_json(self, skip_rounding=False):
+    def to_list(self, skip_rounding=False) -> List[List[float]]:
         _ = self.round_array_or_number
         return [
             self.vector1 if skip_rounding else _(self.vector1),
@@ -35,23 +42,17 @@ class Cell(RoundNumericValuesMixin, BaseModel):
     def clone(self) -> "Cell":
         return self.from_vectors_array(self.vectors_as_array)
 
-    def clone_and_scale_by_matrix(self, matrix: List[List[float]]) -> "Cell":
-        new_cell = self.clone()
-        new_cell.scale_by_matrix(matrix)
-        return new_cell
-
     def convert_point_to_cartesian(self, point: List[float]) -> List[float]:
         np_vector = np.array(self.vectors_as_array)
-        return np.dot(point, np_vector)
+        result_list = np.dot(point, np_vector).tolist()
+        return self.round_array_or_number(result_list)
 
     def convert_point_to_crystal(self, point: List[float]) -> List[float]:
         np_vector = np.array(self.vectors_as_array)
-        return np.dot(point, np.linalg.inv(np_vector))
-
-    def scale_by_matrix(self, matrix: List[List[float]]):
-        np_vector = np.array(self.vectors_as_array)
-        self.vector1, self.vector2, self.vector3 = np.dot(np.array(matrix), np_vector).tolist()
+        result_list = np.dot(point, np.linalg.inv(np_vector)).tolist()
+        return self.round_array_or_number(result_list)
 
     @property
     def volume(self) -> float:
-        return np.linalg.det(np.array(self.vectors_as_array))
+        volume = np.linalg.det(np.array(self.vectors_as_array))
+        return self.round_array_or_number(volume)

package/src/py/mat3ra/made/debug_utils.py

@@ -0,0 +1,73 @@
+import os
+import tempfile
+import time
+import webbrowser
+
+# Use a default div id
+default_div_id = "wave-div"
+
+
+def get_wave_html(div_id=default_div_id, width=600, height=600, title="Material"):
+    size = min(width, height)  # Make it square using the smaller dimension
+    return f"""
+    <h2>{title}</h2>
+    <div id="{div_id}" style="width:{size}px; height:{size}px; border:1px solid #333;"></div>
+    """
+
+
+def get_wave_js(material_json, div_id=default_div_id):
+    return (
+        f"""
+    const materialConfig = {material_json};
+    const container = document.getElementById('{div_id}');
+        """
+        + """
+    (async function() {
+        const module = await import('https://exabyte-io.github.io/wave.js/main.js');
+        window.renderThreeDEditor(materialConfig, container);
+    })();
+    document.head.insertAdjacentHTML(
+        'beforeend',
+        '<link rel="stylesheet" href="https://exabyte-io.github.io/wave.js/main.css"/>'
+    );
+    """
+    )
+
+
+def debug_visualize_material(material, width=600, height=600, title="Material"):
+    """
+    Generates a temporary HTML file that uses Wave.js to visualize the material,
+    and opens it in the default browser.
+
+    Call this function from the PyCharm debugger (e.g., via Evaluate Expression).
+    """
+    # Convert your material to JSON.
+    # (Assuming material.to_json() returns a JSON-serializable object)
+    material_json = material.to_json()
+
+    # Generate a unique div id so multiple calls don't conflict
+    div_id = f"wave-{int(time.time())}"
+
+    # Create HTML content that includes our working code
+    html_content = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <meta charset="UTF-8">
+      <title>Wave.js Debug Viewer</title>
+    </head>
+    <body>
+      {get_wave_html(div_id, width, height, title)}
+      <script type="module">
+        {get_wave_js(material_json, div_id)}
+      </script>
+    </body>
+    </html>
+    """
+
+    # Write the HTML to a temporary file and open it in the default browser
+    fd, file_path = tempfile.mkstemp(suffix=".html", prefix="wave_debug_")
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(html_content)
+
+    webbrowser.open("file://" + file_path)

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

@@ -1,39 +1,63 @@
 import math
-from typing import Any, Dict, List, Optional
+from typing import List, Optional
 
 import numpy as np
+from mat3ra.code.entity import InMemoryEntityPydantic
+from mat3ra.code.vector import RoundedVector3D
+from mat3ra.esse.models.properties_directory.structural.lattice.lattice_bravais import (
+    LatticeImplicitSchema as LatticeBravaisSchema,
+)
+from mat3ra.esse.models.properties_directory.structural.lattice.lattice_bravais import (
+    LatticeTypeEnum,
+    LatticeUnitsSchema,
+)
+from mat3ra.esse.models.properties_directory.structural.lattice.lattice_vectors import (
+    LatticeExplicitUnit as LatticeVectorsSchema,
+)
 from mat3ra.utils.mixins import RoundNumericValuesMixin
-from pydantic import BaseModel
+from pydantic import Field
 
 from .cell import Cell
 
-HASH_TOLERANCE = 3
-DEFAULT_UNITS = {"length": "angstrom", "angle": "degree"}
-DEFAULT_TYPE = "TRI"
+COORDINATE_TOLERANCE = 6
 
 
-class LatticeVectors(BaseModel):
+class LatticeVector(RoundedVector3D):
+    pass
+
+
+class LatticeVectors(RoundNumericValuesMixin, LatticeVectorsSchema):
     """
     A class to represent the lattice vectors.
     """
 
-    a: List[float] = [1.0, 0.0, 0.0]
-    b: List[float] = [0.0, 1.0, 0.0]
-    c: List[float] = [0.0, 0.0, 1.0]
+    a: LatticeVector = Field(default_factory=lambda: LatticeVector(root=[1.0, 0.0, 0.0]))
+    b: LatticeVector = Field(default_factory=lambda: LatticeVector(root=[0.0, 1.0, 0.0]))
+    c: LatticeVector = Field(default_factory=lambda: LatticeVector(root=[0.0, 0.0, 1.0]))
+
+    @classmethod
+    def from_vectors_array(cls, vectors: List[List[float]]) -> "LatticeVectors":
+        return cls(a=LatticeVector(root=vectors[0]), b=LatticeVector(root=vectors[1]), c=LatticeVector(root=vectors[2]))
+
 
+class Lattice(RoundNumericValuesMixin, LatticeBravaisSchema, InMemoryEntityPydantic):
+    __types__ = LatticeTypeEnum
+    __type_default__ = LatticeBravaisSchema.model_fields["type"].default
+    __units_default__ = LatticeBravaisSchema.model_fields["units"].default_factory()
 
-class Lattice(RoundNumericValuesMixin, BaseModel):
     a: float = 1.0
     b: float = a
     c: float = a
     alpha: float = 90.0
     beta: float = 90.0
     gamma: float = 90.0
-    units: Dict[str, str] = DEFAULT_UNITS
-    type: str = DEFAULT_TYPE
 
     @property
     def vectors(self) -> LatticeVectors:
+        vectors = self.calculate_vectors()
+        return LatticeVectors.from_vectors_array(vectors)
+
+    def calculate_vectors(self):
         a = self.a
         b = self.b
         c = self.c
@@ -59,61 +83,56 @@ class Lattice(RoundNumericValuesMixin, BaseModel):
         vector_b = [-b * sin_alpha * cos_gamma_star, b * sin_alpha * sin_gamma_star, b * cos_alpha]
         vector_c = [0.0, 0.0, c]
 
-        return LatticeVectors(a=vector_a, b=vector_b, c=vector_c)
+        return [vector_a, vector_b, vector_c]
 
     @classmethod
     def from_vectors_array(
-        cls, vectors: List[List[float]], units: Optional[Dict[str, str]] = None, type: Optional[str] = None
+        cls,
+        vectors: List[List[float]],
+        units: Optional[LatticeUnitsSchema] = __units_default__,
+        type: Optional[LatticeTypeEnum] = __type_default__,
     ) -> "Lattice":
-        """
-        Create a Lattice object from a nested array of vectors.
-        Args:
-            vectors (List[List[float]]): A nested array of vectors.
-        Returns:
-            Lattice: A Lattice object.
-        """
         a = np.linalg.norm(vectors[0])
         b = np.linalg.norm(vectors[1])
         c = np.linalg.norm(vectors[2])
         alpha = np.degrees(np.arccos(np.dot(vectors[1], vectors[2]) / (b * c)))
         beta = np.degrees(np.arccos(np.dot(vectors[0], vectors[2]) / (a * c)))
         gamma = np.degrees(np.arccos(np.dot(vectors[0], vectors[1]) / (a * b)))
-        if units is None:
-            units = DEFAULT_UNITS
-        if type is None:
-            type = DEFAULT_TYPE
-        return cls(a=float(a), b=float(b), c=float(c), alpha=alpha, beta=beta, gamma=gamma, units=units, type=type)
-
-    def to_json(self, skip_rounding: bool = False) -> Dict[str, Any]:
-        __round__ = RoundNumericValuesMixin.round_array_or_number
-        round_func = __round__ if not skip_rounding else lambda x: x
-        return {
-            "a": round_func(self.a),
-            "b": round_func(self.b),
-            "c": round_func(self.c),
-            "alpha": round_func(self.alpha),
-            "beta": round_func(self.beta),
-            "gamma": round_func(self.gamma),
-            "units": self.units,
-            "type": self.type,
-            "vectors": self.vectors,
-        }
-
-    def clone(self, extra_context: Optional[Dict[str, Any]] = None) -> "Lattice":
-        if extra_context is None:
-            extra_context = {}
-        return Lattice(**{**self.to_json(), **extra_context})
+
+        return cls(
+            a=float(a),
+            b=float(b),
+            c=float(c),
+            alpha=alpha,
+            beta=beta,
+            gamma=gamma,
+            units=units,
+            type=type,
+        )
 
     @property
-    def vector_arrays(self) -> List[List[float]]:
-        """Returns lattice vectors as a nested array"""
-        v = self.vectors
-        return [v.a, v.b, v.c]
+    def vector_arrays(self, skip_rounding=False) -> List[List[float]]:
+        _ = [self.vectors.a, self.vectors.b, self.vectors.c]
+        if not skip_rounding:
+            return list(map(lambda vector: vector.value_rounded, _))
+        return list(map(lambda vector: vector.root, _))
 
     @property
     def cell(self) -> Cell:
         return Cell.from_vectors_array(self.vector_arrays)
 
-    def volume(self) -> float:
-        np_vector = np.array(self.vector_arrays)
-        return abs(np.linalg.det(np_vector))
+    @property
+    def cell_volume(self) -> float:
+        return self.cell.volume
+
+    def get_scaled_by_matrix(self, matrix: List[List[float]]):
+        """
+        Scale the lattice by a matrix.
+        Args:
+            matrix (List[List[float]]): A 3x3 matrix.
+        """
+        np_vectors = np.array(self.vector_arrays)
+        np_matrix = np.array(matrix)
+        scaled_vectors = np.dot(np_matrix, np_vectors).tolist()
+        new_lattice = self.from_vectors_array(vectors=scaled_vectors, units=self.units, type=self.type)
+        return new_lattice