pyextal.jaxGeo.io
=================

.. py:module:: pyextal.jaxGeo.io

.. autoapi-nested-parse::

   Finding and loading a dataset: the ``.h5``, the ``.dat`` it was built against.



Functions
---------

.. autoapisummary::

   pyextal.jaxGeo.io.to_wsl_path
   pyextal.jaxGeo.io.resolve_h5
   pyextal.jaxGeo.io._out_count
   pyextal.jaxGeo.io.resolve_dat
   pyextal.jaxGeo.io.check_pre_refinement
   pyextal.jaxGeo.io.load_dataset


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

.. py:function:: to_wsl_path(path)

   Accepts a Windows path as well as a WSL one.

   ``C:\Users\<user>\Box\...`` maps to ``/mnt/box/...`` (where Box is
   mounted under WSL) and any other ``X:\...`` to ``/mnt/x/...``. POSIX paths
   pass through unchanged.

   :param path: The path as typed.
   :type path: str | Path

   :returns: A path usable from WSL.
   :rtype: Path


.. py:function:: resolve_h5(path)

   The dataset file, given the file itself or the folder holding it.

   :param path: A ``.h5`` file, or a folder containing exactly one.
   :type path: Path

   :returns: The ``.h5`` file.
   :rtype: Path

   :raises SetupError: If ``path`` does not exist, or a folder holds no ``.h5``
       or several.


.. py:function:: _out_count(dat)

   Number of output reflections in a ``.dat``'s ``out`` block, or None.


.. py:function:: resolve_dat(h5, n_beams)

   Finds the ``.dat`` a dataset file was built against.

   In order: the ``dat`` recorded in the file's ``/paths`` group (relative to
   the file's folder, or to the recorded ``base``); otherwise the one ``.dat``
   beside the file whose ``out`` block lists exactly ``n_beams`` reflections --
   the experimental beam axis must match it one to one.

   :param h5: The dataset file.
   :type h5: Path
   :param n_beams: Reflections on its experimental beam axis.
   :type n_beams: int

   :returns: ``(Path, str)`` -- the ``.dat`` and how it was chosen.
   :rtype: tuple

   :raises SetupError: If no single ``.dat`` qualifies.


.. py:function:: check_pre_refinement(h5)

   Raises if the file lacks the ``/pre_refinement`` group this needs.

   :param h5: The dataset file.
   :type h5: Path

   :raises SetupError: With a message naming what the file holds instead.


.. py:function:: load_dataset(h5, subsample=1)

   The refinement inputs from a dataset file, spatially subsampled.

   :param h5: The dataset file.
   :type h5: Path
   :param subsample: Take every Nth scan point in each direction.
   :type subsample: int

   :returns: ``(data, g_include)``. ``data`` holds ``tilts`` (rows, cols, 3),
             ``experimental_data`` and ``variance`` (rows, cols, n_beams) and the
             pre-refined ``geometry`` dict; ``g_include`` (n_beams, 3) labels the
             experimental beam axis.
   :rtype: tuple