pyextal.blochwave
=================

.. py:module:: pyextal.blochwave


Attributes
----------

.. autoapisummary::

   pyextal.blochwave.constants
   pyextal.blochwave.cryst
   pyextal.blochwave.difpar
   pyextal.blochwave.bloch_module
   pyextal.blochwave.sfpar
   pyextal.blochwave.xtal
   pyextal.blochwave.spgr
   pyextal.blochwave.eigen
   pyextal.blochwave.mpiinfo
   pyextal.blochwave.sfmanager
   pyextal.blochwave.gram


Classes
-------

.. autoapisummary::

   pyextal.blochwave.Constants
   pyextal.blochwave.Cryst
   pyextal.blochwave.Difpar
   pyextal.blochwave.BlochModule
   pyextal.blochwave.Sfpar
   pyextal.blochwave.Xtal
   pyextal.blochwave.Spgr
   pyextal.blochwave.Eigen
   pyextal.blochwave.Mpiinfo
   pyextal.blochwave.Sfmanager
   pyextal.blochwave.Gram


Functions
---------

.. autoapisummary::

   pyextal.blochwave.bloch_parse
   pyextal.blochwave.defaultsf
   pyextal.blochwave.resetugh
   pyextal.blochwave.larbed
   pyextal.blochwave.larbed2
   pyextal.blochwave.beamcheck
   pyextal.blochwave.bloch_run
   pyextal.blochwave.dryrun
   pyextal.blochwave.tilt_run


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

.. py:class:: Constants

   .. py:attribute:: pi
      :type:  float


   .. py:attribute:: twopi
      :type:  float


   .. py:attribute:: ratio
      :type:  numpy.ndarray


   .. py:attribute:: dkv
      :type:  float


   .. py:attribute:: hv
      :type:  float


   .. py:attribute:: vol
      :type:  float


   .. py:attribute:: build_version
      :type:  str


   .. py:attribute:: build_date
      :type:  str


.. py:class:: Cryst

   .. py:attribute:: label
      :type:  numpy.ndarray


   .. py:attribute:: cell
      :type:  numpy.ndarray


   .. py:attribute:: abx
      :type:  numpy.ndarray


   .. py:attribute:: zt
      :type:  numpy.ndarray


   .. py:attribute:: v0
      :type:  float


   .. py:attribute:: itype
      :type:  numpy.ndarray


   .. py:attribute:: iftype
      :type:  numpy.ndarray


   .. py:attribute:: atpar
      :type:  numpy.ndarray


   .. py:attribute:: smult
      :type:  numpy.ndarray


   .. py:attribute:: dw
      :type:  numpy.ndarray


   .. py:attribute:: natoms
      :type:  int


   .. py:attribute:: ntype
      :type:  int


.. py:class:: Difpar

   .. py:attribute:: nbeams
      :type:  int


   .. py:attribute:: ncore
      :type:  int


   .. py:attribute:: nidptr
      :type:  int


   .. py:attribute:: nref
      :type:  int


   .. py:attribute:: hkl
      :type:  numpy.ndarray


   .. py:attribute:: idptr
      :type:  numpy.ndarray


   .. py:attribute:: kv
      :type:  float


   .. py:attribute:: bigk
      :type:  float


   .. py:attribute:: ratio1
      :type:  float


   .. py:attribute:: abm
      :type:  float


   .. py:attribute:: sgmax
      :type:  float


   .. py:attribute:: sgmin
      :type:  float


   .. py:attribute:: omgmx
      :type:  float


   .. py:attribute:: gamma
      :type:  float


   .. py:attribute:: wavel
      :type:  float


   .. py:attribute:: gx
      :type:  numpy.ndarray


   .. py:attribute:: gy
      :type:  numpy.ndarray


   .. py:attribute:: zone
      :type:  numpy.ndarray


   .. py:attribute:: snorm
      :type:  numpy.ndarray


   .. py:attribute:: hklf
      :type:  numpy.ndarray


   .. py:attribute:: vhkl
      :type:  numpy.ndarray


   .. py:method:: allocate_arrays_difpar() -> None


   .. py:method:: deallocate_arrays_difpar() -> None


   .. py:method:: updatekv(kv_new: float) -> None


