pyextal.jaxMultipole.wien2k
===========================

.. py:module:: pyextal.jaxMultipole.wien2k

.. autoapi-nested-parse::

   WIEN2k output as reference data: structure factors (lapw3) and density maps (lapw5).

   ``case.output3``
       The section ``X - RAY STRUCTURFACTORS`` lists one reflection per family,
       ``h k l  sin(theta)/lambda  F`` -- the *static* crystal X-ray structure
       factors of the self-consistent density (no thermal factor), as magnitudes.
       :func:`read_output3` returns them; :func:`observations` maps them onto a
       `Crystal`'s canonical keys, with signs from a model, as ``'xray_static'``
       observations a multipole model can be fitted to.
   ``case.rho``
       A lapw5 map: a header ``nx ny xlen ylen`` (bohr) and ``nx * ny`` values in
       e/bohr^3, five per line. With the ``DIFF`` switch it is the crystal density
       minus superposed free atoms -- the deformation density. The plane is set by
       the first three lines of ``case.in5``: origin, x end and y end as integer
       numerators over a common divisor (fractional coordinates).



Functions
---------

.. autoapisummary::

   pyextal.jaxMultipole.wien2k.read_output3
   pyextal.jaxMultipole.wien2k.observations
   pyextal.jaxMultipole.wien2k.read_in5
   pyextal.jaxMultipole.wien2k.read_rho
   pyextal.jaxMultipole.wien2k.rho_plane_points


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

.. py:function:: read_output3(path)

   The crystal structure factors of a lapw3 output.

   :returns: ``(hkl (n, 3) int, s (n,), F (n,))``, F in electrons per cell.
   :rtype: tuple


.. py:function:: observations(path, model, p_sign=None, smax=None, sigma=(0.005, 0.001), drop_000=True)

   WIEN2k structure factors as ``'xray_static'`` observations of ``model``'s crystal.

   :param path: ``case.output3``.
   :type path: path-like
   :param model: Supplies the families (canonical keys) and the
                 signs (lapw3 prints magnitudes; the crystal here is centrosymmetric
                 with the origin on an inversion centre, so the sign is all that is
                 missing).
   :type model: MultipoleModel
   :param p_sign: Parameters for the signs; the IAM by default.
   :type p_sign: array, optional
   :param smax: Keep s <= smax (A^-1).
   :type smax: float, optional
   :param sigma: ``(absolute, relative)``: sigma = abs + rel |F|, a
                 weight for a fit to theory, which has no measurement error.
   :type sigma: tuple

   :returns: Observations


.. py:function:: read_in5(path)

   ``(origin, x_end, y_end)`` of a lapw5 plane, fractional coordinates.


.. py:function:: read_rho(path, angstrom=True)

   A lapw5 map.

   :returns: ``(rho (nx, ny), xlen, ylen)``; rho in e/A^3 and lengths in A
             when ``angstrom`` (else e/bohr^3 and bohr). ``rho[i, j]`` is the point
             ``origin + i/(nx-1) (x_end - origin) + j/(ny-1) (y_end - origin)``.
   :rtype: tuple


.. py:function:: rho_plane_points(crystal, in5, nx, ny)

   Cartesian points (A) of a lapw5 grid, and in-plane coordinates (A).

   :returns: ``(points (nx, ny, 3), U (nx, ny), V (nx, ny))`` with U along
             x_end - origin and V along y_end - origin, both from the origin.
   :rtype: tuple