httk.atomistic.models.cell¶

Submodules¶

Attributes¶

CellLike

Classes¶

`CellAPI`	Abstract base class for the canonical cell interface.
`CellBackend`	Abstract base class for all backends of cell data.
`Cell`	A crystallographic cell: its basis, the 3x3 matrix of cell vectors, held exactly.
`NumericCell`	A plain-numpy presentation of 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.
`PlainCell`	Backend for a cell backed by a raw 3x3 list or tuple of numbers (or any 3x3 vector-like).
`PlainCellView`	A view presenting an underlying cell backend as the raw 3x3 basis matrix of floats.
`CellView`	A view presenting an underlying cell backend as a `Cell`.
`CellViewBase`	Abstract base class for all views of cell data.

Package Contents¶

class httk.atomistic.models.cell.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:

Return the scaled lattice vectors.

property scale: httk.core.SurdScalar¶

Abstractmethod:

Return the positive factor applied to unscaled_basis.

property unscaled_basis: httk.core.SurdVector¶

Abstractmethod:

Return the lattice vectors before applying scale.

property precision: fractions.Fraction | None¶

How precisely the basis was stated, as an absolute length, or None if unknown.

A backend that knows its source’s precision overrides this; one that does not — a bare matrix of numbers with no provenance — inherits None.

Returns:: The absolute basis precision, or None when it is unknown.
Return type:: fractions.Fraction | None

property periodicity: tuple[bool, bool, bool]¶

Which of the three basis rows is a genuine lattice translation.

A backend that knows its periodicity overrides this; one that does not inherit (True, True, True). A cell described only by six lattice parameters or a bare matrix is interpreted as a fully periodic crystal.

Returns:: Flags identifying the periodic basis rows.
Return type:: tuple[bool, bool, bool]

metric()[source]¶

Return the exact Gram matrix of the scaled basis.

Returns:: The Gram matrix of the cell vectors.
Return type:: httk.core.SurdVector

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

Return exact lengths where representable, with a deterministic rational fallback otherwise.

Returns:: The three cell-vector lengths.
Return type:: tuple[httk.core.SurdScalar, Ellipsis]

property angles: tuple[fractions.Fraction, Ellipsis]¶

Return (alpha, beta, gamma) exactly where representable, with a deterministic rational fallback otherwise.

Returns:: The crystallographic angles in degrees.
Return type:: tuple[fractions.Fraction, Ellipsis]

property volume: httk.core.SurdScalar¶

Return the exact absolute determinant of the basis.

Returns:: The cell volume.
Raises:: ValueError – If the cell is not periodic in all three directions.
Return type:: httk.core.SurdScalar

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

Bases: httk.core.Backend[CellBackend], httk.atomistic.models.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.models.cell.Cell(basis, scale=1, precision=None, periodicity=None)[source]¶

Bases: httk.atomistic.models.cell.backend.CellBackend

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 retain exact forms where the underlying operation stays in the supported exact fields, including the usual metric-rational crystallographic case: lengths use sqrt_of() for rational squared row lengths when the rational radicand is a perfect square or stays below the deterministic small-radicand threshold, angles (degrees) use the exact reverse-Niven acos_degrees() where possible, volume comes from the exact determinant, and metric is the exact Gram matrix, which may itself contain surds. For larger rational or irrational squared lengths, 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.

A cell also records its periodicity, which defaults to periodic in all three directions. Where it is not, the basis stops being purely a lattice and becomes partly a coordinate frame: see periodicity for what that means and periodic_measure for the quantity that replaces volume.

Parameters:

basis (httk.core.VectorLike) – The three cell vectors, one per row.
scale (Any) – The positive factor separated from basis.
precision (Any) – The absolute precision carried from the source, if known.
periodicity (Any) – Flags identifying which basis rows are lattice translations.

property scale: httk.core.SurdScalar¶

The overall (strictly positive) length factor.

Returns:: The factor applied to unscaled_basis.
Return type:: httk.core.SurdScalar

property unscaled_basis: httk.core.SurdVector¶

The 3x3 cell vectors before applying scale.

Returns:: The unscaled lattice vectors.
Return type:: httk.core.SurdVector

property basis: httk.core.SurdVector¶

The 3x3 lattice vectors scale * unscaled_basis.

Returns:: The scaled lattice vectors.
Return type:: httk.core.SurdVector

property precision: fractions.Fraction | None¶

How precisely this basis was stated, as an absolute length, or None if unknown.

In the same units as the basis itself, so for ordinary crystallographic data it is an ångström. Derived from the source’s written digits and any stated uncertainty — a CIF cell edge of 5.6402(3) is precise to 3e-4, not to the 1e-4 its four decimals alone would suggest.

None means unknown, which is not the same as exact. It is what a cell built by hand or from a bare matrix reports.

Returns:: The absolute precision, or None when it is unknown.
Return type:: fractions.Fraction | None

