Application Programming Interface

This library contains components for PyIRTAM software.

References

Forsythe et al. (2023), PyIRI: Whole-Globe Approach to the International Reference Ionosphere Modeling Implemented in Python, Space Weather, ESS Open Archive, September 28, 2023.

Bilitza et al. (2022), The International Reference Ionosphere model: A review and description of an ionospheric benchmark, Reviews of Geophysics, 60.

PyIRTAM.lib.IRTAM_EDP_builder(x, aalt)

Construct vertical EDP. This is an old function and will be depreciated.

Parameters:

xarray-like

Array where 1st dimension indicates the parameter (total 11 parameters), second dimension is time, and third is horizontal grid [11, N_T, N_G].

aaltarray-like

1-D array of altitudes [N_V] in km.

Returns:

densityarray-like

3-D electron density [N_T, N_V, N_G] in m-3.

Notes

This function builds the EDP from the provided parameters for all time frames, all vertical and all horizontal points.

References

Forsythe et al. (2023), PyIRI: Whole-Globe Approach to the International Reference Ionosphere Modeling Implemented in Python, Space Weather.

PyIRTAM.lib.IRTAM_F2_top_thickness(foF2, hmF2, B_0, F107)

Return thicknesses of ionospheric layers.

Parameters:

foF2array-like

Critical frequency of F2 region in MHz.

hmF2array-like

Height of the F2 layer.

hmEarray-like

Height of the E layer.

mthint

Month of the year.

F107array-like

Solar flux index in SFU.

Returns:

B_F2_toparray-like

Thickness of F2 top in km.

B_E_botarray-like

Thickness of E bottom in km.

B_E_toparray-like

Thickness of E top in km.

Notes

This function returns thicknesses of ionospheric layers. We assume that B0 from IRTAM is equivalent to the thickness of the bottom side formulated in PyIRI. In reality, it could be different, since PyIRI uses Epstein function for the bottom side and IRTAM uses Ramakrishnan & Rawer function.

References

Forsythe et al. (2023), PyIRI: Whole-Globe Approach to the International Reference Ionosphere Modeling Implemented in Python, Space Weather.

PyIRTAM.lib.IRTAM_density(dtime, alon, alat, modip, TOV, irtam_dir='', use_subdirs=True)

Output ionospheric parameters from daily set of IRTAM coefficients.

Parameters:

dtimeobject

Datetime Python object.

alonarray-like

Flattened array of geographic longitudes in degrees. Must be Numpy array of any size [N_G].

alatarray-like

Flattened array of geographic latitudes in degrees. Must be Numpy array of any size [N_G].

modiparray-like

Modified dip angle in degrees.

TOVfloat

Time of Validity for IRtAM coefficients (use 24 if unknown).

irtam_dirstr

Directory for IRTAM coefficients, or ‘’ to use package directory. (default=’’)

use_subdirsbool

If True, adds YYYY/MMDD subdirectories to the filename path, if False assumes that the entire path to the coefficient directory is provided by irtam_dir (default=True)

Returns:

F2dict

‘fo’ is critical frequency of F2 region in MHz. ‘hm’ is height of the F2 peak in km. ‘B0’ is bottom thickness parameter of the F2 region in km. ‘B1’ is bottom thickness parameter of the F2 region in km. Shape [N_T, N_G].

Notes

This function returns ionospheric parameters and 3-D electron density for a given time using IRTAM coefficients for that time frame.

References

Galkin et al. (2015), GAMBIT Database and Explorer for Real-Time IRI Maps of F2 Layer Peak Height and Density, IES.

Forsythe et al. (2023), PyIRI: Whole-Globe Approach to the International Reference Ionosphere Modeling Implemented in Python, Space Weather.

PyIRTAM.lib.IRTAM_diurnal_functions(time_array, TOV)

Set diurnal functions for F2, M3000, and Es.

Parameters:

time_arrayarray-like

Array of UTs in hours.

Returns:

Darray-like

Diurnal functions for IRTAM.

Notes

This function calculates diurnal functions for IRTAM coefficients

References

Galkin et al. (2015), GAMBIT Database and Explorer for Real-Time IRI Maps of F2 Layer Peak Height and Density, IES.

Forsythe et al. (2023), PyIRI: Whole-Globe Approach to the International Reference Ionosphere Modeling Implemented in Python, Space Weather.

