httk.atomistic¶

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¶

Attributes¶

`CellLike`
`SYMBOLS`	The 118 IUPAC element symbols in atomic-number order (`SYMBOLS[0]` is hydrogen).
`SitesLike`
`SpeciesLike`
`StructureLike`

Classes¶

`Cell`	A crystallographic cell: its basis, the 3x3 matrix of cell vectors, held exactly.
`CellAPI`	Abstract base class for the canonical cell interface.
`CellBackend`	Abstract base class for all backends of cell data.
`CellClass`	Backend for a cell backed by an actual `Cell` object.
`CellClassView`	A view presenting an underlying cell backend as a `Cell`.
`CellNumericView`	A view presenting an underlying cell backend as a `NumericCell`.
`CellParams`	Backend for a cell backed by cell parameters `(a, b, c, alpha, beta, gamma)`.
`CellParamsView`	A view presenting an underlying cell backend as cell parameters.
`CellPrimitive`	Backend for a cell backed by a raw 3x3 list or tuple of numbers (or any 3x3 vector-like).
`CellPrimitiveView`	A view presenting an underlying cell backend as the raw 3x3 basis matrix of floats.
`CellView`	Abstract base class for all views of cell data.
`NumericCell`	A plain-numpy presentation of a `Cell`.
`NumericSites`	A plain-numpy presentation of a `Sites` object.
`NumericStructure`	A plain-numpy presentation of a `Structure`.
`Sites`	The sites of a crystal structure: the Nx3 matrix of reduced coordinates, held exactly.
`SitesAPI`	Abstract base class for the canonical sites interface.
`SitesBackend`	Abstract base class for all backends of sites data.
`SitesClass`	Backend for sites backed by an actual `Sites` object.
`SitesClassView`	A view presenting an underlying sites backend as a `Sites` object.
`SitesNumericView`	A view presenting an underlying sites backend as a `NumericSites` object.
`SitesPrimitive`	Backend for sites backed by a raw Nx3 list or tuple of numbers (or any Nx3 vector-like).
`SitesPrimitiveView`	A view presenting an underlying sites backend as a raw Nx3 matrix of floats.
`SitesView`	Abstract base class for all views of sites data.
`Species`	A chemical species occupying one or more sites, mirroring the OPTIMADE `species` object.
`SpeciesAPI`	Abstract base class for the canonical single-species interface.
`SpeciesBackend`	Abstract base class for all backends of single-species data.
`SpeciesClass`	Backend for a species backed by an actual `Species` object.
`SpeciesClassView`	A view presenting an underlying species backend as a `Species`.
`SpeciesPrimitive`	Backend for a species backed by an OPTIMADE species dict.
`SpeciesPrimitiveView`	A view presenting an underlying species backend as an OPTIMADE species dict.
`SpeciesView`	Abstract base class for all views of single-species data.
`Structure`	A crystal structure in the Simple representation.
`StructureAPI`	Abstract base class for the canonical structure interface.
`StructureBackend`	Abstract base class for all backends of crystal structure data.
`StructureEntryProvider`	Serves OPTIMADE `structures` from a mapping of id to structure.
`StructureNumericView`	A view presenting an underlying structure backend as a `NumericStructure`.
`StructurePrimitive`	Backend for a crystal structure backed by an spglib-like triple.
`StructurePrimitiveView`	A view presenting an underlying structure backend as a primitive triple.
`StructureSimple`	Backend for a crystal structure backed by an actual `Structure` object.
`StructureSimpleView`	A view presenting an underlying structure backend as a `Structure`.
`StructureView`	Abstract base class for all views of crystal structure data.

Functions¶

`atomic_number`(→ int)	Return the atomic number (1-118) of an element symbol.
`symbol_of`(→ str)	Return the element symbol for the atomic number z (1-118).
`load_structure`(→ httk.atomistic.structure.Structure)	Load a file and build a `Structure` from it.
`structure_from_poscar`(→ httk.atomistic.structure.Structure)	Build an exact `Structure` from a neutral POSCAR mapping.

Package Contents¶

