lir_achem.compute_HF_absorption

This modules computes the HF absorption

Functions

`absorption_coefficient`(today, glat, glon, ...)	Compute the absorption coefficients at the given altitude (from Davies, 1990) The notations of the code are those of Zawdie et al., 2017 (Equation 2)
`absorption_coefficient_eccles`(n_here, ...)	Compute the absorption coefficients at the given altitude (from Davies, 1990) The notations of the code are those of Eccles et al., 2005 (Equation 3)
`appleton_hartree`(altitudes, n_here, ions, ...)	Compute the square of the index of refraction at the given altitude The notations of the code are those of Zawdie et al., 2017 (Equations 3 to 6)
`compute_frequencies`(e_here, B[, altitude])	Compute the plasma frequency and the cyclotron frequency at altitude 'altitude'
`compute_total_absorption`(f, today, glat, ...)	Compute the total HF absorption for a wave launched vertically at frequency f as described in Davies, 1990 (around p215)
`get_HF_absorption_from_scratch`(today, glon, ...)	Runs the entire pipeline to get an estimate of the HF absorption at that location
`highest_altitude_wave`(fN, f, altitudes)	Computes the highest altitude reached by the wave.
`magnetic_theta_and_B`(today, glat, glon[, ...])	Computes the angle of the field to the vertical and the total magnetic field

lir_achem.compute_HF_absorption.compute_total_absorption(f, today, glat, glon, e_here, n_here, ions, pm, abs_coeff='AH', ignore_B=False)[source]

Compute the total HF absorption for a wave launched vertically at frequency f as described in Davies, 1990 (around p215)

Parameters:

f – Frequency of the wave (Hz)
today – Datetime, time of the computation
glat/glon – Latitude/Longitude for the computation
e_here – Electron class instance
n_here – Neutrals class instance
ions – List of ions class instance (ions participating in the absorption)
pm – Defines whether we use ‘+’ or ‘-’ in the denominator of the Appleton-Hartree equation. It correspond to choosing a polarisation for the propagating wave. If pm = 1, we will choose ‘+’, if not, we will chose ‘-’
abs_coeff – String, chooses which form of the absorbtion coefficent we use. ‘HA’-> We solve the Appleton Hartree equation (default). ‘Eccles’-< we use the form proposed in Eccles et al., 2005
ignore_B – Ignore B field. Default: False

lir_achem.compute_HF_absorption.highest_altitude_wave(fN, f, altitudes)[source]

Computes the highest altitude reached by the wave. If its frequency is below the plasma frequency, it is reflected at this altitude. If not, the function returns the highest altitude of the D-region

Parameters:

fN – Array, plasma frequency (in Hz). Its size must match the one of e_here
f – Frequency of the wave (in Hz)
altitudes – Altitudes array (in km)

Returns:

altitude_reflected: Altitude at which the wave is reflected

lir_achem.compute_HF_absorption.absorption_coefficient_eccles(n_here, e_here, ions, f)[source]

Compute the absorption coefficients at the given altitude (from Davies, 1990) The notations of the code are those of Eccles et al., 2005 (Equation 3)

Parameters:

n_here – Neutrals class instance
e_here – Electron class instance
ions – List of ions class instance, ions participating in the absorption
f – Frequency of the VLF wave (in Hz)

Returns:

kappa, absorption coefficent (same shape than altitudes, in dB/km)

lir_achem.compute_HF_absorption.absorption_coefficient(today, glat, glon, altitudes, n_here, ions, e_here, f, pm, phi, ignore_B=False, theta=None, B=None)[source]

Compute the absorption coefficients at the given altitude (from Davies, 1990) The notations of the code are those of Zawdie et al., 2017 (Equation 2)

Parameters:

today – Datetime, date at the computation
glat/glon – Latitude/longitude of the point
altitudes – 1D Array, altitudes for the computation (in km)
n_here – Neutrals class instance
ions – List of ions class instance
e_here – Electron class instance
f – Frequency of the VLF wave (in Hz)
pm – Defines whether we use ‘+’ or ‘-’ in the denominator of the Appleton-Hartree equation. It correspond to choosing a polarisation for the propagating wave. If pm = 1, we will choose ‘+’, if not, we will chose ‘-’
phi – Angle of the wave with the vertical (in °)
ignore_B – Ignore magnetic field (Boolean). Default: False
theta – Angle between the wave and the magnetic field for each altitude (default: None)
B – Norm of the magnetic field at each altitude (Default: None)

Returns:

kappa, absorption coefficent (same shape than altitudes, in dB/km)

lir_achem.compute_HF_absorption.appleton_hartree(altitudes, n_here, ions, e_here, f, pm, theta, B, ignore_B=True)[source]

Compute the square of the index of refraction at the given altitude The notations of the code are those of Zawdie et al., 2017 (Equations 3 to 6)

