The make_adb tool is key component of the DIRSIG4 "Classic" atmosphere model (aka "ClassicAtm") and is supported in DIRSIG5 by the BasicAtmosphere plugin). This tool is responsible for creating the atmosopheric database (ADB) from a series of MODTRAN simulations.

Approach

Requirement Collection

When the make_adb tool runs, it is executing MODTRAN simulations that are specific to a given simulation. The specifics of the simulation that are captured by make_adb in the ADB file include:

  • The geographic location of the scene in the simulation,

  • The mean date and time of the simulation,

  • The average altitude of the sensor platform in the simulation,

  • The accumulated field-of-view (FOV) of the sensors in the simulation, and

  • The wavelengths of all the sensor focal planes in the simulation.

The list above includes the words "mean", "average" and "accumulated" because the resulting ADB file contains a single set of tables for the simulation. The general assumption of the ClassicAtm model is that the atmosphere is temporally frozen during the simulation. When the simulation is a single-frame at a point in time, this assumption is easily satisfied. However, when the simulation has a non-zero length collection window and involves a moving platform and/or a scanning sensor(s), then this assumption needs to be accounted for. In these non-instantaneous scenarios, the database is created to span the extents of the simulation in the following ways:

  • The date/time for the database is the mid-point of the collection time window.

  • The altitude for the database is the average altitude of the sensor during the collection time window.

  • The FOV for the database is the accumulated FOV formed by the motion of the platform combined with the platform-relative scanning of the sensor(s) during the collection time window.

Important This frozen time assumption is enforced by a hard-coded time window that spans +/- 15 minutes from the database. If your simulation tasks span more than 30 mins, then you will need to break the simulation into multiple simulations. This is one of the key advantages of the NewAtmosphere toolchain.

During the initialization of the make_adb tool, the tool is gathering the information (date, time, altitude, FOV, wavelengths, etc.) and generating the list of MODTRAN simulations that will need to be run to construct the database required for the simulation.

MODTRAN Interaction

The make_adb tool runs MODTRAN by repeatedly modifying an input MODTRAN "tape5" file, running MODTRAN with that modified input, reading the MODTRAN output and storing it in the atmospheric database. The user-supplied MODTRAN input "tape5" file is referred to as the "template" file since it provides the basis for all the MODTRAN runs executed by the tool. The template "tape5" file is primarily used for it’s card #1 and #2 data (and all the subcards), which describe the optical properties of the atmosphere. In general, the make_adb utility updates the card #3 and #4 data, which contains specifics about the type of path to be modeled, the geometry of that path, the wavelengths, etc. In general, if a tape5 variable describes what the atmosphere looks like, make_adb leaves it alone. If a tape5 variable describes something specific to the DIRSIG simulation, make_adb modifies it. The table below attempts to document which variables are modified. The tool will run 100s of MODTRAN simulations, so different variables are modified at different times depending on the type of MODTRAN simulation being performed.

Note The -save_tapes option will preserve all the MODTRAN input files generated by make_adb and output files generated by MODTRAN if the user wants to verify the modifications to the input "template".
Table 1. MODTRAN "tape5" variables modified by make_adb.
Card Variable Description

Card 1

IEMSCT

Updated as needed to use source irradiance, scattered radiance, etc. modes.

Card 1

ITYPE

Updated as needed to specify the path type.

Card 1A

CDTDIR

Updated to specify the path to the MODTRAN DATA directory.

Card 1A4

DATDIR

Updated to specify the path to the MODTRAN DATA directory.

Card 2

GNDALT

Updated to reflect the ground altitude of the scene.

Card 3

H1

Updated to reflect the path starting altitude.

Card 3

H2

Updated to reflect the path ending altitude.

Card 3

ANGLE

Updated to reflect the path angle.

Card 3

RANGE

Updated to reflect the path range.

Card 3ALT

H1

Updated to reflect the path starting altitude.

Card 3ALT

H2

Updated to reflect the path ending altitude.

Card 3ALT

ANGLE

Updated to reflect the path angle.

Card 3ALT

IDAY

Updated to the day of year (impacts Earth-Sun distance → solar irradiance).

Card 3ALT

RO

Updated to use the default Earth radius (0).

Card 3ALT

ISOURC

Updated to reflect the which exo-source to model (Sun or Moon).

Card 3ALT

ANGLEM

Updated to reflect phase angle of the Moon (from DIRSIG ephemeris model).

Card 3A1

IPARM

Updated to reflect the exo-source geometry method.

Card 3A1

IDAY

Updated to set the day of year (impacts Earth-Sun distance).

Card 3A1

ISOURC

Updated to reflect the which exo-source to model (Sun or Moon).

Card 3A2

PARM[1-4]

Updated to reflect the Sun/Moon position (from DIRSIG ephemeris model).

Card 3A2

PSIPO

