httk-atomistic 0.1.0__py3-none-any.whl

httk/atomistic/__init__.py

@@ -0,0 +1,98 @@
+"""
+httk-atomistic: crystal structure representations for httk v2.
+
+Provides the Structure domain and its component families (Cell, Sites, Species),
+each following the httk-core view/backend pattern. A Structure holds a ``cell``, a
+``sites``, a tuple of ``species``, and a ``species_at_sites``; each component has a
+class representation and a primitive representation convertible through views. ASU and
+exact-vector numerics are planned follow-ups.
+"""
+
+from .cell import Cell
+from .cell_api import CellAPI
+from .cell_backend import CellBackend
+from .cell_class import CellClass
+from .cell_class_view import CellClassView
+from .cell_like import CellLike
+from .cell_params import CellParams
+from .cell_params_view import CellParamsView
+from .cell_primitive import CellPrimitive
+from .cell_primitive_view import CellPrimitiveView
+from .cell_view import CellView
+from .elements import SYMBOLS, atomic_number, symbol_of
+from .sites import Sites
+from .sites_api import SitesAPI
+from .sites_backend import SitesBackend
+from .sites_class import SitesClass
+from .sites_class_view import SitesClassView
+from .sites_like import SitesLike
+from .sites_primitive import SitesPrimitive
+from .sites_primitive_view import SitesPrimitiveView
+from .sites_view import SitesView
+from .species import Species
+from .species_api import SpeciesAPI
+from .species_backend import SpeciesBackend
+from .species_class import SpeciesClass
+from .species_class_view import SpeciesClassView
+from .species_like import SpeciesLike
+from .species_primitive import SpeciesPrimitive
+from .species_primitive_view import SpeciesPrimitiveView
+from .species_view import SpeciesView
+from .structure import Structure
+from .structure_api import StructureAPI
+from .structure_backend import StructureBackend
+from .structure_like import StructureLike
+from .structure_primitive import StructurePrimitive
+from .structure_primitive_view import StructurePrimitiveView
+from .structure_simple import StructureSimple
+from .structure_simple_view import StructureSimpleView
+from .structure_view import StructureView
+
+StructureBackend.backend_classes = [StructureSimple, StructurePrimitive]
+CellBackend.backend_classes = [CellClass, CellPrimitive, CellParams]
+SitesBackend.backend_classes = [SitesClass, SitesPrimitive]
+SpeciesBackend.backend_classes = [SpeciesClass, SpeciesPrimitive]
+
+__all__ = [
+    "Structure",
+    "StructureLike",
+    "StructureAPI",
+    "StructureBackend",
+    "StructureView",
+    "StructureSimple",
+    "StructurePrimitive",
+    "StructureSimpleView",
+    "StructurePrimitiveView",
+    "Cell",
+    "CellLike",
+    "CellAPI",
+    "CellBackend",
+    "CellView",
+    "CellClass",
+    "CellPrimitive",
+    "CellParams",
+    "CellClassView",
+    "CellPrimitiveView",
+    "CellParamsView",
+    "Sites",
+    "SitesLike",
+    "SitesAPI",
+    "SitesBackend",
+    "SitesView",
+    "SitesClass",
+    "SitesPrimitive",
+    "SitesClassView",
+    "SitesPrimitiveView",
+    "Species",
+    "SpeciesLike",
+    "SpeciesAPI",
+    "SpeciesBackend",
+    "SpeciesView",
+    "SpeciesClass",
+    "SpeciesPrimitive",
+    "SpeciesClassView",
+    "SpeciesPrimitiveView",
+    "SYMBOLS",
+    "atomic_number",
+    "symbol_of",
+]

httk/atomistic/cell.py

