httk.io.cif¶

Read CIF and magnetic CIF files into neutral asymmetric-unit payloads.

Submodules¶

Functions¶

`read_cif_asus`(source, *[, autocorrect])	Read a CIF and return its asymmetric units as a neutral, tagged payload.
`single_asu_from_cif_file`(source)	Return the first structural CIF block from `read_cif_asus()`.
`read_cif`(source[, pragmatic, allow_cif2, autocorrect, ...])	Read CIF text as `(data_blocks, header)`.
`mag_asus_from_mcif_file`(source, *[, error_on_nonmag])	Read every mcif data block as a neutral magnetic asymmetric-unit payload.
`read_mcif_asus`(source)	Read an mcif into the neutral payload used by the `.mcif` loader.
`single_mag_asu_from_mcif_file`(source, *[, error_on_nonmag])	Return the first structural mcif block as a neutral magnetic payload.

Package Contents¶

httk.io.cif.read_cif_asus(source, *, autocorrect=False)[source]¶

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. When autocorrect=True, the top-level payload also contains autocorrect=True so downstream adapters can apply compatible repairs.

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, exact numeric text channels, and raw symmetry-operation strings, with no domain objects — so httk-io need not know about httk-atomistic. Turning it into a structure is httk.core.load (which returns an ASUStructure when atomistic support is installed).

Parameters:

source (str | os.PathLike[str] | collections.abc.Iterable[str]) – A filename, open text stream, or iterable of CIF lines.
autocorrect (bool) – Drop malformed auxiliary loops and warn about each repair.

Returns:

A neutral CIF payload containing structural blocks, unparsed block reasons, and the header.

Raises:

ValueError – If the CIF stream contains malformed data that prevents parsing.

Return type:

dict[str, Any]

httk.io.cif.single_asu_from_cif_file(source)[source]¶

Return the first structural CIF block from read_cif_asus().

Parameters:: source (str | os.PathLike[str] | collections.abc.Iterable[str]) – A filename, open text stream, or iterable of CIF lines.
Returns:: The first parsed asymmetric-unit mapping.
Raises:: ValueError – If no structural block is available.
Return type:: dict[str, Any]

httk.io.cif.read_cif(source, pragmatic=True, allow_cif2=False, *, autocorrect=False, structural_only=False)[source]¶

Read CIF text as (data_blocks, header).

Paths are opened through httk.core.TextstreamFileView, including compressed CIF files. Open streams and iterables are consumed but left open.

Parameters:

source (str | os.PathLike[str] | collections.abc.Iterable[str]) – A filename, open text stream, or iterable of CIF lines.
pragmatic (bool) – Accept selected common deviations from strict CIF tokenization.
allow_cif2 (bool) – Parse CIF2 list values in addition to CIF1 data.
autocorrect (bool) – Drop malformed auxiliary loops and warn about each repair.
structural_only (bool) – Retain only tags consumed by httk’s structural adapters and skip auxiliary CIF1 loops.

Returns:

The data blocks and the leading comment header.

Raises:

ValueError – If a loop contains mismatched column value counts.

Return type:

tuple[list[tuple[str, dict[str, Any]]], str]

httk.io.cif.mag_asus_from_mcif_file(source, *, error_on_nonmag=False)[source]¶

Read every mcif data block as a neutral magnetic asymmetric-unit payload.

Parameters:

source (str | os.PathLike[str] | collections.abc.Iterable[str]) – A filename, open text stream, or iterable of mcif lines.
error_on_nonmag (bool) – Reject blocks without usable magnetic moment columns.

Returns:

Magnetic payloads for the data blocks in the source.

Raises:

ValueError – If the mcif stream or a selected block is invalid.

Return type:

list[dict[str, Any]]

httk.io.cif.read_mcif_asus(source)[source]¶

Read an mcif into the neutral payload used by the .mcif loader.

Magnetic positions and moments remain exact central tokens, symmetry operations remain raw strings, and the result contains no magnetic-domain objects. Blocks without atom sites are skipped; blocks that cannot be interpreted are reported in unparsed.

Parameters:: source (str | os.PathLike[str] | collections.abc.Iterable[str]) – A filename, open text stream, or iterable of mcif lines.
Returns:: A neutral mcif payload containing magnetic blocks, unparsed reasons, and the header.
Raises:: ValueError – If the mcif stream contains malformed data that prevents parsing.
Return type:: dict[str, Any]

httk.io.cif.single_mag_asu_from_mcif_file(source, *, error_on_nonmag=False)[source]¶

Return the first structural mcif block as a neutral magnetic payload.

Parameters:

source (str | os.PathLike[str] | collections.abc.Iterable[str]) – A filename, open text stream, or iterable of mcif lines.
error_on_nonmag (bool) – Reject the selected block without usable magnetic moments.

Returns:

The first magnetic asymmetric-unit payload.

Raises:

ValueError – If no structural block is available or the selected block is invalid.

Return type:

dict[str, Any]