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

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


Functions
---------

.. autoapisummary::

   httk.io.cif.expand_asu.pos_key
   httk.io.cif.expand_asu.find_adjacent_key_wrap
   httk.io.cif.expand_asu.apply_op_frac
   httk.io.cif.expand_asu.species_to_numbers
   httk.io.cif.expand_asu.asu_data_to_numbers_by_labels
   httk.io.cif.expand_asu.expand_asu
   httk.io.cif.expand_asu.apply_op_moment
   httk.io.cif.expand_asu.mag_asu_data_to_numbers
   httk.io.cif.expand_asu.cif_to_struct
   httk.io.cif.expand_asu.expand_mag_asu


Module Contents
---------------

.. py:function:: pos_key(v, grid_den, tol=1e-08)

   Hashable key for a position after snapping.


.. py:function:: find_adjacent_key_wrap(k, pos_map, grid_dens)

   Look for k in pos_map; if missing, check the 26 neighbors
   (Chebyshev distance 1) with periodic boundaries.
   Return (found_key or None).


.. py:function:: apply_op_frac(R, t, f)

   Apply a (fractional) symmetry operation and wrap to [0,1).
   Works with int-like R and float-like t/f.


.. py:function:: species_to_numbers(species)

.. py:function:: asu_data_to_numbers_by_labels(asu_data)

   Optional helper mirroring your magnetic 'separate_noneq_atoms' behavior:
   give each distinct *label* a unique number (even if same element symbol).


.. py:function:: expand_asu(positions_frac, species, ops, *, grid_dens=16384, tol=1e-06, moments=None, apply_op_moment_fn: collections.abc.Callable[Ellipsis, Any] | None = None, spin_basis=None, basis=None, mag_grid_dens=16384) -> tuple[Any, Ellipsis]

   Generalized ASU expansion.

   For a non-magnetic expansion::

       positions_full, species_full = expand_asu(pos, species, ops)

   For a magnetic expansion::

       positions_full, species_full, moments_full, mom_classes, symops_classes = expand_asu(
           pos, species, ops, moments=moments, apply_op_moment_fn=apply_op_moment,
           spin_basis=spin_basis, basis=basis, mag_grid_dens=mag_grid_dens)

   For non-magnetic input ``ops`` are ``(R, t)``; for magnetic input they are
   ``(R, t, time_flag)``. Duplicate positions are removed using snapped position keys
   with neighbour wrap-around.


.. py:function:: apply_op_moment(R, time_flag, m, lattice, spin_basis)

.. py:function:: mag_asu_data_to_numbers(mag_asu_data)

   Numbering that separates non-equivalent atoms (labels), mapping each label to a unique id,
   while still storing element symbol as numbers_to_species[id].
   This is the corrected intent of your original helper.


.. py:function:: cif_to_struct(fs, *, separate_noneq_atoms=False, tol=1e-06)

   Read a CIF file, expand the asymmetric unit, and return the result.

   ``fs`` is a filename or file-like object (anything accepted by the ``read_cif``
   layer). When ``separate_noneq_atoms`` is true, unique numbers are assigned by CIF
   label (even for the same element); otherwise numbers are assigned by element
   symbol. ``tol`` controls the expansion consistency tolerance. Returns a dict with
   the expanded structure data.


.. py:function:: expand_mag_asu(fs, *, separate_noneq_atoms=False, error_on_nonmag=True, tol=1e-06, mag_grid_dens=16384)

   Read an mCIF file, expand the asymmetric unit, and return the result.

   ``fs`` is a filename or file-like object (anything accepted by the ``read_cif``
   stack). When ``separate_noneq_atoms`` is true, unique numbers are assigned by CIF
   label (even for the same element symbol); otherwise numbers are assigned by
   element symbol. When ``error_on_nonmag`` is true, an error is raised if no magnetic
   moments can be extracted. ``tol`` is the expansion consistency tolerance and
   ``mag_grid_dens`` is the density used when snapping magnetization directions and
   classes. Returns a dict with the expanded magnetic structure data.