.. _class_definition:

Main objects
=======================

This package is organised around 4 classes, representing real-life objects:

* :py:class:`~lir_achem.class_definition.electrons`

* :py:class:`~lir_achem.class_definition.ions`

* :py:class:`~lir_achem.class_definition.radiation`

* :py:class:`~lir_achem.class_definition.neutrals`

Details about each of those classes are presented below.

Neutrals
----------------------

The neutral class is the most complex of the four classes. In this single class are all the different neutral species, as attributes to the class:

* :py:obj:`altitudes` for the altitude range of the neutrals. It must go higher than the D-region altitudes, since neutrals contribute to the absorption of the solar flux
* :py:obj:`N2, O2, O, He, Ar, H, N, AO, NO, H2O, O3`: Densities (in cm-3) of the various chemical species in the atmosphere. :py:obj:`AO` is the anomalous oxygen.
* :py:obj:`M` is the sum of :py:obj:`O2` and :py:obj:`N2`
* :py:obj:`Tn` is the neutrals temperature
* :py:obj:`f107` is the f10.7 indice
* :py:obj:`glat/glon`: geographic latitude and longitude (in °) of the point of interest

To initialise this class, you need the time (:py:obj:`time_here`) as a timezone-unaware datetime, the :py:obj:`altitudes` for the computation, and the latitude and longitude (:py:obj:`glat` and :py:obj:`glon`) in °. For more details on the initialisation of the different species, please refer to :ref:`neutrals_ini`.

.. code-block::

    n_here = neutrals(today, altitudes, glat, glon)

Electrons
----------------------

The :py:class:`~lir_achem.class_definition.electrons` class represents the electrons present in the D-region. Those are initialised from FIRI [friedrich2018]_, although they are set to 0 at the beginning of the modelling. The initialisation thus only serves as a guideline, and for use in chemistry scheme coefficient, but it does not intervene at t=0 for the electron density.

This class has several attributes:

* :py:obj:`altitudes`: Altitudes (in km) in the D-region
* :py:obj:`densities`: Density (in cm-3) of electrons in the D-region, for each altitude in :py:obj:`altitudes`
* :py:obj:`temperature`: Temperature (in K) of the electrons, assuming that they have the same as the ions

To initialise the electron class, you need the latitude :py:obj:`glat` (in °), the longitude :py:obj:`glon` (in °), the time as a datetime (:py:obj:`today`) and the value of the f10.7 parameter. This last value may be obtained through the neutrals class. You also need the value of the neutral class initialised previously (:py:obj:`n_here`) to have the temperature.

.. code-block::

    e_here = electrons(glat, glon, today, n_here.f107, n_here)


Radiation
----------------------

The radiation class keeps track of the solar radiation. Its attributes are:

* :py:obj:`HXR, SXR, EUV`: Soft X-rays, Hard X-rays and EUV fluxes at the specified time
* :py:obj:`EUV_times, EUV_array`: Time-array for EUV data and EUV data. This should be the EUV daily average from GOES
* :py:obj:`XR_times, SXR_array, HXR_array`: X-ray data (soft and hard) and time-array. This should be the 1s fluxes from GOES
* :py:obj:`tau_SXR, tau_HXR, tau_EUV`: Absorption factors for SXR HXR and EUV fluxes (see :ref:`absorption`). They are arrays with the same shape as the altitudes
* :py:obj:`altitudes_D`: Altitudes in the D-region
* :py:obj:`Ch` and :py:obj:`H`: Values of the Chapman function and H, to avoid having to recomputes them each time

To initialise this class, you need:

* :py:obj:`today`: Datetime, timezone-unaware, date of the computation
* :py:obj:`file_EUV, file_XR`: Complete path to the EUV and XR data
* :py:obj:`altitudes_D`: Altitudes (in km) in the D-region
* :py:obj:`n_here`: Neutrals class instance
* :py:obj:`chi`: Solar zenith angle in °

.. code-block::

    rad_here = radiation(today, EUV_file, XR_file, altitudes_D, n_here, chi)

This class also has a method, :py:obj:`~lir_achem.class_definition.radiation.get_flux_now` which updates the values of the SXR and HXR fluxes.

Ions
------------------

The ion class is the simplest. It has only three parameters:

* :py:obj:`altitudes`: Altitudes (in km) arrays
* :py:obj:`density`: Density of the ion (in cm-3). It should have the same shape as the altitudes array
* :py:obj:`z`: Number charge of the ion

Everything should be inputted by hand, once the ion density is known (after the chemistry code has run for example)

.. code-block::

    O2m = cd.ion_species(e_here.altitudes, -1) # density is not initialised here
    O2m.density = example_density_array