Updated to reflect azimuth angle of the path.

Card 3A2

ANGLEM

Updated to reflect phase angle of the Moon (from DIRSIG ephemeris model).

Card 4

V1

Updated to reflect the minimum wavelength (or frequency) of the bandpass.

Card 4

V2

Updated to reflect the maximum wavelength (or frequency) of the bandpass.

Card 4

DV

Updated to reflect the delta wavelength (or frequency) of the bandpass.

Card 4

FWHM

Updated to reflect the delta wavelength (or frequency) of the bandpass.

Card 4

FLAGS[1-8]

Updated to specify the slit shape, disable extra outputs, etc.

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

MODTRAN Configuration

The setup of DIRSIG to use MODTRAN is described in the MODTRAN Setup section of the DIRSIG Installation Guide. In addition, the MODTRAN Troubleshooting Guide contains useful details about using specific versions of MODTRAN with DIRSIG.

The primary configuration task for the tool is the location of the MODTRAN installation to be used by the tool. The configuration captures three elements:

  1. The path to the MODTRAN executable,

  2. The path to the MODTRAN DATA directory, and

  3. The spectral resolution limit for this version of MODTRAN (1.0 wavenumbers for MODTRAN4 and 0.1 for MODTRAN5 and later).

There are two options for specifying these configuration elements.

Older Configuration File Method

In DIRSIG3, the MODTRAN installation specifics were captured in a configuration file that was contained in the software installation (e.g., $DIRSIG_HOME/config/make_adb). By default, the versions of make_adb included in DIRSIG3 would load this file to get information about the MODTRAN installation to be used. An example of this file is shown below:

An example DIRSIG3 era make_adb configuration file.
#
# This is the make_adb configuration file.  This configuration file
# will most likely NOT work for your facility without modifications
# to reflect the specifics of you MODTRAN installation.
#
MAKE_ADB_CFG = 1.0

MODTRAN {
    MODTRAN_EXE = /usr/local/Mod4v3r1/Mod4v3r1.exe
    MODTRAN_DATA_DIR = /usr/local/Mod4v3r1/DATA
    MODTRAN_MIN_DELTA = 1.0
}

BACKGROUND_RADIANCE_FILE = /usr/local/dirsig/lib/data/misc/star_light.dat

In DIRISG4, this mechanism was replaced with a newer mechanism (see below). However, the DIRISG4 version of make_adb still supported a command-line option (see the -use_config option) to specify the path to one of these DIRSIG3 era configuration files. Although not encouraged, this option can still be used to simplify the deployment or execution of make_adb in complex compute environments.

Newer User Profile Method

The primary limitations of the MODTRAN configuration method utilized in DIRSIG3 was that:

  1. The configuration file had to be migrated/updated with every new DIRSIG software update, and

  2. Individual users had to maintain configuration files if they wanted to manually manage or override the centralized configuration in the DIRSIG installation.

This was addressed in DIRSIG4 by relocating the MODTRAN installation specifics to the user’s DIRSIG personal settings. These settings are stored using the common platform specific mechanisms on each host operating system (e.g., user registry entries on Windows, an application PLIST file on MacOS, etc.). Because they are stored in the user’s account, the MODTRAN settings are not lost between upgrades and the user can easily customize their configuration. In addition, the new mechanism allows the user to have multiple MODTRAN installations configured and choose which to use. The MODTRAN installations can be viewed and modified in the DIRSIG graphical user interface Simulation Editor (DIRSIG or DIRSIG.exe) by opening the settings (FileSettings menu item, or DIRSIGPreferences on MacOS) and going to the MODTRAN tab.

Usage

This section outlines the various options for the make_adb tool.

Atmosphere File Options

The <classicradiativetransfer> element in the DIRSIG4 .atm file captures a variety of inputs for the ClassicAtm model. An example of this XML element is included below:

  <classicradiativetransfer>
    <modtrantape5file externalfile="classic_mls_rural_23km.tp5"/>
    <modtranprofilename>MODTRAN6</modtranprofilename>
    <adbfile>classic_mls_rural_23km.adb</adbfile>
    <removesensorpath>false</removesensorpath>
    <trypolarized>false</trypolarized>
    <usefastsky>false</usefastsky>
  </classicradiativetransfer>

The <modtrantape5file> element supplies the MODTRAN template "tape5" file for MODTRAN. If the externalfile attribute is provided, it is assigned the path to the file to be used. Otherwise, this element will contain the contents of the "tape5" enclosed in an XML CDATA block (see below):

  <classicradiativetransfer>
    <modtrantape5file><![CDATA[
M   2    2    2    0    0    0    0    0    0    0    1    1    1   0.000   0.00
    2    0    0    1    0    0     0.000     0.000     0.000     0.000     0.218
    20.218     0.218   180.000     0.000     0.000     0.000    0
    1    2  236    0
    43.000    77.000     0.000     0.000    12.000     0.000     0.000     0.000
       450     35050       100     2
    0
    ]]></modtrantape5file>
    <modtranprofilename>MODTRAN6</modtranprofilename>
    <adbfile>int_mls.adb</adbfile>
    <removesensorpath>false</removesensorpath>
    <trypolarized>false</trypolarized>
    <usefastsky>false</usefastsky>
  </classicradiativetransfer>

