httk.atomistic.models.structure.asu

A crystal structure held as its asymmetric unit.

An ASUStructure records only the symmetry-distinct sites — the asymmetric unit — plus the space group needed to regenerate the rest. Where a UnitcellStructure lists every atom in the cell, this lists one representative per orbit as a Wyckoff letter and the values of that position’s free parameters.

Any setting, including non-standard ones. Wyckoff data is recorded directly against the tabulated setting it arrived in. No change of basis is done merely to store or expand it. A setting that appears in no table remains representable by recording the Wyckoff data against the standard setting together with an exact transform into the structure’s own coordinates.

Expansion is exact and needs no tolerance. Reduced coordinates, symmetry operations, Wyckoff parameters, and the setting transform are all exact rationals, and the vendored orbits are complete and pre-deduplicated. So generating the full cell is affine arithmetic over the rationals with an exact equality test at the end — no coordinate grid, no snapping, no neighbour search. Tolerance enters this class only where a measured structure is first recognized as symmetric, never in expansion.

Classes

WyckoffSite	Represent one symmetry-distinct site.
FundamentalDomainStructure	Represent a crystal structure by one exact site per symmetry orbit.
ASUStructure	Assert that a fundamental domain is a true asymmetric unit.

Module Contents

class httk.atomistic.models.structure.asu.WyckoffSite

Represent one symmetry-distinct site.

wyckoff is a bare letter ("e", not "4e") naming a position of the structure’s stored setting, and free_params holds one exact value per degree of freedom of that position — none at all for a fixed position such as an inversion centre. species names one of the owning structure’s species.

Moment data uses verbatim-copy semantics: every expanded orbit image carries the same moment. This is physically meaningful only when the site symmetry preserves that moment; magnetic structures that break it must be represented as a unit cell (or via SymopsStructure, coming later).

Partial occupancy needs nothing special here: it lives in the referenced Species, which already carries a composition.

Parameters:

• wyckoff – The Wyckoff letter in the structure’s stored setting.

• free_params – The free values for the Wyckoff position.

• species – The name of the owning structure’s species.

• representative – An optional retained representative coordinate.

• moment – An optional moment assigned to the site.

wyckoff: str

free_params: httk.core.FracVector

species: str

representative: httk.core.FracVector | None = None

moment: httk.atomistic.models.moments.backend.SiteMomentsBackend | None = None

property free_count: int

How many free parameters this site carries.

class httk.atomistic.models.structure.asu.FundamentalDomainStructure(cell, spacegroup, wyckoff_sites, species, transform=None, coordinate_precision=None, *, molecular=False, assemblies=None, chemical_composition=None, chemical_formula_descriptive=None, chemical_formula_hill=None, optimization_type=None, immutable_id=None, last_modified=None, charge=None, _validated_proof=None)

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

Represent a crystal structure by one exact site per symmetry orbit.

Holds the cell in the structure’s own setting, the space-group setting that names its Wyckoff data, an optional transform from that setting to the structure’s own, one WyckoffSite per symmetry-distinct site, and the species they name. On first expansion, a site whose orbit contributes no new points raises ValueError because it duplicates an earlier site’s orbit.

Parameters:

• cell (httk.atomistic.models.cell.like.CellLike) – The cell in the structure’s own setting.

