httk.atomistic.models.sites¶

Submodules¶

Attributes¶

SitesLike

Classes¶

`SitesAPI`	Abstract base class for the canonical sites interface.
`SitesBackend`	Abstract base class for all backends of sites data.
`NumericSites`	A plain-numpy presentation of a `Sites` object.
`SitesNumericView`	A view presenting an underlying sites backend as a `NumericSites` object.
`PlainSites`	Backend for sites backed by a raw Nx3 list or tuple of numbers (or any Nx3 vector-like).
`PlainSitesView`	A view presenting an underlying sites backend as a raw Nx3 matrix of floats.
`Sites`	The sites of a crystal structure: the Nx3 matrix of reduced coordinates, held exactly.
`SitesView`	A view presenting an underlying sites backend as a `Sites` object.
`SitesViewBase`	Abstract base class for all views of sites data.

Package Contents¶

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

Return the reduced site coordinates.

property num_sites: int¶

Return the number of coordinate rows.

Returns:: The number of sites.
Return type:: int

property precision: fractions.Fraction | None¶

How precisely the coordinates were stated, in fractional units, or None.

Fractional, not a length: reduced coordinates are dimensionless and a Sites has no cell to convert with. cartesian_precision() does the conversion, where the cell is known.

Concrete rather than abstract, so a backend with no source of precision inherits None instead of breaking.

Returns:: The fractional precision, or None when unknown.
Return type:: fractions.Fraction | None

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

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

type httk.atomistic.models.sites.SitesLike = httk.atomistic.models.sites.backend.SitesBackend | httk.atomistic.models.sites.view_base.SitesViewBase | httk.atomistic.models.sites.sites.Sites | httk.core.VectorLike[source]¶

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

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

property precision: float | None¶

The fractional coordinate precision, or None if unknown.

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

property reduced_coords: httk.core.NumericVector¶

The Nx3 reduced site coordinates.

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

property exact: httk.atomistic.models.sites.sites.Sites¶

The exact sites this presentation wraps.

Returns:: The exact sites.
Return type:: httk.atomistic.models.sites.sites.Sites

class httk.atomistic.models.sites.SitesNumericView(obj, **hints)[source]¶

Bases: httk.atomistic.models.sites.view_base.SitesViewBase, httk.atomistic.models.sites.numeric.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 lazily from the backend on first access. Like a NumericSites it requires numpy (raising ImportError otherwise).

Parameters:

obj (httk.atomistic.models.sites.like.SitesLike) – The sites-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 standalone numeric sites.

Returns:: The plain-numpy presentation.
Return type:: httk.atomistic.models.sites.numeric.NumericSites

class httk.atomistic.models.sites.PlainSites(obj, **hints)[source]¶

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

Parameters:

obj (Any) – The raw reduced-coordinate representation.
**hints (Any) – Backend-selection hints.

property reduced_coords: httk.core.FracVector¶

Return the reduced coordinates in the canonical representation.

Returns:: The exact reduced coordinates.
Return type:: httk.core.FracVector

unwrap()[source]¶

Return the original coordinate object.

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

class httk.atomistic.models.sites.PlainSitesView(obj, **hints)[source]¶

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

Parameters:

obj (httk.atomistic.models.sites.like.SitesLike) – The sites-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 the presented coordinates as a plain tuple.

Returns:: The reduced-coordinate rows.
Return type:: tuple[tuple[float, Ellipsis], Ellipsis]

class httk.atomistic.models.sites.Sites(reduced_coords, precision=None)[source]¶

Bases: httk.atomistic.models.sites.backend.SitesBackend

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 rejected; the exact Cartesian frame — where radicals belong — is obtained instead via cartesian_sites().

Parameters:

reduced_coords (httk.core.VectorLike) – The reduced coordinates, one site per row.
precision (Any) – The fractional precision carried from the source, if known.

property reduced_coords: httk.core.FracVector¶

The Nx3 reduced site coordinates as an exact FracVector (one site per row).

property precision: fractions.Fraction | None¶

How precisely these coordinates were stated, in fractional units, or None.

Fractional and therefore dimensionless: reduced coordinates are fractions of a cell edge, and a Sites carries no cell to convert with. Use cartesian_precision() for the corresponding length, which is the number an interatomic tolerance or an spglib symprec actually wants.

It is the coarsest precision among the coordinates, since a structure is only as precisely stated as its least precisely stated number. None means unknown.