httk.atomistic.models.structure.unitcell¶

The Simple structure representation for httk-atomistic.

Classes¶

UnitcellStructure

Represent a crystal structure in the Unitcell representation.

Module Contents¶

class httk.atomistic.models.structure.unitcell.UnitcellStructure(cell, sites, species=None, species_at_sites=None, *, site_moments=None, molecular=False, assemblies=None, symmetry=None, chemical_composition=None, chemical_formula_descriptive=None, chemical_formula_hill=None, optimization_type=None, immutable_id=None, last_modified=None, charge=None)[source]¶

Bases: httk.atomistic.models.structure.semantics.StructureSemanticsMixin, httk.atomistic.models.structure.backend.StructureBackend

Represent a crystal structure in the Unitcell representation.

A UnitcellStructure 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. When species is omitted, species_at_sites may itself contain species-like values; the distinct species table is then inferred in first-occurrence order.

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.

Parameters:

cell (httk.atomistic.models.cell.like.CellLike) – The unit-cell geometry.
sites (httk.atomistic.models.sites.like.SitesLike) – The reduced coordinates of the sites.
species (collections.abc.Sequence[httk.atomistic.models.species.like.SpeciesLike] | None) – The distinct species definitions. Omit this to infer them from species_at_sites.
species_at_sites (collections.abc.Sequence[httk.atomistic.models.species.like.SpeciesLike] | None) – The species name occupying each site; this value is required.
site_moments (httk.atomistic.models.moments.like.SiteMomentsLike | None) – Optional magnetic moments aligned with the sites.
molecular (bool) – Whether the structure describes a molecular unit cell.
assemblies (collections.abc.Sequence[httk.atomistic.composition.Assembly] | None) – Optional correlations among sites.
symmetry (httk.atomistic.models.structure.semantics.StructureSymmetry | None) – Optional symmetry metadata.
chemical_composition (ChemicalComposition | None) – Optional chemical composition metadata.
chemical_formula_descriptive (str | None) – Optional descriptive chemical formula.
chemical_formula_hill (str | None) – Optional Hill chemical formula.
optimization_type (str | None) – Optional optimization provenance.
immutable_id (str | None) – Optional immutable source identifier.
last_modified (datetime.datetime | None) – Optional source modification timestamp.
charge (fractions.Fraction | int | str | None) – An explicitly assigned charge for the cell content; it is not derived from the species, and an explicit zero remains distinct from an unstated charge.

kind: ClassVar[str] = 'unitcell'[source]¶

property cell: httk.atomistic.models.cell.cell.Cell[source]¶

Expose the cell geometry.

Returns:: The cell in the structure’s exact representation.
Return type:: httk.atomistic.models.cell.cell.Cell

property sites: httk.atomistic.models.sites.sites.Sites[source]¶

Expose the reduced site coordinates.

Returns:: The sites in the structure’s exact representation.
Return type:: httk.atomistic.models.sites.sites.Sites

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

Expose the distinct species.

Returns:: The species referenced by the structure.
Return type:: tuple[httk.atomistic.models.species.species.Species, Ellipsis]

property species_at_sites: tuple[str, Ellipsis][source]¶

Expose the species name occupying each site.

Returns:: Site species names in site order.
Return type:: tuple[str, Ellipsis]

property site_moments: httk.atomistic.models.moments.backend.SiteMomentsBackend | None[source]¶

Expose optional per-site magnetic moments in sites order.

Returns:: Site moments, or None when they are unstated.
Return type:: httk.atomistic.models.moments.backend.SiteMomentsBackend | None

property charge: fractions.Fraction | None[source]¶

Expose the explicitly assigned exact charge of the cell.

Returns:: The assigned charge, or None when it is unstated.
Return type:: fractions.Fraction | None

property coordinate_precision: fractions.Fraction | None[source]¶

Expose the precision recorded for the reduced coordinates.

Read through from sites. Dimensionless — see cartesian_precision() for the corresponding length.

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

property basis_precision: fractions.Fraction | None[source]¶

Expose the precision recorded for the cell basis.

Read through from cell.

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

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