class httk.atomistic.Cell(basis: httk.core.VectorLike, scale: Any = 1)[source]¶

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 SurdScalar scale times an unscaled_basis (a 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 SurdVector basis keeps its radicals. Derived quantities are exact whenever the geometry is metric-rational (the crystallographic case): lengths come from sqrt_of() of the rational squared row lengths, angles (degrees) from the exact reverse-Niven 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, numeric() (true numpy arrays), or a view of your choice.

property scale: httk.core.SurdScalar¶: The overall (strictly positive) length factor, as an exact SurdScalar.

property unscaled_basis: httk.core.SurdVector¶: The 3x3 cell vectors before applying scale, as an exact SurdVector.

property basis: httk.core.SurdVector¶: The 3x3 lattice vectors scale * unscaled_basis (one vector per row), exact.

numeric() → httk.atomistic.numeric_cell.NumericCell[source]¶: A plain-numpy presentation of this cell (requires the httk-atomistic[numpy] extra).

metric() → httk.core.SurdVector[source]¶: The exact Gram matrix matrix * matrix^T (rational for a metric-rational cell).

property lengths: tuple[httk.core.SurdScalar, Ellipsis]¶

The lengths of the three cell vectors (the scaled row norms).

Exact via 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).

property angles: 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 (acos_degrees()) for an exact answer; a non-Niven angle falls back to a deterministic acos() at _FALLBACK_PREC.

property volume: httk.core.SurdScalar¶: The cell volume, the exact absolute determinant of basis.

class httk.atomistic.CellAPI[source]¶

Bases: 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.

property basis: httk.core.SurdVector¶

Abstractmethod:

property scale: httk.core.SurdScalar¶

Abstractmethod:

property unscaled_basis: httk.core.SurdVector¶

Abstractmethod:

class httk.atomistic.CellBackend(backend, **hints)[source]¶

Bases: httk.core.Backend[CellBackend], 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.

backend_classes: ClassVar[list[type[httk.core.Backend[Any]]]]¶

class httk.atomistic.CellClass(obj: httk.atomistic.cell.Cell, **hints: Any)[source]¶

Bases: 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.

property basis: httk.core.SurdVector¶

property scale: httk.core.SurdScalar¶

property unscaled_basis: httk.core.SurdVector¶

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.CellClassView(obj: httk.atomistic.cell_like.CellLike, **hints: Any)[source]¶

Bases: httk.atomistic.cell_view.CellView, 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.

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

type httk.atomistic.CellLike = cell_backend.CellBackend | cell_view.CellView | cell.Cell | httk.core.VectorLike[source]¶

class httk.atomistic.CellNumericView(obj: httk.atomistic.cell_like.CellLike, **hints: Any)[source]¶

Bases: httk.atomistic.cell_view.CellView, 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 ImportError otherwise).

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.CellParams(obj: Any, **hints: Any)[source]¶

