pyextal.jaxMultipole.settings
=============================

.. py:module:: pyextal.jaxMultipole.settings

.. autoapi-nested-parse::

   Settings of a multipole fit, and the ladder of nested models it runs.

   A fit is defined by four things: the crystal (the ``.dat`` the Bloch
   refinements used), the data, how each site is modelled (`AtomSpec` fields) and
   which parameters each step of the ladder refines (`SiteRefine` fields).

   The default ladder adds one physical ingredient per step and is judged by
   Hamilton's test at each one::

       IAM+ADP   symmetry-allowed U_ij only, neutral spherical atoms
       +Pv       valence populations (one eliminated by electroneutrality)
       +kappa    valence expansion/contraction
       +Plm      the symmetry-allowed multipoles (kappa' fixed)
       +kappa_p  kappa'   (only when ``ladder_kappa_p`` is set)

   A site whose spec has ``lmax = -1`` never gets multipoles; ``fix_kappa`` names
   sites whose kappa stays at 1 throughout (Sr in Friis et al. 2004).



Classes
-------

.. autoapisummary::

   pyextal.jaxMultipole.settings.FitSettings


Functions
---------

.. autoapisummary::

   pyextal.jaxMultipole.settings.default_ladder


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

.. py:class:: FitSettings

   Everything a `jaxMultipole.cli` run needs.

   :ivar dat: Crystal ``.dat`` (cell, atoms, space group, voltage).
   :vartype dat: str
   :ivar h5: Dataset HDF5 files, or glob patterns, for the per-scan runs.
   :vartype h5: list
   :ivar notes: Notes prefix selecting the runs (``'geo'``: per-scan).
   :vartype notes: str
   :ivar run: ``'latest'`` or a run key.
   :vartype run: str
   :ivar method: ``'robust'`` or ``'mean'`` aggregation (`data.from_scan_runs`).
   :vartype method: str
   :ivar clip: Robust rejection threshold, sigma.
   :vartype clip: float
   :ivar sigma: ``'std'`` or ``'sem'``.
   :vartype sigma: str
   :ivar min_n: Minimum measurements per family.
   :vartype min_n: int
   :ivar floor: ``(absolute, relative)`` sigma floor.
   :vartype floor: tuple
   :ivar joint_json: Take central values from this joint run,
                     sigmas from the scans.
   :vartype joint_json: str, optional
   :ivar tables: Extra data, ``dict(path=..., kind='xray')``.
   :vartype tables: list[dict]
   :ivar exclude: Families to leave out, as ``[h, k, l]``.
   :vartype exclude: list
   :ivar smax: Leave out reflections beyond this s.
   :vartype smax: float, optional
   :ivar sites: ``label -> AtomSpec`` keyword dict.
   :vartype sites: dict
   :ivar fix_kappa: Sites whose kappa is never refined.
   :vartype fix_kappa: list[str]
   :ivar ladder: ``[(name, {label: SiteRefine kwargs})]``;
                 `default_ladder` when None.
   :vartype ladder: list, optional
   :ivar ladder_kappa_p: Append a kappa' step to the default ladder.
   :vartype ladder_kappa_p: bool
   :ivar restraints: ``dict(name='Ti1.kappa_p', target=1, sigma=0.05)``.
   :vartype restraints: list[dict]
   :ivar start: Physical starting values, ``{'O1.Pv': 6.5}``.
   :vartype start: dict
   :ivar dependent: Population eliminated by electroneutrality.
   :vartype dependent: str, optional
   :ivar out: Output prefix (``<out>.json``, ``<out>.txt``, maps).
   :vartype out: str
   :ivar maps: Deformation-density planes: ``dict(name, origin, u,
               v, extent=(-2, 2, -2, 2), n=121)`` in fractional / lattice units.

   :vartype maps: list[dict]


   .. py:attribute:: dat
      :type:  str
      :value: None



   .. py:attribute:: h5
      :type:  list
      :value: []



   .. py:attribute:: notes
      :type:  str
      :value: 'geo'



   .. py:attribute:: run
      :type:  str
      :value: 'latest'



   .. py:attribute:: method
      :type:  str
      :value: 'robust'



   .. py:attribute:: clip
      :type:  float
      :value: 4.0



   .. py:attribute:: sigma
      :type:  str
      :value: 'std'



   .. py:attribute:: min_n
      :type:  int
      :value: 3



   .. py:attribute:: floor
      :type:  tuple
      :value: (2e-05, 0.0)



   .. py:attribute:: joint_json
      :type:  str
      :value: None



   .. py:attribute:: tables
      :type:  list
      :value: []



   .. py:attribute:: exclude
      :type:  list
      :value: []



   .. py:attribute:: smax
      :type:  float
      :value: None



   .. py:attribute:: sites
      :type:  dict


   .. py:attribute:: fix_kappa
      :type:  list
      :value: []



   .. py:attribute:: ladder
      :type:  list
      :value: None



   .. py:attribute:: ladder_kappa_p
      :type:  bool
      :value: False



   .. py:attribute:: restraints
      :type:  list
      :value: []



   .. py:attribute:: start
      :type:  dict


   .. py:attribute:: dependent
      :type:  str
      :value: None



   .. py:attribute:: out
      :type:  str
      :value: 'multipole_fit'



   .. py:attribute:: maps
      :type:  list
      :value: []



.. py:function:: default_ladder(model, fix_kappa=(), kappa_p=False)

   The nested sequence of refinements described in the module docs.