httk.atomistic.models.cell.cell

The Cell class for httk-atomistic.

Classes

Cell	A crystallographic cell: its basis, the 3x3 matrix of cell vectors, held exactly.

Module Contents

class httk.atomistic.models.cell.cell.Cell(basis, scale=MISSING, precision=MISSING, periodicity=MISSING)

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.

The constructor accepts any cell-like value: a 3x3 basis (one cell vector per row), the six cell parameters (a, b, c, alpha, beta, gamma) in degrees (built through CellParams in the standard orientation, so Cell([3, 3, 5, 90, 90, 120]) is the exact hexagonal cell), or another cell backend or view, whose scale, precision and periodicity are adopted unless given explicitly.

Parameters:

• basis (Any) – The three cell vectors, one per row; or six cell parameters; or a cell.

• scale (Any) – The positive factor separated from basis (default 1).

• precision (Any) – The absolute precision carried from the source, if known.

• periodicity (Any) – Flags identifying which basis rows are lattice translations (default all).

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

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

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, ...]

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, …]

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

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, …]

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