Quickstart
=============================

This package is designed to model the D-region during solar flares and estimate the HF absorption that will result from the electron density increase. Below is an example of each steps and the different functions that can be called. Further examples may be found in the `Notebooks <https://codeberg.org/pteysseyre/D-region-ion-scheme/src/branch/main/Notebooks>`_ .

The simplest way to obtain the HF absorption estimate is to run the function :py:func:`~lir_achem.compute_HF_absorption.get_HF_absorption_from_scratch`.

The first step is to import the different libraries needed:

.. code-block:: ruby

    import lir_achem.compute_HF_absorption as cha

    import numpy as np
    import matplotlib.pyplot as plt
    import datetime as dt
    import matplotlib as mpl
    import pickle


Then, we need to define the time and location of the computation, as well as the time (in s) for which we want to run the computation:

.. code-block:: ruby

    # Day and time of interest
    today = dt.datetime(
        2023, 11, 5, 11, 36, 0, 0
    )  # The timezeone should not be put here (msise00 doesn't accept it)

    # Lattitude and longitude (in °)
    glon = 8.82
    glat = 42.4

    # Files for the EUV and XR fluxes (from GOES daily EUV flux and 1s XR fluxes)
    la_date = today.strftime("%Y%m%d")
    EUV_file = "/Volumes/LaCie/GOES/sci_euvs-l2-avg1d_g18_s20220909_e20251104_v1-0-6.nc"
    XR_file = "/Volumes/LaCie/GOES/FLUX/sci_xrsf-l2-flx1s_g16_d" + la_date + "_v2-2-0.nc"

    # Frequencies (in Hz) for which we compute the absorption
    f = np.array([1e6, 5e6, 10e6, 30e6])

    # Time end: time (in s) after start when we want to run the model
    time_end = 10


To obtain the different ions and electron species and compute the HF absorption, you can run the following command:

.. code-block:: ruby

    output = cha.get_HF_absorption_from_scratch(today, glon, glat, EUV_file, XR_file, time_end, f)


There are optional parameters that can be specified to the function. Those are described in the description of the function (:py:func:`~lir_achem.compute_HF_absorption.get_HF_absorption_from_scratch`). Of particular importance is :py:obj:`time_HF` which controls the time-resolution for the HF absorption and :py:obj:`alpha` which avoids the first ion initialisation if :py:obj:`alpha` is already known.

.. important::

    By default, the solar zenith angle will be assumed constant throughout the modelling. This can be changed by specifying :py:obj:`compute_sza=True` to the :py:func:`~lir_achem.compute_HF_absorption.get_HF_absorption_from_scratch` function. In this case, at each iteration in time, the solar zenith angle will be recomputed, along with the values of :py:obj:`tau`, :py:obj:`Ch` and :py:obj:`H` (:ref:`absorption`). This impacts the solar flux absorption, and thus the ionisation coefficients. However, due to the additional computation, the computation time is longer.

Output
----------------

The output variable is a dictionnary, with different keys:

* :py:obj:`the_time`: time array (in s), from 0 to :py:obj:`time_end` which is the end of the simulation specified in the code
* :py:obj:`altitudes`: Altitudes array (in km)
* :py:obj:`electrons`: Electron density (in :math:`cm^{-3}`). It has a shape `altitude * the_time`.
* :py:obj:`O2m`, :py:obj:`Xm`, :py:obj:`NOp`, :py:obj:`Yp`, :py:obj:`O2p`, :py:obj:`O4p`: Ions density (same format as :py:obj:`electrons`). They are respectively the densities of :math:`O_2^-`, :math:`X^-`, :math:`NO^+`, :math:`Y^+`, :math:`O_2^+` and :math:`O_4^+`
* :py:obj:`Phi_SXR` and :py:obj:`Phi_HXR`: same format as :py:obj:`electrons`, those are the absorbed soft and hard X-ray fluxes in the D-region
* :py:obj:`tau_SXR` and :py:obj:`tau_HXR` are the absorption coefficients for the solar flux (see :ref:`absorption`)
* :py:obj:`HF_AH_O`, :py:obj:`HF_AH_X` and :py:obj:`HF_Ec` are the HF absorption using different formulations for the absorption coefficient (see :ref:`HF_abs`). They are in the format `the_time*f`.
* :py:obj:`f`, the frequencies in Hz that we inputted in the computation
* :py:obj:`time_HF`: Time array for the HF absorption computation
* :py:obj:`date`: Date, in the format `yyyymmdd`
* :py:obj:`glat/glon`: Latitude/longitude (in °)
* :py:obj:`sza`: Solar zenith angle (in °)
* :py:obj:`alpha`: Factor multiplied to :math:`[NO]` as given by [mitra1966]_ to obtain the correct electron density at 75 km (see :ref:`neutrals_ini`)

The different variables may be called like this:

.. code-block:: python

    the_time = output["the_time"]


The output may be save in a file with the command:

.. code-block:: python

    import pickle

    with open('saved_dictionary.pkl', 'wb+') as f:
        pickle.dump(output, f)


and a\ ``pkl``\ file may be imported into a python dictionary as:

.. code-block:: ruby

    with open('saved_dictionary.pkl', 'rb') as f:
        output = pickle.load(f)


.. tip::

    The longest step in the entire computation is the initialisation of ions. Thus, we let an option to give files with pre-computed neutral and/or ions/electron profiles which would be taken as initial densities. A `Notebook <https://codeberg.org/pteysseyre/D-region-ion-scheme/src/branch/main/Notebooks/Create_optional_input_file.ipynb>`_  is given to help create those files. To use them, two optional argument can be given to the :py:func:`~lir_achem.compute_HF_absorption.get_HF_absorption_from_scratch`:

    - :py:obj:`file_manual_ini_ions`, which should point to a :py:obj:`.pkl` file with the correct format (see Notebook) for the initialisation of the ion and electron profiles
    - :py:obj:`file_manual_ini_neutrals` for the neutrals

    Note that both can be specified, or only one of them.