httk.atomistic.cif_structures

Build an exact ASUStructure from a neutral CIF mapping.

asu_structure_from_cif() consumes the plain, string-preserving mapping produced by httk.atomistic.io.cif (format tag "cif") and turns it into an exact ASU representation. The conversion only understands the neutral mapping shape, keeping the parser and domain model decoupled; the private reader bridge below adds precision metadata needed by this adapter.

A CIF is the natural source for an ASU: it lists one site per orbit and states the symmetry operations that generate the rest. That means no symmetry search is needed, and spglib is not involved. The setting is identified by comparing the file’s operations against the tabulated ones exactly, so a file written in a non-standard setting is recognized as such rather than silently reinterpreted.

Functions

asu_structures_from_cif(payload, *[, autocorrect])

Return every structure in a loaded CIF payload, one per structural data block.

asu_structure_from_cif(data, *[, tolerance, ...])

Build an exact ASUStructure from a neutral CIF mapping.

cif_setting(data, *[, trust_declared_symmetry])

The space-group setting a CIF block is written in.

Module Contents

httk.atomistic.cif_structures.asu_structures_from_cif(payload, *, autocorrect=False, **options)[source]

Return every structure in a loaded CIF payload, one per structural data block.

Accepts either a whole loaded payload (with blocks) or a single block.

Reading a CIF is tolerant — a file may hold blocks that are not structures at all — but asking it for structures is not. If the file yielded none, the reasons the reader recorded are raised here rather than returning an empty list, so a file that could not be interpreted does not read as a file that contained nothing.

Parameters:
Returns:

One asymmetric-unit structure for each structural data block.

Raises:

ValueError – If the payload has no interpretable structural data or a block is invalid.

Return type:

list[httk.atomistic.models.structure.asu.ASUStructure]

httk.atomistic.cif_structures.asu_structure_from_cif(data, *, tolerance=None, limit_denominator=None, trust_declared_symmetry=True, allow_large_cif_uncertainty=False, autocorrect=False)[source]

Build an exact ASUStructure from a neutral CIF mapping.

data is one block of the mapping returned by httk.atomistic.io.cif (its format must be "cif").

The cell is built exactly from the file’s a, b, c, alpha, beta, gamma rather than from the pre-multiplied floating-point basis, so a cubic cell keeps exact right angles and a hexagonal one keeps its sqrt(3) instead of inheriting rounding noise.

Coordinates are embedded as the rational the file literally wrote — 0.3333 is 3333/10000, not the binary value of float("0.3333") — and are then snapped onto the Wyckoff position they lie within tolerance of. That snapping is the only tolerant step; see recognition for the full contract.

tolerance left unspecified is derived from the precision the file’s own digits imply, so a coarsely written file is matched loosely and a carefully written one tightly, without anybody choosing a constant.

Site occupancies become the composition of the corresponding Species, so a half-occupied site survives into the structure instead of being dropped.

trust_declared_symmetry=False ignores the file’s declared Hall symbol or space-group number and identifies the setting from its symmetry operations alone; see cif_setting() for when that is the right thing to do.

Parameters:

  • data (collections.abc.Mapping[str, Any]) – One loaded CIF data block.

  • tolerance (float | None) – The Cartesian matching tolerance, or None to derive it from the CIF.

  • limit_denominator (int | None) – The maximum denominator for snapped free parameters, if supplied.

  • trust_declared_symmetry (bool) – Whether to validate the declared symmetry before matching operations.

  • allow_large_cif_uncertainty (bool) – Whether to allow positional uncertainty at or above one angstrom.

  • autocorrect (bool) – Apply documented CIF input repairs with warnings.

Returns:

The exact asymmetric-unit structure.

Raises:

ValueError – If the block format, symmetry, coordinates, occupancies, or Wyckoff matches are invalid.

Return type:

httk.atomistic.models.structure.asu.ASUStructure

httk.atomistic.cif_structures.cif_setting(data, *, trust_declared_symmetry=True)[source]

The space-group setting a CIF block is written in.

The setting is identified from the file’s symmetry operations, by exact set comparison against the tabulated settings. That is what makes a file written in a non-standard setting come out as itself rather than being silently reinterpreted.

What the file declares — a Hall symbol, an International Tables number, or a recognized H-M symbol — is treated as a claim to be checked, not a hint to be taken or dropped. A declaration that names no known setting, or that names one whose operations are not the file’s, is a genuine inconsistency in the file and raises rather than being worked around: the two halves of the file disagree, and quietly believing one of them is how a wrong structure gets built. An unrecognized H-M spelling is the exception and remains ignored.

Pass trust_declared_symmetry=False to ignore the declaration entirely and identify the setting from the operations alone. That is the escape hatch for a file whose symbols are known to be wrong but whose operations are good.

A Hermann-Mauguin symbol is consulted, when neither a Hall symbol nor an International Tables number is declared, only if its normalized spelling is recognized. A recognized symbol narrows the candidate IT number; the operations still identify the exact setting and a contradiction fails like a contradicting IT-number declaration. Unrecognized H-M spellings are ignored for compatibility with the previous operations-only behavior.

Raises ValueError when the block states no operations, when a declaration is inconsistent with them, or when the operations match no tabulated setting at all. In the last case the transform to the standard setting genuinely cannot be derived — infinitely many are equally valid and they describe different crystals — so such a file has to be built with an explicit SettingTransform.

Parameters:

  • data (collections.abc.Mapping[str, Any]) – The loaded CIF data block.

  • trust_declared_symmetry (bool) – Whether to check the declared Hall, IT, or H-M symbol.

Returns:

The tabulated space-group setting matching the block’s operations.

Raises:

ValueError – If operations are absent, inconsistent with the declaration, or unknown.

Return type:

httk.atomistic.symmetry.spacegroup.Spacegroup