Expose which cell directions are periodic.

Read through from cell, where the full account lives. (True, True, True) for an ordinary crystal, which is what a structure built without saying otherwise is.

Returns:: The periodicity flags for the cell directions.
Return type:: tuple[bool, bool, bool]

property site_coordinate_span: str[source]¶

Expose the coordinate span asserted by this representation.

Returns:: unit_cell or molecular_unit_cell.
Return type:: str

property molecular: bool[source]¶

Expose whether this structure describes a molecular unit cell.

Returns:: Whether molecular semantics are enabled.
Return type:: bool

property symmetry: httk.atomistic.models.structure.semantics.StructureSymmetry | None[source]¶

Expose the optional symmetry metadata.

Returns:: The symmetry metadata, or None when it is absent.
Return type:: httk.atomistic.models.structure.semantics.StructureSymmetry | None

cartesian_precision()[source]¶

The coordinate precision as a length, or None if it is unknown.

This is the number a real tolerance wants — an interatomic matching tolerance or an spglib symprec is a distance, and a fractional precision is not. A coordinate good to 1e-4 of a cell edge means something quite different in a 3 Å cell and a 30 Å one.

Computed as the fractional precision times the longest cell edge, which is the conservative choice: it is the largest displacement that fractional uncertainty can produce along any axis. The cell’s own precision is folded in as well, since a cell stated to 1e-3 cannot place an atom better than that however many digits the coordinates carry.

Returns:: The conservative Cartesian precision, or None when the coordinate precision is unknown.
Return type:: fractions.Fraction | None

cartesian_sites()[source]¶

Compute the exact Cartesian site positions.

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.

Returns:: The Cartesian positions in the exact surd representation.
Return type:: httk.core.SurdVector

numeric()[source]¶

Create a plain-numpy presentation of this structure.

Returns:: The numpy-backed structure view.
Raises:: ImportError – If numpy is unavailable.
Return type:: httk.atomistic.models.structure.numeric_view.NumericUnitcellStructureView

supercell(transformation, *, max_sites=100000)[source]¶

Build an exact supercell from an integer transformation.

Parameters:

transformation (httk.core.VectorLike) – The lattice transformation to apply.
max_sites (int | None) – The maximum permitted number of sites, or None for no limit.

Returns:

The generated supercell and transformation metadata.

Return type:

httk.atomistic.supercell.SupercellResult

orthogonal_supercell(multiplier=None, *, tolerance=None, max_multiplier=None, search_radius=1, max_sites=100000)[source]¶

Build a deterministically selected orthogonal supercell.

Parameters:

multiplier (int | None) – The requested volume multiplier, or None to search.
tolerance (fractions.Fraction | str | float | None) – The geometric tolerance used during the search.
max_multiplier (int | None) – The largest multiplier considered when searching.
search_radius (int) – The integer search radius for candidate transformations.
max_sites (int | None) – The maximum permitted number of sites, or None for no limit.

Returns:

The generated supercell and transformation metadata.

Return type:

httk.atomistic.supercell.SupercellResult

cubic_supercell(multiplier=None, *, tolerance=None, max_multiplier=None, search_radius=1, max_sites=100000)[source]¶

Build a deterministically selected cubic supercell.

Parameters:

multiplier (int | None) – The requested volume multiplier, or None to search.
tolerance (fractions.Fraction | str | float | None) – The geometric tolerance used during the search.
max_multiplier (int | None) – The largest multiplier considered when searching.
search_radius (int) – The integer search radius for candidate transformations.
max_sites (int | None) – The maximum permitted number of sites, or None for no limit.

Returns:

The generated supercell and transformation metadata.

Return type:

httk.atomistic.supercell.SupercellResult

conventional_cell(*, tolerance=None, limit_denominator=None)[source]¶

Express this structure in its conventional standard-setting cell.

Parameters:

tolerance (float | None) – The tolerance used when standardizing the structure.
limit_denominator (int | None) – The denominator limit used for rationalizing measured coordinates.

Returns:

The standardized structure and its transformation metadata.

Return type:

httk.atomistic.symmetry.standardization.ConventionalCellResult