httk-atomistic 0.1.0__py3-none-any.whl

httk/atomistic/elements.py

@@ -0,0 +1,156 @@
+"""
+Minimal periodic table for httk-atomistic.
+
+Provides the IUPAC element symbols in atomic-number order and helpers to convert
+between a chemical symbol and its atomic number. The pseudo-symbols ``"X"``
+(unknown element) and ``"vacancy"`` are deliberately not elements here; they are
+handled at the ``Species`` level.
+"""
+
+SYMBOLS: tuple[str, ...] = (
+    "H",
+    "He",
+    "Li",
+    "Be",
+    "B",
+    "C",
+    "N",
+    "O",
+    "F",
+    "Ne",
+    "Na",
+    "Mg",
+    "Al",
+    "Si",
+    "P",
+    "S",
+    "Cl",
+    "Ar",
+    "K",
+    "Ca",
+    "Sc",
+    "Ti",
+    "V",
+    "Cr",
+    "Mn",
+    "Fe",
+    "Co",
+    "Ni",
+    "Cu",
+    "Zn",
+    "Ga",
+    "Ge",
+    "As",
+    "Se",
+    "Br",
+    "Kr",
+    "Rb",
+    "Sr",
+    "Y",
+    "Zr",
+    "Nb",
+    "Mo",
+    "Tc",
+    "Ru",
+    "Rh",
+    "Pd",
+    "Ag",
+    "Cd",
+    "In",
+    "Sn",
+    "Sb",
+    "Te",
+    "I",
+    "Xe",
+    "Cs",
+    "Ba",
+    "La",
+    "Ce",
+    "Pr",
+    "Nd",
+    "Pm",
+    "Sm",
+    "Eu",
+    "Gd",
+    "Tb",
+    "Dy",
+    "Ho",
+    "Er",
+    "Tm",
+    "Yb",
+    "Lu",
+    "Hf",
+    "Ta",
+    "W",
+    "Re",
+    "Os",
+    "Ir",
+    "Pt",
+    "Au",
+    "Hg",
+    "Tl",
+    "Pb",
+    "Bi",
+    "Po",
+    "At",
+    "Rn",
+    "Fr",
+    "Ra",
+    "Ac",
+    "Th",
+    "Pa",
+    "U",
+    "Np",
+    "Pu",
+    "Am",
+    "Cm",
+    "Bk",
+    "Cf",
+    "Es",
+    "Fm",
+    "Md",
+    "No",
+    "Lr",
+    "Rf",
+    "Db",
+    "Sg",
+    "Bh",
+    "Hs",
+    "Mt",
+    "Ds",
+    "Rg",
+    "Cn",
+    "Nh",
+    "Fl",
+    "Mc",
+    "Lv",
+    "Ts",
+    "Og",
+)
+"""The 118 IUPAC element symbols in atomic-number order (``SYMBOLS[0]`` is hydrogen)."""
+
+_NUMBER_OF: dict[str, int] = {symbol: z for z, symbol in enumerate(SYMBOLS, start=1)}
+
+
+def atomic_number(symbol: str) -> int:
+    """
+    Return the atomic number (1-118) of an element symbol.
+
+    Raises ValueError for anything that is not one of the 118 element symbols
+    (in particular for the ``"X"`` and ``"vacancy"`` pseudo-symbols).
+    """
+    try:
+        return _NUMBER_OF[symbol]
+    except KeyError:
+        raise ValueError(f"Unknown element symbol: {symbol!r}") from None
+
+
+def symbol_of(z: int) -> str:
+    """
+    Return the element symbol for the atomic number z (1-118).
+
+    Raises ValueError for atomic numbers outside the 1-118 range.
+    """
+    if not 1 <= z <= len(SYMBOLS):
+        raise ValueError(f"Unknown atomic number: {z!r}")
+    return SYMBOLS[z - 1]

httk/atomistic/sites.py

