pyextal.jaxMultipole.params
===========================

.. py:module:: pyextal.jaxMultipole.params

.. autoapi-nested-parse::

   Which physical parameters are refined, and how they are tied.

   The model evaluates a full physical vector ``p`` (`jaxMultipole.model.Layout`).
   A refinement varies a much smaller vector ``x``, mapped linearly:

   .. math::

       \mathbf p = \mathbf p_0 + M \mathbf x .

   The columns of ``M`` carry everything structural:

   * site symmetry -- each allowed multipole function and each allowed ADP
     direction is one column (``O1.P20``; ``Ti1.P40`` with ``P44+ = 0.7404536
     P40`` folded in; ``O1.U22`` meaning ``U22 = U33``), so the refinement cannot
     leave the symmetry-allowed subspace;
   * freezing -- a parameter without a column stays at ``p0``;
   * electroneutrality -- one valence population is made dependent, so that
     ``sum_j occ_j mult_j (P_c + P_v + P00) = sum_j occ_j mult_j Z_j`` holds
     exactly for every ``x``.

   Each column is named after the leading coefficient of its basis vector, so the
   refined values read as ordinary ``P_lm`` and ``U_ij``. Covariances map back as
   ``M C_x M^T``.

   d-orbital populations
   ---------------------

   On a cubic transition-metal site (m-3m, -43m, ...) the d shell's population and
   its cubic hexadecapole can be refined as the electrons per eg and per t2g
   orbital instead (``SiteRefine(dpop=True)``; Holladay, Leung & Coppens 1983):

       Pv(d) = 2 n_eg + 3 n_t2g,    P40 = 0.214942 (2 n_eg - 2 n_t2g),

   with ``P44+ = 0.7404536 P40``. Bounds keep both populations between 0 and 2, so
   a fit can no longer reach the negative orbital populations an unconstrained
   P40 produces on weak data. The two columns are named ``<site>.n_eg`` and
   ``<site>.n_t2g``; their values are ``ParameterMap.extra[name] + x``.



Classes
-------

.. autoapisummary::

   pyextal.jaxMultipole.params.SiteRefine
   pyextal.jaxMultipole.params.ParameterMap


Functions
---------

.. autoapisummary::

   pyextal.jaxMultipole.params.build_parameter_map


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

.. py:class:: SiteRefine

   Refinement switches for one site.

   :ivar Pv: Refine the valence population(s); a list of names
             (``['Pv_3d']``) refines only those shells.
   :vartype Pv: bool | list
   :ivar kappa: Refine kappa.
   :vartype kappa: bool
   :ivar kappa_p: Refine kappa'.
   :vartype kappa_p: bool
   :ivar multipoles: ``'allowed'`` for every symmetry-allowed
                     function with ``1 <= l <= lmax`` of the spec, ``[]`` for none, or a
                     list of leading labels (``['P20', 'P40']``) to pick from the allowed
                     ones. ``P00`` is only refined when named explicitly.
   :vartype multipoles: str | list
   :ivar U: Refine the symmetry-allowed U_ij.
   :vartype U: bool
   :ivar dpop: Refine the d shell as eg / t2g orbital populations (cubic
               sites only; replaces that shell's Pv and the l = 4 function).

   :vartype dpop: bool


   .. py:attribute:: Pv
      :type:  bool
      :value: True



   .. py:attribute:: kappa
      :type:  bool
      :value: True



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



   .. py:attribute:: multipoles
      :type:  object
      :value: 'allowed'



   .. py:attribute:: U
      :type:  bool
      :value: True



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



.. py:class:: ParameterMap

   ``p = p0 + M x``.

   :ivar names: Free-parameter names, one per column of ``M``.
   :vartype names: list[str]
   :ivar p0: Physical starting vector.
   :vartype p0: np.ndarray
   :ivar M: ``(len(p0), len(names))``.
   :vartype M: np.ndarray
   :ivar lower, upper: Box bounds on ``x``.
   :vartype lower, upper: np.ndarray
   :ivar x0: Starting ``x`` (zeros unless the start was shifted).
   :vartype x0: np.ndarray
   :ivar dependent: The population eliminated by neutrality.
   :vartype dependent: str | None
   :ivar layout: The model's layout, for name look-ups.
   :vartype layout: Layout
   :ivar extra: Free parameters that are not themselves physical layout
                entries (``n_eg``, ``n_t2g``) -> their value at ``x = 0``.

   :vartype extra: dict


   .. py:attribute:: names
      :type:  list


   .. py:attribute:: p0
      :type:  numpy.ndarray


   .. py:attribute:: M
      :type:  numpy.ndarray


   .. py:attribute:: lower
      :type:  numpy.ndarray


   .. py:attribute:: upper
      :type:  numpy.ndarray


   .. py:attribute:: x0
      :type:  numpy.ndarray


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



   .. py:attribute:: layout
      :type:  object
      :value: None



   .. py:attribute:: extra
      :type:  dict


   .. py:method:: __len__()


   .. py:method:: p(x)


   .. py:method:: p_cov(cov_x)


   .. py:method:: value(x, name)

      A physical parameter, e.g. ``'O1.U33'`` or ``'Sr1.Pv'``, or an ``extra`` one.



.. py:function:: build_parameter_map(model, refine=None, neutral=True, dependent=None, start=None)

   Assembles the free parameters of a refinement.

   :param model: The model.
   :type model: MultipoleModel
   :param refine: ``site label -> SiteRefine`` (or a dict of its
                  fields). Sites not listed get ``SiteRefine()`` -- everything allowed,
                  except kappa' -- while ``'cm'`` sites refine their ADPs only.
   :type refine: dict, optional
   :param neutral: Enforce electroneutrality.
   :type neutral: bool
   :param dependent: The population to eliminate, e.g.
                     ``'O1.Pv'``; the last refined one by default.
   :type dependent: str, optional
   :param start: Physical starting values overriding the
                 model's ``p0`` (``{'O1.Pv': 6.4, 'Ti1.kappa': 1.02}``).
   :type start: dict, optional

   :returns: ParameterMap