Jones, W. B., Graham, R. P., & Leftin, M. (1966). Advances in ionospheric mapping by numerical methods.

PyIRTAM.lib.IRTAM_find_hmF1(B0, B1, NmF2, hmF2, NmF1)

Return hmF1 for the given parameters.

Parameters:

B0array-like

Thickness parameter in km.

B1array-like

Thickness parameter in km.

NmF2array-like

Peak of F2 layer in m-3.

hmF2int

Height of F2 layer in km.

NmF1array-like

Peak of F1 layer in m-3.

Returns:

hmF1array-like

Height of F1 layer in km.

Notes

This function returns height of F1 layer if the bottom of F2 is constructed using Ramakrishnan & Rawer equation.

References

Bilitza et al. (2022), The International Reference Ionosphere model: A review and description of an ionospheric benchmark, Reviews of Geophysics, 60.

PyIRTAM.lib.IRTAM_freq_to_Nm(f)

Convert critical frequency to plasma density.

Parameters:

farray-like

Critical frequency in MHz.

Returns:

Nmarray-like

Peak density in m-3.

Notes

This function returns maximum density for the given critical frequency and limits it to 1 if it is below zero.

PyIRTAM.lib.IRTAM_gamma(G, D, F_B0, F_B1, F_foF2, F_hmF2)

Calculate foF2, M3000 propagation parameter, and foEs.

Parameters:

Garray-like

Global functions for F2 region.

Darray-like

Diurnal functions for F2 region.

F_B0array-like

IRTAM coefficients for B0.

F_B1array-like

IRTAM coefficients for B1.

F_foF2array-like

IRTAM coefficients for foF2.

F_hmF2array-like

IRTAM coefficients for hmF2.

Returns:

gamma_B0array-like

Thickness B0 in km.

gamma_B1array-like

Thickness B1 in km.

gamma_foF2array-like

Critical frequency of F2 layer in MHz.

gamma_hmF2array-like

Height of F2 layer.

Notes

This function calculates numerical maps for B0, B1, foF2, and hmF2 using matrix multiplication

References

Forsythe et al. (2023), PyIRI: Whole-Globe Approach to the International Reference Ionosphere Modeling Implemented in Python, Space Weather.

PyIRTAM.lib.IRTAM_highest_power_of_extension()

Provide the highest power of extension.

Returns:

constdict

Dictionary that has QM, nk, and nj parameters.

Notes

This function sets a common set of constants that define the power of expansions. QM = array of highest power of sin(x). nk = highest order of geographic extension. e.g. there are 76 functions in Table 3 on page 18 in Jones & Graham 1965. nj = highest order in diurnal variation.

References

Forsythe et al. (2023), PyIRI: Whole-Globe Approach to the International Reference Ionosphere Modeling Implemented in Python, Space Weather.

Jones, W. B., & Gallet, R. M. (1965). Representation of diurnal and geographic variations of ionospheric data by numerical methods, control of instability, ITU Telecommunication Journal , 32 (1), 18–28.

PyIRTAM.lib.IRTAM_read_coeff(dtime, coeff_dir='', use_subdirs=True)

Read coefficients from IRTAM.

Parameters:

dtimeint

Month.

coeff_dirstr

Directory for IRTAM coefficients, or ‘’ to use package directory. (default=’’)

use_subdirsbool

If True, adds YYYY/MMDD subdirectories to the filename path, if False assumes that the entire path to the coefficient directory is provided by irtam_dir (default=True)

Returns:

b0_irtamarray-like

IRTAM coefficients for B0 thickness.

b1_irtamarray-like

IRTAM coefficients for B1 thickness.

fof2_irtamarray-like

IRTAM coefficients for F2 frequency.

hmf2_irtamarray-like

IRTAM coefficients for F2 peak height.

Notes

This function reads U_jk coefficients (from IRTAM and Es maps). Acknowledgement for Es coefficients: Mrs. Estelle D. Powell and Mrs. Gladys I. Waggoner in supervising the collection, keypunching and processing of the foEs data. This work was sponsored by U.S. Navy as part of the SS-267 program. The final development work and production of the foEs maps was supported by the U.S Information Agency. Acknowledgments to Doug Drob (NRL) for giving me these coefficients.