@@ -0,0 +1,49 @@
+"""
+The Sites class for httk-atomistic.
+"""
+
+from collections.abc import Iterator, Sequence
+
+
+class Sites:
+    """
+    The sites of a crystal structure: the Nx3 matrix of reduced coordinates.
+
+    A Sites object holds N sites as the rows of ``reduced_coords`` and is iterable and
+    indexable over those length-3 coordinate rows (with ``len`` giving the number of
+    sites).
+
+    Note: the numeric values are stored as interim nested tuples of floats. They are
+    intended to be replaced by the httk exact vector representation fairly soon; keep
+    numeric access behind the ``reduced_coords`` accessor so that change stays contained.
+    """
+
+    _reduced_coords: tuple[tuple[float, ...], ...]
+
+    def __init__(self, reduced_coords: Sequence[Sequence[float]]) -> None:
+        norm = tuple(tuple(float(x) for x in row) for row in reduced_coords)
+        if any(len(row) != 3 for row in norm):
+            raise ValueError("Sites reduced_coords must be a sequence of length-3 coordinates")
+        self._reduced_coords = norm
+
+    @property
+    def reduced_coords(self) -> tuple[tuple[float, ...], ...]:
+        """The Nx3 reduced site coordinates as nested float tuples (one site per row)."""
+        return self._reduced_coords
+
+    def __len__(self) -> int:
+        return len(self._reduced_coords)
+
+    def __iter__(self) -> Iterator[tuple[float, ...]]:
+        return iter(self._reduced_coords)
+
+    def __getitem__(self, index: int) -> tuple[float, ...]:
+        return self._reduced_coords[index]
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Sites):
+            return NotImplemented
+        return self._reduced_coords == other._reduced_coords
+
+    def __repr__(self) -> str:
+        return f"Sites(reduced_coords={self._reduced_coords!r})"

httk/atomistic/sites_api.py

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

httk/atomistic/sites_backend.py

@@ -0,0 +1,20 @@
+"""
+The abstract base class for all sites backends in httk-atomistic.
+"""
+
+from typing import Any, ClassVar
+
+from httk.core import Backend
+
+from .sites_api import SitesAPI
+
+
+class SitesBackend(Backend["SitesBackend"], SitesAPI):
+    """
+    Abstract base class for all backends of sites data.
+
+    Concrete backends carry a native representation and produce the canonical Nx3
+    ``reduced_coords`` declared by ``SitesAPI`` from it.
+    """
+
+    backend_classes: ClassVar[list[type[Backend[Any]]]]

httk/atomistic/sites_class.py

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

httk/atomistic/sites_class_view.py

@@ -0,0 +1,40 @@
+"""
+A view presenting any sites backend as a Sites object (the class representation).
+"""
+
+from typing import Any, Self
+
+from httk.core import unwrap
+
+from .sites import Sites
+from .sites_backend import SitesBackend
+from .sites_like import SitesLike
+from .sites_view import SitesView
+
+
+class SitesClassView(SitesView, Sites):
+    """
+    A view presenting an underlying sites backend as a ``Sites`` object.
+
+    This view is a genuine ``Sites``, so it can be passed anywhere a Sites is accepted.
+    Its coordinates are built eagerly from the backend on construction.
+    """
+
+    _backend: SitesBackend
+
+    def __new__(cls, obj: SitesLike, **hints: Any) -> Self:
+        if isinstance(obj, cls):
+            return obj
+        backend = cls._prepare_backend(obj, hints)
+        instance = super().__new__(cls)
+        # Sites 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.
+        Sites.__init__(instance, backend.reduced_coords)
+        instance._backend = backend
+        return instance
+
+    def __init__(self, obj: SitesLike, **hints: Any) -> None:
+        pass
+
+    def unwrap(self) -> Any:
+        return unwrap(self._backend)

httk/atomistic/sites_like.py

@@ -0,0 +1,9 @@
+"""
+The accepted-input union for sites functions in httk-atomistic.
+"""
+
+from typing import Any
+
+from . import sites, sites_backend, sites_view
+
+type SitesLike = (sites_backend.SitesBackend | sites_view.SitesView | sites.Sites | tuple[Any, ...] | list[Any])

httk/atomistic/sites_primitive.py

@@ -0,0 +1,56 @@
+"""
+Backend wrapping a raw Nx3 matrix of reduced coordinates.
+"""
+
+from typing import Any
+
+from .sites_backend import SitesBackend
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _is_nx3(matrix: Any) -> bool:
+    if not isinstance(matrix, (list, tuple)):
+        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 SitesPrimitive(SitesBackend):
+    """
+    Backend for sites backed by a raw Nx3 list or tuple of numbers.
+
+    The native representation is an Nx3 nested list or tuple of reduced coordinates (one
+    site per row). The ``reduced_coords`` are derived lazily and cached, and ``unwrap``
+    returns the original raw object.
+    """
+
+    _raw: Any
+    _reduced_coords_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_nx3(obj):
+            return None
+        return super().__new__(cls)
+
+    def __init__(self, obj: Any, **hints: Any) -> None:
+        self._raw = obj
+        self._reduced_coords_cache = None
+
+    @property
+    def reduced_coords(self) -> tuple[tuple[float, ...], ...]:
+        if self._reduced_coords_cache is None:
+            self._reduced_coords_cache = tuple(tuple(float(x) for x in row) for row in self._raw)
+        return self._reduced_coords_cache
+
+    def unwrap(self) -> Any:
+        return self._raw

