Ionospheric State

All ionospheric state functions take the same input parameters:

  • utime: Unix Time (seconds from January 1, 1970)

  • glat: Geodetic Latitude (degrees)

  • glon: Geodetic Longitude (degrees)

  • galt: Geodetic Altitude (meters)

Other parameters that are needed to define the state should be specified in the appropriate section of the configuration file. The parameters that are needed to define different types of ionospheric state functions are listed below.

Density

class amisrsynthdata.state_functions.Density(type, params, utime0)[source]

Bases: object

chapman(utime, glat, glon, galt)[source]

Standard Chapman profile.

z’ = (z-z0)/H

Ne = N0 * exp(0.5(1-z’-exp(-z’))/cos(sza))

From Schunk and Nagy, 2009; Equation 11.57

Parameters:

  • N0 (float) – Peak electron density (m-3)

  • z0 (float) – Peak altitude (m)

  • H (float) – Scale height (m)

  • sza (float) – Solar zenith angle (degrees)

circle_patch(utime, glat, glon, galt)[source]

Polar cap patch formed from a 3D Gaussian.

Parameters:

  • N0 (float) – Electron density at patch peak (m-3)

  • width (float) – Patch width - Horizontal Gaussian FWHM (m)

  • height (float) – Patch height - Horizontal Gaussian FWHM (m)

  • cent_lat (float) – Geodetic latitude of center of patch (deg)

  • cent_lon (float) – Geodetic longitude of center of patch (deg)

  • cent_alt (float) – Geodetic altitude of center of patch (m)

gemini(utime, glat, glon, galt)[source]

Electron density output from GEMINI model.

Parameters:

gemini_output_dir (string) – Path to directory of GEMINI output files

gradient(utime, glat, glon, galt)[source]

Single horizontal gradient crated with a hyperbolic tangent function.

Parameters:

  • N0 (float) – Electron density at high side of gradient (m-3)

  • L (float) – Gradient scale length (m)

  • cent_lat (float) – Geodetic latitude of point to center the gradient around (deg)

  • cent_lon (float) – Geodetic longitude of point to center the gradient around (deg)

  • az (float) – Azimuth of gradient normal direction from geodetic north (deg)

tubular_patch(utime, glat, glon, galt)[source]

“Infintite tubular patch” of the variety that has traditionally been used to model polar cap patchs in numerical models. Formed from two hyperbolic tangients in the horizontal direction and a Gaussian in the vertical direction. A non-zero velocity will make the patch move in time.

Parameters:

  • N0 (float) – Peak electron density within the patch (m-3)

  • L (float) – Gradient scale length (m)

  • width (float) – Patch width (m)

  • height (float) – Patch height (m)

  • cent_lat (float) – Geodetic latitude of point to center the gradient around (deg)

  • cent_lon (float) – Geodetic longitude of point to center the gradient around (deg)

  • cent_alt (float) – Geodetic altitude of point to center the gradient around (m)

  • az (float) – Azimuth of gradient normal direction from geodetic north (deg)

  • velocity (list) – Patch velocity [E, N, U] (m/s)

uniform(utime, glat, glon, galt)[source]

Uniform electron density at all points.

Parameters:

value (float) – The value to assign at all points (m-3).

wave(utime, glat, glon, galt)[source]

A wave-like structure, such as traveling ionospheric distrubances (TID) or gravity waves (GW). The wave has the functional form:

Ne = A0 * sin( 2pi * (k*r + t/P) ) * exp( (z-wave_alt)^2 / H^2 )

This function produces wave purturbations around zero with amplitude decaying as H^-2 moving away from the specified peak wave altitude.

Parameters:

  • A0 (float) – Wave amplitude (m^-3)

  • k (list) – Wavevector [E, N, U] (m/s)

  • P (float) – Wave period (m)

  • orig_lat (float) – Geodetic latitude wavevector is defined from (deg)

  • orig_lon (float) – Geodetic longitude wavevector is defined from (deg)

  • orig_alt (float) – Geodetic altiude wavevector is defined from (m)

  • H (float) – Scale height for wave amplitude decay (m)

  • wave_alt (float) – Peak altitude of wave that it should decay away from (m)

Notes

If this function is not used in conjunction with a suitable background, it WILL generate negative values for electron density. If a uniform background density is selected, make sure A0 is less than the uniform background value. If a Chapman layer background is desired, the easiest way to ensure positive definite density is to follow these guidlines:

N0_chap > A0

z0_chap = wave_alt

H_chap > H

Temperature

These general temperature functions are used to specify both ion and electron temperature.

class amisrsynthdata.state_functions.Temperature(type, params, utime0)[source]

Bases: object

gemini(utime, glat, glon, galt)[source]

Temperature output from GEMINI model.

Parameters:

  • gemini_output_dir (string) – Path to directory of GEMINI output files

  • species (string) – Which species (ion or electron) should be read from GEMINI output (‘Te’ or ‘Ti’)

hypertan(utime, glat, glon, galt)[source]

Temperature increases in altitude as a hyperbolic tangent.

Parameters:

  • maxtemp (float) – The temperature at infinity to asymptope to (K)

  • scale_height (float) – Vertical scale height (m)

uniform(utime, glat, glon, galt)[source]

Uniform temperature at all points.

Parameters:

value (float) – The value to assign at all points (K)

Velocity

class amisrsynthdata.state_functions.Velocity(type, params, utime0, apex=None)[source]

Bases: object

gemini(utime, glat, glon, galt)[source]