References

Galkin et al. (2015), GAMBIT Database and Explorer for Real-Time IRI Maps of F2 Layer Peak Height and Density, IES.

Forsythe et al. (2023), PyIRI: Whole-Globe Approach to the International Reference Ionosphere Modeling Implemented in Python, Space Weather.

Jones, W. B., Graham, R. P., & Leftin, M. (1966). Advances in ionospheric mapping 476 by numerical methods.

PyIRTAM.lib.IRTAM_read_files(filename)

Read IRTAM file.

Parameters:

filenamestr

Path to the IRTAM folder file.

Returns:

F_IRTAMarray-like

Array of IRTAM coefficients.

Raises:

IOError

If filename is unknown

Notes

This function reads IRTAM file and outputs [14, 96] array.

PyIRTAM.lib.IRTAM_set_gl_G(alon, alat, modip)

Calculate global functions.

Parameters:

alonarray-like

Flattened array of geographic longitudes in degrees.

alatarray-like

Flattened array of geographic latitudes in degrees.

modiparray-like

Modified dip angle in degrees.

Returns:

Garray-like

Global functions for IRTAM (same as for CCIR foF2).

Notes

This function sets Geographic Coordinate Functions G_k(position) page # 18 of Jones & Graham 1965 for F0F2, M3000, and Es coefficients

References

Forsythe et al. (2023), PyIRI: Whole-Globe Approach to the International Reference Ionosphere Modeling Implemented in Python, Space Weather.

Galkin et al. (2015), GAMBIT Database and Explorer for Real-Time IRI Maps of F2 Layer Peak Height and Density, IES.

Jones, W. B., & Gallet, R. M. (1965). Representation of diurnal and geographic variations of ionospheric data by numerical methods, control of instability, ITU Telecommunication Journal , 32 (1), 18–28.

PyIRTAM.lib.Ramakrishnan_Rawer_function(NmF2, hmF2, B0, B1, h)

Construct density Ramakrishnan & Rawer F2 bottomside.

Parameters:

NmF2array-like

F2 region peak in m-3.

hmF2array-like

Height of F2 layer in km.

B0array-like

Thickness parameter for F2 region in km.

B1array-like

Thickness parameter for F2 region in km.

harray-like

Altitude in km.

Returns:

denarray-like

Constructed density in m-3.

Notes

This function constructs bottomside of F2 layer using Ramakrishnan & Rawer equation (as in IRI). All inputs are supposed to have same size.

References

Bilitza et al. (2022), The International Reference Ionosphere model: A review and description of an ionospheric benchmark, Reviews of Geophysics, 60.

PyIRTAM.lib.call_IRTAM_PyIRI(aUT, dtime, alon, alat, aalt, f2, f1, e_peak, es_peak, modip, TOV, irtam_dir='', use_subdirs=True)

Update parameters and build EDP for IRTAM for one time frame.

Parameters:

aUTarray-like

Time array that was used for PyIRI in hours.

dtimedtime object

F2 region peak in m-3.

alonarray-like

Longitudes 1-D array in degrees.

alatarray-like

Latitudes 1-D array in degrees.

aaltarray-like

Altitude 1-D array in km for EDP construction.

f2dict

‘Nm’ is peak density of F2 region in m-3. ‘fo’ is critical frequency of F2 region in MHz. ‘M3000’ is the obliquity factor for a distance of 3,000 km. Defined as refracted in the ionosphere, can be received at a distance of 3,000 km, unitless. ‘hm’ is height of the F2 peak in km. ‘B_topi is top thickness of the F2 region in km. ‘B_bot’ is bottom thickness of the F2 region in km. Shape [N_T, N_G].

f1dict

‘Nm’ is peak density of F1 region in m-3. ‘fo’ is critical frequency of F1 region in MHz. ‘P’ is the probability occurrence of F1 region, unitless. ‘hm’ is height of the F1 peak in km. ‘B_bot’ is bottom thickness of the F1 region in km. Shape [N_T, N_G].

e_peakdict

‘Nm’ is peak density of E region in m-3. ‘fo’ is critical frequency of E region in MHz. ‘hm’ is height of the E peak in km. ‘B_top’ is bottom thickness of the E region in km. ‘B_bot’ is bottom thickness of the E region in km. Shape [N_T, N_G].

