httk.io.cif
===========

.. py:module:: httk.io.cif


Submodules
----------

.. toctree::
   :maxdepth: 1

   /reference/autoapi/httk/io/cif/cif_parser/index
   /reference/autoapi/httk/io/cif/cif_reader/index
   /reference/autoapi/httk/io/cif/cif_writer/index
   /reference/autoapi/httk/io/cif/mcif_parser/index
   /reference/autoapi/httk/io/cif/symops_utils/index


Functions
---------

.. autoapisummary::

   httk.io.cif.asus_from_cif_file
   httk.io.cif.read_cif_asus
   httk.io.cif.single_asu_from_cif_file
   httk.io.cif.read_cif
   httk.io.cif.mag_asus_from_mcif_file
   httk.io.cif.single_mag_asu_from_mcif_file


Package Contents
----------------

.. py:function:: asus_from_cif_file(fs)

.. py:function:: 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``.


.. py:function:: single_asu_from_cif_file(fs)

.. py:function:: read_cif(fs, pragmatic=True, allow_cif2=False, use_types=False)

   Generic cif reader, given a filename / ioadapter it places all data in a python dictionary.

   It returns a tuple: (header, list)
   Where list are pairs of data blocks names and data blocks

   Each data block is a dictionary with tag_name:value

   For loops, value is another dictionary with format column_name:value

   The optional parameter pragmatic regulates handling of some counter-intuitive aspects of the cif specification, where
   the default pragmatic=True handles these features the way people usually use them, whereas pragmatic=False means
   to read the cif file precisely according to the spec. For example, in a multiline text field::

       ;
       some text
       ;

   Means the string '\nsome text'. For this specific case pragmatic=True removes the leading newline.

   set use_types to True to convert things that look like floats and integers to those respective types

   A filename (``str`` or :class:`os.PathLike`) is opened through
   :class:`httk.core.TextstreamFileView`, so a compressed file (``.cif.bz2``,
   ``.cif.gz``, ...) is decompressed transparently. An already-open text stream
   or a plain iterable of lines is consumed as-is and left open for the caller.


.. py:function:: mag_asus_from_mcif_file(fs, *, error_on_nonmag=False)

.. py:function:: single_mag_asu_from_mcif_file(fs, *, error_on_nonmag=False)