pyextal.jaxJoint.settings
=========================

.. py:module:: pyextal.jaxJoint.settings

.. autoapi-nested-parse::

   Every option of a joint refinement, in one place.

   A joint refinement is a list of `jaxGeo.RefineSettings`, one per dataset, that
   agree on the options deciding the shared parameters and the schedule of the one
   optimiser (`JOINT_FIELDS`). `JointSettings` holds the options common to all
   datasets in ``common`` and each dataset's departures from them in ``datasets``;
   `JointSettings.resolved` merges the two and checks them.



Attributes
----------

.. autoapisummary::

   pyextal.jaxJoint.settings.JOINT_FIELDS
   pyextal.jaxJoint.settings.WEIGHTINGS


Classes
-------

.. autoapisummary::

   pyextal.jaxJoint.settings.JointSettings


Functions
---------

.. autoapisummary::

   pyextal.jaxJoint.settings.display_names
   pyextal.jaxJoint.settings._as_dict


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

.. py:data:: JOINT_FIELDS
   :value: ('symmetry', 'imag', 'layers', 'refine_layers', 'steps', 'warmup', 'lr', 'geometry',...


.. py:data:: WEIGHTINGS
   :value: ('pixels', 'equal')


.. py:function:: display_names(paths)

   Short names that tell the datasets apart.

   The file stem when the stems differ. Otherwise the first path component,
   counting up from the file, that differs between the datasets, without the
   prefix they all share up to its last ``_``, ``-`` or space -- so
   ``.../STO_..._30pA_R5/refinement/STO_001.h5`` and ``.../STO_..._30pA_R4/
   refinement/STO_001.h5`` become ``R5`` and ``R4``.

   :param paths: Dataset paths.
   :type paths: sequence

   :returns: list[str]


.. py:function:: _as_dict(entry)

.. py:class:: JointSettings

   Options for `jaxJoint.refine.refine`.

   :param common: Options every dataset starts from, including all
                  of `JOINT_FIELDS`.
   :type common: RefineSettings
   :param datasets: One entry per dataset: a dict of the fields that
                    differ from ``common`` (at least ``h5``), a full `RefineSettings`,
                    or just the dataset path.
   :type datasets: sequence
   :param names: Display names; default `display_names`.
   :type names: sequence, optional
   :param weighting: ``'pixels'`` weights each dataset's mean chi^2 by its number
                     of data points, so the loss is the chi^2 of all of them pooled;
                     ``'equal'`` averages the datasets' chi^2; a sequence gives explicit
                     relative weights.
   :param out_dir: Where the joint summary goes; default the
                   first dataset's folder.
   :type out_dir: Path, optional


   .. py:attribute:: common
      :type:  pyextal.jaxGeo.settings.RefineSettings


   .. py:attribute:: datasets
      :type:  Tuple
      :value: ()



   .. py:attribute:: names
      :type:  Optional[Tuple[str, ...]]
      :value: None



   .. py:attribute:: weighting
      :type:  Union[str, Tuple[float, ...]]
      :value: 'pixels'



   .. py:attribute:: out_dir
      :type:  Optional[pathlib.Path]
      :value: None



   .. py:method:: resolved()

      Checks the options and returns a canonical copy.

      :returns: ``common`` resolved, ``datasets`` as a tuple of
                resolved `RefineSettings`, ``names`` filled in and ``weighting`` as
                'pixels', 'equal' or a tuple of floats.
      :rtype: JointSettings

      :raises SetupError: On an inconsistent option, a dataset setting a joint
          field, or the same file twice.