.. py:class:: BlochModule

   .. py:attribute:: ughr
      :type:  numpy.ndarray


   .. py:attribute:: ughi
      :type:  numpy.ndarray


   .. py:attribute:: cinv
      :type:  numpy.ndarray


   .. py:attribute:: v
      :type:  numpy.ndarray


   .. py:attribute:: cc
      :type:  numpy.ndarray


   .. py:attribute:: ig
      :type:  numpy.ndarray


   .. py:attribute:: ipvt
      :type:  numpy.ndarray


   .. py:attribute:: ndiag
      :type:  int


   .. py:method:: allocate_arrays_bloch(nbeams: int) -> None


   .. py:method:: deallocate_arrays_bloch() -> None


.. py:class:: Sfpar

   .. py:attribute:: stab
      :type:  numpy.ndarray


   .. py:attribute:: ftab
      :type:  numpy.ndarray


   .. py:attribute:: ftab2
      :type:  numpy.ndarray


   .. py:attribute:: ntab
      :type:  numpy.ndarray


   .. py:attribute:: istab
      :type:  int


.. py:class:: Xtal

   .. py:attribute:: atm
      :type:  numpy.ndarray


   .. py:attribute:: xyz
      :type:  numpy.ndarray


   .. py:attribute:: xyz0
      :type:  numpy.ndarray


   .. py:attribute:: jtype
      :type:  numpy.ndarray


   .. py:attribute:: jftype
      :type:  numpy.ndarray


   .. py:attribute:: nsite
      :type:  int


.. py:class:: Spgr

   .. py:attribute:: aspg
      :type:  str


   .. py:attribute:: alag
      :type:  str


   .. py:attribute:: syst
      :type:  str


   .. py:attribute:: ngp
      :type:  int


   .. py:attribute:: centro
      :type:  int


   .. py:attribute:: ncsub4
      :type:  int


   .. py:attribute:: gp
      :type:  numpy.ndarray


   .. py:attribute:: csub4
      :type:  numpy.ndarray


.. py:class:: Eigen

   .. py:attribute:: ndiags
      :type:  numpy.ndarray


   .. py:attribute:: eigenvectors
      :type:  numpy.ndarray


   .. py:attribute:: cinvs
      :type:  numpy.ndarray


   .. py:attribute:: eigenvalues
      :type:  numpy.ndarray


   .. py:attribute:: tilt
      :type:  numpy.ndarray


   .. py:method:: check_allocated_eigen() -> bool


   .. py:method:: check_size_eigen(nbeams: int, ntilt: int, nout: int) -> bool


   .. py:method:: allocate_arrays_eigen(nbeams: int, ntilt: int, nout: int) -> None


   .. py:method:: deallocate_arrays_eigen() -> None


   .. py:method:: allocate_tilt(ntilt: int) -> None


   .. py:method:: deallocate_tilt() -> None


.. py:class:: Mpiinfo

   .. py:attribute:: intercomm
      :type:  int


   .. py:attribute:: first
      :type:  bool


   .. py:method:: mpiinfo_despawn() -> None


.. py:class:: Sfmanager

   .. py:method:: e2xray(gg: numpy.ndarray, value: numpy.ndarray) -> numpy.ndarray


.. py:class:: Gram

   .. py:attribute:: gmx
      :type:  numpy.ndarray


   .. py:attribute:: gmxr
      :type:  numpy.ndarray


.. py:data:: constants
   :type:  Constants

.. py:data:: cryst
   :type:  Cryst

.. py:data:: difpar
   :type:  Difpar

.. py:data:: bloch_module
   :type:  BlochModule

.. py:data:: sfpar
   :type:  Sfpar

.. py:data:: xtal
   :type:  Xtal

.. py:data:: spgr
   :type:  Spgr

.. py:data:: eigen
   :type:  Eigen

.. py:data:: mpiinfo
   :type:  Mpiinfo

.. py:data:: sfmanager
   :type:  Sfmanager

.. py:data:: gram
   :type:  Gram

.. py:function:: bloch_parse(fname: str, t_x: float = 0.0, t_y: float = 0.0) -> Tuple[int, int, numpy.ndarray, float, float, numpy.ndarray, numpy.ndarray, numpy.ndarray]

   Parses a .dat input file and initializes the simulation parameters.

   :param fname: Path to the .dat input file.
   :param t_x: Additional tilt in x direction (degrees). Default is 0.0.
   :param t_y: Additional tilt in y direction (degrees). Default is 0.0.

   :returns:     - nout (int): Number of reflections to be output.
                 - nx2 (int): Sampling size.
                 - hklout (np.ndarray): (3, 1000) integer array of output reflections.
                 - disks (float): Convergence angle/disk radius.
                 - alpha (float): Angle between zone axis and surface normal.
                 - tilt0 (np.ndarray): (3, 3) real array of incident beam direction and disk centers.
                 - gvx (np.ndarray): (3,) real array of horizontal reciprocal vector.
                 - gvy (np.ndarray): (3,) real array of vertical reciprocal vector.
   :rtype: A tuple containing


