abinslib.isotropic_incoherent
=============================

.. py:module:: abinslib.isotropic_incoherent

.. autoapi-nested-parse::

   Incoherent phonon mode intensities in the fully-isotropic approximation.



Functions
---------

.. autoapisummary::

   abinslib.isotropic_incoherent.calculate_isotropic_incoherent_fundamentals
   abinslib.isotropic_incoherent.calculate_isotropic_dw_factor
   abinslib.isotropic_incoherent.calculate_isotropic_incoherent_spectra
   abinslib.isotropic_incoherent.q_scaling_isotropic_incoherent_spectra


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

.. py:function:: calculate_isotropic_incoherent_fundamentals(modes: euphonic.QpointPhononModes, mode_displacements: euphonic.Quantity, atomic_displacements: euphonic.Quantity, nominal_q2: euphonic.Quantity, include_dw: bool = True) -> numpy.ndarray

   Calculate mode intensities in fully-isotropic approximation.

   S = exp(-(Q^2 tr(A)/3)) Q^2 tr(B) / 3

   - Fundamentals only
   - Atomic cross sections not applied
   - Ignore actual q-points and use nominal Q^2 instead

   Return array indices (qpt, mode, atom)



.. py:function:: calculate_isotropic_dw_factor(atomic_displacements: euphonic.Quantity, q2: euphonic.Quantity) -> numpy.ndarray

   Calculate fully-isotropic Debye-Waller factor.

   The dot product between atomic displacements and Q vector is replaced with
   a scalar product between Q and tr(A)/3.

   :param atomic_displacements: displacement tensors with shape (natoms, 3, 3),
                                corresponding to sum over phonon modes with <2n+1> Bose statistics.
                                Generally this is obtained using
                                :func:`abinslib.displacements.Displacements.to_atomic_displacements()`
   :param q2: scalar Q^2 array of arbitrary shape and length^-2 dimensions

   :returns: Debye-Waller factor array with shape ``(natoms, *q2.shape)``


.. py:function:: calculate_isotropic_incoherent_spectra(modes: euphonic.QpointPhononModes, mode_displacements: abinslib.Displacements, atomic_displacements: euphonic.Quantity, nominal_q2: euphonic.Quantity, bins: euphonic.Quantity, apply_cross_section: bool = True, include_dw: bool = True) -> euphonic.spectra.Spectrum1DCollection

   Calculate INS intensities in fully-isotropic incoherent approximation.

   Actual q-points of phonon modes will be disregarded; instead each mode
   intensity will be based on a separate array of nominal Q^2 values
   corresponding to modes. This is intended to approximate powder-averaging
   with kinematic constraints: for indirect geometry the energy-Q^2
   relationship can be determined using abinslib.utils.calculate_indirect_q2.

   :param modes: phonon frequency and eigenvector dataset
   :param mode_displacements: phonon mode displacement dataset
                              (This can be obtained using :func:`Displacements.from_modes(modes)`.)
   :param atomic_displacements: thermal average atomic displacements indexed
                                (atom, direction, direction)
   :param nominal_q2: Scalar Q^2 values corresponding to modes; note that all q-points
                      are used and this is typically related to the mode frequency by
                      neutron instrument parameters.
   :param bins: Energy or frequency bins used as x_data in resulting spectra
   :param apply_cross_section: Multiply each atom/isotope spectrum by a corresponding total
                               neutron scattering cross-section (σ_tot).
   :param include_dw: Multiply each spectrum by Debye-Waller factor; this is calculated
                      from atomic_displacements and follows nominal_q2.

   :returns: binned spectra of contribution from each nucleus


.. py:function:: q_scaling_isotropic_incoherent_spectra(modes: euphonic.QpointPhononModes, mode_displacements: abinslib.Displacements, atomic_displacements: euphonic.Quantity, nominal_q2: euphonic.Quantity, bins: euphonic.Quantity) -> euphonic.spectra.Spectrum1DCollection

   Calculate INS intensities in fully-isotropic incoherent approximation.

   Note that to give expected results, mode_displacements should have N+1 Bose
   occupation and atomic_displacements should have 2N+1 occupation.

   Actual q-points of phonon modes will be disregarded; instead each mode
   intensity will be calculated at Q=1/Å then rescaled to nominal Q^2 values
   corresponding to energy bins. This is intended to approximate
   powder-averaging with kinematic constraints: for indirect geometry the
   energy-Q^2 relationship can be determined using
   abinslib.utils.calculate_indirect_q2.

   :param modes: phonon frequency and eigenvector dataset
   :param mode_displacements: phonon mode displacement dataset
                              (This can be obtained using :func:`Displacements.from_modes(modes)`.)
   :param atomic_displacements: thermal average atomic displacements indexed
                                (atom, direction, direction)
   :param nominal_q2: Scalar Q^2 values corresponding to output bin centers.
   :param bins: Energy or frequency bins used as x_data in resulting spectra
   :param apply_cross_section: Multiply each atom/isotope spectrum by a corresponding total
                               neutron scattering cross-section (σ_tot).

   :returns: binned spectra of contribution from each nucleus