Dionne
======

.. toctree::
   :maxdepth: 4
   :hidden:

Presentation
------------

This model provides the |SEEY| :math:`\delta`.
All the terms in its expression have a physical meaning.
In its original version :cite:`Lye1957,Dionne1973,Dionne1975`, it does not take the incidence angle of |PEs| into account.
For a 3D version, see :ref:`Dionne 3D <dionne3d-link>`.

Input files
-----------

This model should preferably be fitted to |SEEY| data, although it can also be fitted to |TEEY| data.

+-----------------------------+---------------+-----------------------------+---------------------------+
|                             |Emission Yield |Emission energy distribution |Emission angle distribution|
+=============================+===============+=============================+===========================+
| "True" secondaries          | ✅            | ❌                          | ❌                        |
+-----------------------------+---------------+-----------------------------+---------------------------+
| Elastically backscattered   | ❌            | ❌                          | ❌                        |
+-----------------------------+---------------+-----------------------------+---------------------------+
| Inelastically backscattered | ❌            | ❌                          | ❌                        |
+-----------------------------+---------------+-----------------------------+---------------------------+
| Total                       | ✅            | ❌                          | ❌                        |
+-----------------------------+---------------+-----------------------------+---------------------------+

Definitions
-----------

The |SEEY| is given by:

.. math::
   \delta = G \cdot T \cdot S

Where :math:`G` is the mean number of |SEs| generated by a |PE| of energy :math:`E`.
:math:`T` is their probability of reaching the surface.
:math:`S` is their probability of crossing the surface.

Range
^^^^^

:math:`G` and :math:`T` depend on the range, denoted :math:`R`, which is the depth reached by the |PE| in the material.
We assume that the |PE| loses its energy following a power law.
This is called the *power law* or *Thomson-Whiddington model* :cite:`Whiddington1914`.

.. math::
    R = \frac{E^n}{A\cdot n}

where :math:`A` and :math:`n` are obtained by fitting.

.. note::
    This is currently the only energy loss model implemented.
    However, it has been shown that it was not suitable at low energies.
    *Continuous Slowing-Down Approximation* (CSDA) :cite:`Young1956` may be better suited:

    .. math::
       \frac{\mathrm{d}E}{\mathrm{d}x} = - E / R

    CSDA may also be inaccurate at low-energies, were the range is almost constant.
    See Refs. :cite:`Inguimbert2017,Inguimbert2017a` for an alternative model.

Generation term
^^^^^^^^^^^^^^^

This is the probability for an incident electron with an energy :math:`E` to generate a secondary electron.

.. math::
   G = \frac{1}{R}\frac{E}{\xi}

:math:`\xi` is the energy required to excite a secondary electron in the material.
We set it to the work function of the material :cite:`Dionne1975` even if, in reality, :math:`\xi > W_f`.
Note that, in reality, this parameter can be set to anything, as the product :math:`A\cdot\xi` appears in the
final expression and :math:`A` is fitted.

Transport term
^^^^^^^^^^^^^^

This is the probability that a generated secondary electron reaches the
sample surface.

.. math::
   T = d\left(1-\mathrm{e}^{-R/d}\right)

where the diffusion length :math:`d` is the typical distance between to |SE|-material interactions.
It is determined by fitting.

Escape term
^^^^^^^^^^^

This is a constant obtained by fitting.

Other expression
^^^^^^^^^^^^^^^^

In the original Dionne paper :cite:`Dionne1973`, the |SEEY| expression is:

.. math::
   \delta = \frac{B}{\xi} \left( \frac{An}{\alpha} \right)^{1/n} \left( \alpha d \right)^{(1-n)/n} \left( \mathrm{e}^{-\alpha d} \right)

As this expression is not simplified and does not make appear physical parameters explicit, it is not used.
Correspondency between the notations used here and in Dionne's paper are listed below.

+------------------------------+---------------------+--------------------------------+
| Quantity                     | Notation in EEmiLib | Notation in :cite:`Dionne1973` |
+==============================+=====================+================================+
| Escape term                  | :math:`S`           | :math:`B`                      |
+------------------------------+---------------------+--------------------------------+
| Diffusion length/attenuation | :math:`d`           | :math:`1/\alpha`               |
+------------------------------+---------------------+--------------------------------+
| Range                        | :math:`R`           | :math:`d`                      |
+------------------------------+---------------------+--------------------------------+

Model parameters
----------------

The parameters list is dynamically created here: :py:mod:`Dionne API documentation<.dionne>`.

To-do list
----------

.. todo::
   - Handle |SEEY| vs |TEEY| files.
   - Set up tests.
