---
title: "Perform forward ATM calculation"
method: POST
path: "/api/v2/atm/forward"
tags: ["Auroral Transport Model (ATM)"]
---

# Perform forward ATM calculation

`POST /api/v2/atm/forward`

## Request

- Base URL: `https://api.phys.ucalgary.ca` (the document declares no server; this is the origin it was published from)
- URL: `https://api.phys.ucalgary.ca/api/v2/atm/forward`
- Auth: none declared
- TypeScript: <https://skmtc.dev/ucalgary/apis/ucalgary-space-remote-sensing-api/docs/api/v2/atm/forward/post.ts> (a function with typed inputs; its response is checked against the schema)

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

## Request body

- SrcAtmV2SchemasForwardATMForwardRequest
  - `timestamp` string, date-time, required
  - `geodetic_latitude` number, required
  - `geodetic_longitude` number, required
  - `maxwellian_energy_flux` number
  - `maxwellian_characteristic_energy` number
  - `maxwellian_mean_energy` number, nullable
  - `gaussian_energy_flux` number
  - `gaussian_peak_energy` number
  - `gaussian_spectral_width` number
  - `kappa_energy_flux` number
  - `kappa_mean_energy` number
  - `kappa_k_index` number
  - `exponential_energy_flux` number
  - `exponential_characteristic_energy` number
  - `exponential_starting_energy` number
  - `proton_energy_flux` number
  - `proton_characteristic_energy` number
  - `d_region` boolean
  - `nrlmsis_model_version` '00' | '2.0'
  - `oxygen_correction_factor` number
  - `timescale_auroral` integer
  - `timescale_transport` integer
  - `custom_spectrum` ATMForwardCustomSpectrum
    - `energy` number[], required
    - `flux` number[], required
  - `custom_neutral_profile` ATMForwardCustomNeutralProfile
    - `altitude` union[], required
      - union
        - number
        - integer
    - `o_density` number[], required
    - `o2_density` number[], required
    - `n2_density` number[], required
    - `n_density` number[], required
    - `no_density` number[], required
    - `temperature` union[], required
      - union
        - number
        - integer
  - `output` SrcAtmV2SchemasForwardATMForwardRequestOutputFlags
    - `height_integrated_rayleighs_4278` boolean
    - `height_integrated_rayleighs_5577` boolean
    - `height_integrated_rayleighs_6300` boolean
    - `height_integrated_rayleighs_8446` boolean
    - `height_integrated_rayleighs_1304` boolean
    - `height_integrated_rayleighs_1356` boolean
    - `height_integrated_rayleighs_smile_uvi_lbh` boolean
    - `height_integrated_rayleighs_lbh` boolean
    - `altitudes` boolean
    - `emission_4278` boolean
    - `emission_5577` boolean
    - `emission_6300` boolean
    - `emission_8446` boolean
    - `emission_1304` boolean
    - `emission_1356` boolean
    - `emission_smile_uvi_lbh` boolean
    - `emission_lbh` boolean
    - `plasma_electron_density` boolean
    - `plasma_o2plus_density` boolean
    - `plasma_oplus_density` boolean
    - `plasma_noplus_density` boolean
    - `plasma_ionisation_rate` boolean
    - `plasma_electron_temperature` boolean
    - `plasma_ion_temperature` boolean
    - `plasma_pedersen_conductivity` boolean
    - `plasma_pederson_conductivity` boolean
    - `plasma_hall_conductivity` boolean
    - `neutral_o2_density` boolean
    - `neutral_o_density` boolean
    - `neutral_n2_density` boolean
    - `neutral_n_density` boolean
    - `neutral_temperature` boolean
    - `production_rate_o2plus` boolean
    - `production_rate_oplus` boolean
    - `production_rate_oneg` boolean
    - `production_rate_o` boolean
    - `production_rate_nplus` boolean
    - `production_rate_n2plus` boolean
    - `production_rate_n` boolean
    - `production_rate_n2d` boolean
  - `no_cache` boolean

## Response `200`

Calculated outputs