The benefit of this "internal" method is that it removes an external file dependency on the .atm file. When you share the .atm file you do not need to also share the "tape5" file referenced in the .atm file.

Important Be careful to avoid perturbing the formatting of the tape5 file when importing the "tape5" file. With the exception of removing empty lines at the start and end of the CDATA the contents are parsed directly as a "tape5" file.

The <modtranprofilename> element specifies which MODTRAN installation profile will be used. In this example, the profile with the name MODTRAN6 fill be used.

Tip If the <modtranprofilename> is not supplied, the tool will use the first (default) profile in the user’s account.

The <adbfile> element contains the name of the ADB file produced by make_adb.

The <removesensorpath> element controls an option to "remove" the path between the sensor and the scene. Setting this option to true will cause the path transmission data to be reset to 1 and the path radiance data to be reset to 0 after reading the database. As a result, the radiance at the sensor is essentially the surface leaving radiance.

The <trypolarized> element mirrors the -polarized command-line option (discussed below). This option will try to run MODTRAN in polarized mode. This mode was only supported by the limited access version of MODTRAN4 that had polarization support (referred to as MODTRAN4-P). Using this option with any other version of MODTRAN will result in an error.

The <usefastsky> element controls an option to populate the angularly sampled sky irradiance data table with a single uplooking sky path from MODTRAN. Originally introduced to facilitate quick database builds when debugging the use of this option is strongly discouraged.

Command-Line Options

DIRSIG4
Release: 2022.05 (03a571b) built on Jan 31 2022 14:22:02
Copyright 2015-2022 Rochester Institute of Technology

usage: make_adb [options] <SIM file>
    where [options] are:
    -help                           Print this help/usage message
    -use_config <file>              Use alternate MODTRAN configuration info
    -show_config                    Print MODTRAN configuration info
    -max_inversion <alt>            Set the max inversion altitude
    -max_range <range>              Set the max range [km] for sensor paths
    -fov_min_deltas <theta,phi>     Set the minimum angle between paths within the sensor FOV
    -polarized                      Create a polarized atmosphere
    -save_tapes                     Save copies of generated tape file
    -interactive <bandpass>         Create Interactive Mode queries atmosphere

The -use_config option can be used to specify the path to a DIRSIG3 era MODTRAN installation configuration file.

The -show_config option will print the MODTRAN configuration(s) available.

The -max_inversion option lets the user specify the inversion altitude used to update the boundary layer data in a MODTRAN user-defined atmosphere (MODTRAN MODEL = 7) from the weather data supplied to the DIRSIG simulation.

The -max_range option is used to specify the maximum range for a simulation where the FOV of the sensor is entirely above the horizon.

The -fov_min_deltas options lets the user override the minimum zenith and azimuth angles between paths within the sensor FOV.

The -polarized option will try to run MODTRAN in polarized mode. This mode was only supported by the limited access version of MODTRAN4 that had polarization support (referred to as MODTRAN4-P). Using this option with any other version of MODTRAN will result in an error.

The -save_tapes option will preserve all the MODTRAN run directories, including the input and outputs.

The -interactive option runs the tool in the "interactive" mode, which supports DIRSIG4’s interactive mode.

Using MODTRAN4-P

A small project in the early 2000s produced a prototype version of MODTRAN4 that had a limited set of updated scattering phase functions that enabled the prediction of polarized atmospheric path radiance. If you have access to this version of MODTRAN (referred to as MODTRAN4-P), you can configure it for use in DIRSIG. Simply create a MODTRAN installation profile that points to the MODTRAN4-P installation and use it with the -polarized option:

$ make_adb -polarized demo.sim

If you choose to create an alternate MODTRAN installation configuration file, your command line will look something like this:

$ make_adb -use_config modtran4p.conf -polarized demo.sim

If you receive the following error while make_adb is running in polarized mode then you should verify that you are correctly running MODTRAN4-P.

make_adb: MODTRAN ERROR
      MODTRAN output is not polarized!
Important Work on the MODTRAN4-P prototype ceased nearly 20 years ago. If you do not already have access to this restricted version of MODTRAN, please do not ask RIT and the DIRSIG team how to acquire it.

Troubleshooting

If you are having problems with make_adb that are MODTRAN related, consider running with the -save_tapes option and reviewing the input and output files for the MODTRAN simulation that failed.

In addition, consult the MODTRAN Troubleshooting Guide for specific issues.