MODTRAN Integration Guide

At this time, DIRSIG has been tested to work with the following versions of MODTRAN:

These versions of MODTRAN have been found to work on Windows, MacOS and UNIX platforms.

Prior to MODTRAN6, MODTRAN did not come with a robust, standardized, well documented application programming interface (API) and software like DIRSIG had to integrate with MODTRAN through MODTRAN’s standard file interfaces. For a variety of reasons, this coupling was problematic. For example, different versions of MODTRAN behaved differently when an error occurred or reported that same error differently. In other cases, the format of various input and output files changed and software that reads and writes those files must be updated.

MODTRAN6 (the latest version of MODTRAN) 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.

MODTRAN uses a "band model" approach to store the spectral absorption lines of the native gases in the atmosphere. That means there is a database containing the absorption lines rendered to a specific spectral resolution. For example, MODTRAN6 comes with 4 band model files supporting 4 different spectral resolutions:

Many users are more familiar with wavelength units (microns, nanometers, etc.) and find working with wavenumbers awkward. It is important to recognize that there is an inverse relationship between wavenumbers and wavelengths. To compute the equivalent wavenumber for a 0.5 microns, the math is:

\begin{equation*} \frac{10,000}{0.5~\mathrm{microns}} = 20,000 ~\mathrm{cm^{-1}} \end{equation*}

Converting a resolution is not as straight forward since the equivalent wavenumber interval between the converted wavelengths must be computed. For example, a 0.02 micron interval centered at 0.50 microns (0.49 → 0.51 microns) converts to:

\begin{equation*} \frac{10,000}{0.49~\mathrm{microns}} - \frac{10,000}{0.51~\mathrm{microns}} = 20408.163 ~\mathrm{cm^{-1}} - 19607.843 ~\mathrm{cm^{-1}} \approx 800 ~\mathrm{cm^{-1}} \end{equation*}

However, the same 0.02 micron interval centered at 5.0 microns (4.99 → 5.01 microns) converts to:

\begin{equation*} \frac{10000}{4.99~\mathrm{microns}} - \frac{10000}{5.01~\mathrm{microns}} = 2004.008 ~\mathrm{cm^{-1}} - 1996.007 ~\mathrm{cm^{-1}} \approx 8 ~\mathrm{cm^{-1}} \end{equation*}

So the same wavelength interval has a dramatically different equivalent wavenumber interval depending on the wavelength. To make it easier, we provide the following table that includes the equivalent resolution limits for different versions of MODTRAN at different wavelengths:

The MODTRAN installation folder contains a folder named TEST, which contains 50+ test scenarios for use with MODTRAN. It is best to test the correct operation of your MODTRAN installation by attempting to run some of those test cases. Specifically, verifying that those test cases can be run in a folder outside the MODTRAN installation folder is important. Consider the following test procedure:

If MODTRAN does not run correctly, consider the following steps to understand the nature of the problem:

The most common message that a user will receive is that DIRSIG is that the tape7.scn (or .7scn) file could not be read.

The major development in MODTRAN6 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.

Using MODTRAN6 with the DIRSIG5-era atm_builder and fourcurve_builder tools is described in the Atmosphere Model Backends Manual.

Using MODTRAN6 with the DIRSIG4-era make_adb tool is described in this section of the make_adb manual.

This first section discusses the typical installation layout of MODTRAN5. Although the MODTRAN software comes with installation documentation, we will highlight some important aspects here.

As of MODTRAN 5.2.0, both the Windows and MacOS releases had the MODTRAN program, band model files, etc. pre-packaged and ready to use:

On the UNIX platform, the software must be compiled from the source code. Follow the instructions included with MODTRAN on how to perform this task.

The MODTRAN input files generated by DIRSIG will include the path to the MODTRAN DATA folder containing the band model, correlated-k, etc. database files. The field for this folder path in MODTRAN is limited to 80 characters.

If you are using DIRSIG and/or MODTRAN on a Windows machine that employs the "Universal Naming Convention" (UNC) or what is sometimes called "Mapped Network Drives", a variety of problems have been reported. A UNC path in Windows is when a shortcut to a shared drive is created that does not contain a drive letter. For example, rather than a user’s home folder being Z:\joeuser, the mapped name might be \\home\joeuser.