@@ -0,0 +1,79 @@
+"""
+The Cell class for httk-atomistic.
+"""
+
+import math
+from collections.abc import Sequence
+
+
+class Cell:
+    """
+    A crystallographic cell: the 3x3 matrix of cell (basis) vectors.
+
+    A Cell holds three cell vectors as the rows of a 3x3 ``matrix`` and exposes the
+    basic derived quantities ``lengths`` (the row norms), ``angles`` (the crystallographic
+    ``alpha``/``beta``/``gamma`` in degrees), and ``volume`` (the absolute determinant).
+
+    Note: the numeric values are stored as interim nested tuples of floats and the
+    derived quantities use plain float arithmetic. They are intended to be replaced by
+    the httk exact vector representation fairly soon; keep numeric access behind the
+    ``matrix`` accessor so that change stays contained.
+    """
+
+    _matrix: tuple[tuple[float, ...], ...]
+
+    def __init__(self, matrix: Sequence[Sequence[float]]) -> None:
+        norm = tuple(tuple(float(x) for x in row) for row in matrix)
+        if len(norm) != 3 or any(len(row) != 3 for row in norm):
+            raise ValueError("Cell matrix must be a 3x3 sequence")
+        self._matrix = norm
+
+    @property
+    def matrix(self) -> tuple[tuple[float, ...], ...]:
+        """The 3x3 cell vectors as nested float tuples (one vector per row)."""
+        return self._matrix
+
+    @property
+    def lengths(self) -> tuple[float, float, float]:
+        """The lengths of the three cell vectors (the row norms)."""
+        rows = self._matrix
+        return (
+            math.sqrt(sum(x * x for x in rows[0])),
+            math.sqrt(sum(x * x for x in rows[1])),
+            math.sqrt(sum(x * x for x in rows[2])),
+        )
+
+    @property
+    def angles(self) -> tuple[float, float, float]:
+        """
+        The cell angles ``(alpha, beta, gamma)`` in degrees.
+
+        Following the crystallographic convention, ``alpha`` is the angle between rows
+        ``b`` and ``c``, ``beta`` between ``a`` and ``c``, and ``gamma`` between ``a``
+        and ``b``.
+        """
+        a, b, c = self._matrix
+        return (self._angle(b, c), self._angle(a, c), self._angle(a, b))
+
+    @property
+    def volume(self) -> float:
+        """The cell volume, the absolute value of the determinant of ``matrix``."""
+        (a0, a1, a2), (b0, b1, b2), (c0, c1, c2) = self._matrix
+        det = a0 * (b1 * c2 - b2 * c1) - a1 * (b0 * c2 - b2 * c0) + a2 * (b0 * c1 - b1 * c0)
+        return abs(det)
+
+    @staticmethod
+    def _angle(u: Sequence[float], v: Sequence[float]) -> float:
+        dot = sum(ui * vi for ui, vi in zip(u, v))
+        nu = math.sqrt(sum(ui * ui for ui in u))
+        nv = math.sqrt(sum(vi * vi for vi in v))
+        cosine = max(-1.0, min(1.0, dot / (nu * nv)))
+        return math.degrees(math.acos(cosine))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Cell):
+            return NotImplemented
+        return self._matrix == other._matrix
+
+    def __repr__(self) -> str:
+        return f"Cell(matrix={self._matrix!r})"

httk/atomistic/cell_api.py

