DIRSIG5 Atmosphere Model Backends

One of the key features of the atmospheric modeling support developed during the DIRSIG5 lifecycle was a unified interface to different, third-party atmospheric physics and radiative transfer models.

These external atmospheric models are referred to "backends", and there are currently three backend interfaces that have been created:

The Dummy backend, which doesn’t interface to an external model. Instead, it has analytical models for the atmosphere that are similar to the capabilities of the simple atmosphere model in DIRSIG4.
The MODTRAN Tape backend, which interfaces with MODTRAN using the legacy "tape-based" input/output files. This should be compatible with MODTRAN4, MODTRAN5 and MODTRAN6.
The MODTRAN JSON backend, which interfaces with MODTRAN using the new JSON input file introduced with MODTRAN6. This backend is only compatible with MODTRAN6.

At a future date, backends will be developed to interface with other commonly used atmospheric ratiative transfer models (i.e., 6SV, etc.).

These supported backend models are used by the DIRSIG5-era atmospheric database builders including atm_builder and fourcurve_builder.

This document outlines the JSON configuration options for the available backends.

The Dummy Backend

The "Dummy" backend is built-in (it does not call an external program) and it implements a set simplified calculations to approximate nominal illumination conditions:

The sun is modeled with a 5800K blackbody spectral distribution that is magnitude normalized to approximate the Earth reaching irradiance of the sun.
The moon is modeled using the same solar spectral distribution, but is magnitude normalized to approximate the Earth reaching irradiance of the moon.
The sky is modeled with an exponentially decaying spectral distribution that approximates clear sky scattering conditions in the visible.
There is no path radiance or transmission along other paths.

This backed is configured without any additional options:

        "backend": {
          "name": "dummy"
        }

The "dummy" backend is primarily for testing purposes and rapid use during simulation setup and debugging. It should not be used for data production simulations.

The MODTRAN Backends

There are a pair of backends designed to integrate with MODTRAN:

The ModtranTape backend, which is designed to work with MODTRAN5 (and earlier) using the older tape5 file as the primary input, and
The ModtranJson backend, which is designed to work with MODTRAN6 using the newer JSON formatted file as the primary input.

From the user perspective, the primary difference between the two backends is the input file provided by the user. Otherwise, the backends are identical.

For more information about interactions with MODTRAN, see the MODTRAN Integration Guide.

MODTRAN Interaction

The backend runs MODTRAN by modifying an input MODTRAN description ("tape5" or JSON file or parameter set, depending on the backend), running MODTRAN with that modified input and then reading the MODTRAN output. The user-supplied MODTRAN input is referred to as the "template" since it provides the basis for all the MODTRAN runs executed by the tool. The template is primarily used for the variables that describe the optical properties of the atmosphere (atmosphere profile, haze models, native gas overrides, etc.). In general, the backends update the variables contains specifics about the type of path to be modeled, the geometry of that path, the wavelengths, etc. In general, if a variable describes what the atmosphere looks like, the backends leave it alone. If a tape5 variable describes something specific to the DIRSIG simulation, the backend modifies it. The backends run 100s of MODTRAN simulations, so different variables are modified at different times depending on the type of MODTRAN simulation being performed. The table below attempts to document which variables are modified.

The atmospheric database builder tools that leverage these backends can set a flag that will preserve all the MODTRAN input files generated by the backend and the output files generated by MODTRAN if the user wants to verify the modifications to the input "template". For example, see the --save_files option in the atm_builder tool.