es_peakdict

‘Nm’ is peak density of Es region in m-3. ‘fo’ is critical frequency of Es region in MHz. ‘hm’ is height of the Es peak in km. ‘B_top’ is bottom thickness of the Es region in km. ‘B_bot’ is bottom thickness of the Es region in km. Shape [N_T, N_G].

modiparray-like

Modified dip angle in degrees.

TOVfloat

Time of Validity in decimal hours. Use 24 if not known.

irtam_dirstr

Directory for IRTAM coefficients, or ‘’ to use package directory. (default=’’)

use_subdirsbool

If True, adds YYYY/MMDD subdirectories to the filename path, if False assumes that the entire path to the coefficient directory is provided by irtam_dir (default=True)

Returns:

f2dict

‘Nm’ is peak density of F2 region in m-3. ‘hm’ is height of the F2 peak in km. ‘B_top is top thickness of the F2 region in km. ‘B0’ is bottom thickness parameter of the F2 region in km. ‘B1’ is bottom thickness parameter of the F2 region in km. Shape [N_T, N_G].

f1dict

‘Nm’ is peak density of F1 region in m-3. ‘hm’ is height of the F1 peak in km. ‘B_bot’ is bottom thickness of the F1 region in km. Shape [N_T, N_G].

e_peakdict

‘Nm’ is peak density of E region in m-3. ‘hm’ is height of the E peak in km. ‘B_top’ is bottom thickness of the E region in km. ‘B_bot’ is bottom thickness of the E region in km. Shape [N_T, N_G].

es_peakdict

‘Nm’ is peak density of Es region in m-3. ‘hm’ is height of the Es peak in km. ‘B_top’ is bottom thickness of the Es region in km. ‘B_bot’ is bottom thickness of the Es region in km. Shape [N_T, N_G].

EDP_resultarray-like

Electron density profile in m-3. Shape [N_T, N_V, N_G].

Notes

This function uses IRTAM coefficients to construct NmF2, hmF2, B0, B1 maps, collects other parameters from PyIRI, updates hmF1 and B_F1_bot, and constructs the EDP.

PyIRTAM.lib.run_PyIRTAM(year, month, day, aUT, alon, alat, aalt, F107, irtam_dir='', use_subdirs=True, download=False)

Update parameters and build EDP for IRTAM for one time frame.

Parameters:

yearint

Year.

mthint

Month of year.

aUTarray-like

Array of universal time (UT) in hours. Must be Numpy array of any size [N_T].

alonarray-like

Flattened array of geographic longitudes in degrees. Must be Numpy array of any size [N_G].

alatarray-like

Flattened array of geographic latitudes in degrees. Must be Numpy array of any size [N_G].

aaltarray-like

Array of altitudes in km. Must be Numpy array of any size [N_V].

F107float

User provided F10.7 solar flux index in SFU.

irtam_dirstr

Directory with IRTAM coefficients, or ‘’ to use package directory. (default=’’)

use_subdirsbool

If True, adds YYYY/MMDD subdirectories to the filename path, if False assumes that the entire path to the coefficient directory is provided by irtam_dir (default=True)

downloadbool

If True, downloads coefficient files (default=False)

Returns:

f2_bdict

F2 parameters form PyIRI ‘Nm’ is peak density of F2 region in m-3. ‘fo’ is critical frequency of F2 region in MHz. ‘M3000’ is the obliquity factor for a distance of 3,000 km. Defined as refracted in the ionosphere, can be received at a distance of 3,000 km, unitless. ‘hm’ is height of the F2 peak in km. ‘B_topi is top thickness of the F2 region in km. ‘B_bot’ is bottom thickness of the F2 region in km. Shape [N_T, N_G, 2].

f1_bdict

F1 parameters form PyIRI ‘Nm’ is peak density of F1 region in m-3. ‘fo’ is critical frequency of F1 region in MHz. ‘P’ is the probability occurrence of F1 region, unitless. ‘hm’ is height of the F1 peak in km. ‘B_bot’ is bottom thickness of the F1 region in km. Shape [N_T, N_G, 2].

e_bdict