Velocity output from GEMINI model.

Parameters:

gemini_output_dir (string) – Path to directory of GEMINI output files

uniform(utime, glat, glon, galt)[source]

Uniform velocity at all points. Uniform velocity is caluclated by translating the velocity vetor to all points in cartesain coordinates, then adjusting the vertical velocity to zero and renormalizing so they all have the same magnitude. This creates the approximate effect of uniform velocity across the entire FoV regardless of the local coordinate system.

Parameters:

  • value (list) – The vector value to assign at all points [E, N, U] (m/s)

  • cent_lat (float) – Geodetic latitude of initial specified vector (deg)

  • cent_lon (float) – Geodetic longitude of initial specified vector (deg)

uniform_glat_aligned(utime, glat, glon, galt)[source]

Velocity will have the same Geodetic components at all points. CAUTION: This is probably not the most appropriate function for creating a “uniform” field close to the poles.

Parameters:

value (list) – The vector value to assign at all points [E, N, U] (m/s)

uniform_mlat_aligned(utime, glat, glon, galt)[source]

Velocity will have the same Apex magnetic components at all points. This is useful for flows expected to align with magnetic meridians (i.e., in the auroral zone).

Parameters:

value (list) – The Apex vector value to assign at all points [mag E, mag N, mag U] (m/s)

Create New State Functions

If the existing functions are not sufficient to create the ionospheric state of interest, you can write your own and add them to the package. Instructions are provided below for adding these functions to your own local version of the code, but the package developers encourage users to create a pull request to contribute their additions to the main version of the package and improve the functionality. Please refer to the contributing guidelines for general information about how to set up the package locally for development and community best practices.

Overview

In the source code the directory amisrsynthdata/state_functions contains the files density.py, temperature.py, and velocity.py. Each of these files contains a class which, after instantiation, can be called to return the value of that particular parameter. The state functions that describe different structures or features that can be selected for the artificial ionosphere are methods of this class. As an example, density.py contains the class Density, which has the methods chapman, circle_patch, and wave (amongst others) which can be used to create a Chapman layer, a circular density enhancement, or a wave-like structure in plasma density. Note that there is only one Temperature class which is used to specify both ion and electron temperature as the functional forms of both are often similar.

New functions should be added as methods to the class of the parameter they represent. For example, if an ionosphere with a localized ion heating even is desired, a function named something like plasma_heating should be added to the Temperature class (in temperature.py) that returns enhanced temperature in a small area. It technically does not matter where in the class this function is added, but at the bottom or grouped with other similar functions is recommended.

Function Guidelines

Functions must have a unique name from functions already used by that class, and MUST take in the following variable in this order:

  • Unix Time (seconds since January 1, 1970)

  • Geodetic Latitude (degrees)

  • Geodetic Longitude (degrees)

  • Geodetic Altitude (meters)

Latitude, longitude, and altitude can be scalar or multidimensional arrays, but they will always all be the same shape. Unix Time will either be a scalar or a 1D array of any length. Functions should be able to handle any combination of these inputs gracefully. Functions should return scalar parameters (density and temperature) as arrays where the first dimension matches the length of the Unix Time array, and subsequent dimensions match the shape of the position arrays. Velocity functions should return a similar array, but with one final dimension that holds the three velocity vector components.

Density values must be returned in units of m -3, temperature values in units of K, and velocity values in units of m/s. The geodetic components of velocity vectors must be returned in the order east, north, up. Any transformation to/from other units or coordinate systems must be handled completely within the function. Parameters input through the configuration file can technically be in any units, but you are encouraged to use standard SI units (meters, seconds, and Kelvin) to be consistent with other functions.

New functions that duplicate the effect of some combination of existing functions are discouraged. For instance, avoid adding a double-hump density profile function as the same effect could be achieved by specifying two Chapman functions in the config file with different altitude parameters. This keeps the package lightweight and avoids having multiple ways to accomplish one thing, which is more user-friendly. Functions that have fundamentally different shapes or characteristics (i.e., a Chapman profile and an Epstein profile) are permitted.

Functions contributed back to the main package MUST include a numpy-style docstring that provides a short description of the function and what it should be used for and lists the parameters that must be specified in the configuration file. ANY parameter your function needs as input aside from the four position/time parameters listed above MUST be in the configuration file.

Parameters specified in the config file will be available as attributes of the class, so if a parameter N1 is defined in the config file it will be available for your function to use as self.N1. When multiple state functions are summed for one parameter, an independent instance of the class is created for each of them, so it is fine to repeat variable names between different functions.

Anytime a new state function is added, a new section should be added to state_functions_config.yaml in the tests directory that specifies the function and some standard parameters for it. This ensures the standard unit tests that confirm the function does not crash under expected conditions will run automatically on the new function. It is NOT necessary to modify any of the test python scripts for this, just edit the config file. At this time, specific additional tests for each state function are not required, although you are encouraged to thoroughly test your function under a variety of input parameters.

Step-by-step Instructions

  1. Fork and clone the source repository and install following the developer instructions.

  2. Create a new branch to develop your new function.

  3. Add your function to the appropriate file in amisrsynthdata/state_functions following the Function Guidelines.

  4. Modify your configuration file to use your new function.

  5. TEST!!!

  6. Add your function to state_functions_config.yaml.

  7. Push your new branch to GitHub and create a pull request to merge it into the develop branch of the main package repository.

  8. If you are not interested in contributing your function to the main repository, simply merge the branch you developed the function on with your local main branch.