pyextal.jaxJoint.datasets
=========================

.. py:module:: pyextal.jaxJoint.datasets

.. autoapi-nested-parse::

   Setting up the datasets and the shared structure factors.

   Three passes, each dataset with the engine switched to it:

   1. load the dataset and its ``.dat``, validate the geometry model, and decide
      which reflections it asks to refine (``reflections``, as in `jaxGeo`);
   2. take the union of those, as canonical keys: every one becomes a shared
      parameter, used in **every** dataset whose structure matrix holds it, so the
      crystal has one potential across all of them -- whether or not that dataset
      measured the reflection;
   3. build each dataset's configuration and metadata with every orbit member of
      the union in its beam list requested (whichever one the engine picks as its
      label is then among them), link each label to its canonical key and check
      the link against the engine.



Attributes
----------

.. autoapisummary::

   pyextal.jaxJoint.datasets.KIND_NAMES


Classes
-------

.. autoapisummary::

   pyextal.jaxJoint.datasets.Dataset


Functions
---------

.. autoapisummary::

   pyextal.jaxJoint.datasets._load
   pyextal.jaxJoint.datasets._configure
   pyextal.jaxJoint.datasets._weights
   pyextal.jaxJoint.datasets.prepare
   pyextal.jaxJoint.datasets._describe


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

.. py:class:: Dataset(index, name, settings)

   One dataset of a joint refinement, and its refinement state.

   Attributes set at setup: ``index``, ``name``, ``settings`` (its resolved
   `RefineSettings`), ``h5``, ``dat``, ``data``, ``g_include``, ``constants``,
   ``model`` (`GeometryModel`), ``fns`` (its JAX geometry functions),
   ``config``, ``metadata``, ``links`` (``(local key, canonical key, M)`` in
   the dataset's reflection order), ``selected`` (canonical keys it asked to
   refine), ``n_points`` and ``weight``.

   Refinement state: ``x`` (geometry vector), ``tilts``, ``geo_config``,
   ``hessian``, ``checked``, ``geo_history`` and ``loss_history``.


   .. py:attribute:: x


   .. py:attribute:: geo_config
      :value: None



   .. py:attribute:: hessian


   .. py:attribute:: checked


   .. py:attribute:: geo_history
      :value: []



   .. py:attribute:: loss_history
      :value: []



   .. py:attribute:: active


   .. py:attribute:: units


   .. py:method:: __repr__()


.. py:function:: _load(ds, engine, dry_run)

   Pass 1: data, ``.dat``, constants, geometry model, reflection choice.


.. py:function:: _configure(ds, engine, union, symmetry, centro, settings)

   Pass 3: config and metadata with the union requested, then the links.


.. py:function:: _weights(datasets, weighting)

.. py:function:: prepare(js, engine)

   Loads and sets up every dataset, and builds the joint parameter tree.

   :param js: Resolved.
   :type js: JointSettings
   :param engine: Empty; the datasets are added to it.
   :type engine: EngineSwitch

   :returns: ``(datasets, G, table)`` -- the `Dataset` list, the joint
             tree and the shared-parameter table (`shared_table`).
   :rtype: tuple

   :raises SetupError: If the datasets cannot be refined together.


.. py:data:: KIND_NAMES

.. py:function:: _describe(m)

   ``'+'``, ``'-'``, ``'*'`` (conjugate), ``'-*'`` or the phase in degrees.