pyextal.jaxMultipole.maps
=========================

.. py:module:: pyextal.jaxMultipole.maps

.. autoapi-nested-parse::

   Static deformation density maps in direct space.

   ``Delta rho = rho_multipole - rho_IAM``: the valence shells at the refined
   population and kappa minus the neutral spherical atoms, plus every deformation
   term, summed over all atoms (orbit images and neighbouring cells) within
   ``cutoff`` of the plane. No thermal smearing -- a *static* map -- and no Fourier
   series, so it carries no truncation ripple; with ~30 reflections a Fourier
   residual map would be mostly ripple.

   Each image of an asymmetric atom at ``W x + w`` carries its density rotated by
   the Cartesian ``R = A W A^-1``: ``rho_j(r) = rho_0(R^T (r - r_j))``, evaluated in
   the asymmetric atom's local frame ``F`` as ``F R^T (r - r_j)``.



Functions
---------

.. autoapisummary::

   pyextal.jaxMultipole.maps.shell_density
   pyextal.jaxMultipole.maps.plane_grid
   pyextal.jaxMultipole.maps.deformation_density
   pyextal.jaxMultipole.maps.plane_atoms
   pyextal.jaxMultipole.maps.plot_map


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

.. py:function:: shell_density(shell, r_A, renormalize=True)

   One electron's worth of a shell's spherical density, e/Angstrom^3.


.. py:function:: plane_grid(crystal, origin, u, v, extent=(-2.0, 2.0, -2.0, 2.0), n=121)

   Cartesian points of a plane through ``origin`` spanned by ``u`` and ``v``.

   :param origin: Fractional coordinates of the centre.
   :type origin: array-like
   :param u: Direct-lattice directions; ``v`` is orthogonalised
             to ``u``.
   :type u: array-like
   :param v: Direct-lattice directions; ``v`` is orthogonalised
             to ``u``.
   :type v: array-like
   :param extent: ``(umin, umax, vmin, vmax)`` in Angstrom.
   :type extent: tuple
   :param n: Points per side.
   :type n: int

   :returns: ``(points (n, n, 3) Cartesian, U, V)`` with ``U``, ``V`` the
             in-plane coordinates in Angstrom.
   :rtype: tuple


.. py:function:: deformation_density(model, p, points, cutoff=6.5, terms='all')

   ``rho_model - rho_IAM`` at Cartesian ``points``, e/Angstrom^3.

   :param model: The model ('cm' sites contribute nothing).
   :type model: MultipoleModel
   :param p: Physical parameters (e.g. ``FitResult.p``).
   :type p: array-like
   :param points: ``(..., 3)`` Cartesian positions, Angstrom.
   :type points: np.ndarray
   :param cutoff: Atom images farther than this from a point are left
                  out at that point. The diffuse shells (Ti 4s, Sr 5s) still carry
                  ~1e-3 e/A^3 at 4 A, which shows as steps where an image crosses the
                  cutoff; at 6.5 A their tails are ~1e-5.
   :type cutoff: float
   :param terms: ``'all'`` -- the full static deformation density;
                 ``'spherical'`` -- only the valence shells' change (population and
                 kappa); ``'multipole'`` -- only the ``P_lm`` terms, the aspherical
                 part. Cores are frozen, so they cancel in every case.
   :type terms: str

   :returns: Shape ``points.shape[:-1]``.
   :rtype: np.ndarray


.. py:function:: plane_atoms(crystal, origin, u, v, extent=(-2.0, 2.0, -2.0, 2.0), tol=0.05)

   Atoms lying in a plane (within ``tol`` Angstrom), as in-plane coordinates.

   :returns: ``(site label, element, U, V)`` for every image inside
             ``extent`` (with a small margin).
   :rtype: list[tuple]


.. py:function:: plot_map(U, V, rho, ax=None, step=0.05, vmax=0.4, title=None, atoms=None)

   Contour plot: solid positive, dashed negative, dotted zero.

   Contours stop at ``+-vmax`` (0.4 e/A^3, the range of Friis et al.'s Fig. 5);
   near the nuclei a deformation map is steep and would otherwise be solid ink.
   ``vmax=None`` contours the full range.