Table 1. MODTRAN variables modified by the backend.
Tape5 Card	JSON Section	Variable	Description
Card 1	RTOPTIONS	IEMSCT	Updated as needed to use source irradiance, scattered radiance, etc. modes.
Card 1	GEOMETRY	ITYPE	Updated as needed to specify the path type.
Card 1A	FILEOPTIONS	CDTDIR	Updated to specify the path to the MODTRAN `DATA` directory.
Card 1A4	FILEOPTIONS	DATDIR	Updated to specify the path to the MODTRAN `DATA` directory.
Card 2	SURFACE	GNDALT	Updated to reflect the ground altitude of the scene.
Card 3	GEOMETRY	H1ALT	Updated to reflect the path starting altitude.
Card 3	GEOMETRY	H2ALT	Updated to reflect the path ending altitude.
Card 3	GEOMETRY	OBSZEN	Updated to reflect the path angle.
Card 3	GEOMETRY	BCKZEN	Updated to reflect the path angle.
Card 3	GEOMETRY	HRANGE	Updated to reflect the path range.
Card 3ALT	GEOMETRY	H1ALT	Updated to reflect the path starting altitude.
Card 3ALT	GEOMETRY	H2ALT	Updated to reflect the path ending altitude.
Card 3ALT	GEOMETRY	OBSZEN	Updated to reflect the path angle.
Card 3ALT	GEOMETRY	IDAY	Updated to the day of year (impacts Earth-Sun distance → solar irradiance).
Card 3ALT	GEOMETRY	RAD_E	Updated to use the default Earth radius (`0`).
Card 3ALT	N/A	ISOURC	Updated to reflect the which exo-source to model (Sun or Moon).
Card 3ALT	GEOMETRY	ANGLEM	Updated to reflect phase angle of the Moon (from DIRSIG ephemeris model).
Card 3A1	GEOMETRY	IPARM	Updated to reflect the exo-source geometry method.
Card 3A1	GEOMETRY	IDAY	Updated to set the day of year (impacts Earth-Sun distance).
Card 3A1	N/A	ISOURC	Updated to reflect the which exo-source to model (Sun or Moon).
Card 3A2	GEOMETRY	PARM[1-4]	Updated to reflect the Sun/Moon position (from DIRSIG ephemeris model).
Card 3A2	GEOMETRY	TRUEAZ	Updated to reflect azimuth angle of the path.
Card 3A2	GEOMETRY	ANGLEM	Updated to reflect phase angle of the Moon (from DIRSIG ephemeris model).
Card 4	SPECTRAL	V1	Updated to reflect the minimum wavelength (or frequency) of the bandpass.
Card 4	SPECTRAL	V2	Updated to reflect the maximum wavelength (or frequency) of the bandpass.
Card 4	SPECTRAL	DV	Updated to reflect the delta wavelength (or frequency) of the bandpass.
Card 4	SPECTRAL	FWHM	Updated to reflect the delta wavelength (or frequency) of the bandpass.
Card 4	SPECTRAL	FLAGS[1-8]	Updated to specify the slit shape, disable extra outputs, etc.

CARD 3ALT contains redundant variables with CARD 3A1 and CARD 3A2 but is used for directly transmitted irradiance runs versus scattered radiance runs.

Specifying the MODTRAN Paths

Both backends are configured with a variety of options that provide details about the external MODTRAN installation and user input files. For the examples included here, the specific paths to the MODTRAN executable, data folder, etc. may differ from your installation.

Although the examples below show various configurations for older versions of MODTRAN, the user is strongly encouraged to use the latest version of MODTRAN6. Visit the MODTRAN page at the Spectral Sciences, Inc. website for more information.

There are three options for specifying the paths to the MODTRAN executable and data folder:

Specifying a pre-defined profile in your DIRSIG settings
- On each platform, DIRSIG has a set of stored settings that includes things including recently used files, where the documentation should be launched from, etc. This also includes a way to store multiple MODTRAN "profiles", where each profile includes the paths to a specific MODTRAN executable and data folder. These profiles are accessed and modified via the graphical user interface. This method is chosen by assigning the name of the desired profile to the modtran_profile variable.
Specifying the paths to the MODTRAN executable and data folder
- This method is chosen by assigning the paths to the executable and data folder via the modtran_exe and modtran_data variables, respectively.
Specifying the environment variables for the MODTRAN executable and data folder
- This method is chosen by assigning the names of environment variables containing the paths to the executable and data folder via the modtran_exe and modtran_data variables, respectively.

All three options eventually require knowing the paths to the MODTRAN executable and data folder. Consult this section of DIRSIG’s MODTRAN Integration Guide for important tips for working with MODTRAN6 on Windows.

Specifying a MODTRAN profile