Bases: 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 Fraction values (parsed via 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.

property basis: httk.core.SurdVector¶

property scale: httk.core.SurdScalar¶

property unscaled_basis: httk.core.SurdVector¶

property params: tuple[fractions.Fraction, Ellipsis]¶: The stored (a, b, c, alpha, beta, gamma) as exact Fractions (angles in degrees).

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.CellParamsView(obj: httk.atomistic.cell_like.CellLike, **hints: Any)[source]¶

Bases: httk.atomistic.cell_view.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.

property a: float¶: The length of the first cell vector.

property b: float¶: The length of the second cell vector.

property c: float¶: The length of the third cell vector.

property alpha: float¶: The angle between the second and third cell vectors, in degrees.

property beta: float¶: The angle between the first and third cell vectors, in degrees.

property gamma: float¶: The angle between the first and second cell vectors, in degrees.

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.CellPrimitive(obj: Any, **hints: Any)[source]¶

Bases: 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 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.

property basis: httk.core.SurdVector¶

property scale: httk.core.SurdScalar¶

property unscaled_basis: httk.core.SurdVector¶

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.CellPrimitiveView(obj: httk.atomistic.cell_like.CellLike, **hints: Any)[source]¶

Bases: httk.atomistic.cell_view.CellView, 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.

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.CellView[source]¶

Bases: httk.core.View[httk.atomistic.cell_backend.CellBackend]

Abstract base class for all views of cell data.

httk.atomistic.SYMBOLS: tuple[str, Ellipsis] = ('H', 'He', 'Li', 'Be', 'B', 'C', 'N', 'O', 'F', 'Ne', 'Na', 'Mg', 'Al', 'Si', 'P', 'S', 'Cl',...[source]¶: The 118 IUPAC element symbols in atomic-number order (SYMBOLS[0] is hydrogen).

httk.atomistic.atomic_number(symbol: str) → int[source]¶

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).

httk.atomistic.symbol_of(z: int) → str[source]¶

Return the element symbol for the atomic number z (1-118).

Raises ValueError for atomic numbers outside the 1-118 range.

class httk.atomistic.NumericCell(cell: httk.atomistic.cell_like.CellLike)[source]¶

A plain-numpy presentation of a Cell.

Where a Cell holds its geometry exactly (a SurdVector basis, exact SurdScalar lengths/volume, exact Fraction angles), a NumericCell mirrors that interface but returns plain numpy numbers — a float64 numpy.ndarray for every vector and a plain 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 ImportError eagerly when it is unavailable. The exact object is always one hop away via exact.

property scale: float¶: The overall length factor as a plain float.

property unscaled_basis: httk.core.NumericVector¶: The 3x3 cell vectors before applying scale as a float64 numpy array.

property basis: httk.core.NumericVector¶: The 3x3 lattice vectors scale * unscaled_basis as a float64 numpy array.

property lengths: httk.core.NumericVector¶: The three cell-vector lengths as a (3,) float64 numpy array.

property angles: httk.core.NumericVector¶: The cell angles (alpha, beta, gamma) in degrees as a (3,) float64 numpy array.

property volume: float¶: The cell volume as a plain float.

metric() → httk.core.NumericVector[source]¶: The Gram matrix basis * basis^T as a float64 numpy array.

property exact: httk.atomistic.cell.Cell¶: The exact Cell this presentation wraps.

class httk.atomistic.NumericSites(sites: httk.atomistic.sites_like.SitesLike)[source]¶

A plain-numpy presentation of a Sites object.

Where a Sites holds its reduced coordinates exactly (an Nx3 rational 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 ImportError eagerly when it is unavailable. The exact object is always one hop away via exact.

property reduced_coords: httk.core.NumericVector¶: The Nx3 reduced site coordinates as a float64 numpy array.

property exact: httk.atomistic.sites.Sites¶: The exact Sites this presentation wraps.

class httk.atomistic.NumericStructure(structure: httk.atomistic.structure_like.StructureLike)[source]¶

A plain-numpy presentation of a 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 cell is a NumericCell, its sites a NumericSites, and 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 ImportError eagerly when it is unavailable. The exact object is always one hop away via exact.

property cell: httk.atomistic.numeric_cell.NumericCell¶: The cell as a NumericCell.

property sites: httk.atomistic.numeric_sites.NumericSites¶: The sites as a NumericSites.

property species: tuple[httk.atomistic.species.Species, Ellipsis]¶: The distinct species, passed through unchanged.

property species_at_sites: tuple[str, Ellipsis]¶: The species name occupying each site, passed through unchanged.

cartesian_sites() → httk.core.NumericVector[source]¶: The Cartesian site positions as an (N, 3) float64 numpy array.

property exact: httk.atomistic.structure.Structure¶: The exact Structure this presentation wraps.

class httk.atomistic.Sites(reduced_coords: httk.core.VectorLike)[source]¶

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 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 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 cartesian_sites().

property reduced_coords: httk.core.FracVector¶: The Nx3 reduced site coordinates as an exact FracVector (one site per row).

numeric() → httk.atomistic.numeric_sites.NumericSites[source]¶: A plain-numpy presentation of these sites (requires the httk-atomistic[numpy] extra).

class httk.atomistic.SitesAPI[source]¶

Bases: abc.ABC

Abstract base class for the canonical sites interface.

It declares the single reduced_coords accessor (the exact Nx3 rational 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.

property reduced_coords: httk.core.FracVector¶

Abstractmethod:

class httk.atomistic.SitesBackend(backend, **hints)[source]¶

Bases: httk.core.Backend[SitesBackend], 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.

backend_classes: ClassVar[list[type[httk.core.Backend[Any]]]]¶

class httk.atomistic.SitesClass(obj: httk.atomistic.sites.Sites, **hints: Any)[source]¶

Bases: 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.

property reduced_coords: httk.core.FracVector¶

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.SitesClassView(obj: httk.atomistic.sites_like.SitesLike, **hints: Any)[source]¶

Bases: httk.atomistic.sites_view.SitesView, 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.

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

type httk.atomistic.SitesLike = sites_backend.SitesBackend | sites_view.SitesView | sites.Sites | httk.core.VectorLike[source]¶

class httk.atomistic.SitesNumericView(obj: httk.atomistic.sites_like.SitesLike, **hints: Any)[source]¶

Bases: httk.atomistic.sites_view.SitesView, 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 ImportError otherwise).

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.SitesPrimitive(obj: Any, **hints: Any)[source]¶

Bases: 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 FracVector reduced_coords are built lazily and cached, and unwrap returns the original raw object.

property reduced_coords: httk.core.FracVector¶

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.SitesPrimitiveView(obj: httk.atomistic.sites_like.SitesLike, **hints: Any)[source]¶

Bases: httk.atomistic.sites_view.SitesView, 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.

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.SitesView[source]¶

Bases: httk.core.View[httk.atomistic.sites_backend.SitesBackend]

Abstract base class for all views of sites data.

class httk.atomistic.Species[source]¶

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, Ellipsis]¶

concentration: tuple[float, Ellipsis]¶

mass: tuple[float, Ellipsis] | None = None¶

original_name: str | None = None¶

attached: tuple[str, Ellipsis] | None = None¶

nattached: tuple[int, Ellipsis] | None = None¶

property is_single_element: 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.

classmethod create(obj: Species | dict[str, Any]) → Species[source]¶: Return a Species from either an existing Species (returned unchanged) or an OPTIMADE species dict.

class httk.atomistic.SpeciesAPI[source]¶

Bases: 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.

property name: str¶

Abstractmethod:

property chemical_symbols: tuple[str, Ellipsis]¶

Abstractmethod:

property concentration: tuple[float, Ellipsis]¶

Abstractmethod:

property mass: tuple[float, Ellipsis] | None¶

Abstractmethod:

property attached: tuple[str, Ellipsis] | None¶

Abstractmethod:

property nattached: tuple[int, Ellipsis] | None¶

Abstractmethod:

property original_name: str | None¶

Abstractmethod:

class httk.atomistic.SpeciesBackend(backend, **hints)[source]¶

Bases: httk.core.Backend[SpeciesBackend], 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.

backend_classes: ClassVar[list[type[httk.core.Backend[Any]]]]¶

class httk.atomistic.SpeciesClass(obj: httk.atomistic.species.Species, **hints: Any)[source]¶

Bases: 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.

property name: str¶

property chemical_symbols: tuple[str, Ellipsis]¶

property concentration: tuple[float, Ellipsis]¶

property mass: tuple[float, Ellipsis] | None¶

property attached: tuple[str, Ellipsis] | None¶

property nattached: tuple[int, Ellipsis] | None¶

property original_name: str | None¶

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.SpeciesClassView(obj: httk.atomistic.species_like.SpeciesLike, **hints: Any)[source]¶

Bases: httk.atomistic.species_view.SpeciesView, 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.

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

type httk.atomistic.SpeciesLike = species_backend.SpeciesBackend | species_view.SpeciesView | species.Species | dict[str, Any][source]¶

class httk.atomistic.SpeciesPrimitive(obj: dict[str, Any], **hints: Any)[source]¶

Bases: 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.

property name: str¶

property chemical_symbols: tuple[str, Ellipsis]¶

property concentration: tuple[float, Ellipsis]¶

property mass: tuple[float, Ellipsis] | None¶

property attached: tuple[str, Ellipsis] | None¶

property nattached: tuple[int, Ellipsis] | None¶

property original_name: str | None¶

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.SpeciesPrimitiveView(obj: httk.atomistic.species_like.SpeciesLike, **hints: Any)[source]¶

Bases: httk.atomistic.species_view.SpeciesView, 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.

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.SpeciesView[source]¶

Bases: httk.core.View[httk.atomistic.species_backend.SpeciesBackend]

Abstract base class for all views of single-species data.

class httk.atomistic.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])[source]¶

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 FracVector. The Cartesian frame — where radicals such as the hexagonal sqrt(3) appear — is exact in the squarefree-radical field: cell.basis is a SurdVector and 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.

