This guide is meant to help users understand and resolve common warnings and errors generated by DIRSIG and it’s companion utilities.
Configuration Verification Failures
At the start of execution, the atmospheric database builders (make_adb, atm_builder, etc.) perform a multi-step configuration check on the supplied MODTRAN configuration soon after the program starts but before it starts to run MODTRAN for the specific cases needed for your simulation. The point of this check is to identify specific configuration issues before getting into the data generation phase of the execution. The checks focus on commonly occuring mistakes made in the configuration provided to DIRSIG. This checks include:
Verifying the MODTRAN executable provided exists,
Verifying the MODTRAN executable provided is a program,
Verifying the MODTRAN
DATAdirectory provided exists,
Verifying the MODTRAN
DATAdirectory is a directory,
Verifying that a simple MODTRAN input can be read,
Verifying that this simple MODTRAN input can be run, and
Verifying that the expected MODTRAN output files are produced.
When correctly configured, this series of checks will produce the following series of messages:
Verifying MODTRAN configuration: Checking if MODTRAN program path exists ... passed! Checking if MODTRAN program is executable ... passed! Checking if MODTRAN data path exists ... passed! Checking if MODTRAN data path is a directory ... passed! Reading a simple MODTRAN example ... passed! Running a simple MODTRAN example ... passed! Checking for MODTRAN output files ... passed!
If any of the checks fail, an informative error should be provided that identifies the problem. For example:
Verifying MODTRAN configuration: Checking if MODTRAN program path exists ... checkAtmModels: ERROR! Invalid path for MODTRAN executable File does not exits! Executable path = '/opt/Mod4v3r1/Mod4v3r1.exe'
In this case, the provided path to the MODTRAN executable was invalid.
The user should verify the correct path and update the relevant profile
in their user settings or input configuration file. Similar errors are
generated for checking the existance of the
DATA directory provided
and permissions for the executable and data directory. For example:
Verifying MODTRAN configuration: Checking if MODTRAN program path exists ... passed! Checking if MODTRAN program is executable ... checkAtmModels: ERROR MODTRAN is not executable by this user! Executable path = '/opt/Mod4v3r1/Mod4v3r1.exe'
This error indicates that the path to the MODTRAN executable might be valid but the user does not have permissions to run the program.
Providing specific solutions for the large variety of reasons that MODTRAN might not run the simple test scenario is not possible. Instead, the following specific troubleshooting tips related to a failed test execution are provided:
If the "running a simple example" check fails, look in the
test_runfolder for the input
tape5file that was used and any MODTRAN output files.
Depending on the DIRSIG program, the version of MODTRAN, etc. specific errors might be captured in the following files:
For DIRSIG5-era generators, look in
For DIRSIG4-era generators, look for the
Any MODTRAN version specific warning or error files (e.g.,
If it exists, the
<root>.tp6file can contain errors.
Could not open MODTRAN output file
A make_adb run fails with the following (or similar) error:
make_adb: OPEN ERROR Could not open MODTRAN output file! Filename = solar_path_00000/tape7.scn Exiting...
The folder containing the file might vary (
sky_path_xxxxx, etc.) but the key element is
that a file named
tape7.scn could not be opened.
This file is one of the standard MODTRAN output files that the
program tries to read in. If this file cannot be opened, it means it was
never generated. Which means that MODTRAN (a) never started or (b) started
but did not complete.
There are numerous reasons why MODTRAN might not start or might not complete and this guide cannot individually address all of them. Instead, we should start with finding out what MODTRAN might have reported when attempting to run this case:
Start by looking at the
modtran.logfile for your simulation. This will contain a series of messages related to running MODTRAN behind the scenes. It may also have captured error messages were generated by MODTRAN that would normally have gone to the console. Such an error (if present) would likely explain the specific issue clearer than a long list of possible issues would here.
It can then be valuable to look in the folder itself (in this case,
solar_path_00000). That folder should contain the
tape5file that was generated by the
If MODTRAN completely failed to start, then there won’t be any other files present and the
modtran.logfile will have the most information.
If MODTRAN ran, but failed to complete then there will be a
tape6file present, and potentially a
tape7file present, but the
tape7.scnfile is not present. In this case, you want to check the
modtran.logfile but also the
tape6file for errors and/or warnings.
The user can always attempt to manually run MODTRAN in this folder to directly observe any MODTRAN warnings and/or errors. Be sure to run the exact same executable that
make_adbis using (i.e., the executable path from the respective MODTRAN profile from the user’s Preferences/Settings).
If using MODTRAN6 with the suggested
wrapper script approach, then the
MODTRAN output files might still be
Spectral resolution is too fine
A MODTRAN simulation fails with a message indicating that the "spectral
resolution is too fine" (normally output by the
CHKRES function in
STOP Error in CHKRES: Spectral resolution is too fine.
Depending of the version of MODTRAN, this error might have been captured by
the logs created by DIRSIG of the MODTRAN console output or it might appear
xxx.tp6) output file.
When this error is generated, it means that the requested spectral output requested in the MODTRAN input file exceeded the spectral resolution of the band model being used. Unless otherwise specified via advanced options in the input, MODTRAN will automatically pick the appropriate band model. In the case of using the automatic selection mode (the most commonly used), then the error indicates that the requested resolution exceeded that of the highest resolution band model file available. If your input explicitly requests a specific band model file, then the resolution exceeds that supported by the requested file.
There are several possible solutions to this problem:
If the user-supplied input (e.g.,
tape5file) explicitly requests a band model file, select an alternate band model file that supports the requested resolution. Or let MODTRAN choose the best band model file automatically.
If using an old version of MODTRAN (e.g., MODTRAN4), upgrade to the latest version (e.g., MODTRAN6) to gain access to the higher resolution band model and dozens of other improvements.
Decrease the spectral resolution of the sensor to meet the resolution of the available band models.
NewAtmosphere Plugin Related
The following warnings and errors are specific to the NewAtmosphere plugin.
Backend Request Failure
The "backend" modules interface DIRSIG5’s various atmospheric database builders with atmospheric radiative transfer models. Each backend is an adapter between generic atmospheric radiative transfer requests and the specific model that they interface with (e.g., MODTRAN). Due to the complex nature of the interaction, a myriad of errors can occur. Using one possible error scenario, this section attempts to provide the user with a guide to identify the specific error that occurred in their situation.
During the building of a new atmospheric database using the atm_builder tool, an error similar to that below is generated:
Version: 2022.27 (d968ad6) built on Jul 6 2022 07:02:14 Copyright 2015-2022 Rochester Institute of Technology ... [output deleted for documentation purposes] ... Generating data for spectral+temporal state #0 (226 requests) Sun zenith/azimuth = 45.000000,90.000000 Moon zenith/azimuth = 45.000000,270.000000 Moon phase angle = 0.000000 (fraction = 0.500000) Multi-threaded atm model request runner is using 10 threads (processes) Exception encountered while building database! backend failed to perform request: MODTRAN output file "/Users/dirsig/test/modtran_runs0/127/tmp.7sc" is empty
This is considered a fatal error and will halt execution.
The error indicates that the builder attempted to run MODTRAN and that
attempt failed. In this case, the specific MODTRAN run in the
modtran_runs0/127 folder was the one that failed. The
folder is a temporary folder created by
atm_builder within which it
constructs a series of sub-folders for each MODTRAN run to execute. The
run sub-folders are numbered based on their position in the request
queue. In this case, run
127 was the setup that failed. Various errors
might be encountered that would indicate the MODTRAN run did not execute as
expected. However, these are usually related to one or more of the MODTRAN
output files is missing or empty. In example above, the
was found to be empty.
There are many reasons why a MODTRAN run can fail that are unrelated to your simulation. These primarily have to do with the configuration of MODTRAN in the backend:
The path to the MODTRAN executable is wrong (see the
modtran_exevariable in the backend configuration).
The path to the MODTRAN
DATAdirectory is wrong (see the
modtran_datavariable in the backend configuration).
ModtranTapebackend, the name of the "root" filename is wrong (see the
modroot_filenamevariable in the backend configuration).
Backend configuration issues should start with a review of the backend setup options.
To diagnose the root cause and hopefully address the nature of the
problem, we will look at the files in the run sub-folder. In this
case the name of the folder where the run failed was
but the exact name of the sub-folder can obviously vary. Browse
to this folder and look at what files exist. The list of files is
the first indicator of where things went wrong.
The folder listing below illustrates the minimal set of input files for
MODTRAN that were generated by the
-rw-r--r-- 1 dirsig dirsig 253 Jul 6 07:22 README.txt -rw-r--r-- 1 dirsig dirsig 3 Jul 6 07:22 modroot.in -rw-r--r-- 1 dirsig dirsig 553 Jul 6 07:22 tmp.tp5
If this is all the files contained in the folder, then MODTRAN never ran and the problem is most likely in the backend configuration.
If the folder listing contains the files
modtran_stdout.txt, then MODTRAN was run and failed. Most likely,
some of the MODTRAN output files will also exist in in this case. Below
a long/detailed listing of the files you might find in the folder in this
case if MODTRAN ran but failed:
-rw-r--r-- 1 dirsig dirsig 253 Jul 6 07:22 README.txt -rw-r--r-- 1 dirsig dirsig 3 Jul 6 07:22 modroot.in -rw-r----- 1 dirsig dirsig 138 Jul 6 07:22 modtran_stderr.txt -rw-r----- 1 dirsig dirsig 0 Jul 6 07:20 modtran_stdout.txt -rw-r--r-- 1 dirsig dirsig 0 Jul 6 07:22 tmp.7sc -rw-r--r-- 1 dirsig dirsig 0 Jul 6 07:20 tmp.7sr -rw-r--r-- 1 dirsig dirsig 0 Jul 6 07:22 tmp.mc -rw-r--r-- 1 dirsig dirsig 553 Jul 6 07:22 tmp.tp5 -rw-r--r-- 1 dirsig dirsig 1940 Jul 6 07:22 tmp.tp6 -rw-r--r-- 1 dirsig dirsig 0 Jul 6 07:22 tmp.tp7 -rw-r--r-- 1 dirsig dirsig 0 Jul 6 07:22 tmp.tp8
As we can see in this detailed listing, many of the MODTRAN output files
are zero length (empty), which corresponds to the error specifically used
in this example (
tmp.7sc is empty).
The first place to start is looking at the
modtran_stdout.txt. In this case, the error file is not empty (it is
138 bytes long) and most likely contains an error produced by MODTRAN.
$ more modtran_stderr.txt Note: The following floating-point exceptions are signalling: IEEE_UNDERFLOW_FLAG STOP Error in CHKRES: Spectral resolution is too fine.
|For guidance on how to resolve this specific error see this section.|
modtran_stdout.txt files do not contain
any useful error messages, then you should look in other locations.
Look at end of the
tmp.tp6file for warnings and/or errors.
Check if there is a
If none of the MODTRAN output files contain a useful error, then it is
possible the error was written to the output and (somehow) not captured
modtran_stdout.txt files. In this case,
we suggest you manually run MODTRAN from the command-line to observe any
warnings or errors produced.
Missing Spectral/Temporal State
During the execution of the simulation, the following error is generated:
NewAtmosphere::updateState: Missing spectral/temporal state in atmosphere database! Filename = 'example.adb.hdf'
This is considered an error and will halt execution.
When the atmospheric database was generated (see the atm_builder utility), the sensor plugin(s) associated with the simulation defined a set of spectral and temporal states that the database was created to support. A spectral state is a set of wavelengths and a temporal state is a date/time. Each table in the database is for a given sensor (the spectral state) and time (the temporal state) and this error indicates that during the simulation a spectral and temporal state combination was looked for in the atmospheric database but it could not be found.
This can arise from changes to the simulation since the atmospheric database was created. For example:
The spectral description of one of the sensor plugins was altered. For example, the spectral bandpass or sampling of a bandpass was changed.
The temporal description of one of the sensor plugins was altered. For example, the start time, end time and/or duration that a sensor plugin is collecting changed.
A new sensor plugin was added to the simulation or a new camera, instrument, focal plane, etc. was added to an existing sensor plugin.
The atmospheric database needs to be reconstructed to reflect the additional spectral and/or temporal states required by the sensor plugin(s) in the simulation.
BasicPlatform Plugin Related
The following warnings and errors are specific to the BasicPlatform plugin.
Unevenly Sampled Bandpass
During the setup of a sensor plugin, the following error message is generated:
readBandpass: Bandpass is not evenly sampled! [0.4 - 0.705] @ 0.01
This is considered an error and will halt execution.
The BasicPlatform plugin attempted to create the list of wavelengths
for the supplied bandpass but discovered that the range defined by
the min and max cannot be evenly divided by the delta. In this
example, we can see that the delta (
0.010) would not evenly
sample the range from
0.705. Specifically, we could
see that if we start computing the wavelengths starting at the
0.420 …) that when we get to
the end of the bandpass the samples don’t include the supplied
0.710 does not
There are two ways to resolve this problem:
Adjust the bandpass minimum or maximum to agree with the delta. In this case, we could leave the minimum and delta as is and adjust the maximum to be
Adjust the delta to evenly sample the range defined by the minimum and maximum. In this case, we can adjust the delta to be
0.005which would produce a wavelength list that includes the minimum and maximum (e.g.,
During the setup of a sensor plugin, the following warning message is generated:
Channel::setup: WARNING! Channel is truncated by the bandpass! Name = 'Red' Bandpass = [0.40000 - 0.70000] microns Channel = [0.32400 - 0.57600] microns
This is only a warning and will not halt execution.
You have defined a channel that has a given spectral extent but the spectral bandpass associated with the focal plane truncates that channel. When the platform file generating this warning is loaded into the graphical Platform Editor the channel plot in the Basic Capture Editor helps to visualize the problem:
Red channel is the highlighted Gaussian shaped channel to the far
left and you can see that the
0.700 bandpass is clipping off
the leading tail of that channel.
|This warning can be generated for multiple channels and applies to both tabulated and functional channel shapes.|
To resolve this warning, you will want to adjust the bandpass minimum (or
maximum) so that it correctly spans the channels associated with the
focal plane. In this example, the minimum of the bandpass needs to
be changed to a shorter wavelength to avoid clipping the
Below shows the channel plot with the bandpass minimum adjusted from
0.400 down to
0.370 and which resolves the issue:
Scene/Sensor Spectral Overlap
When a simulation starts, you receive an error that resembles the following:
While checking spectral consistency: State wavelength range: 0.45 - 1.5 [um] Scene wavelength range: 0.30 - 1.4 [um]
This is considered an error and will halt execution.
The "state" wavelength range corresponds to the spectral bandpass for one of the sensor plugins in your simulation. For example, if you are using BasicPlatform plugin then this would correspond to the bandpass associated with one of the focal planes. The "scene" wavelength range corresponds to the scene used in your simulation. When someone builds a scene, they might not have enough data to populate the spectral databases at all wavelengths. As part of the scene meta-data, the scene builder can indicate which wavelengths the spectral database for the scene supports.
What the error is highlighting is that you are using a sensor that is looking at wavelengths that are not supported by the scene. Specifically, the scene has spectral coverage out to 1.4 microns but the sensor wants to simulate out to 1.5 microns.
There are limited solutions for this situation:
Since the scene does not contain the spectral data to support the sensor, we can improve the scene databases to include that data and then update the meta-data spectral coverage description to indicate the expanded coverage.
Since the scene doesn’t support the sensor’s needs, use a different scene.
Since the scene doesn’t support the sensor’s needs, use a different sensor.