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 .

The simplest way to obtain the HF absorption estimate is to run the function get_HF_absorption_from_scratch().

The first step is to import the different libraries needed:

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:

# 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:

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 (get_HF_absorption_from_scratch()). Of particular importance is time_HF which controls the time-resolution for the HF absorption and alpha which avoids the first ion initialisation if alpha is already known.

Important

By default, the solar zenith angle will be assumed constant throughout the modelling. This can be changed by specifying compute_sza=True to the 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 tau, Ch and H (Absorption of the solar flux). 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:

  • the_time: time array (in s), from 0 to time_end which is the end of the simulation specified in the code

  • altitudes: Altitudes array (in km)

  • electrons: Electron density (in \(cm^{-3}\)). It has a shape altitude * the_time.

  • O2m, Xm, NOp, Yp, O2p, O4p: Ions density (same format as electrons). They are respectively the densities of \(O_2^-\), \(X^-\), \(NO^+\), \(Y^+\), \(O_2^+\) and \(O_4^+\)

  • Phi_SXR and Phi_HXR: same format as electrons, those are the absorbed soft and hard X-ray fluxes in the D-region

  • tau_SXR and tau_HXR are the absorption coefficients for the solar flux (see Absorption of the solar flux)

  • HF_AH_O, HF_AH_X and HF_Ec are the HF absorption using different formulations for the absorption coefficient (see Computing the HF absorption). They are in the format the_time*f.

  • f, the frequencies in Hz that we inputted in the computation

  • time_HF: Time array for the HF absorption computation

  • date: Date, in the format yyyymmdd

  • glat/glon: Latitude/longitude (in °)

  • sza: Solar zenith angle (in °)

  • alpha: Factor multiplied to \([NO]\) as given by [mitra1966] to obtain the correct electron density at 75 km (see Neutral densities)

The different variables may be called like this:

the_time = output["the_time"]

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

import pickle

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

and apklfile may be imported into a python dictionary as:

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 is given to help create those files. To use them, two optional argument can be given to the get_HF_absorption_from_scratch():

  • file_manual_ini_ions, which should point to a pkl file with the correct format (see Notebook) for the initialisation of the ion and electron profiles

  • file_manual_ini_neutrals for the neutrals

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