- SrcAtmV2SchemasForwardATMForwardResponse
  - `data` SrcAtmV2SchemasForwardATMForwardResponseData, required
    - `height_integrated_rayleighs_4278` number
    - `height_integrated_rayleighs_5577` number
    - `height_integrated_rayleighs_6300` number
    - `height_integrated_rayleighs_8446` number
    - `height_integrated_rayleighs_1304` number
    - `height_integrated_rayleighs_1356` number
    - `height_integrated_rayleighs_smile_uvi_lbh` number
    - `height_integrated_rayleighs_lbh` number
    - `altitudes` unknown[]
      - unknown
    - `emission_4278` unknown[]
      - unknown
    - `emission_5577` unknown[]
      - unknown
    - `emission_6300` unknown[]
      - unknown
    - `emission_8446` unknown[]
      - unknown
    - `emission_1304` unknown[]
      - unknown
    - `emission_1356` unknown[]
      - unknown
    - `emission_smile_uvi_lbh` unknown[]
      - unknown
    - `emission_lbh` unknown[]
      - unknown
    - `plasma_electron_density` unknown[]
      - unknown
    - `plasma_o2plus_density` unknown[]
      - unknown
    - `plasma_noplus_density` unknown[]
      - unknown
    - `plasma_oplus_density` unknown[]
      - unknown
    - `plasma_ionisation_rate` unknown[]
      - unknown
    - `plasma_electron_temperature` unknown[]
      - unknown
    - `plasma_ion_temperature` unknown[]
      - unknown
    - `plasma_pedersen_conductivity` unknown[]
      - unknown
    - `plasma_pederson_conductivity` unknown[]
      - unknown
    - `plasma_hall_conductivity` unknown[]
      - unknown
    - `neutral_o2_density` unknown[]
      - unknown
    - `neutral_o_density` unknown[]
      - unknown
    - `neutral_n2_density` unknown[]
      - unknown
    - `neutral_n_density` unknown[]
      - unknown
    - `neutral_temperature` unknown[]
      - unknown
    - `production_rate_o2plus` unknown[]
      - unknown
    - `production_rate_oplus` unknown[]
      - unknown
    - `production_rate_oneg` unknown[]
      - unknown
    - `production_rate_o` unknown[]
      - unknown
    - `production_rate_nplus` unknown[]
      - unknown
    - `production_rate_n2plus` unknown[]
      - unknown
    - `production_rate_n` unknown[]
      - unknown
    - `production_rate_n2d` unknown[]
      - unknown
  - `request` SrcAtmV2SchemasForwardATMForwardRequest, required
    - `timestamp` string, date-time, required
    - `geodetic_latitude` number, required
    - `geodetic_longitude` number, required
    - `maxwellian_energy_flux` number
    - `maxwellian_characteristic_energy` number
    - `maxwellian_mean_energy` number, nullable
    - `gaussian_energy_flux` number
    - `gaussian_peak_energy` number
    - `gaussian_spectral_width` number
    - `kappa_energy_flux` number
    - `kappa_mean_energy` number
    - `kappa_k_index` number
    - `exponential_energy_flux` number
    - `exponential_characteristic_energy` number
    - `exponential_starting_energy` number
    - `proton_energy_flux` number
    - `proton_characteristic_energy` number
    - `d_region` boolean
    - `nrlmsis_model_version` '00' | '2.0'
    - `oxygen_correction_factor` number
    - `timescale_auroral` integer
    - `timescale_transport` integer
    - `custom_spectrum` ATMForwardCustomSpectrum
      - `energy` number[], required
      - `flux` number[], required
    - `custom_neutral_profile` ATMForwardCustomNeutralProfile
      - `altitude` union[], required
        - union
          - number
          - integer
      - `o_density` number[], required
      - `o2_density` number[], required
      - `n2_density` number[], required
      - `n_density` number[], required
      - `no_density` number[], required
      - `temperature` union[], required
        - union
          - number
          - integer
    - `output` SrcAtmV2SchemasForwardATMForwardRequestOutputFlags
      - `height_integrated_rayleighs_4278` boolean
      - `height_integrated_rayleighs_5577` boolean
      - `height_integrated_rayleighs_6300` boolean
      - `height_integrated_rayleighs_8446` boolean
      - `height_integrated_rayleighs_1304` boolean
      - `height_integrated_rayleighs_1356` boolean
      - `height_integrated_rayleighs_smile_uvi_lbh` boolean
      - `height_integrated_rayleighs_lbh` boolean
      - `altitudes` boolean
      - `emission_4278` boolean
      - `emission_5577` boolean
      - `emission_6300` boolean
      - `emission_8446` boolean
      - `emission_1304` boolean
      - `emission_1356` boolean
      - `emission_smile_uvi_lbh` boolean
      - `emission_lbh` boolean
      - `plasma_electron_density` boolean
      - `plasma_o2plus_density` boolean
      - `plasma_oplus_density` boolean
      - `plasma_noplus_density` boolean
      - `plasma_ionisation_rate` boolean
      - `plasma_electron_temperature` boolean
      - `plasma_ion_temperature` boolean
      - `plasma_pedersen_conductivity` boolean
      - `plasma_pederson_conductivity` boolean
      - `plasma_hall_conductivity` boolean
      - `neutral_o2_density` boolean
      - `neutral_o_density` boolean
      - `neutral_n2_density` boolean
      - `neutral_n_density` boolean
      - `neutral_temperature` boolean
      - `production_rate_o2plus` boolean
      - `production_rate_oplus` boolean
      - `production_rate_oneg` boolean
      - `production_rate_o` boolean
      - `production_rate_nplus` boolean
      - `production_rate_n2plus` boolean
      - `production_rate_n` boolean
      - `production_rate_n2d` boolean
    - `no_cache` boolean
  - `calculation_duration_ms` number, required

## Other responses

- `400`: Problematic request made
- `422`: Validation Error
- `500`: Data generation error

---

[API](https://skmtc.dev/ucalgary/apis/ucalgary-space-remote-sensing-api.md) - [All operations](https://skmtc.dev/ucalgary/apis/ucalgary-space-remote-sensing-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ucalgary/apis/ucalgary-space-remote-sensing-api/revisions/e451a425b5eb?raw)