Perform forward ATM calculation

Perform a forward calculation using VERSION 2 of the TREx Auroral Transport Model and the supplied input parameters.

NOTE: As of API version 1.78.0 (released 2026-09-23), all energy fluxes default to 0 (the maxwellian energy flux previously defaulted to 10), and at least one must be set to a nonzero value unless a custom spectrum is supplied. Further, the maxwellian_mean_energy parameter can now be used in place of maxwellian_characteristic_energy.

NOTE: As of API version 1.41.0 (released 2026-01-30), the height_integrated_rayleighs_lbh and emission_lbh output flags have been renamed to height_integrated_rayleighs_smile_uvi_lbh and emission_smile_uvi_lbh. Further, the plasma_pederson_conductivity output flag has been renamed to plasma_pedersen_conductivity. The original names will be removed in a later release to be determined.

Input notes:

• By default requests are cached. Use the 'no_cache' parameter to disable this functionality
• Latitude and longitude are to be in geodetic coordinates (-90 to 90 lat, -180 to 180 lon)
• Timestamp
  • timestamp is expected to be in UTC, and is valid for any value up to the end of the previous day
  • the 'Z' character at the end of the timestamp is optional, and will be ignored if it is supplied
• Spectral shapes
  • At least one of the energy fluxes (maxwellian, gaussian, kappa, exponential, proton) must be non-zero, or a custom spectrum must be supplied. A 400 error will be returned otherwise.
  • If the maxwellian_energy_flux is not 0, then maxwellian_characteristic_energy will be used. Alternatively, maxwellian_mean_energy can be supplied instead, in which case the characteristic energy will be set to half of the mean energy. Only one of maxwellian_characteristic_energy or maxwellian_mean_energy can be supplied. If neither is specified, then the default characteristic energy will be used.
  • If the gaussian_energy_flux is not 0, then gaussian_peak_energy and gaussian_spectral_width will be used. If these two values are not specified, then the defaults will be used.
  • If kappa_energy_flux is not 0, then kappa_mean_energy and kappa_k_index will be used. If these two values are not specified, then the defaults will be used.
  • If exponential_energy_flux is not 0, then exponential_characteristic_energy and exponential_starting_energy will be used. If these two values are not specified, then the defaults will be used.
  • IMPORTANT: All the above spectral shapes are super-imposable except exponential. The exponential spectrum should be only be used for high-energy tail and, starting from E0 (proton_starting_energy), will override any other spectral specification.
• If proton_energy_flux is not 0, then proton_characteristic_energy will be used. If the proton_characteristic_energy is not specified, then the default will be used.
• The ATM model is 1D and time-independent. However, the optional parameters timescale_auroral and timescale_transport provide limited support for time-dependent and transport process.
  • timescale_auroral (T0) is the duration of the precipitation; default value is 600 sec
  • timescale_transport is defined by L/v0, in which L is the dimension of the auroral structure, and v0 is the cross-structure drift speed. Default value is 600 sec.
  • the model quasi-analytically solves the continuity equation under a square input (with time duration T0 and spatial width L) input of precipitation. The initial/boundary conditions are given by IRI. The output yields the mean density/VER over [0-L] at time T0.
• NOTE: proton precipitation is presently only for ionization rate and density calculations. Proton auroras are not nominal TREx characteristics and currently not computed in this version of the model.
• Units and defaults
  • maxwellian total energy flux: erg/cm2/s, default is 0 (indicating all maxwellian parameters are disabled)
  • maxwellian characteristic energy: eV, default is 5000
  • maxwellian mean energy: eV, no default (optional alternative to the characteristic energy, equal to 2x the characteristic energy)
  • gaussian total energy flux: erg/cm2/s, default is 0 (indicating all gaussian parameters are disabled)
  • gaussian peak energy: eV, default is 1000
  • gaussian spectral width: eV, default is 100
  • kappa total energy flux: erg/cm2/s, default is 0 (indicating all kappa parameters are disabled)
  • kappa mean energy: eV, default is 30000
  • kappa k-index: no unit, default is 5
  • exponential total energy flux: erg/cm2/s, default is 0 (indicating all exponential parameters are disabled)
  • exponential characteristic energy: eV, default is 50000
  • exponential starting energy: eV, default is 50000
  • proton total energy flux: erg/cm2/s, default is 0 (indicating all proton parameters are disabled)
  • proton characteristic energy: eV, default is 10000
  • d-region flag: defaults to false
  • custom spectrum (precipitation)
    • energy in eV, flux in 1/cm2/s/eV
    • energy and flux arrays must be the same length
    • users are responsible for fully covering the energy range of interest in the provided spectrum. The model only performs interpolation, not extrapolation.
  • custom neutral profile
    • altitude in km, density in cm^-3, temperature in K.
    • users are responsible for fully covering the altitude range of interest in the provided profile (80-800 km if d_region_flag=0, or 50-500 km if d_region_flag=1). The model only performs interpolation, not extrapolation.
  • nrlmsis_model_version: valid values are "00" and "2.0", default is "2.0". Note that if the d-region flag is enabled, the only supported value is "2.0".
  • oxygen_correction_factor: default is 1.0
  • timescale_auroral: seconds, default is 600
  • timescale_transport: seconds, default is 600

Output notes:

• output parameter of the request are toggles the enable/disable each field's inclusion in the response
• all output parameters are false by default
• altitude: kilometers
• emission data: 1-D arrays -- volume emission rate, 1/cm^3/s
• plasma electron density: 1-D array, cm^-3
• plasma O2+ density: 1-D array, cm^-3
• plasma NO+ density: 1-D array, cm^-3
• plasma O+ density: 1-D array, cm^-3
• plasma ionisation rate: 1-D array, 1/cm^3/s
• plasma electron temperature: 1-D array, K
• plasma ion temperature: 1-D array, K
• plasma pedersen conductivity: 1-D array, S/m
• plasma hall conductivity: 1-D array, S/m
• neutral O2 density: 1-D array, cm^-3
• neutral O density: 1-D array, cm^-3
• neutral N2 density: 1-D array, cm^-3
• neutral N density: 1-D array, cm^-3
• neutral temperature: 1-D array, K
• production_rate_o2plus: 1-D array, 1/cm^3/s
• production_rate_oplus: 1-D array, 1/cm^3/s
• production_rate_oneg: 1-D array, 1/cm^3/s
• production_rate_o: 1-D array, 1/cm^3/s
• production_rate_nplus: 1-D array, 1/cm^3/s
• production_rate_n2plus: 1-D array, 1/cm^3/s
• production_rate_n: 1-D array, 1/cm^3/s
• production_rate_n2d: 1-D array, 1/cm^3/s