E parameters form PyIRI ‘Nm’ is peak density of E region in m-3. ‘fo’ is critical frequency of E region in MHz. ‘hm’ is height of the E peak in km. ‘B_top’ is bottom thickness of the E region in km. ‘B_bot’ is bottom thickness of the E region in km. Shape [N_T, N_G, 2].

es_bdict

Es parameters form PyIRI ‘Nm’ is peak density of Es region in m-3. ‘fo’ is critical frequency of Es region in MHz. ‘hm’ is height of the Es peak in km. ‘B_top’ is bottom thickness of the Es region in km. ‘B_bot’ is bottom thickness of the Es region in km. Shape [N_T, N_G, 2].

sundict

‘lon’ is longitude of subsolar point in degrees. ‘lat’ is latitude of subsolar point in degrees. Shape [N_G].

magdict

‘inc’ is inclination of the magnetic field in degrees. ‘modip’ is modified dip angle in degrees. ‘mag_dip_lat’ is magnetic dip latitude in degrees. Shape [N_G].

edp_barray-like

Electron density profiles from PyIRI in m-3 with shape [N_T, N_V, N_G]

f2_daydict

F2 parameters form PyIRTAM ‘Nm’ is peak density of F2 region in m-3. ‘hm’ is height of the F2 peak in km. ‘B_top is top thickness of the F2 region in km. ‘B0’ is bottom thickness parameter of the F2 region in km. ‘B1’ is bottom thickness parameter of the F2 region in km. Shape [N_T, N_G].

f1_daydict

F1 parameters form PyIRTAM ‘Nm’ is peak density of F1 region in m-3. ‘hm’ is height of the F1 peak in km. ‘B_bot’ is bottom thickness of the F1 region in km. Shape [N_T, N_G].

e_daydict

E parameters form PyIRTAM ‘Nm’ is peak density of E region in m-3. ‘hm’ is height of the E peak in km. ‘B_top’ is bottom thickness of the E region in km. ‘B_bot’ is bottom thickness of the E region in km. Shape [N_T, N_G].

es_daydict

Es parameters form PyIRTAM ‘Nm’ is peak density of Es region in m-3. ‘hm’ is height of the Es peak in km. ‘B_top’ is bottom thickness of the Es region in km. ‘B_bot’ is bottom thickness of the Es region in km. Shape [N_T, N_G].

edp_dayarray-like

Electron density profile from PyIRTAM in m-3. Shape [N_T, N_V, N_G].

Notes

This function runs PyIRTAM for a day of interest.

This module contains functions to obtain and update the IRTAM coefficients.

PyIRTAM.coeff.download_irtam_coeffs(dtime, param, irtam_dir='', use_subdirs=True, overwrite=False)

Retrieve the IRTAM coefficients from the UMass Lowell GIRO Data Center.

Parameters:

dtimedt.datetime

Date and time for the desired coefficents

paramstr

Coefficient parameter to retrieve. Expects one of: ‘foF2’, ‘hmF2’, ‘B0’, and ‘B1’

irtam_dirstr

Directory for IRTAM coefficients, or ‘’ to use package directory. (default=’’)

use_subdirsbool

If True, adds YYYY/MMDD subdirectories to the filename path, if False assumes that the entire path to the coefficient directory is provided by irtam_dir (default=True)

overwritebool

Allow overwriting of existing parameter files if True (default=False)

Returns:

dstatbool

Download status: True if file was downloaded, False if not

fstatbool

File status: True if parameter coefficient file exists, False if not

msgstr

Potential message with more details about status flags, empty if both are True

Notes

LGDC claims to also support ‘VTEC’, ‘MUF3000’, ‘TAU’, but tests for these paramaters failed

PyIRTAM.coeff.get_irtam_param_filename(dtime, param, irtam_dir='', use_subdirs=True)

Determine the filename for the desired IRTAM coefficients.

Parameters:

dtimedt.datetime

Date and time for the desired coefficents

paramstr

Coefficient parameter to retrieve. Expects one of: ‘foF2’, ‘hmF2’, ‘B0’, and ‘B1’

irtam_dirstr

Directory for IRTAM coefficients, or ‘’ to use package directory. (default=’’)

use_subdirsbool

If True, adds YYYY/MMDD subdirectories to the filename path, if False assumes that the entire path to the coefficient directory is provided by irtam_dir (default=True)

Returns:

filenamestr

IRTAM coefficient filename with full directory path