httk.io.cif.cif_parser

Classes

CifMeta

What a CIF number claims about its own precision, beyond its value.

Functions

parse_cif_float(…)	Parse a CIF numeric field.
parse_cif_int(→ int)	Convert a CIF numeric token (e.g., '123(4)', '3E2', '1.0E3') to an int using the central value.
parse_linear_expr(expr[, use_fractions])	expr: e.g. 'x-y', '-z+1/2', 'x', 'y', 'z-1', 'x-2y', '3x+1/2'
parse_xyz_op(op[, use_fractions])	op: e.g. 'x-y,x,-z+1/2'
xyz_symops_to_matrix(symops_xyz[, use_fractions])
cif_exact_token(→ str | None)	The numeric part of a CIF value, as text, with any uncertainty estimate removed.
parse_asu_cell(cifblock)
parse_structural_modulation(cifblock)	Extract structural superspace modulation information from a standard CIF.
cifblock_to_asu(cifblock, *[, return_single])
read_cif_asus(fs)	Read a CIF and return its asymmetric units as a neutral, tagged payload.
asus_from_cif_file(fs)
single_asu_from_cif_file(fs)

Module Contents

class httk.io.cif.cif_parser.CifMeta

Bases: TypedDict

What a CIF number claims about its own precision, beyond its value.

Both are exact rationals, or None when the token makes no such claim. None is not the same as claiming exactness: a value written 1/3 states an exact number and reports None for both, while ? states nothing at all and also reports None.

precision is implied by the digits written (0.3333 is good to 1/10000); esd is the standard uncertainty a file states explicitly, so 0.3333(7) reports a precision of 1/10000 and an esd of 7/10000. They measure different things and the coarser of the two is the honest claim.

esd: fractions.Fraction | None

precision: fractions.Fraction | None

httk.io.cif.cif_parser.parse_cif_float(token: str, *, meta: Literal[False] = ..., pragmatic: bool = ...) → float | None

httk.io.cif.cif_parser.parse_cif_float(token: str, *, meta: Literal[True], pragmatic: bool = ...) → tuple[float | None, CifMeta]

Parse a CIF numeric field.

If meta=False:

return float_value or None.

If meta=True:

return (float_value_or_None, CifMeta) — the value plus what the token claims about its own precision. See CifMeta; both of its fields are exact rationals or None.

httk.io.cif.cif_parser.parse_cif_int(token: str, *, strict: bool = True, allow_round: bool = False) → int

Convert a CIF numeric token (e.g., ‘123(4)’, ‘3E2’, ‘1.0E3’) to an int using the central value. - strict=True: require the value to be exactly integral; otherwise raise ValueError. - allow_round=True (only if strict=False): round half-even to the nearest int.

httk.io.cif.cif_parser.parse_linear_expr(expr, use_fractions=False)

expr: e.g. ‘x-y’, ‘-z+1/2’, ‘x’, ‘y’, ‘z-1’, ‘x-2y’, ‘3x+1/2’ Returns (row, const) where row is [ax, ay, az] (integers or Fractions), and const is a float or Fraction depending on use_fractions.

httk.io.cif.cif_parser.parse_xyz_op(op, use_fractions=False)

op: e.g. ‘x-y,x,-z+1/2’ Returns (R, t) where R is 3x3 (list of rows), t is length-3 float list

httk.io.cif.cif_parser.xyz_symops_to_matrix(symops_xyz, use_fractions=False)

httk.io.cif.cif_parser.cif_exact_token(token: str) → str | None

The numeric part of a CIF value, as text, with any uncertainty estimate removed.

"0.3333(5)" becomes "0.3333"; "?" and "." become None. The point of keeping the text rather than a float is fidelity: a consumer that wants an exact value can read 0.3333 as the rational 3333/10000, which is what the file says, whereas float("0.3333") is a binary approximation whose exact rational value is 6004199023210345/18014398509481984 and says something the file did not.

httk.io.cif.cif_parser.parse_asu_cell(cifblock)

httk.io.cif.cif_parser.parse_structural_modulation(cifblock)

Extract structural superspace modulation information from a standard CIF.

Returns a tuple (structural_q, mod_dim, has_struct_mod, struct_mod_atoms) where structural_q is a list of q-vectors or None, mod_dim is the modulation dimension (0 if absent), has_struct_mod is a bool, and struct_mod_atoms is a sorted list of atom-site labels.

httk.io.cif.cif_parser.cifblock_to_asu(cifblock, *, return_single=False)

httk.io.cif.cif_parser.read_cif_asus(fs)

Read a CIF and return its asymmetric units as a neutral, tagged payload.

This is what httk.core.load returns for a .cif file: a mapping with format set to "cif", blocks holding one asymmetric-unit mapping per data block that describes a structure, and header the file’s leading comment. The tag lets a consumer dispatch on the file type without knowing which reader produced the payload.

Loading never fails on account of a block that is not a structure. CIF is a general-purpose format and a file may hold bibliographic entries, powder patterns, or an incomplete draft alongside — or instead of — anything crystallographic. Blocks without atom sites are simply not structures and are passed over; blocks that have atom sites but cannot be interpreted are collected in unparsed, each with the reason, so that nothing is dropped silently and the failure surfaces when a structure is actually asked for.

The mapping stays neutral — plain lists, strings, and exact Fraction symmetry operations, with no domain objects — so httk-io need not know about httk-atomistic. Turning it into a structure is httk.atomistic.asu_structure_from_cif.

httk.io.cif.cif_parser.asus_from_cif_file(fs)

httk.io.cif.cif_parser.single_asu_from_cif_file(fs)