property periodicity: tuple[bool, bool, bool]¶

Which of the three basis rows is a genuine lattice translation.

(True, True, True) — the default, and what every ordinary crystal is. A slab is (True, True, False), a nanowire has one True, and an isolated molecule is (False, False, False).

A row flagged False is not a lattice vector. It is only a frame: it says what a fractional coordinate means along that direction, and nothing more. Coordinates there are unbounded — freely below 0 or above 1 — and are never wrapped into [0, 1). There is no vacuum and no padding involved, so making that row a unit vector simply means the coordinate along it is a length in the basis’s units.

This is the same notion, in the same order, as OPTIMADE’s dimension_types.

Returns:: Flags identifying the periodic basis rows.
Return type:: tuple[bool, bool, bool]

property nperiodic_dimensions: int¶

How many of the three directions are periodic.

Returns:: The number of periodic directions.
Return type:: int

numeric()[source]¶

Return a plain-numpy presentation of this cell.

Returns:: The numpy-backed presentation.
Raises:: ImportError – If numpy is unavailable.
Return type:: httk.atomistic.models.cell.numeric.NumericCell

metric()[source]¶

Return the exact, potentially surd-valued Gram matrix matrix * matrix^T.

Returns:: The Gram matrix of the cell vectors.
Return type:: httk.core.SurdVector

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

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

Exact via sqrt_of() when the row’s squared length is a perfect-square rational or a rational with numerator times denominator at most 10**18. Larger rational radicands and irrational squared lengths use a deterministic rational approximation at _FALLBACK_PREC.

Returns:: The three cell-vector lengths.
Return type:: tuple[httk.core.SurdScalar, Ellipsis]

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.

Returns:: (alpha, beta, gamma) in degrees.
Return type:: tuple[fractions.Fraction, Ellipsis]

property volume: httk.core.SurdScalar¶

The cell volume, the exact absolute determinant of basis.

Defined only for a fully periodic cell, and raises ValueError otherwise. For anything less, the determinant mixes real lattice vectors with frame vectors, so it is not a volume: it changes when a frame vector is rescaled, even though nothing about the material did. Any density or packing fraction derived from it would inherit that. See periodic_measure for the quantity that is defined.

Returns:: The absolute determinant of the basis.
Raises:: ValueError – If the cell is not periodic in all three directions.
Return type:: httk.core.SurdScalar

property periodic_measure: httk.core.SurdScalar¶

The size of the repeating unit, whatever its dimension.

A volume for a crystal, an area for a slab, a length for a nanowire. For a fully non-periodic cell there is no repeating unit and this is the empty product, 1, which is dimensionless rather than a length of any kind.

Exact in the crystallographic case. The 3D case is the determinant and needs no square root at all; the 2D and 1D cases take the same square root that lengths does, so they are exact whenever the squared measure is a rational with a small radicand and fall back to a deterministic rational approximation otherwise.

Returns:: The measure of the periodic sublattice.
Return type:: httk.core.SurdScalar

type httk.atomistic.models.cell.CellLike = httk.atomistic.models.cell.backend.CellBackend | httk.atomistic.models.cell.view_base.CellViewBase | httk.atomistic.models.cell.cell.Cell | httk.core.VectorLike[source]¶

