httk.atomistic ============== .. py:module:: httk.atomistic .. autoapi-nested-parse:: 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. Submodules ---------- .. toctree:: :maxdepth: 1 /reference/autoapi/httk/atomistic/cell/index /reference/autoapi/httk/atomistic/cell_api/index /reference/autoapi/httk/atomistic/cell_backend/index /reference/autoapi/httk/atomistic/cell_class/index /reference/autoapi/httk/atomistic/cell_class_view/index /reference/autoapi/httk/atomistic/cell_like/index /reference/autoapi/httk/atomistic/cell_numeric_view/index /reference/autoapi/httk/atomistic/cell_params/index /reference/autoapi/httk/atomistic/cell_params_view/index /reference/autoapi/httk/atomistic/cell_primitive/index /reference/autoapi/httk/atomistic/cell_primitive_view/index /reference/autoapi/httk/atomistic/cell_view/index /reference/autoapi/httk/atomistic/elements/index /reference/autoapi/httk/atomistic/numeric_cell/index /reference/autoapi/httk/atomistic/numeric_sites/index /reference/autoapi/httk/atomistic/numeric_structure/index /reference/autoapi/httk/atomistic/sites/index /reference/autoapi/httk/atomistic/sites_api/index /reference/autoapi/httk/atomistic/sites_backend/index /reference/autoapi/httk/atomistic/sites_class/index /reference/autoapi/httk/atomistic/sites_class_view/index /reference/autoapi/httk/atomistic/sites_like/index /reference/autoapi/httk/atomistic/sites_numeric_view/index /reference/autoapi/httk/atomistic/sites_primitive/index /reference/autoapi/httk/atomistic/sites_primitive_view/index /reference/autoapi/httk/atomistic/sites_view/index /reference/autoapi/httk/atomistic/species/index /reference/autoapi/httk/atomistic/species_api/index /reference/autoapi/httk/atomistic/species_backend/index /reference/autoapi/httk/atomistic/species_class/index /reference/autoapi/httk/atomistic/species_class_view/index /reference/autoapi/httk/atomistic/species_like/index /reference/autoapi/httk/atomistic/species_primitive/index /reference/autoapi/httk/atomistic/species_primitive_view/index /reference/autoapi/httk/atomistic/species_view/index /reference/autoapi/httk/atomistic/structure/index /reference/autoapi/httk/atomistic/structure_api/index /reference/autoapi/httk/atomistic/structure_backend/index /reference/autoapi/httk/atomistic/structure_entries/index /reference/autoapi/httk/atomistic/structure_like/index /reference/autoapi/httk/atomistic/structure_numeric_view/index /reference/autoapi/httk/atomistic/structure_primitive/index /reference/autoapi/httk/atomistic/structure_primitive_view/index /reference/autoapi/httk/atomistic/structure_simple/index /reference/autoapi/httk/atomistic/structure_simple_view/index /reference/autoapi/httk/atomistic/structure_view/index /reference/autoapi/httk/atomistic/vasp_structures/index Attributes ---------- .. autoapisummary:: httk.atomistic.CellLike httk.atomistic.SYMBOLS httk.atomistic.SitesLike httk.atomistic.SpeciesLike httk.atomistic.StructureLike Classes ------- .. autoapisummary:: httk.atomistic.Cell httk.atomistic.CellAPI httk.atomistic.CellBackend httk.atomistic.CellClass httk.atomistic.CellClassView httk.atomistic.CellNumericView httk.atomistic.CellParams httk.atomistic.CellParamsView httk.atomistic.CellPrimitive httk.atomistic.CellPrimitiveView httk.atomistic.CellView httk.atomistic.NumericCell httk.atomistic.NumericSites httk.atomistic.NumericStructure httk.atomistic.Sites httk.atomistic.SitesAPI httk.atomistic.SitesBackend httk.atomistic.SitesClass httk.atomistic.SitesClassView httk.atomistic.SitesNumericView httk.atomistic.SitesPrimitive httk.atomistic.SitesPrimitiveView httk.atomistic.SitesView httk.atomistic.Species httk.atomistic.SpeciesAPI httk.atomistic.SpeciesBackend httk.atomistic.SpeciesClass httk.atomistic.SpeciesClassView httk.atomistic.SpeciesPrimitive httk.atomistic.SpeciesPrimitiveView httk.atomistic.SpeciesView httk.atomistic.Structure httk.atomistic.StructureAPI httk.atomistic.StructureBackend httk.atomistic.StructureEntryProvider httk.atomistic.StructureNumericView httk.atomistic.StructurePrimitive httk.atomistic.StructurePrimitiveView httk.atomistic.StructureSimple httk.atomistic.StructureSimpleView httk.atomistic.StructureView Functions --------- .. autoapisummary:: httk.atomistic.atomic_number httk.atomistic.symbol_of httk.atomistic.load_structure httk.atomistic.structure_from_poscar Package Contents ---------------- .. py:class:: Cell(basis: httk.core.VectorLike, scale: Any = 1) A crystallographic cell: its basis, the 3x3 matrix of cell vectors, held **exactly**. The lattice vectors are the rows of ``basis``. Internally a Cell factors that basis into a positive :class:`~httk.core.SurdScalar` ``scale`` times an ``unscaled_basis`` (a :class:`~httk.core.SurdVector` of shape ``(3, 3)``), with ``basis == scale * unscaled_basis``. The split lets an overall length factor be carried symbolically: a hexagonal cell of lattice parameter ``a`` and ratio ``c/a`` is the exact ``unscaled`` rows ``(1, 0, 0)``, ``(-1/2, sqrt(3)/2, 0)``, ``(0, 0, c/a)`` scaled by ``a`` — so the ``sqrt(3)`` stays exact regardless of ``a``. A cell built from an absolute basis simply has ``scale == 1``. Numbers embed exactly: rationals (and rational-valued floats) stay rational, and a :class:`~httk.core.SurdVector` basis keeps its radicals. Derived quantities are exact whenever the geometry is metric-rational (the crystallographic case): ``lengths`` come from :meth:`~httk.core.SurdVector.sqrt_of` of the rational squared row lengths, ``angles`` (degrees) from the exact reverse-Niven :meth:`~httk.core.SurdScalar.acos_degrees` where possible, ``volume`` from the exact determinant, and ``metric`` is the exact rational Gram matrix. When a squared length happens to be irrational, ``lengths``/``angles`` fall back to a deterministic rational approximation (documented per accessor). Exact accessors return vector objects — render them with ``.to_floats()`` (nested plain-float lists, numpy-free), ``float(...)`` on scalars, :meth:`numeric` (true numpy arrays), or a view of your choice. .. py:property:: scale :type: httk.core.SurdScalar The overall (strictly positive) length factor, as an exact ``SurdScalar``. .. py:property:: unscaled_basis :type: httk.core.SurdVector The 3x3 cell vectors before applying ``scale``, as an exact ``SurdVector``. .. py:property:: basis :type: httk.core.SurdVector The 3x3 lattice vectors ``scale * unscaled_basis`` (one vector per row), exact. .. py:method:: numeric() -> httk.atomistic.numeric_cell.NumericCell A plain-numpy presentation of this cell (requires the ``httk-atomistic[numpy]`` extra). .. py:method:: metric() -> httk.core.SurdVector The exact Gram matrix ``matrix * matrix^T`` (rational for a metric-rational cell). .. py:property:: lengths :type: tuple[httk.core.SurdScalar, Ellipsis] The lengths of the three cell vectors (the scaled row norms). Exact via :meth:`~httk.core.SurdVector.sqrt_of` whenever the row's squared length is rational (the crystallographic case); otherwise a deterministic rational-approximation ``SurdScalar`` at ``_FALLBACK_PREC`` (the length would be a nested radical, outside the surd field). .. py:property:: angles :type: tuple[fractions.Fraction, Ellipsis] The cell angles ``(alpha, beta, gamma)`` in degrees, as exact ``Fraction`` values. Following the crystallographic convention, ``alpha`` is the angle between rows ``b`` and ``c``, ``beta`` between ``a`` and ``c``, and ``gamma`` between ``a`` and ``b``. Angles are scale-independent, so they are computed from the unscaled basis. The cosine is formed exactly in the surd field and reversed through the Niven table (:meth:`~httk.core.SurdScalar.acos_degrees`) for an exact answer; a non-Niven angle falls back to a deterministic :func:`~httk.core.vectors.exactmath.acos` at ``_FALLBACK_PREC``. .. py:property:: volume :type: httk.core.SurdScalar The cell volume, the exact absolute determinant of ``basis``. .. py:class:: CellAPI Bases: :py:obj:`abc.ABC` Abstract base class for the canonical cell interface. It declares the exact accessors that every cell backend produces from its own native representation and every cell view builds its presentation from: the ``basis`` of 3x3 lattice vectors (``scale * unscaled_basis``), the positive ``scale``, and the ``unscaled_basis``. All three are exact httk-core vectors; this is the single interchange format, with no pairwise conversion between backends. .. py:property:: basis :type: httk.core.SurdVector :abstractmethod: .. py:property:: scale :type: httk.core.SurdScalar :abstractmethod: .. py:property:: unscaled_basis :type: httk.core.SurdVector :abstractmethod: .. py:class:: CellBackend(backend, **hints) Bases: :py:obj:`httk.core.Backend`\ [\ :py:obj:`CellBackend`\ ], :py:obj:`httk.atomistic.cell_api.CellAPI` Abstract base class for all backends of cell data. Concrete backends carry a native representation and produce the canonical 3x3 ``basis`` declared by ``CellAPI`` from it. .. py:attribute:: backend_classes :type: ClassVar[list[type[httk.core.Backend[Any]]]] .. py:class:: CellClass(obj: httk.atomistic.cell.Cell, **hints: Any) Bases: :py:obj:`httk.atomistic.cell_backend.CellBackend` Backend for a cell backed by an actual ``Cell`` object. Its exact accessors delegate to the wrapped Cell (preserving its ``scale``/``unscaled_basis`` split), and ``unwrap`` returns that Cell. .. py:property:: basis :type: httk.core.SurdVector .. py:property:: scale :type: httk.core.SurdScalar .. py:property:: unscaled_basis :type: httk.core.SurdVector .. py:method:: unwrap() -> Any Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: CellClassView(obj: httk.atomistic.cell_like.CellLike, **hints: Any) Bases: :py:obj:`httk.atomistic.cell_view.CellView`, :py:obj:`httk.atomistic.cell.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 basis is built eagerly from the backend on construction. .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:type:: CellLike :canonical: cell_backend.CellBackend | cell_view.CellView | cell.Cell | httk.core.VectorLike .. py:class:: CellNumericView(obj: httk.atomistic.cell_like.CellLike, **hints: Any) Bases: :py:obj:`httk.atomistic.cell_view.CellView`, :py:obj:`httk.atomistic.numeric_cell.NumericCell` A view presenting an underlying cell backend as a ``NumericCell``. This view is a genuine ``NumericCell``, so it can be passed anywhere one is accepted. Its exact ``Cell`` is built eagerly from the backend on construction, preserving the scale/unscaled split. Like a ``NumericCell`` it requires numpy (raising :class:`ImportError` otherwise). .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: CellParams(obj: Any, **hints: Any) Bases: :py:obj:`httk.atomistic.cell_backend.CellBackend` Backend for a cell backed by cell parameters ``(a, b, c, alpha, beta, gamma)``. The native representation is a flat length-6 vector-like of the cell-vector lengths ``a``/``b``/``c`` and the angles ``alpha``/``beta``/``gamma`` in degrees, stored as exact :class:`~fractions.Fraction` values (parsed via :func:`~httk.core.vectors.exactmath.any_to_fraction`). The exact ``basis`` is derived lazily and cached using the standard crystallographic orientation convention (first cell vector along x, second in the xy-plane); for the common Niven angles it is exact (radicals intact). Since parameters carry no separate length factor, ``scale`` is the exact ``1`` and ``unscaled_basis == basis``. Parameters carry no orientation, so a cell → parameters → cell round-trip reproduces lengths, angles, and volume, but not the original orientation. ``unwrap`` returns the original raw object. .. py:property:: basis :type: httk.core.SurdVector .. py:property:: scale :type: httk.core.SurdScalar .. py:property:: unscaled_basis :type: httk.core.SurdVector .. py:property:: params :type: tuple[fractions.Fraction, Ellipsis] The stored ``(a, b, c, alpha, beta, gamma)`` as exact Fractions (angles in degrees). .. py:method:: unwrap() -> Any Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: CellParamsView(obj: httk.atomistic.cell_like.CellLike, **hints: Any) Bases: :py:obj:`httk.atomistic.cell_view.CellView`, :py:obj:`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. .. py:property:: a :type: float The length of the first cell vector. .. py:property:: b :type: float The length of the second cell vector. .. py:property:: c :type: float The length of the third cell vector. .. py:property:: alpha :type: float The angle between the second and third cell vectors, in degrees. .. py:property:: beta :type: float The angle between the first and third cell vectors, in degrees. .. py:property:: gamma :type: float The angle between the first and second cell vectors, in degrees. .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: CellPrimitive(obj: Any, **hints: Any) Bases: :py:obj:`httk.atomistic.cell_backend.CellBackend` Backend for a cell backed by a raw 3x3 list or tuple of numbers (or any 3x3 vector-like). The native representation is preserved verbatim (one cell vector per row); the exact :class:`~httk.core.SurdVector` ``basis`` is built lazily and cached. This representation carries no separate length factor, so ``scale`` is the exact ``1`` and ``unscaled_basis == basis``. ``unwrap`` returns the original raw object. .. py:property:: basis :type: httk.core.SurdVector .. py:property:: scale :type: httk.core.SurdScalar .. py:property:: unscaled_basis :type: httk.core.SurdVector .. py:method:: unwrap() -> Any Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: CellPrimitiveView(obj: httk.atomistic.cell_like.CellLike, **hints: Any) Bases: :py:obj:`httk.atomistic.cell_view.CellView`, :py:obj:`tuple` A view presenting an underlying cell backend as the raw 3x3 basis matrix of floats. This view is a genuine tuple of three cell-vector rows (the scaled lattice vectors rendered to floats from the exact ``basis``), built eagerly and immutable. .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: CellView Bases: :py:obj:`httk.core.View`\ [\ :py:obj:`httk.atomistic.cell_backend.CellBackend`\ ] Abstract base class for all views of cell data. .. py:data:: SYMBOLS :type: tuple[str, Ellipsis] :value: ('H', 'He', 'Li', 'Be', 'B', 'C', 'N', 'O', 'F', 'Ne', 'Na', 'Mg', 'Al', 'Si', 'P', 'S', 'Cl',... The 118 IUPAC element symbols in atomic-number order (``SYMBOLS[0]`` is hydrogen). .. py:function:: 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). .. py:function:: 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. .. py:class:: NumericCell(cell: httk.atomistic.cell_like.CellLike) A plain-numpy presentation of a :class:`~httk.atomistic.Cell`. Where a ``Cell`` holds its geometry **exactly** (a :class:`~httk.core.SurdVector` basis, exact ``SurdScalar`` lengths/volume, exact ``Fraction`` angles), a ``NumericCell`` mirrors that interface but returns plain numpy numbers — a ``float64`` :class:`numpy.ndarray` for every vector and a plain :class:`float` for every scalar — for callers who do not need exact arithmetic and just want numpy arrays. The presentation is numpy-backed, so constructing a ``NumericCell`` **requires numpy** (the ``httk-atomistic[numpy]`` extra) and raises :class:`ImportError` eagerly when it is unavailable. The exact object is always one hop away via :attr:`exact`. .. py:property:: scale :type: float The overall length factor as a plain ``float``. .. py:property:: unscaled_basis :type: httk.core.NumericVector The 3x3 cell vectors before applying ``scale`` as a ``float64`` numpy array. .. py:property:: basis :type: httk.core.NumericVector The 3x3 lattice vectors ``scale * unscaled_basis`` as a ``float64`` numpy array. .. py:property:: lengths :type: httk.core.NumericVector The three cell-vector lengths as a ``(3,)`` ``float64`` numpy array. .. py:property:: angles :type: httk.core.NumericVector The cell angles ``(alpha, beta, gamma)`` in degrees as a ``(3,)`` ``float64`` numpy array. .. py:property:: volume :type: float The cell volume as a plain ``float``. .. py:method:: metric() -> httk.core.NumericVector The Gram matrix ``basis * basis^T`` as a ``float64`` numpy array. .. py:property:: exact :type: httk.atomistic.cell.Cell The exact :class:`~httk.atomistic.Cell` this presentation wraps. .. py:class:: NumericSites(sites: httk.atomistic.sites_like.SitesLike) A plain-numpy presentation of a :class:`~httk.atomistic.Sites` object. Where a ``Sites`` holds its reduced coordinates exactly (an Nx3 rational :class:`~httk.core.FracVector`), a ``NumericSites`` mirrors that interface but returns plain ``float64`` numpy arrays, for callers who do not need exact arithmetic and just want numpy arrays. It is len/iter/indexable over its rows, each yielded as a ``(3,)`` numpy array. The presentation is numpy-backed, so constructing a ``NumericSites`` **requires numpy** (the ``httk-atomistic[numpy]`` extra) and raises :class:`ImportError` eagerly when it is unavailable. The exact object is always one hop away via :attr:`exact`. .. py:property:: reduced_coords :type: httk.core.NumericVector The Nx3 reduced site coordinates as a ``float64`` numpy array. .. py:property:: exact :type: httk.atomistic.sites.Sites The exact :class:`~httk.atomistic.Sites` this presentation wraps. .. py:class:: NumericStructure(structure: httk.atomistic.structure_like.StructureLike) A plain-numpy presentation of a :class:`~httk.atomistic.Structure`. Where a ``Structure`` holds its geometry exactly (a surd ``cell`` basis, rational reduced coordinates, an exact Cartesian frame), a ``NumericStructure`` mirrors that interface but returns plain numpy numbers: its :attr:`cell` is a :class:`~httk.atomistic.NumericCell`, its :attr:`sites` a :class:`~httk.atomistic.NumericSites`, and :meth:`cartesian_sites` a ``float64`` numpy array. The ``species``/``species_at_sites`` are passed through unchanged (they are already plain data). It is for callers who do not need exact arithmetic and just want numpy arrays. The presentation is numpy-backed, so constructing a ``NumericStructure`` **requires numpy** (the ``httk-atomistic[numpy]`` extra) and raises :class:`ImportError` eagerly when it is unavailable. The exact object is always one hop away via :attr:`exact`. .. py:property:: cell :type: httk.atomistic.numeric_cell.NumericCell The cell as a :class:`~httk.atomistic.NumericCell`. .. py:property:: sites :type: httk.atomistic.numeric_sites.NumericSites The sites as a :class:`~httk.atomistic.NumericSites`. .. py:property:: species :type: tuple[httk.atomistic.species.Species, Ellipsis] The distinct species, passed through unchanged. .. py:property:: species_at_sites :type: tuple[str, Ellipsis] The species name occupying each site, passed through unchanged. .. py:method:: cartesian_sites() -> httk.core.NumericVector The Cartesian site positions as an ``(N, 3)`` ``float64`` numpy array. .. py:property:: exact :type: httk.atomistic.structure.Structure The exact :class:`~httk.atomistic.Structure` this presentation wraps. .. py:class:: Sites(reduced_coords: httk.core.VectorLike) The sites of a crystal structure: the Nx3 matrix of reduced coordinates, held **exactly**. Reduced (fractional) coordinates are the symmetry-native frame: point-group operations are integer matrices and translations are rationals, so no radicals ever appear. They are therefore stored as an exact rational :class:`~httk.core.FracVector` of shape ``(N, 3)``. A Sites object is iterable and indexable over its length-3 coordinate rows (each a ``FracVector``), with ``len`` giving the number of sites. Inputs embed exactly: rationals (and rational-valued floats), rational strings, and numpy arrays all land on their exact rational value. An irrational :class:`~httk.core.SurdVector` input is reduced deterministically through the vector family's ``fractions`` hub (never raising on data); the exact Cartesian frame — where radicals belong — is obtained instead via :meth:`~httk.atomistic.Structure.cartesian_sites`. .. py:property:: reduced_coords :type: httk.core.FracVector The Nx3 reduced site coordinates as an exact ``FracVector`` (one site per row). .. py:method:: numeric() -> httk.atomistic.numeric_sites.NumericSites A plain-numpy presentation of these sites (requires the ``httk-atomistic[numpy]`` extra). .. py:class:: SitesAPI Bases: :py:obj:`abc.ABC` Abstract base class for the canonical sites interface. It declares the single ``reduced_coords`` accessor (the exact Nx3 rational :class:`~httk.core.FracVector` of 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. .. py:property:: reduced_coords :type: httk.core.FracVector :abstractmethod: .. py:class:: SitesBackend(backend, **hints) Bases: :py:obj:`httk.core.Backend`\ [\ :py:obj:`SitesBackend`\ ], :py:obj:`httk.atomistic.sites_api.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. .. py:attribute:: backend_classes :type: ClassVar[list[type[httk.core.Backend[Any]]]] .. py:class:: SitesClass(obj: httk.atomistic.sites.Sites, **hints: Any) Bases: :py:obj:`httk.atomistic.sites_backend.SitesBackend` Backend for sites backed by an actual ``Sites`` object. Its ``reduced_coords`` accessor delegates to the wrapped Sites, and ``unwrap`` returns that Sites. .. py:property:: reduced_coords :type: httk.core.FracVector .. py:method:: unwrap() -> Any Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: SitesClassView(obj: httk.atomistic.sites_like.SitesLike, **hints: Any) Bases: :py:obj:`httk.atomistic.sites_view.SitesView`, :py:obj:`httk.atomistic.sites.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. .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:type:: SitesLike :canonical: sites_backend.SitesBackend | sites_view.SitesView | sites.Sites | httk.core.VectorLike .. py:class:: SitesNumericView(obj: httk.atomistic.sites_like.SitesLike, **hints: Any) Bases: :py:obj:`httk.atomistic.sites_view.SitesView`, :py:obj:`httk.atomistic.numeric_sites.NumericSites` A view presenting an underlying sites backend as a ``NumericSites`` object. This view is a genuine ``NumericSites``, so it can be passed anywhere one is accepted. Its exact ``Sites`` is built eagerly from the backend on construction. Like a ``NumericSites`` it requires numpy (raising :class:`ImportError` otherwise). .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: SitesPrimitive(obj: Any, **hints: Any) Bases: :py:obj:`httk.atomistic.sites_backend.SitesBackend` Backend for sites backed by a raw Nx3 list or tuple of numbers (or any Nx3 vector-like). The native representation is preserved verbatim (one site per row); the exact rational :class:`~httk.core.FracVector` ``reduced_coords`` are built lazily and cached, and ``unwrap`` returns the original raw object. .. py:property:: reduced_coords :type: httk.core.FracVector .. py:method:: unwrap() -> Any Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: SitesPrimitiveView(obj: httk.atomistic.sites_like.SitesLike, **hints: Any) Bases: :py:obj:`httk.atomistic.sites_view.SitesView`, :py:obj:`tuple` A view presenting an underlying sites backend as a raw Nx3 matrix of floats. This view is a genuine tuple of reduced-coordinate rows (rendered to floats from the exact ``reduced_coords``), built eagerly and immutable. .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: SitesView Bases: :py:obj:`httk.core.View`\ [\ :py:obj:`httk.atomistic.sites_backend.SitesBackend`\ ] Abstract base class for all views of sites data. .. py: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. .. py:attribute:: name :type: str .. py:attribute:: chemical_symbols :type: tuple[str, Ellipsis] .. py:attribute:: concentration :type: tuple[float, Ellipsis] .. py:attribute:: mass :type: tuple[float, Ellipsis] | None :value: None .. py:attribute:: original_name :type: str | None :value: None .. py:attribute:: attached :type: tuple[str, Ellipsis] | None :value: None .. py:attribute:: nattached :type: tuple[int, Ellipsis] | None :value: None .. py:property:: is_single_element :type: 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. .. py:method:: create(obj: Species | dict[str, Any]) -> Species :classmethod: Return a Species from either an existing Species (returned unchanged) or an OPTIMADE species dict. .. py:class:: SpeciesAPI Bases: :py:obj:`abc.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``. .. py:property:: name :type: str :abstractmethod: .. py:property:: chemical_symbols :type: tuple[str, Ellipsis] :abstractmethod: .. py:property:: concentration :type: tuple[float, Ellipsis] :abstractmethod: .. py:property:: mass :type: tuple[float, Ellipsis] | None :abstractmethod: .. py:property:: attached :type: tuple[str, Ellipsis] | None :abstractmethod: .. py:property:: nattached :type: tuple[int, Ellipsis] | None :abstractmethod: .. py:property:: original_name :type: str | None :abstractmethod: .. py:class:: SpeciesBackend(backend, **hints) Bases: :py:obj:`httk.core.Backend`\ [\ :py:obj:`SpeciesBackend`\ ], :py:obj:`httk.atomistic.species_api.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. .. py:attribute:: backend_classes :type: ClassVar[list[type[httk.core.Backend[Any]]]] .. py:class:: SpeciesClass(obj: httk.atomistic.species.Species, **hints: Any) Bases: :py:obj:`httk.atomistic.species_backend.SpeciesBackend` Backend for a species backed by an actual ``Species`` object. Its accessors delegate to the wrapped Species, and ``unwrap`` returns that Species. .. py:property:: name :type: str .. py:property:: chemical_symbols :type: tuple[str, Ellipsis] .. py:property:: concentration :type: tuple[float, Ellipsis] .. py:property:: mass :type: tuple[float, Ellipsis] | None .. py:property:: attached :type: tuple[str, Ellipsis] | None .. py:property:: nattached :type: tuple[int, Ellipsis] | None .. py:property:: original_name :type: str | None .. py:method:: unwrap() -> Any Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: SpeciesClassView(obj: httk.atomistic.species_like.SpeciesLike, **hints: Any) Bases: :py:obj:`httk.atomistic.species_view.SpeciesView`, :py:obj:`httk.atomistic.species.Species` A view presenting an underlying species backend as a ``Species``. This view is a genuine frozen ``Species``, so it can be passed anywhere a Species is accepted. Its fields are built eagerly from the backend on construction, with full ``Species`` validation applied at that point. .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:type:: SpeciesLike :canonical: species_backend.SpeciesBackend | species_view.SpeciesView | species.Species | dict[str, Any] .. py:class:: SpeciesPrimitive(obj: dict[str, Any], **hints: Any) Bases: :py:obj:`httk.atomistic.species_backend.SpeciesBackend` Backend for a species backed by an OPTIMADE species dict. The native representation is a mapping with the OPTIMADE ``species`` fields; the required ``name``/``chemical_symbols``/``concentration`` are validated conservatively on construction. The accessors read the corresponding fields (optional fields absent from the dict read as ``None``), and ``unwrap`` returns the original dict. .. py:property:: name :type: str .. py:property:: chemical_symbols :type: tuple[str, Ellipsis] .. py:property:: concentration :type: tuple[float, Ellipsis] .. py:property:: mass :type: tuple[float, Ellipsis] | None .. py:property:: attached :type: tuple[str, Ellipsis] | None .. py:property:: nattached :type: tuple[int, Ellipsis] | None .. py:property:: original_name :type: str | None .. py:method:: unwrap() -> Any Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: SpeciesPrimitiveView(obj: httk.atomistic.species_like.SpeciesLike, **hints: Any) Bases: :py:obj:`httk.atomistic.species_view.SpeciesView`, :py:obj:`dict` A view presenting an underlying species backend as an OPTIMADE species dict. This view is a genuine ``dict`` carrying the OPTIMADE ``species`` fields (optional fields that are ``None`` are omitted; list-valued fields are plain lists). Unlike the immutable-subclass views, a dict is mutable, so this view is a detached copy: mutating it does not affect the underlying backend. .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: SpeciesView Bases: :py:obj:`httk.core.View`\ [\ :py:obj:`httk.atomistic.species_backend.SpeciesBackend`\ ] Abstract base class for all views of single-species data. .. py:class:: Structure(cell: httk.atomistic.cell_like.CellLike, sites: httk.atomistic.sites_like.SitesLike, species: collections.abc.Sequence[httk.atomistic.species_like.SpeciesLike], species_at_sites: collections.abc.Sequence[str]) A crystal structure in the Simple representation. A Structure holds a ``cell`` (a ``Cell`` of 3x3 cell vectors), ``sites`` (a ``Sites`` of Nx3 reduced coordinates), a list of ``species`` (each a ``Species``), and a length-N ``species_at_sites`` giving the species name occupying each site. Inputs are normalized on construction through the component families: the cell, sites, and each species are passed through their ``*Like`` unions, and every ``species_at_sites`` name must match one of the (uniquely named) species. The numeric model is exact and split by purpose. The fractional frame — reduced coordinates and symmetry — is rational and lives in ``sites`` as a :class:`~httk.core.FracVector`. The Cartesian frame — where radicals such as the hexagonal ``sqrt(3)`` appear — is exact in the squarefree-radical field: ``cell.basis`` is a :class:`~httk.core.SurdVector` and :meth:`cartesian_sites` returns the exact Cartesian positions. Pure magnitudes (bond-length comparisons) stay rational-exact via ``cell.metric()``. Floats appear only at the presentation and JSON boundaries. .. py:property:: cell :type: httk.atomistic.cell.Cell The cell (3x3 cell vectors) as a ``Cell``. .. py:property:: sites :type: httk.atomistic.sites.Sites The site coordinates (Nx3 reduced coordinates) as a ``Sites``. .. py:property:: species :type: tuple[httk.atomistic.species.Species, Ellipsis] The distinct species of this structure. .. py:property:: species_at_sites :type: tuple[str, Ellipsis] The species name occupying each site, in site order. .. py:method:: cartesian_sites() -> httk.core.SurdVector The exact Cartesian site positions as an ``(N, 3)`` :class:`~httk.core.SurdVector`. Under the row-vector convention this is ``reduced_coords * cell.basis`` (each Cartesian position is the sum over lattice vectors ``sum_k reduced[k] * basis[k]``). The reduced coordinates are rational (a ``FracVector``), the cell basis carries the radicals (a ``SurdVector``), so the product is exact in the surd field — the hexagonal ``sqrt(3)`` survives into the Cartesian positions. .. py:method:: numeric() -> httk.atomistic.numeric_structure.NumericStructure A plain-numpy presentation of this structure (requires the ``httk-atomistic[numpy]`` extra). .. py:class:: StructureAPI Bases: :py:obj:`abc.ABC` Abstract base class for the canonical structure interface. It declares the Simple quartet that every structure backend produces from its own native representation and every structure view builds its presentation from: ``cell``, ``sites``, ``species``, and ``species_at_sites``. This is the single interchange format; there is no pairwise conversion between backends. .. py:property:: cell :type: httk.atomistic.cell.Cell :abstractmethod: .. py:property:: sites :type: httk.atomistic.sites.Sites :abstractmethod: .. py:property:: species :type: tuple[httk.atomistic.species.Species, Ellipsis] :abstractmethod: .. py:property:: species_at_sites :type: tuple[str, Ellipsis] :abstractmethod: .. py:class:: StructureBackend(backend, **hints) Bases: :py:obj:`httk.core.Backend`\ [\ :py:obj:`StructureBackend`\ ], :py:obj:`httk.atomistic.structure_api.StructureAPI` Abstract base class for all backends of crystal structure data. Concrete backends carry a native representation and produce the canonical Simple quartet declared by ``StructureAPI`` from it. .. py:attribute:: backend_classes :type: ClassVar[list[type[httk.core.Backend[Any]]]] .. py:class:: StructureEntryProvider(entries: collections.abc.Mapping[str, httk.atomistic.structure_like.StructureLike | None], *, extra_definitions: collections.abc.Mapping[str, httk.core.PropertyDefinition] | None = None, properties: collections.abc.Mapping[str, collections.abc.Mapping[str, Any]] | None = None) Bases: :py:obj:`httk.core.EntryProvider` Serves OPTIMADE ``structures`` from a mapping of id to structure. ``entries`` maps each entry id to a :class:`~httk.atomistic.Structure` (or any structure exposing the ``cell``/``sites``/``species``/ ``species_at_sites`` quartet, or a ``(cell, sites, species, species_at_sites)`` tuple), or to ``None`` for a known entry that has no structure (its structural columns then serve null). The always-served structural fields are ``id``, ``type``, ``nsites``, ``elements``, ``nelements``, ``species`` (as OPTIMADE species dicts), ``species_at_sites``, ``lattice_vectors`` (the cell basis rows), ``cartesian_site_positions`` (reduced coordinates times the cell basis), and ``structure_features`` (``disorder`` when any species mixes several chemical symbols; ``site_attachments`` when any species has attached atoms). The standard composition fields ``nperiodic_dimensions``, ``dimension_types``, ``elements_ratios``, ``chemical_formula_reduced`` / ``_anonymous`` / ``_descriptive`` are auto-derived for a fully ordered structure (every species a single, unattached element), else served as null. ``extra_definitions`` extends the served entry-type definition with custom database-specific properties (each carrying a registered prefix), and ``properties`` supplies their per-entry values as ``{entry_id: {name: value}}``; every property named there MUST be described by the (extended) definition (a :class:`ValueError` at construction names any offender), and a value absent for an entry is served as null. .. py:method:: entry_types() -> collections.abc.Mapping[str, httk.core.EntryTypeDefinition] .. py:method:: columns(entry_type: str) -> collections.abc.Mapping[str, str] .. py:method:: records(entry_type: str) -> collections.abc.Iterable[collections.abc.Mapping[str, Any]] .. py:type:: StructureLike :canonical: structure_backend.StructureBackend | structure_view.StructureView | structure.Structure | tuple[httk.core.VectorLike, httk.core.VectorLike, Any] | list[Any] .. py:class:: StructureNumericView(obj: httk.atomistic.structure_like.StructureLike, **hints: Any) Bases: :py:obj:`httk.atomistic.structure_view.StructureView`, :py:obj:`httk.atomistic.numeric_structure.NumericStructure` A view presenting an underlying structure backend as a ``NumericStructure``. This view is a genuine ``NumericStructure``, so it can be passed anywhere one is accepted. Its exact ``Structure`` is built eagerly from the backend's quartet on construction. Like a ``NumericStructure`` it requires numpy (raising :class:`ImportError` otherwise). .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: StructurePrimitive(obj: Any, **hints: Any) Bases: :py:obj:`httk.atomistic.structure_backend.StructureBackend` Backend for a crystal structure backed by an spglib-like triple. The native representation is a length-3 ``(lattice, positions, numbers)`` list or tuple, where ``lattice`` is 3x3, ``positions`` is Nx3 reduced coordinates, and ``numbers`` is the length-N sequence of atomic numbers. The quartet is derived lazily and cached: ``cell`` is a ``Cell``, ``sites`` a ``Sites``, ``species`` one single-element ``Species`` per distinct atomic number, and ``unwrap`` returns the original triple. .. py:property:: cell :type: httk.atomistic.cell.Cell .. py:property:: sites :type: httk.atomistic.sites.Sites .. py:property:: species :type: tuple[httk.atomistic.species.Species, Ellipsis] .. py:property:: species_at_sites :type: tuple[str, Ellipsis] .. py:method:: unwrap() -> Any Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: StructurePrimitiveView(obj: httk.atomistic.structure_like.StructureLike, **hints: Any) Bases: :py:obj:`httk.atomistic.structure_view.StructureView`, :py:obj:`tuple` A view presenting an underlying structure backend as a primitive triple. This view is a genuine ``(lattice, positions, numbers)`` tuple, built eagerly and immutable. Because the primitive representation carries only bare atomic numbers, every site's species must be a single, unattached chemical element (see ``Species.is_single_element``); otherwise a TypeError is raised. .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: StructureSimple(obj: httk.atomistic.structure.Structure, **hints: Any) Bases: :py:obj:`httk.atomistic.structure_backend.StructureBackend` Backend for a crystal structure backed by an actual ``Structure`` object. Its quartet accessors delegate to the wrapped Structure, and ``unwrap`` returns that Structure. .. py:property:: cell :type: httk.atomistic.cell.Cell .. py:property:: sites :type: httk.atomistic.sites.Sites .. py:property:: species :type: tuple[httk.atomistic.species.Species, Ellipsis] .. py:property:: species_at_sites :type: tuple[str, Ellipsis] .. py:method:: unwrap() -> Any Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: StructureSimpleView(obj: httk.atomistic.structure_like.StructureLike, **hints: Any) Bases: :py:obj:`httk.atomistic.structure_view.StructureView`, :py:obj:`httk.atomistic.structure.Structure` A view presenting an underlying structure backend as a ``Structure``. This view is a genuine ``Structure``, so it can be passed anywhere a Structure is accepted. Its quartet is built eagerly from the backend on construction. .. py:method:: unwrap() -> Any Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a Like type, that representation will be returned. If this is not possible, the instance itself is returned. .. py:class:: StructureView Bases: :py:obj:`httk.core.View`\ [\ :py:obj:`httk.atomistic.structure_backend.StructureBackend`\ ] Abstract base class for all views of crystal structure data. .. py:function:: load_structure(path: str) -> httk.atomistic.structure.Structure Load a file and build a :class:`~httk.atomistic.Structure` from it. ``httk.core.load(path)`` selects the reader by file type (transparently decompressing ``.bz2`` / ``.gz`` files); the payload's ``"format"`` tag then selects the matching structure builder. A payload without a recognized ``"format"`` tag (for example a CIF, which returns a different shape) raises a clear :class:`ValueError`. .. py:function:: structure_from_poscar(data: collections.abc.Mapping[str, Any]) -> httk.atomistic.structure.Structure Build an exact :class:`~httk.atomistic.Structure` from a neutral POSCAR mapping. ``data`` is the mapping returned by ``httk.io.read_poscar`` (its ``format`` must be ``"vasp-poscar"``). The cell basis is taken exactly from the file's string rows. For a positive universal scaling factor the ``scale`` string is used directly as the cell's exact scale; for a negative scaling factor (a target **volume** ``V``) the scale is the cube root of ``V / |det(basis)|`` — a value outside the exact surd field, so it is a deterministic rational approximation (the basis rows themselves stay exact). Direct coordinates become reduced coordinates directly (exact strings). Cartesian coordinates are converted exactly as ``cart * basis.inv()`` under the row-vector convention; because VASP scales *both* the lattice vectors and the Cartesian positions by the universal scaling factor, that factor cancels and the reduced coordinates are exact regardless of the scale/volume case. Species come from the VASP-5 species line (one single-element, unattached :class:`~httk.atomistic.Species` of concentration 1.0 per distinct symbol); a VASP-4 file (no species symbols) raises a :class:`ValueError`. Selective dynamics flags, if present, are ignored.