pyextal.acom.datfile
====================

.. py:module:: pyextal.acom.datfile

.. autoapi-nested-parse::

   Writing a `.dat` for a solved orientation.

   The crystal block is copied verbatim from a template file rather than
   regenerated, so cell, atoms and space group cannot drift. Only the orientation
   and the two beam blocks are rewritten.



Functions
---------

.. autoapisummary::

   pyextal.acom.datfile._fmt
   pyextal.acom.datfile.write_dat
   pyextal.acom.datfile.write_oriented_dat
   pyextal.acom.datfile.read_dat_beams


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

.. py:function:: _fmt(rows)

.. py:function:: write_dat(template, dst, zone, xaxis, beams, out_beams, kt=(0, 0, 0), norm=None, conv=None, samp=None, sgmax=None, sgmin=None, omeg=None, abs_=None)

   Writes a `.dat` for one orientation, with explicit beam and output blocks.

   The output beams are written as a **prefix** of the beam list, so
   ``hkl[:nout] == hklout`` and the engine's `idptr` mapping is the identity.
   That is not cosmetic: `bloch_parse` resolves each `out` entry against `hkl`
   and *appends* any it cannot find, writing past the array it already allocated
   from the declared beam count.

   :param template: Existing `.dat` supplying the crystal block.
   :type template: str | Path
   :param dst: File to write.
   :type dst: str | Path
   :param zone: Zone axis.
   :type zone: tuple[int, int, int]
   :param xaxis: Reflection defining the horizontal axis.
   :type xaxis: tuple[int, int, int]
   :param beams: (n, 3) every beam in the calculation.
   :type beams: array-like
   :param out_beams: (m, 3) reflections to output.
   :type out_beams: array-like
   :param kt: Tangential incident wavevector. Defaults to (0,0,0).
   :type kt: tuple, optional
   :param norm: Surface normal; `zone` is used when None.
   :type norm: tuple, optional
   :param conv: Convergence angle; the template's value is kept
                when None.
   :type conv: float, optional
   :param samp: Sampling; the template's value is kept when None.
   :type samp: int, optional
   :param sgmax: Maximum excitation error. Defaults to 3.5 when
                 the template used `sele` and gave no standalone value.
   :type sgmax: float, optional
   :param sgmin: Minimum excitation error; template value kept
                 when None.
   :type sgmin: float, optional
   :param omeg: Bethe parameter; template value kept when None.
   :type omeg: float, optional
   :param abs_: Mean absorption; template value kept when None.
   :type abs_: float, optional

   :returns: The file written.
   :rtype: Path

   :raises ValueError: If an output beam is missing from `beams`, or the template
       lacks a block that has to be replaced.


.. py:function:: write_oriented_dat(template, dst, zone, xaxis, kt=(0, 0, 0), norm=None)

   Copies a `.dat`, changing only the orientation.

   The beam-selection blocks are left exactly as the template had them, so a
   template using `sele`/`aper` still selects its beams geometrically -- at the
   new orientation. That makes it the natural reference to compare an explicit
   ACOM beam list against: same crystal, same cutoffs, same engine, only the
   zone axis replaced.

   :param template: Existing `.dat`.
   :type template: str | Path
   :param dst: File to write.
   :type dst: str | Path
   :param zone: Zone axis.
   :type zone: tuple[int, int, int]
   :param xaxis: Reflection defining the horizontal axis.
   :type xaxis: tuple[int, int, int]
   :param kt: Tangential incident wavevector. Defaults to (0,0,0).
   :type kt: tuple, optional
   :param norm: Surface normal; `zone` is used when None.
   :type norm: tuple, optional

   :returns: The file written.
   :rtype: Path


.. py:function:: read_dat_beams(path)

   Reads the explicit `hkl` and `out` blocks back out of a `.dat`.

   Lets downstream code take its reflection list from the file the engine will
   actually parse, rather than from a variable that may have drifted from it.

   :param path: A `.dat` with explicit blocks, as written by
                :func:`write_dat`.
   :type path: str | Path

   :returns: ``(beams, out_beams)`` as (h, k, l) tuples.
   :rtype: tuple[list, list]

   :raises ValueError: If either block is missing, or a declared count does not
       match the rows that follow it.