property cell: httk.atomistic.cell.Cell¶: The cell (3x3 cell vectors) as a Cell.

property sites: httk.atomistic.sites.Sites¶: The site coordinates (Nx3 reduced coordinates) as a Sites.

property species: tuple[httk.atomistic.species.Species, Ellipsis]¶: The distinct species of this structure.

property species_at_sites: tuple[str, Ellipsis]¶: The species name occupying each site, in site order.

cartesian_sites() → httk.core.SurdVector[source]¶

The exact Cartesian site positions as an (N, 3) 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.

numeric() → httk.atomistic.numeric_structure.NumericStructure[source]¶: A plain-numpy presentation of this structure (requires the httk-atomistic[numpy] extra).

class httk.atomistic.StructureAPI[source]¶

Bases: 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.

property cell: httk.atomistic.cell.Cell¶

Abstractmethod:

property sites: httk.atomistic.sites.Sites¶

Abstractmethod:

property species: tuple[httk.atomistic.species.Species, Ellipsis]¶

Abstractmethod:

property species_at_sites: tuple[str, Ellipsis]¶

Abstractmethod:

class httk.atomistic.StructureBackend(backend, **hints)[source]¶

Bases: httk.core.Backend[StructureBackend], 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.

backend_classes: ClassVar[list[type[httk.core.Backend[Any]]]]¶

