httk.atomistic.io.cif.mcif_parser

Functions

extract_parent_q_basis(cifblock)	Return the parent propagation basis as a list of (kx, ky, kz) tuples,
extract_fourier_coeffs(cifblock)	Return (coeff_rows, m) where coeff_rows is a list of coefficient tuples
extract_fourier(cifblock)	Return the (basis, coeffs) descriptor, or None if there is insufficient data.
cifblock_to_mag_asu(cifblock, *[, error_on_nonmag])	Convert one normalized mcif block to a neutral magnetic payload.
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.

Module Contents

httk.atomistic.io.cif.mcif_parser.extract_parent_q_basis(cifblock)

Return the parent propagation basis as a list of (kx, ky, kz) tuples, or None if it is not present.

Parameters:

cifblock (dict[str, Any]) – Normalized mcif data for one data block.

Returns:

Parent propagation vectors, or None when the block has none.

Raises:

ValueError – If a propagation vector is not a three-component exact vector.

Return type:

list[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction]] | None

httk.atomistic.io.cif.mcif_parser.extract_fourier_coeffs(cifblock)

Return (coeff_rows, m) where coeff_rows is a list of coefficient tuples (c1, c2, ..., cm) and m is the number of q-vectors detected (>= 0).

All present q{i}_coeff columns are found, zipped row-wise with missing entries filled by zeros, and duplicate coefficient tuples are removed.

Parameters:

cifblock (dict[str, Any]) – Normalized mcif data for one data block.

Returns:

Unique coefficient rows and the number of q-vector columns detected.

Return type:

tuple[list[tuple[Any, Ellipsis]], int]

httk.atomistic.io.cif.mcif_parser.extract_fourier(cifblock)

Return the (basis, coeffs) descriptor, or None if there is insufficient data.

basis comes from parent_propagation_vector.kxkykz and coeffs are the unique coefficient tuples from atom_site_Fourier_wave_vector.q*_coeff.

Parameters:

cifblock (dict[str, Any]) – Normalized mcif data for one data block.

Returns:

The parent basis and unique coefficient rows, or None when either is absent.

Return type:

tuple[list[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction]], list[tuple[Any, Ellipsis]]] | None

httk.atomistic.io.cif.mcif_parser.cifblock_to_mag_asu(cifblock, *, error_on_nonmag=False)

Convert one normalized mcif block to a neutral magnetic payload.

The payload keeps exact numeric tokens for positions and magnetic moments, raw symmetry-operation strings, and plain mappings and sequences rather than domain objects.

Parameters:

• cifblock (dict[str, Any]) – Normalized mcif data for one data block.

• error_on_nonmag (bool) – Reject blocks without usable magnetic moment columns.

Returns:

A neutral mapping containing structural and magnetic channels.

Raises:

ValueError – If required structural or magnetic data is missing or invalid.

Return type:

dict[str, Any]

httk.atomistic.io.cif.mcif_parser.mag_asus_from_mcif_file(source, *, error_on_nonmag=False)

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.atomistic.io.cif.mcif_parser.read_mcif_asus(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.atomistic.io.cif.mcif_parser.single_mag_asu_from_mcif_file(source, *, error_on_nonmag=False)

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]