.. module:: ase.utils.xrdebye

===========================
X-ray scattering simulation
===========================


The module for simulation of X-ray scattering properties from the atomic
level. The approach works only for finite systems, so that periodic boundary
conditions and cell shape are ignored.

Theory
======

The scattering can be calculated using Debye formula [Debye1915]_ :

.. math::

    I(q) = \sum_{a, b} f_a(q) \cdot f_b(q) \cdot
    \frac{\sin(q \cdot r_{ab})}{q \cdot r_{ab}}

where:

- `a` and `b` -- atom indexes;
- `f_a(q)` -- `a`-th atomic scattering factor;
- `r_{ab}` -- distance between atoms `a` and `b`;
- `q` is a scattering vector length defined using scattering angle
  (`\theta`) and wavelength (`\lambda`) as
  `q = 4\pi \cdot \sin(\theta)/\lambda`.

The thermal vibration of atoms can be accounted by introduction of damping
exponent factor (Debye-Waller factor) written as `\exp(-B \cdot q^2 / 2)`.
The angular dependency of geometrical and polarization factors are expressed
as [Iwasa2007]_ `\cos(\theta)/(1 + \alpha \cos^2(2\theta))`, where `\alpha
\approx 1` if incident beam is not polarized.


Units
-----

The following measurement units are used:

- scattering vector `q` -- inverse Angstrom (1/Å),
- thermal damping parameter `B` -- squared Angstrom (Å\ :sup:`2`).


Example
=======

The considered system is a nanoparticle of silver which is built using
``FaceCenteredCubic`` function (see :mod:`ase.cluster`) with parameters
selected to produce approximately 2 nm sized particle::

  from ase.cluster.cubic import FaceCenteredCubic
  from ase.utils.xrdebye import XrDebye
  import numpy as np

  surfaces = [(1, 0, 0), (1, 1, 0), (1, 1, 1)]
  atoms = FaceCenteredCubic('Ag', [(1, 0, 0), (1, 1, 0), (1, 1, 1)],
                            [6, 8, 8], 4.09)

Next, we need to specify the wavelength of the X-ray source::

  xrd = XrDebye(atoms=atoms, wavelength=0.50523)

The X-ray diffraction pattern on the `2\theta` angles ranged from 15 to 30
degrees can be simulated as follows::

  xrd.calc_pattern(x=np.arange(15, 30, 0.1), mode='XRD')
  xrd.plot_pattern('xrd.png')

The resulted X-ray diffraction pattern shows (220) and (311) peaks at 20 and
~24 degrees respectively.

.. image:: xrd.png

The small-angle scattering curve can be simulated too. Assuming that
scattering vector is ranged from `10^{-2}=0.01` to `10^{-0.3}\approx 0.5` 1/Å
the following code should be run: ::

  xrd.calc_pattern(x=np.logspace(-2, -0.3, 50), mode='SAXS')
  xrd.plot_pattern('saxs.png')

The resulted SAXS pattern:

.. image:: saxs.png


Further details
===============

The module contains wavelengths dictionary with X-ray wavelengths for copper
and wolfram anodes::

  from ase.utils.xrdebye import wavelengths
  print('Cu Kalpha1 wavelength: %f Angstr.' % wavelengths['CuKa1'])


The dependence of atomic form-factors from scattering vector is calculated
based on coefficients given in ``waasmaier`` dictionary according
[Waasmaier1995]_ if method of calculations is set to 'Iwasa'. In other case,
the atomic factor is equal to atomic number and angular damping factor is
omitted.


XrDebye class members
---------------------

.. autoclass:: XrDebye
   :members:


References
==========

.. [Debye1915] P. Debye  Ann. Phys. **351**, 809–823 (1915)
.. [Iwasa2007] T. Iwasa, K. Nobusada J. Phys. Chem. C, **111**, 45-49 (2007) :doi:`10.1021/jp063532w`
.. [Waasmaier1995] D. Waasmaier, A. Kirfel Acta Cryst. **A51**, 416-431 (1995)