The first option for specifying the MODTRAN setup is using the MODTRAN "profiles" in the user’s DIRSIG settings (or preferences). In that case the setup includes the modtran_profile variable:

Example setup using a MODTRAN profile.

        "backend": {
          "name": "modtran_tape",
          "modtran_profile": "MODTRAN5_2_4",
          ...
        }

In this example, the profile named "MODTRAN5_2_4" might be mapped to a MODTRAN5 2.4 installation.

Specifying the installation paths

Another option is to specify the path to the executable and data directory directly in the backend description:

Example setup using MODTRAN paths.

        "backend": {
          "name": "modtran_tape",
          "modtran_exe": "/Users/dirsig/Modtran5.2.4/mod5_cons.exe",
          "modtran_data": "/Users/dirsig/Modtran5.2.4/DATA",
          "modtran_min_delta": 0.1,
          ...
        }

In this example, the user is pointing at a MODTRAN5 2.4 installation in their own directory. The modtran_exe variable is assigned the full path to the MODTRAN executable, the modtran_data is assigned the full path to the MODTRAN DATA directory and the modtran_min_delta variable is assigned the limiting frequency resolution for the band model database available with that version of MODTRAN (0.1 wavenumbers for MODTRAN5 and later).

The specific paths to the MODTRAN executable will vary based on your installation.

Specifying environment variables

To avoid hard coding the paths to a MODTRAN executable and data folder into your inputs, the modtran_exe and modtran_data variables can also be assigned the names of user environment variables. The names of the variables can be whatever you want. In the example below, we are using MODTRAN_EXE and MODTRAN_DATA as the names of these variables:

Example setup using MODTRAN environment variables.

        "backend": {
          "name": "modtran_tape",
          "modtran_exe": "${MODTRAN_EXE}",
          "modtran_data": "${MODTRAN_DATA}",
          "modtran_min_delta": 0.1,
          ...
        }

An environment variable is indicated as a string wrapped by ${ and }. If an incorrectly formatted variable is found, or the indicated variable does not exist, an error will occur. Also note that the name of the variables can be whatever you want as long as the variable name provided can be resolved to an environment variable at run time.

The option to extract atmospheric profile data

The MODTRAN tape backend can optionally extract the atmospheric profile from the MODTRAN output "tape6" file. When this profile data is extracted, it is supplied to the radiometry core to drive refraction through the atmosphere. This option is controlled via the extract_profile variable, which is set to either true or false (note, boolean values in JSON are not strings, so do not assign the variable "true").

This option is disabled by default.

The ModtranTape5 Backend

The primary input for the ModtranTape backend is the "tape5" input files used by MODTRAN5 (and older versions). This backend allows the contents of that file to be supplied using one of three different methods:

Generated on-the-fly from a simple parametric description,
Externally referenced (the file exists and will be read in at run time), or
Internally stored (the file is stored in the JSON configuration for the plugin).

The ModtranTape5 backend can also be used with MODTRAN6, however, the user is strongly encouraged to migrate to the new JSON formatted input and the ModtranJson backend when using MODTRAN6.

Using parameters

The tape5_parameters object can be used to parametrically generate a MODTRAN tape5 file on-the-fly for a basic MODTRAN scenario. The description of each variable in this input option includes the names of the relevant MODTRAN variables. The user is strongly encouraged to consult the MODTRAN manual for information and recommendations on what values to use for your scenario.

Example parameterized MODTRAN configuration using the urban aerosol model.

        "backend": {
          "name": "modtran_tape",
          "modtran_profile": "MODTRAN5",
          "tape5_parameters": {
            "atmospheric_model": "MidLatitudeSummer",
            "co2_mixing_ratio_ppm": 395,
            "band_model_name": "p1_2013",
            "boundary_aerosol_model": {
              "type": "Urban",
              "parameters": {
                "visibility_km": 38.0
              }
            },
            "multiple_scattering": {
              "type": "Issac",
              "parameters": {
              }
            }
          }
        }

