pyextal.jaxMultipole.protocol
=============================

.. py:module:: pyextal.jaxMultipole.protocol

.. autoapi-nested-parse::

   A staged refinement protocol for data that constrain the valence density weakly.

   The silicon test (Zuo et al. 1997) and the SrTiO3 LARBED fits point to the same
   recipe when the data are few, or confined to one plane of reciprocal space:

   0. **ADPs from high-order data alone.** Above s ~ 0.7 A^-1 the valence density
      contributes almost nothing, so the IAM with refined U_ij describes those
      reflections, and the U_ij it gives are not contaminated by bonding. They are
      then *fixed* (Zuo fixes B the same way).
   1. **charge**: valence populations and the anion's kappa; electroneutrality
      eliminates one population; sites listed in ``fixed`` keep given values (e.g.
      Sr from a fit to theory, where the data alone cannot separate it).
   2. **+ quadrupole**: the anion's bond-directed P20, the one aspherical term with
      a clear physical meaning (O along Ti-O in SrTiO3).
   3. **+ d populations**: the transition metal's cubic hexadecapole refined as eg /
      t2g orbital populations, bounded at zero (`params.SiteRefine(dpop=True)`).

   kappa' stays fixed throughout -- exponent and populations trade off even on
   excellent data (kappa'/octupole correlation 0.93 for Si). Every step is kept or
   rejected by Hamilton's test against the previous one.



Functions
---------

.. autoapisummary::

   pyextal.jaxMultipole.protocol.adp_from_high_order
   pyextal.jaxMultipole.protocol.protocol_steps
   pyextal.jaxMultipole.protocol.run_protocol


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

.. py:function:: adp_from_high_order(model, obs, smin=0.7, device='cpu', sites=None)

   IAM refinement of the U_ij on the reflections with s >= smin.

   :returns: ``(FitResult, start dict of the refined U_ij)``.
   :rtype: tuple


.. py:function:: protocol_steps(model, anion='O1', metal='Ti1', fixed_sites=(), quadrupoles=('P20', ), refine_U=False, metal_pv=('Pv_3d', ))

   The ladder after the ADP step: charge -> + anion quadrupole -> + metal d populations.

   :param model: Its metal site needs the d orbitals in a shell
                 of their own for step 3.
   :type model: MultipoleModel
   :param anion: Site labels.
   :type anion: str
   :param metal: Site labels.
   :type metal: str
   :param fixed_sites: Sites whose populations stay at their start.
   :type fixed_sites: sequence
   :param quadrupoles: Anion multipoles of step 2.
   :type quadrupoles: tuple
   :param refine_U: Keep refining U (for static data set False; U is moot).
   :type refine_U: bool
   :param metal_pv: The metal populations refined in steps 1-2.
   :type metal_pv: tuple


.. py:function:: run_protocol(model, obs, start=None, smin=0.7, adp=True, fixed_sites=(), dependent=None, device='cpu', log=print, **kw)

   Steps 0-3; returns ``(adp FitResult or None, ladder, start dict)``.