httk/atomistic/sites_primitive_view.py

@@ -0,0 +1,35 @@
+"""
+A view presenting any sites backend as a raw Nx3 tuple of reduced coordinates.
+"""
+
+from typing import Any, Self
+
+from httk.core import unwrap
+
+from .sites_backend import SitesBackend
+from .sites_like import SitesLike
+from .sites_view import SitesView
+
+
+class SitesPrimitiveView(SitesView, tuple):
+    """
+    A view presenting an underlying sites backend as a raw Nx3 matrix.
+
+    This view is a genuine tuple of reduced-coordinate rows, built eagerly and immutable.
+    """
+
+    _backend: SitesBackend
+
+    def __new__(cls, obj: SitesLike, **hints: Any) -> Self:
+        if isinstance(obj, cls):
+            return obj
+        backend = cls._prepare_backend(obj, hints)
+        instance = super().__new__(cls, backend.reduced_coords)
+        instance._backend = backend
+        return instance
+
+    def __init__(self, obj: SitesLike, **hints: Any) -> None:
+        super().__init__()
+
+    def unwrap(self) -> Any:
+        return unwrap(self._backend)

httk/atomistic/sites_view.py

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

httk/atomistic/species.py

@@ -0,0 +1,87 @@
+"""
+Species definition for httk-atomistic, mirroring the OPTIMADE ``species`` entry.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from .elements import SYMBOLS
+
+_ELEMENTS: frozenset[str] = frozenset(SYMBOLS)
+_SPECIAL_SYMBOLS: frozenset[str] = frozenset({"X", "vacancy"})
+
+
+@dataclass(frozen=True)
+class Species:
+    """
+    A chemical species occupying one or more sites, mirroring the OPTIMADE ``species`` object.
+
+    A species has a ``name`` (unique within a structure; it need not be a chemical
+    symbol), a list of ``chemical_symbols`` composing it, and a matching list of
+    ``concentration`` values. Each chemical symbol is an element symbol, or one of
+    the pseudo-symbols ``"X"`` (unknown) or ``"vacancy"``. The optional ``mass``,
+    ``attached``, ``nattached``, and ``original_name`` fields carry the remaining
+    OPTIMADE species information; ``attached`` and ``nattached`` must be given
+    together and share their length.
+    """
+
+    name: str
+    chemical_symbols: tuple[str, ...]
+    concentration: tuple[float, ...]
+    mass: tuple[float, ...] | None = None
+    original_name: str | None = None
+    attached: tuple[str, ...] | None = None
+    nattached: tuple[int, ...] | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "chemical_symbols", tuple(self.chemical_symbols))
+        object.__setattr__(self, "concentration", tuple(float(c) for c in self.concentration))
+        if self.mass is not None:
+            object.__setattr__(self, "mass", tuple(float(m) for m in self.mass))
+        if self.attached is not None:
+            object.__setattr__(self, "attached", tuple(self.attached))
+        if self.nattached is not None:
+            object.__setattr__(self, "nattached", tuple(int(n) for n in self.nattached))
+
+        if len(self.concentration) != len(self.chemical_symbols):
+            raise ValueError("Species concentration must have the same length as chemical_symbols")
+        for symbol in self.chemical_symbols:
+            if symbol not in _ELEMENTS and symbol not in _SPECIAL_SYMBOLS:
+                raise ValueError(f"Species chemical symbol is not an element, 'X', or 'vacancy': {symbol!r}")
+        if self.mass is not None and len(self.mass) != len(self.chemical_symbols):
+            raise ValueError("Species mass must have the same length as chemical_symbols")
+        if (self.attached is None) != (self.nattached is None):
+            raise ValueError("Species attached and nattached must be given together or not at all")
+        if self.attached is not None and self.nattached is not None and len(self.attached) != len(self.nattached):
+            raise ValueError("Species attached and nattached must have the same length")
+
+    @property
+    def is_single_element(self) -> bool:
+        """
+        Whether this species is a single, unattached, real chemical element.
+
+        True only for a species composed of exactly one element symbol (not ``"X"``
+        or ``"vacancy"``) with no attached particles. Such species are the ones that
+        can be represented as a bare atomic number in the primitive representation.
+        """
+        return len(self.chemical_symbols) == 1 and self.chemical_symbols[0] in _ELEMENTS and self.attached is None
+
+    @classmethod
+    def create(cls, obj: "Species | dict[str, Any]") -> "Species":
+        """
+        Return a Species from either an existing Species (returned unchanged) or an OPTIMADE species dict.
+        """
+        if isinstance(obj, Species):
+            return obj
+        attached = obj.get("attached")
+        nattached = obj.get("nattached")
+        mass = obj.get("mass")
+        return cls(
+            name=obj["name"],
+            chemical_symbols=tuple(obj["chemical_symbols"]),
+            concentration=tuple(obj["concentration"]),
+            mass=None if mass is None else tuple(mass),
+            original_name=obj.get("original_name"),
+            attached=None if attached is None else tuple(attached),
+            nattached=None if nattached is None else tuple(nattached),
+        )

httk/atomistic/species_api.py

@@ -0,0 +1,51 @@
+"""
+The minimal canonical species interface for httk-atomistic.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class SpeciesAPI(ABC):
+    """
+    Abstract base class for the canonical single-species interface.
+
+    It declares the accessors mirroring the OPTIMADE ``species`` fields that every
+    species backend produces from its own native representation and every species view
+    builds its presentation from: ``name``, ``chemical_symbols``, ``concentration``,
+    and the optional ``mass``, ``attached``, ``nattached``, and ``original_name``.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def chemical_symbols(self) -> tuple[str, ...]:
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def concentration(self) -> tuple[float, ...]:
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def mass(self) -> tuple[float, ...] | None:
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def attached(self) -> tuple[str, ...] | None:
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def nattached(self) -> tuple[int, ...] | None:
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def original_name(self) -> str | None:
+        raise NotImplementedError

httk/atomistic/species_backend.py

@@ -0,0 +1,20 @@
+"""
+The abstract base class for all species backends in httk-atomistic.
+"""
+
+from typing import Any, ClassVar
+
+from httk.core import Backend
+
+from .species_api import SpeciesAPI
+
+
+class SpeciesBackend(Backend["SpeciesBackend"], SpeciesAPI):
+    """
+    Abstract base class for all backends of single-species data.
+
+    Concrete backends carry a native representation and produce the canonical OPTIMADE
+    species accessors declared by ``SpeciesAPI`` from it.
+    """
+
+    backend_classes: ClassVar[list[type[Backend[Any]]]]

httk/atomistic/species_class.py

@@ -0,0 +1,60 @@
+"""
+Backend wrapping a Species in the class representation.
+"""
+
+from typing import Any
+
+from .species import Species
+from .species_backend import SpeciesBackend
+
+
+class SpeciesClass(SpeciesBackend):
+    """
+    Backend for a species backed by an actual ``Species`` object.
+
+    Its accessors delegate to the wrapped Species, and ``unwrap`` returns that Species.
+    """
+
+    _species: Species
+
+    # Cannot type annotate __new__ as `Self | None` for some reason
+    def __new__(cls, obj: Any, **hints: Any) -> Any:
+        if not isinstance(obj, Species):
+            return None
+        if hints and hints.get("kind", "class") != "class":
+            return None
+        return super().__new__(cls)
+
+    def __init__(self, obj: Species, **hints: Any) -> None:
+        self._species = obj
+
+    @property
+    def name(self) -> str:
+        return self._species.name
+
+    @property
+    def chemical_symbols(self) -> tuple[str, ...]:
+        return self._species.chemical_symbols
+
+    @property
+    def concentration(self) -> tuple[float, ...]:
+        return self._species.concentration
+
+    @property
+    def mass(self) -> tuple[float, ...] | None:
+        return self._species.mass
+
+    @property
+    def attached(self) -> tuple[str, ...] | None:
+        return self._species.attached
+
+    @property
+    def nattached(self) -> tuple[int, ...] | None:
+        return self._species.nattached
+
+    @property
+    def original_name(self) -> str | None:
+        return self._species.original_name
+
+    def unwrap(self) -> Any:
+        return self._species