class httk.atomistic.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)[source]¶

Bases: httk.core.EntryProvider

Serves OPTIMADE structures from a mapping of id to structure.

entries maps each entry id to a 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 ValueError at construction names any offender), and a value absent for an entry is served as null.

entry_types() → collections.abc.Mapping[str, httk.core.EntryTypeDefinition][source]¶

columns(entry_type: str) → collections.abc.Mapping[str, str][source]¶

records(entry_type: str) → collections.abc.Iterable[collections.abc.Mapping[str, Any]][source]¶

type httk.atomistic.StructureLike = structure_backend.StructureBackend | structure_view.StructureView | structure.Structure | tuple[httk.core.VectorLike, httk.core.VectorLike, Any] | list[Any][source]¶

class httk.atomistic.StructureNumericView(obj: httk.atomistic.structure_like.StructureLike, **hints: Any)[source]¶

Bases: httk.atomistic.structure_view.StructureView, 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 ImportError otherwise).

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.StructurePrimitive(obj: Any, **hints: Any)[source]¶

Bases: 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.

property cell: httk.atomistic.cell.Cell¶

property sites: httk.atomistic.sites.Sites¶

property species: tuple[httk.atomistic.species.Species, Ellipsis]¶

property species_at_sites: tuple[str, Ellipsis]¶

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.StructurePrimitiveView(obj: httk.atomistic.structure_like.StructureLike, **hints: Any)[source]¶

Bases: httk.atomistic.structure_view.StructureView, 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.

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.StructureSimple(obj: httk.atomistic.structure.Structure, **hints: Any)[source]¶

Bases: 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.

property cell: httk.atomistic.cell.Cell¶

property sites: httk.atomistic.sites.Sites¶

property species: tuple[httk.atomistic.species.Species, Ellipsis]¶

property species_at_sites: tuple[str, Ellipsis]¶

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.StructureSimpleView(obj: httk.atomistic.structure_like.StructureLike, **hints: Any)[source]¶

Bases: httk.atomistic.structure_view.StructureView, 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.

unwrap() → Any[source]¶: 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 <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.atomistic.StructureView[source]¶

Bases: httk.core.View[httk.atomistic.structure_backend.StructureBackend]

Abstract base class for all views of crystal structure data.

httk.atomistic.load_structure(path: str) → httk.atomistic.structure.Structure[source]¶

Load a file and build a 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 ValueError.

httk.atomistic.structure_from_poscar(data: collections.abc.Mapping[str, Any]) → httk.atomistic.structure.Structure[source]¶

Build an exact 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 Species of concentration 1.0 per distinct symbol); a VASP-4 file (no species symbols) raises a ValueError. Selective dynamics flags, if present, are ignored.