Example parameterized MODTRAN configuration using the Navy Maritime aerosol model.

        "backend": {
          "name": "modtran_tape",
          "modtran_profile": "MODTRAN6",
          "tape5_parameters": {
            "atmospheric_model": "Tropical",
            "co2_mixing_ratio_ppm": 405,
            "band_model_name": "p1_2013",
            "boundary_aerosol_model": {
              "type": "NavyMaritime",
              "parameters": {
                "current_wind_speed_ms": 4.5,
                "average_wind_speed_ms": 3.7,
                "air_mass_influence": 7
              }
            },
            "multiple_scattering": {
              "type": "Disort",
              "parameters": {
                "streams": 16
              }
            }
          }
        }

atmospheric_model (required)

The name of one of the six built-in, geographical-seasonal, vertical profile atmospheric models in MODTRAN. This variable drives the MODEL variable in MODTRAN. The allowed values are:

Tropical,
MidLatitudeSummer,
MidLatitudeWinter,
SubArticSummer,
SubArticWinter or
UsStandard1976

A user-defined profile model is not supported via this simple input option due to the complexity of the required input data. For this option the user is encouraged to create an appropriate tape5 file and use the other input options.

multiple_scattering (required)

This object contains a description of the multiple scattering mode for MODTRAN. This variable drives the IMULT, DIS and NSTR variables in MODTRAN. The choices are supplied via the type variable:

None: Only a single-scattering solution is performed, or
Isacc: The older Isaac 2-stream multiple-scattering solution is performed, or
Disort: The newer multi-stream, Discrete Ordinate (DISORT) solution is performed.
- For this option, the parameters object must be added and contain the streams variable. The allowed number of streams for DISORT are 2, 4, 8, 16, 32, 64 and 128.

boundary_aerosol_model (required)

The name of one of the built-in boundary aerosol models in MODTRAN. This variable drives the IHAZE variable in MODTRAN. The allowed values are:

NoAerosolOrClouds,
RuralVis23Km,
RuralVis5Km,
NavyMaritime,
MaritimeVis23Km,
UrbanVis5Km,
TroposphericVis50Km,
AdvectiveFoxVis0_2Km,
RadiativeFogVis0_5Km or
Desert

A user-defined aerosol model is not supported via this simple input option due to the complexity of the required input data. For this option the user is encouraged to create an appropriate tape5 file and use the other input options.

current_wind_speed_ms (conditional): The current wind speed in m/s. This value is used by the NavyMaritime and Desert aerosol models to drive the visibility calculation. This variable drives the WSS variable in MODTRAN. When set to 0, MODTRAN uses a default wind speed based on the atmosphere profile model (see the MODTRAN manual for the list of default values).
average_wind_speed_ms (conditional): The 24-hour average wind speed in m/s. This value is used by the NavyMaritime aerosol model to drive the visibility calculation. This variable drives the WHH variable in MODTRAN. When set to 0, MODTRAN uses a default wind speed based on the atmosphere profile model (see the MODTRAN manual for the list of default values).
air_mass_influence (conditional): The ocean/continental air mass influence value. This value is required by the NavyMaritime aerosol model to drive the visibility calculation based on the influence of (or proximity to) the ocean. This variable is assigned a value between 1 → 10, where a value of 1 corresponds to "open ocean" (greatest influence) and a value of 10 corresponds to "continental" (least influence). This variable drives the ICSTL variable in MODTRAN.
co2_mixing_ratio_ppm (optional): Overrides the default CO₂ mixing ratio in ppm. The default value of 330 ppm should be replaced with an appropriate modern value (e.g., 415 as of 2023). This variable drives the CO2MX variable in MODTRAN.
visibility_km (optional): When set to a value greater than 0, it overrides the default visibility (meteorological range) for the specified aerosol model. This variable drives the VIS variable in MODTRAN.
band_model_name (optional): Overrides the default 1 wavenumber band model file used by MODTRAN. This allows the user to select an alternative band model file. In most cases, this is so the user can switch from the default 1 wavenumber file (i.e., 01_2013) to the 0.1 wavenumber band file (i.e., p1_2013). This variable drives the LBMNAM and BMNAM variables in MODTRAN.

Using an External File