.. py:function:: defaultsf(id: int, gg: numpy.ndarray) -> Tuple[float, float, float, float, float]

   Calculates the default structure factor for a given reflection.

   :param id: Atom type index.
   :param gg: (3,) reflection vector (h, k, l).

   :returns:     - ss (float): Scattering vector length squared.
                 - xfre (float): Real part of the X-ray structure factor.
                 - xfim (float): Imaginary part of the X-ray structure factor.
                 - afre (float): Real part of the absorption structure factor.
                 - afim (float): Imaginary part of the absorption structure factor.
   :rtype: A tuple containing


.. py:function:: resetugh() -> None

   Resets and updates the Ugh (potential) matrices in the bloch_module.


.. py:function:: larbed(depth: float, ntilt: int, alpha: float, gg: numpy.ndarray, nout: int) -> numpy.ndarray

   Calculates the LARBED (Large Angle Rocking Beam Electron Diffraction) pattern.

   :param depth: Sample thickness in Angstroms.
   :param ntilt: Number of tilt positions.
   :param alpha: Convergence angle.
   :param gg: (3,) reciprocal space vector.
   :param nout: Number of output reflections.

   :returns: (ntilt * nout,) real array of intensities.
   :rtype: yt (np.ndarray)


.. py:function:: larbed2(depth: numpy.ndarray, nout: int, alpha: float, gg: numpy.ndarray) -> numpy.ndarray

   Calculates the LARBED pattern with thickness varying for each tilt.

   :param depth: (ntilt,) real array of sample thicknesses.
   :param nout: Number of output reflections.
   :param alpha: Convergence angle.
   :param gg: (3,) reciprocal space vector.

   :returns: (ntilt * nout,) real array of intensities.
   :rtype: yt (np.ndarray)


.. py:function:: beamcheck(tiltCheck: numpy.ndarray) -> int

   Checks the number of beams within the excitation error limit for a given tilt.

   :param tiltCheck: (3,) real array of the tilt vector.

   :returns: Number of diagonal elements (beams) included.
   :rtype: ndiagCheck (int)


.. py:function:: bloch_run(nout: int, tilt0: numpy.ndarray, gg: numpy.ndarray, g_horizontal: numpy.ndarray, pixsiz: float, subAper: int, subnx: numpy.ndarray, subny: numpy.ndarray, ncores: int, collector: Callable[[int, numpy.ndarray, int, int, int], int]) -> int

   Runs the Bloch wave simulation over a range of tilts, using MPI if enabled.

   :param nout: Number of output reflections.
   :param tilt0: (3,) incident tilt vector.
   :param gg: (3,) reciprocal space vector.
   :param g_horizontal: (3,) horizontal direction in reciprocal space.
   :param pixsiz: Pixel size in reciprocal space.
   :param subAper: Aperture type.
   :param subnx: (2,) sampling range in x.
   :param subny: (2,) sampling range in y.
   :param ncores: Number of MPI cores to use.
   :param collector: Callback function to collect results for each tilt.

   :returns: Total number of tilts simulated.
   :rtype: ntilt (int)


.. py:function:: dryrun(nout: int, tilt0: numpy.ndarray, gg: numpy.ndarray, g_horizontal: numpy.ndarray, pixsiz: float, subAper: int, subnx: numpy.ndarray, subny: numpy.ndarray, ncores: int) -> float

   Calculates the estimated memory usage for a simulation.

   :param nout: Number of output reflections.
   :param tilt0: (3,) incident tilt vector.
   :param gg: (3,) reciprocal space vector.
   :param g_horizontal: (3,) horizontal direction in reciprocal space.
   :param pixsiz: Pixel size in reciprocal space.
   :param subAper: Aperture type.
   :param subnx: (2,) sampling range in x.
   :param subny: (2,) sampling range in y.
   :param ncores: Number of MPI cores to use.

   :returns: Estimated memory usage.
   :rtype: memuse (float)


.. py:function:: tilt_run(nout: int, indices: numpy.ndarray, ncores: int) -> None

   Runs the Bloch wave simulation for specific indices using MPI.

   :param nout: Number of output reflections.
   :param indices: (nhklout,) integer array of reflection indices.
   :param ncores: Number of MPI cores to use.