• spacegroup (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – The setting that names the stored Wyckoff data.

• wyckoff_sites (collections.abc.Sequence[WyckoffSite]) – The symmetry-distinct site definitions.

• species (collections.abc.Sequence[httk.atomistic.models.species.like.SpeciesLike]) – The species referenced by the site definitions.

• transform (httk.atomistic.symmetry.setting_transform.SettingTransform | None) – The change of basis from the stored setting to the structure’s setting.

• coordinate_precision (Any) – The precision recorded for the reduced coordinates.

• molecular (bool) – Whether the structure describes molecular entities.

• assemblies (collections.abc.Sequence[Any] | None) – Optional correlations among domain sites.

• chemical_composition (Any) – 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 expanded cell content; it is not derived from the species.

• _validated_proof (_ValidatedASUProof | None) – Internal proof that the supplied CIF expansion already validates the representatives.

kind: ClassVar[str] = 'asu'

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

Expose the cell in the structure’s own setting.

property spacegroup: httk.atomistic.symmetry.spacegroup.Spacegroup

Expose the setting that names the stored Wyckoff data.

property transform: httk.atomistic.symmetry.setting_transform.SettingTransform

Expose the transform from the stored setting to the structure’s setting.

property transform_from_standard: httk.atomistic.symmetry.setting_transform.SettingTransform

Return the exact transform from the IT standard setting to this structure.

property wyckoff_sites: tuple[WyckoffSite, Ellipsis]

Expose the symmetry-distinct sites.

property domain_sites: tuple[WyckoffSite, Ellipsis]

Expose the directly stored fundamental-domain sites.

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

Expose the species referenced by the sites.

property coordinate_precision: fractions.Fraction | None

Expose the recorded precision of the reduced coordinates.

Fractional, and expressed in this structure’s own setting — the frame the data arrived in — so it needs no transforming on the way to the expanded sites. Recording it here is what lets an asymmetric unit say how good the data behind it was, rather than leaving that to be guessed again downstream.

It is provenance, never an operating parameter: expansion remains exact and uses no tolerance at all.

Returns:

The fractional precision, or None when it is unknown.

Return type:

fractions.Fraction | None

property asu: FundamentalDomainStructure

Expose this structure as its own fundamental domain.

property periodicity: tuple[bool, bool, bool]

Expose the cell’s periodic directions.

property molecular: bool

Expose whether molecular semantics are enabled.

property domain_species_at_sites: tuple[str, Ellipsis]

Expose species names for the directly represented domain sites.

cartesian_sites()

Compute the exact Cartesian positions of the represented sites.

Returns:

The Cartesian representative positions in the exact surd representation.

Return type:

httk.core.SurdVector

property fractional_site_positions: list[list[float]]

Expose representative positions as floating-point coordinates.

property nsites: int

Expose the number of directly represented sites.

property site_coordinate_span: str

Expose the fundamental-domain coordinate span.

property space_group_it_number: int

Expose the space group’s International Tables number.

property space_group_symbol_hall: str | None

Expose the Hall symbol for the active setting.

property space_group_symbol_hermann_mauguin: str | None

Expose the Hermann–Mauguin symbol for the active setting.

property space_group_symbol_hermann_mauguin_extended: str | None

Expose the extended Hermann–Mauguin symbol for the active setting.

property space_group_symmetry_operations_xyz: tuple[str, Ellipsis]

Expose the active setting’s symmetry operations in xyz notation.

property wyckoff_positions: tuple[str, Ellipsis] | None

Expose Wyckoff positions in the active setting.

property is_standard_setting: bool

Expose whether the structure uses its space group’s standard setting.

setting()

The tabulated setting this structure is written in, or None if untabulated.

A structure in an arbitrary setting is perfectly representable but has no tabulated name; that is the point of storing the transform rather than a setting label.

A transform looked up from the tables remembers which setting it came from, but one that was constructed directly does not, so an equal transform is also matched against the group’s tabulated settings. An identity transform means the stored tabulated setting is already the structure’s own setting.

Returns:

The matching tabulated setting, or None when untabulated.

Return type:

httk.atomistic.symmetry.spacegroup.Spacegroup | None

expand_sites()

Every site of the unit cell, as exact reduced coordinates in this structure’s setting.

The orbit of each asymmetric-unit site is generated directly from its stored setting’s table, wrapped into [0, 1), and deduplicated by exact equality. Only an untabulated setting uses the stored transform. Deduplication then also handles a transform that shrinks the cell; the opposite case, a transform onto a larger cell, is covered by lattice_cosets().

Returns:

All unit-cell sites in the structure’s exact setting.

Return type:

httk.atomistic.models.sites.sites.Sites

expand_species_at_sites()

Expose the species names produced by expand_sites().

Returns:

Species names in expanded site order.

Return type:

tuple[str, Ellipsis]

expand_site_moments()

Expand one exact moment for every represented site.

Returns:

Expanded site moments, or None when moments are unstated.

Return type:

httk.atomistic.models.moments.backend.SiteMomentsBackend | None

multiplicities()

How many cell sites each asymmetric-unit site generates, in order.

Usually the Wyckoff position’s tabulated multiplicity, but not always: a setting transform that changes the cell volume changes the count too, by a factor of three for the rhombohedral-axes settings.

Returns:

The number of expanded sites generated by each domain site.

Return type:

tuple[int, Ellipsis]

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

Expose representative or expanded sites according to the semantics.

property species_at_sites: tuple[str, Ellipsis]

Expose representative or expanded species names according to the semantics.

property site_moments: httk.atomistic.models.moments.backend.SiteMomentsBackend | None

Expose representative or expanded site moments.

property charge: fractions.Fraction | None

Expose the explicitly assigned exact charge of the expanded cell.

Returns:

The assigned charge, or None when it is unstated.

Return type:

fractions.Fraction | None

property assemblies: tuple[httk.atomistic.composition.Assembly, Ellipsis] | None

Expose correlations among the domain sites.

class httk.atomistic.models.structure.asu.ASUStructure(cell, spacegroup, wyckoff_sites, species, transform=None, coordinate_precision=None, *, molecular=False, assemblies=None, chemical_composition=None, chemical_formula_descriptive=None, chemical_formula_hill=None, optimization_type=None, immutable_id=None, last_modified=None, charge=None, _validated_proof=None)

Bases: FundamentalDomainStructure

Assert that a fundamental domain is a true asymmetric unit.

property site_coordinate_span: str

Expose the asymmetric-unit coordinate span.