The tape5_filename variable defines the name of the input "tape5" file that is used as a template for the MODTRAN runs. In general, the backend is using the description of the atmosphere in this file (which model, aerosols, visibility, etc.) and is only updating the key parameters that are relevant to the specific DIRSIG simulation (the wavelengths, the source position, the path geometry, etc.).

Example configuration for the ModtranTape backend using a external tape5 file.

        "backend": {
          "name": "modtran_tape",
          "modtran_profile": "MODTRAN6",
          "tape5_filename": "./mls.tp5",
          ...
        }

Using an Internal File

The user also has the option to store the MODTRAN "tape5" file within the input JSON description via the tape5_contents variable. However, because the "tape5" file is multiple lines and you cannot embed newlines inside a JSON variable, the user will need to make the file a single string by replacing the newlines with the \n character:

Example configuration for the ModtranTape backend using a internal tape5 file.

        "backend": {
          "name": "modtran_tape",
          "modtran_profile": "MODTRAN6",
          "tape5_contents": "M   2    2    2    0    0    0    0    0    0    0    1    1    1   0.000   0.00\n    2    0    0    1    0    0     0.000     0.000     0.000     0.000     0.218\n    20.218     0.218   180.000     0.000     0.000     0.000    0\n    1    2  236    0\n    43.000    77.000     0.000     0.000    12.000     0.000     0.000     0.000\n       450     35050       100     2\n0"
          ...
        }

The user needs to be very careful when performing this newline replacement operation to otherwise not disrupt the precise format of the MODTRAN "tape5" file.

The ModtranJson Backend

The primary input for the ModtranJson backend is the new JSON input files used by MODTRAN6. The key piece of information for the backend is the name of the file containing the JSON formatted input description for MODTRAN6 (see the json_filename variable).

For the examples included here, the specific paths to the MODTRAN executable, data folder, etc. may differ from your installation.

Example configuration for the ModtranJson backend.

        "backend": {
          "name": "modtran_json",
          "modtran_profile": "MODTRAN6",
          "json_filename": "./mls.json",
          ...
        }

In this example, the profile named "MODTRAN6" might be mapped to a MODTRAN6 installation.

Errors and Debugging

In most situations, the source of errors will be related to the external model executed by the backend. When an error occurs with either the running of the backend model process or in reading the output of the backend model, an error will be generated and the related files will be preserved in the reported path for debugging.

See the trouble shooting guide for more information.

Under the hood

The MODTRAN backends creates a folder for all the MODTRAN executions (named modtran_runs) within which each model execution is stored in a sub-folder using a simple numerical numbering scheme from 0 to N. The use of individual folders for each MODTRAN request allows multiple MODTRAN processes to run at the same time without interference. The backend will purge the contents of the model request folders after the model has been successfully run and the output ingested. However, these folders can be preserved by using the --save_files command-line option to the respective builder application.

The file listing below shows the contents of a preserved model request folder after execution:

Listing of a run folder created by the backend.

$ ls modtran_runs/0
README.txt              modtran_stdout.txt      tmp.tp7
mod5root.in             tmp.7sc                 tmp.wrn
modroot.in              tmp.tp5
modtran_stderr.txt      tmp.tp6

The README.txt file contain a "human readable" description of the inputs to MODTRAN:

An example README file created by the backend.

Path radiance for the average background
General path run (inside atmosphere, downlooking)
ITYPE = 2, using H1 = 3.100, RANGE = 3.099 and BCKZEN = 0.000 (swapped BCKZEN -> OBSZEN)
Day of year = 348
Ground altitude = 0 [meters]
Path altitude = 3100 [meters]
Path range = 3100 [meters]
Path zenith = 180 [degrees]
Path azimuth = 0 [degrees]
Source is the Sun
Source zenith = 60 [degrees]
Source azimuth = 0 [degrees]

The mod5root.in contains the basename of the input/output files (in the case of this backend, it is always tmp), the modtran_stderr.txt and modtran_stdout.txt files contain the standard error and standard output (console) of the MODTRAN program, respectively. The tmp.tp5 and tmp.tp6, tmp.tp7, tmp.7sc, etc. files are the respective input and output files of the model execution.