@@ -0,0 +1,21 @@
+"""
+The minimal canonical cell interface for httk-atomistic.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class CellAPI(ABC):
+    """
+    Abstract base class for the canonical cell interface.
+
+    It declares the single ``matrix`` accessor (the 3x3 cell vectors) that every cell
+    backend produces from its own native representation and every cell view builds its
+    presentation from. This is the single interchange format; there is no pairwise
+    conversion between backends.
+    """
+
+    @property
+    @abstractmethod
+    def matrix(self) -> tuple[tuple[float, ...], ...]:
+        raise NotImplementedError

httk/atomistic/cell_backend.py

@@ -0,0 +1,20 @@
+"""
+The abstract base class for all cell backends in httk-atomistic.
+"""
+
+from typing import Any, ClassVar
+
+from httk.core import Backend
+
+from .cell_api import CellAPI
+
+
+class CellBackend(Backend["CellBackend"], CellAPI):
+    """
+    Abstract base class for all backends of cell data.
+
+    Concrete backends carry a native representation and produce the canonical 3x3
+    ``matrix`` declared by ``CellAPI`` from it.
+    """
+
+    backend_classes: ClassVar[list[type[Backend[Any]]]]

httk/atomistic/cell_class.py

@@ -0,0 +1,37 @@
+"""
+Backend wrapping a Cell in the class representation.
+"""
+
+from typing import Any
+
+from .cell import Cell
+from .cell_backend import CellBackend
+
+
+class CellClass(CellBackend):
+    """
+    Backend for a cell backed by an actual ``Cell`` object.
+
+    Its ``matrix`` accessor delegates to the wrapped Cell, and ``unwrap`` returns that
+    Cell.
+    """
+
+    _cell: Cell
+
+    # Cannot type annotate __new__ as `Self | None` for some reason
+    def __new__(cls, obj: Any, **hints: Any) -> Any:
+        if not isinstance(obj, Cell):
+            return None
+        if hints and hints.get("kind", "class") != "class":
+            return None
+        return super().__new__(cls)
+
+    def __init__(self, obj: Cell, **hints: Any) -> None:
+        self._cell = obj
+
+    @property
+    def matrix(self) -> tuple[tuple[float, ...], ...]:
+        return self._cell.matrix
+
+    def unwrap(self) -> Any:
+        return self._cell

httk/atomistic/cell_class_view.py

@@ -0,0 +1,40 @@
+"""
+A view presenting any cell backend as a Cell (the class representation).
+"""
+
+from typing import Any, Self
+
+from httk.core import unwrap
+
+from .cell import Cell
+from .cell_backend import CellBackend
+from .cell_like import CellLike
+from .cell_view import CellView
+
+
+class CellClassView(CellView, Cell):
+    """
+    A view presenting an underlying cell backend as a ``Cell``.
+
+    This view is a genuine ``Cell``, so it can be passed anywhere a Cell is accepted.
+    Its matrix is built eagerly from the backend on construction.
+    """
+
+    _backend: CellBackend
+
+    def __new__(cls, obj: CellLike, **hints: Any) -> Self:
+        if isinstance(obj, cls):
+            return obj
+        backend = cls._prepare_backend(obj, hints)
+        instance = super().__new__(cls)
+        # Cell is mutable, so its state is initialized here in __new__ (keeping __init__ a no-op),
+        # so that rewrapping an existing view via cls(view) does not re-initialize it.
+        Cell.__init__(instance, backend.matrix)
+        instance._backend = backend
+        return instance
+
+    def __init__(self, obj: CellLike, **hints: Any) -> None:
+        pass
+
+    def unwrap(self) -> Any:
+        return unwrap(self._backend)

httk/atomistic/cell_like.py

@@ -0,0 +1,16 @@
+"""
+The accepted-input union for cell functions in httk-atomistic.
+"""
+
+from typing import Any
+
+from . import cell, cell_backend, cell_view
+
+type CellLike = (
+    cell_backend.CellBackend
+    | cell_view.CellView
+    | cell.Cell
+    | tuple[Any, Any, Any]
+    | tuple[Any, Any, Any, Any, Any, Any]
+    | list[Any]
+)

httk/atomistic/cell_params.py

@@ -0,0 +1,94 @@
+"""
+Backend wrapping cell parameters (a, b, c, alpha, beta, gamma).
+"""
+
+import math
+from typing import Any
+
+from .cell_backend import CellBackend
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _is_params(obj: Any) -> bool:
+    return isinstance(obj, (list, tuple)) and len(obj) == 6 and all(_is_number(x) for x in obj)
+
+
+def _params_to_matrix(params: tuple[float, ...]) -> tuple[tuple[float, ...], ...]:
+    a, b, c, alpha, beta, gamma = params
+    cos_alpha = math.cos(math.radians(alpha))
+    cos_beta = math.cos(math.radians(beta))
+    cos_gamma = math.cos(math.radians(gamma))
+    sin_gamma = math.sin(math.radians(gamma))
+    cy = (cos_alpha - cos_beta * cos_gamma) / sin_gamma
+    cz_sq = 1.0 - cos_beta * cos_beta - cy * cy
+    return (
+        (a, 0.0, 0.0),
+        (b * cos_gamma, b * sin_gamma, 0.0),
+        (c * cos_beta, c * cy, c * math.sqrt(cz_sq)),
+    )
+
+
+class CellParams(CellBackend):
+    """
+    Backend for a cell backed by cell parameters ``(a, b, c, alpha, beta, gamma)``.
+
+    The native representation is a flat length-6 list or tuple of the cell-vector
+    lengths ``a``/``b``/``c`` and the angles ``alpha``/``beta``/``gamma`` in degrees.
+    The ``matrix`` is derived lazily and cached using the standard crystallographic
+    orientation convention (the first cell vector along x, the second in the xy-plane);
+    since parameters carry no orientation, converting a cell to parameters and back
+    reproduces its lengths, angles, and volume, but not its original orientation.
+    ``unwrap`` returns the original raw object.
+    """
+
+    _raw: Any
+    _params: tuple[float, ...]
+    _matrix_cache: tuple[tuple[float, ...], ...] | None
+
+    # Cannot type annotate __new__ as `Self | None` for some reason
+    def __new__(cls, obj: Any, **hints: Any) -> Any:
+        if hints and hints.get("kind", "params") != "params":
+            return None
+        if not _is_params(obj):
+            return None
+        return super().__new__(cls)
+
+    def __init__(self, obj: Any, **hints: Any) -> None:
+        params = tuple(float(x) for x in obj)
+        a, b, c, alpha, beta, gamma = params
+        if a <= 0.0 or b <= 0.0 or c <= 0.0:
+            raise ValueError("Cell parameter lengths a, b, c must be positive")
+        if not all(0.0 < angle < 180.0 for angle in (alpha, beta, gamma)):
+            raise ValueError("Cell parameter angles alpha, beta, gamma must be strictly between 0 and 180 degrees")
+        cos_alpha = math.cos(math.radians(alpha))
+        cos_beta = math.cos(math.radians(beta))
+        cos_gamma = math.cos(math.radians(gamma))
+        volume_factor = (
+            1.0
+            - cos_alpha * cos_alpha
+            - cos_beta * cos_beta
+            - cos_gamma * cos_gamma
+            + 2.0 * cos_alpha * cos_beta * cos_gamma
+        )
+        if volume_factor <= 0.0:
+            raise ValueError("Cell parameter angles do not describe a valid (non-degenerate) cell")
+        self._raw = obj
+        self._params = params
+        self._matrix_cache = None
+
+    @property
+    def matrix(self) -> tuple[tuple[float, ...], ...]:
+        if self._matrix_cache is None:
+            self._matrix_cache = _params_to_matrix(self._params)
+        return self._matrix_cache
+
+    @property
+    def params(self) -> tuple[float, ...]:
+        """The stored ``(a, b, c, alpha, beta, gamma)`` as a tuple of floats (angles in degrees)."""
+        return self._params
+
+    def unwrap(self) -> Any:
+        return self._raw

httk/atomistic/cell_params_view.py

@@ -0,0 +1,75 @@
+"""
+A view presenting any cell backend as cell parameters (a, b, c, alpha, beta, gamma).
+"""
+
+from typing import Any, Self
+
+from httk.core import unwrap
+
+from .cell import Cell
+from .cell_backend import CellBackend
+from .cell_like import CellLike
+from .cell_view import CellView
+
+
+class CellParamsView(CellView, tuple):
+    """
+    A view presenting an underlying cell backend as cell parameters.
+
+    This view is a genuine flat 6-tuple ``(a, b, c, alpha, beta, gamma)`` with the
+    angles in degrees, built eagerly and immutable, with the elements also available
+    as the named properties ``a``/``b``/``c``/``alpha``/``beta``/``gamma``.
+    Parameters carry no orientation, so converting a cell to parameters is lossy:
+    reconstructing a cell from this view reproduces the lengths, angles, and volume,
+    but not the original cell-vector orientation.
+    """
+
+    _backend: CellBackend
+
+    def __new__(cls, obj: CellLike, **hints: Any) -> Self:
+        if isinstance(obj, cls):
+            return obj
+        backend = cls._prepare_backend(obj, hints)
+        params = getattr(backend, "params", None)
+        if params is None:
+            reference = Cell(backend.matrix)
+            params = reference.lengths + reference.angles
+        instance = super().__new__(cls, params)
+        instance._backend = backend
+        return instance
+
+    def __init__(self, obj: CellLike, **hints: Any) -> None:
+        super().__init__()
+
+    @property
+    def a(self) -> float:
+        """The length of the first cell vector."""
+        return self[0]
+
+    @property
+    def b(self) -> float:
+        """The length of the second cell vector."""
+        return self[1]
+
+    @property
+    def c(self) -> float:
+        """The length of the third cell vector."""
+        return self[2]
+
+    @property
+    def alpha(self) -> float:
+        """The angle between the second and third cell vectors, in degrees."""
+        return self[3]
+
+    @property
+    def beta(self) -> float:
+        """The angle between the first and third cell vectors, in degrees."""
+        return self[4]
+
+    @property
+    def gamma(self) -> float:
+        """The angle between the first and second cell vectors, in degrees."""
+        return self[5]
+
+    def unwrap(self) -> Any:
+        return unwrap(self._backend)

httk/atomistic/cell_primitive.py

@@ -0,0 +1,56 @@
+"""
+Backend wrapping a raw 3x3 cell-vector matrix.
+"""
+
+from typing import Any
+
+from .cell_backend import CellBackend
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _is_3x3(matrix: Any) -> bool:
+    if not isinstance(matrix, (list, tuple)) or len(matrix) != 3:
+        return False
+    for row in matrix:
+        if not isinstance(row, (list, tuple)) or len(row) != 3:
+            return False
+        if not all(_is_number(x) for x in row):
+            return False
+    return True
+
+
+class CellPrimitive(CellBackend):
+    """
+    Backend for a cell backed by a raw 3x3 list or tuple of numbers.
+
+    The native representation is a 3x3 nested list or tuple of cell vectors (one vector
+    per row). The ``matrix`` is derived lazily and cached, and ``unwrap`` returns the
+    original raw object.
+    """
+
+    _raw: Any
+    _matrix_cache: tuple[tuple[float, ...], ...] | None
+
+    # Cannot type annotate __new__ as `Self | None` for some reason
+    def __new__(cls, obj: Any, **hints: Any) -> Any:
+        if hints and hints.get("kind", "primitive") != "primitive":
+            return None
+        if not _is_3x3(obj):
+            return None
+        return super().__new__(cls)
+
+    def __init__(self, obj: Any, **hints: Any) -> None:
+        self._raw = obj
+        self._matrix_cache = None
+
+    @property
+    def matrix(self) -> tuple[tuple[float, ...], ...]:
+        if self._matrix_cache is None:
+            self._matrix_cache = tuple(tuple(float(x) for x in row) for row in self._raw)
+        return self._matrix_cache
+
+    def unwrap(self) -> Any:
+        return self._raw

httk/atomistic/cell_primitive_view.py

@@ -0,0 +1,35 @@
+"""
+A view presenting any cell backend as a raw 3-row tuple of cell vectors.
+"""
+
+from typing import Any, Self
+
+from httk.core import unwrap
+
+from .cell_backend import CellBackend
+from .cell_like import CellLike
+from .cell_view import CellView
+
+
+class CellPrimitiveView(CellView, tuple):
+    """
+    A view presenting an underlying cell backend as a raw 3x3 matrix.
+
+    This view is a genuine tuple of three cell-vector rows, built eagerly and immutable.
+    """
+
+    _backend: CellBackend
+
+    def __new__(cls, obj: CellLike, **hints: Any) -> Self:
+        if isinstance(obj, cls):
+            return obj
+        backend = cls._prepare_backend(obj, hints)
+        instance = super().__new__(cls, backend.matrix)
+        instance._backend = backend
+        return instance
+
+    def __init__(self, obj: CellLike, **hints: Any) -> None:
+        super().__init__()
+
+    def unwrap(self) -> Any:
+        return unwrap(self._backend)

httk/atomistic/cell_view.py

@@ -0,0 +1,21 @@
+"""
+The abstract base class for all cell views in httk-atomistic.
+"""
+
+from typing import ClassVar, Self
+
+from httk.core import View
+
+from .cell_backend import CellBackend
+
+
+class CellView(View[CellBackend]):
+    """
+    Abstract base class for all views of cell data.
+    """
+
+    _backend_base_cls: ClassVar[type[CellBackend]] = CellBackend  # type: ignore[type-abstract]
+    _view_base_cls: ClassVar[type[Self]]
+
+
+CellView._view_base_cls = CellView