.. _LMP:

Estimating the electron density
=========================================

Background
----------------------

An important quantity to estimate in real-time is the electron density profile in the D-region. The simplest model to consider
for this profile is the *Wait profile* [wait1964]_. This assumes that the electron density profile is an exponential given by:

.. math::
    Ne = 1.43 \times 10^{13} \exp(-0.15 h') \exp\left[(\beta - 0.15)(z - h')\right]
    :label: wait

where :math:`h'` is the effective ionosphere height and :math:`\beta` is linked to the electron density gradients.

Therefore, an estimation of the electron density can be obtained by estimating :math:`h'` and :math:`\beta`.

Use of the LMP model
-----------------------------

To estimate those values, the `Longwave Mode Propagator <https://fgasdia.github.io/LongwaveModePropagator.jl/dev/>`_ [gasdia2021]_
can be used.

This code models the amplitude and phase of the propagating VLF waves in the Earth-Ionosphere waveguide. By using this code, it
is therefore possible to have an estimate of the values of the amplitude and phase at the position of the receiver for different
values of :math:`h'` and :math:`\beta`.

.. note::
    It is assumed that the user has used the LMP model beforehand, (see `Longwave Mode Propagator <https://fgasdia.github.io/LongwaveModePropagator.jl/dev/>`_ for the model
    documentation and tutorials) to create tables of modelled amplitude and phase at the receiver site, for each transmitter that
    is followed.

It is furthermore assumed that those tables have a name such as `AmplitudeCALLSIGN.csv` and `PhaseCALLSIGN.csv`. They should be of the form

.. list-table:: AmplitudeNAA.csv
    :header-rows: 1
    :widths: 25 25 25

    * -
      - :math:`\beta_1`
      - :math:`\beta_2`
    * - :math:`h'_1`
      - Amplitude
      - Amplitude
    * - :math:`h'_2`
      - Amplitude
      - Amplitude

Finding the correct :math:`h'` and :math:`\beta`
--------------------------------------------------------

The goal now is to find the values of :math:`h'` and :math:`\beta` that reproduce best the measurements in amplitude and phase.
This is handled by the :py:func:`vlf4ions.compute_electron_density.LMP_findminimum` function, which uses the golden ratio method to find those values. So far, it
find the parameter values that represent best the results; therefore, it is assumed that there is no noise in the data.
This is a simplification, and may cause some problems. However, the parameters are computed independently for any point
in time (for any couple Amplitude/Phase), and that the results found when applying this to real time-series do not present much
variations in the parameters (see Example).

.. important::
    Because of errors in the calibration of the antenna, and because there is an uncertainty on the value of the phase, it is not
    possible to directly use the measured values. Instead, the variations of the amplitude and phase to their pre-flare levels are
    used, througth the :py:attr:`~vlf4ions.class_definition.station.DA` and :py:attr:`~vlf4ions.class_definition.station.DP` station class attributes.

    The quiet values of the amplitude and phase are taken as a reference, and it is assumed that the electron densities that would
    be computed from them match the expected ones [mcraethomson2000]_. The quiet values of the parameters :math:`h'` and :math:`\beta`
    only depend on the solar zenith angle at the middle of the path, which is stored as a parameter of the :py:class:`~vlf4ions.class_definition.station` class.