class httk.atomistic.models.cell.NumericCell(cell)[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.

Parameters:: cell (httk.atomistic.models.cell.like.CellLike) – The cell or cell-like object to present.

property scale: float¶

The overall length factor.

Returns:: The scale as a floating-point value.
Return type:: float

property precision: float | None¶

The cell precision, or None if unknown.

Returns:: The absolute precision as a floating-point value.
Return type:: float | None

property periodicity: tuple[bool, bool, bool]¶

Which of the three basis rows is a genuine lattice translation.

Returns:: Flags identifying the periodic basis rows.
Return type:: tuple[bool, bool, bool]

property nperiodic_dimensions: int¶

How many of the three directions are periodic.

Returns:: The number of periodic directions.
Return type:: int

property unscaled_basis: httk.core.NumericVector¶

The 3x3 cell vectors before applying scale.

Returns:: The unscaled lattice vectors as floating-point values.
Return type:: httk.core.NumericVector

property basis: httk.core.NumericVector¶

The 3x3 lattice vectors scale * unscaled_basis.

Returns:: The scaled lattice vectors as floating-point values.
Return type:: httk.core.NumericVector

property lengths: httk.core.NumericVector¶

The three cell-vector lengths.

Returns:: The lengths as floating-point values.
Return type:: httk.core.NumericVector

property angles: httk.core.NumericVector¶

The cell angles (alpha, beta, gamma) in degrees.

Returns:: The angles as floating-point values.
Return type:: httk.core.NumericVector

property volume: float¶

The cell volume.

Returns:: The volume as a floating-point value.
Raises:: ValueError – If the exact cell is not periodic in all three directions.
Return type:: float

metric()[source]¶

The Gram matrix basis * basis^T.

Returns:: The Gram matrix as floating-point values.
Return type:: httk.core.NumericVector

property exact: httk.atomistic.models.cell.cell.Cell¶

The exact cell this presentation wraps.

Returns:: The exact cell.
Return type:: httk.atomistic.models.cell.cell.Cell

class httk.atomistic.models.cell.CellNumericView(obj, **hints)[source]¶

Bases: httk.atomistic.models.cell.view_base.CellViewBase, httk.atomistic.models.cell.numeric.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 lazily from the backend on first access, preserving the scale/unscaled split. Like a NumericCell it requires numpy (raising ImportError otherwise).

Parameters:

obj (httk.atomistic.models.cell.like.CellLike) – The cell-like object to present.
**hints (Any) – Backend-selection hints.

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return this presentation as a standalone numeric cell.

Returns:: The plain-numpy presentation.
Return type:: httk.atomistic.models.cell.numeric.NumericCell

class httk.atomistic.models.cell.CellParams(obj, **hints)[source]¶

Bases: httk.atomistic.models.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 neither orientation nor periodicity, so a cell → parameters → cell round-trip reproduces lengths and angles, and reproduces volume only for a fully periodic source. Reconstruction uses the fully periodic default and therefore discards any non-3D periodicity as well as the original orientation. unwrap returns the original raw object.

Parameters:

obj (Any) – The six cell parameters in crystallographic order.
**hints (Any) – Backend-selection hints.

property basis: httk.core.SurdVector¶

Return the basis derived from the stored parameters.

Returns:: The standard-orientation cell vectors.
Return type:: httk.core.SurdVector

property scale: httk.core.SurdScalar¶

Return the unit scale factor.

Returns:: The factor applied to unscaled_basis.
Return type:: httk.core.SurdScalar

property unscaled_basis: httk.core.SurdVector¶

Return the parameter-derived basis before scaling.

Returns:: The cell vectors.
Return type:: httk.core.SurdVector

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

Return the natively stored cell-vector lengths.

Returns:: The exact stored a, b, and c lengths.
Return type:: tuple[httk.core.SurdScalar, Ellipsis]

property angles: tuple[fractions.Fraction, Ellipsis]¶

Return the natively stored cell angles in degrees.

Returns:: The exact stored alpha, beta, and gamma angles.
Return type:: tuple[fractions.Fraction, Ellipsis]

property params: tuple[fractions.Fraction, Ellipsis]¶

The stored (a, b, c, alpha, beta, gamma) in degrees.

Returns:: The exact cell parameters.
Return type:: tuple[fractions.Fraction, Ellipsis]

unwrap()[source]¶

Return the original parameter object.

Returns:: The raw parameter representation.
Return type:: Any

class httk.atomistic.models.cell.CellParamsView(obj, **hints)[source]¶

Bases: httk.atomistic.models.cell.view_base.CellViewBase, 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 and angles, and reproduces volume only for a fully periodic source. The reconstruction inherits the fully periodic default, so this view discards the source periodicity as well as the original cell-vector orientation.

Parameters:

obj (httk.atomistic.models.cell.like.CellLike) – The cell-like object to present.
**hints (Any) – Backend-selection hints.

property a: float¶

The length of the first cell vector.

Returns:: The first vector length.
Return type:: float

property b: float¶

The length of the second cell vector.

Returns:: The second vector length.
Return type:: float

property c: float¶

The length of the third cell vector.

Returns:: The third vector length.
Return type:: float

property alpha: float¶

The angle between the second and third cell vectors, in degrees.

Returns:: The alpha angle.
Return type:: float

property beta: float¶

The angle between the first and third cell vectors, in degrees.

Returns:: The beta angle.
Return type:: float

property gamma: float¶

The angle between the first and second cell vectors, in degrees.

Returns:: The gamma angle.
Return type:: float

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return the presented parameters as a plain tuple.

Returns:: The six cell parameters.
Return type:: tuple[float, Ellipsis]

class httk.atomistic.models.cell.PlainCell(obj, **hints)[source]¶

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

Parameters:

obj (Any) – The raw 3x3 basis representation.
**hints (Any) – Backend-selection hints.

property basis: httk.core.SurdVector¶

Return the raw basis in the canonical representation.

Returns:: The cell vectors.
Return type:: httk.core.SurdVector

property scale: httk.core.SurdScalar¶

Return the unit scale factor.

Returns:: The factor applied to unscaled_basis.
Return type:: httk.core.SurdScalar

property unscaled_basis: httk.core.SurdVector¶

Return the basis before scaling.

Returns:: The cell vectors.
Return type:: httk.core.SurdVector

unwrap()[source]¶

Return the original basis object.

Returns:: The raw basis representation.
Return type:: Any

class httk.atomistic.models.cell.PlainCellView(obj, **hints)[source]¶

Bases: httk.atomistic.models.cell.view_base.CellViewBase, 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.

Parameters: