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 and MODTRAN5.

  • The MODTRAN JSON backend, which interfaces with MODTRAN using the new JSON input file introduced with MODTRAN6. This backend is only compatible with MODTRAN6.

Tip At a future date, backends will be developed to interface with the 6SV model.

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"
        }
Important 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.

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.

Important 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.

Tip 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).

Note 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,
          ...
        }
Note 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.

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").

Note 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 verions). This backend allows the contents of that file to be supplied using one of three different methods:

  1. Generated on-the-fly from a simple parametric description,

  2. Externally referenced (the file exists and will be read in at run time), or

  3. Internally stored (the file is stored in the JSON configuration for the plugin).

Important 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,
            "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,
            "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

Note 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 appropiate tape5 file and use the other input options.
co2_mixing_ratio_ppm (optional)

Overrides the default CO2 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.

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

Note 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 appropiate 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.

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.

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"
          ...
        }
Important 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 contraining the JSON formatted input description for MODTRAN6 (see the json_filename variable).

Note 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 infomation.

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.