Using MODTRAN6 with DIRSIG

It has been a pretty exciting year for the team at Spectral Sciences, Inc. with the release of MODTRAN6. This latest version marks a major milestone in the continued development of one of the most popular and trusted codes for simulating radiative transfer in the atmosphere. In addition to important science related advancements, this latest code also includes significant improvements to the general usability of the software. This includes a new graphical user interface (GUI) and the introduction of a formal application programmer interface (API), which let's codes like DIRSIG interact with MODTRAN in a far more robust way than previous versions allowed.

New MODTRAN, new interfaces

The major development in the interface area is a shift from the old "tape5" style inputs to a new JSON (JavaScript Object Notation) style input. In addition to improving the general readability of the input, the JSON document format is much easier to read in, modify and write back out. The old tape5 format required software like DIRSIG to know a great deal about the format of the input file in order to correctly read in, modify and write back out a set of MODTRAN inputs. If a new variable was added to an existing input "card", a new input "card" added, etc. then the DIRSIG code needed to be modified to know to read it in and write it back out, even if it never modified those variables. The JSON document style input now employed by MODTRAN6 can be read into a generic structure, the variables of interest can be modified in a straight-forward way, and the document written back out without needing to code extensive logic that understands the meaning and impact of every variable. The DIRSIG development team is very excited to begin work on a new interface to MODTRAN6 that will leverage the new JSON inputs later this fall.

However, for the time being we have plenty of users that are using existing releases of DIRSIG4 and they are getting MODTRAN6 installed. And the question is "How do I use MODTRAN6 with DIRSIG?". And that is the purpose of this post.

Interfacing options

Although there is the new and more robust JSON file interface available in MODTRAN6, it should be noted that MODTRAN6 can still use the old tape5 style input files using one of the following mechanisms:

1. The name of a tape5 file can be specified as a command-line argument if the file is named with a ".tp5" extension. For example, "mod6c_cons foo.tp5"
2. If the name of a tape5 file uses the ".tp5" extension convention, the basename for the file (for example, "tmp" for "tmp.tp5") can be placed in a "modroot" input file and the name of that file provided via a command-line option.  For example, "mod6c_cons -modroot tmp".
3. The tape5 file can be converted into a new JSON file using the conversion utility provided with MODTRAN6 and the name of the converted JSON file can be provided as a command-line argument. For example, "mod6c_cons foo.json".

Currently, DIRSIG writes the "tape5" input file and calls MODTRAN without any additional command-line arguments. So the reality is that none of these mechanism can be immediately utilized because they would all require a modification to the DIRSIG code to to call MODTRAN with specific a command-line option. And since these command-line are specific to MODTRAN6, we would need to introduce an additional flag to say "I'm using MODTRAN6, so launch it this way". Finally, it would not address how to let slightly older versions of DIRSIG4 use MODTRAN6. Hence, our short-term solution is to make a script that wraps around the MODTRAN executable and perform some basic file manipulations so that the script makes MODTRAN6 "look like" older versions of MODTRAN. As a result, MODTRAN6 can be used with any existing version of DIRSIG without any code modifications to DIRSIG or installation updates for the end-user.

Example Wrapper Script

The example script below assumes DIRSIG wrote to the file "tape5", it renames that file to "tmp.tp5" and then launches MODTRAN6 supplying "tmp.tp5" as a command-line argument. Note that this rename approach was selected over the option of converting the input file to JSON in order to avoid the runtime associated with that conversion.  Additionally, DIRSIG expects the output files to be named "tape6", "tape7", etc. so this script also renames the output files after MODTRAN6 has finished execution.

Here is a basic Bourne/Bash script version of the wrapper than can be utilized on Linux or macOS:

#!/bin/sh
#
# MODTRAN6 wrapper for Linux and macOS for DIRSIG4
#

# This variable points to MODTRAN6 bin folder
BIN_DIR=/usr/local/MODTRAN6.0.0/bin/linux

# This variable points to the MODTRAN6 DATA folder.
# Note that this is redundant to what is stored in
# the MODTRAN profile in the DIRSIG4 settings. But
# it MUST be correctly specified here because
# it is a required command-line option that is not
# passed in by DIRSIG4.
DATA_DIR=/usr/local/MODTRAN6.0.0/DATA

# This variable defines the basename of the temporary
# MODTRAN intput and output files. This makes it easy to
# change if we find the current one is a bad choice.
TMP_BASENAME=mod6_tmp

# Step #1:
# Rename "tape5" to a file with a ".tp5" extension so we
# can provide a it as a command-line argument in Step #2.
mv tape5 ${TMP_BASENAME}.tp5

# Step #2:
# Run the MODTRAN6 "console" executable (not the GUI!)
# by specifying the name of our renamed "tape5" file.
# We also provide the path to the DATA folder.
${BIN_DIR}/mod6c_cons ${TMP_BASENAME}.tp5 ${DATA_DIR}

# Step #3:
# Rename all the output files to what DIRSIG4 expects
# them to be.
mv ${TMP_BASENAME}.tp5 tape5
mv ${TMP_BASENAME}.tp6 tape6
mv ${TMP_BASENAME}.tp7 tape7
mv ${TMP_BASENAME}.7sc tape7.scn

# Step #4:
# Remove other output files we don't care about.
rm ${TMP_BASENAME}.psc

The user must modify the script to reflect the location of their MODTRAN6 installation. Specifically, the paths assigned to the BIN_DIR and DATA_DIR variables in the script.

On our systems, we have named this script "mod6_wrapper.sh", given it execute permissions and placed it in the MODTRAN6 "bin" folder with the distributed executables. To use the script, you should add a new MODTRAN profile to your DIRSIG user settings (see the "MODTRAN" tab in the settings/preferences dialog available in the main simulation editor). Rather than point the DIRSIG profile at the MODTRAN executable, you should select the name of this script instead.

Limitations

The primary limitation of this short-term approach is that the it relies on using MODTRAN5 and earlier tape5 files as the primary input. That means any new features the user wishes to utilize in MODTRAN6 (accessed with new options in the new MODTRAN6-specific JSON input file) are not available. However, we wish to emphasize that this a short-term solution that should allow anyone to use MODTRAN6 immediately without needing to update your existing DIRSIG installation.

This script currently relies on the native Bourne/Bash shell execution environments available on Linux and macOS. Since the Windows execution environment does not support these scripts, a similar script will need to be created using the Windows "batch" script facilities.