Parameters:

n_here – Neutrals class instance
ions – List of ions class instance
e_here – Electron class instance
f – Frequency of the VLF wave (in Hz)
pm – Defines whether we use ‘+’ or ‘-’ in the denominator of the Appleton-Hartree equation. It correspond to choosing a polarisation for the propagating wave. If pm = 1, we will choose ‘+’, if not, we will chose ‘-’
theta – Angle of the wave with the B field (Array, same size as altitudes)
B – Magnetic field (in T). Array, same size as altitudes

Returns:

n_2, square of the refractive index. n_2 has the same shape as altitudes. vah, total collision frequency. theta, angle (in °) of the wave compared to the B field (to avoid computing it again). fecf, electron cyclotron frequency (in s-1) to avoid recomputing

lir_achem.compute_HF_absorption.compute_frequencies(e_here, B, altitude=75)[source]

Compute the plasma frequency and the cyclotron frequency at altitude ‘altitude’

Parameters:

e_here – Electrons class instance
B – Norm of the magnetic field (may be obtained through magnetic_theta_and_B)
altitude – Altitude at the computation (in km). Default: 75 km

Returns:

fN, plasma frequency (s-1) and fecf, electron collision frequency (s-1)

lir_achem.compute_HF_absorption.magnetic_theta_and_B(today, glat, glon, altitude=75, phi=0)[source]

Computes the angle of the field to the vertical and the total magnetic field

Parameters:

today – Datetime, time for the computation
glat/glon – Latitude and longitude for the computation
altitude – Altitude at the computation (in km). Default: 75 km
phi – Angle of the wave with the vertical (in °, 0° is upwards). Default: 0

Returns:

theta, angle of the magnetic field and the vertical, B, norm of the field

lir_achem.compute_HF_absorption.get_HF_absorption_from_scratch(today, glon, glat, EUV_file, XR_file, time_end, f, chi=None, AH_O=True, AH_X=True, Ec=True, ignore_B=False, time_initialisation=4000.0, time_HF=60, alpha=None, compute_sza=False, HXR_bins=True, max_altitude=90, file_manual_ini_neutrals=None, file_manual_ini_ions=None, time_first_ini=40)[source]

Runs the entire pipeline to get an estimate of the HF absorption at that location

Parameters:

today – Datetime, must be timezone-blind BUT the time must correspond to the UT time
glon/glat – Geographic longitude and latitude (in °)
EUV_file – Filename with the daily EUV average (from GOES)
XR_file – Filename with the 1s XR flux (from GOES)
time_end – Maximum number of second after today when we run the simulation. today MUST be in quiet time since it is used for the initialisation
f – HF frequency of the waves (in Hz). Maybe an array
chi – If it is specified, will run everything as normal BUT the sza will be set to the specified value (Default: None)
AH_O – Boolean, if True computes the absorption of a HF vertical wave (O-mode) using Appleton-Hartree equation (Default:True)
AH_X – Boolean, if True computes the absorption of a HF vertical wave (X-mode) using Appleton-Hartree equation (Default:True)
Ec – Boolean, if True computes the absorption of a HF vertical wave using the equation in Eccles, 2005 (Default:True)
ignore_B – Boolean. If True, we ignore the contribution of the magnetic field. Default:False
time_initialisation – Number of seconds needed to initialise the ions the second time (Default:4000)
time_HF – Time resolution to compute the HF absorption (Default:60, meaning one point out of 60 in the output)
alpha – If specified, corrects [NO] with alpha, thus only initialising ions once (Default: None)
compute_sza – Boolean. If True, the solar zenith angle will be recomputed at each time step and the absorption, Ch and H recomputed. Default:False
HXR_bins – Boolean, default:True. If True, the ionisation from HXR will be discretized in bins. If False, it will only be caused by the average HXR wavelength of GOES data.
max_altitude – Maximum altitude of the D-region (Default, 90). Physically, the only constraint is the ionisation of O2(1Dg), which is only valid below 90 km (Paulsen, 1972). However, we can set this to None, in which case it will be limited by FIRI, or to another value above 60 km
file_manual_ini_neutrals – Default: None. If a path to a pickle file is specified with precomputed neutral profiles, the neutrals will be initialised from the file. Note: This file must contain exactly the attributes of the neutrals class instance (see documentation)
file_manual_ini_ions – Default: None. If a path to a pickle file is specified with precomputed ions profiles, the ions will be initialised from the file. Note: This file must contain all ions and electron profiles (see documentation for the required format)
time_first_ini – Time (in s) for the first initialisation (without adjusted NO). Default: 40

Returns:

A dictionnary, countaining the different ion and electron densities through time, the time and altitudes array abd the estimation of the HF absorption using the Appleton Hartree equation or the one from Eccles et al., (2005)