DIRSIG Troubleshooting Guide

A make_adb run fails with the following (or similar) errors:

Or a atm_builder or fourcurve_builder run fails with the following (or similar) error:

The folder containing the file might vary (solar_path_xxxxx, sensor_path_xxxxx, sky_path_xxxxx, modtran_runs0, 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 make_adb, atm_builder, fourcurve_builder, etc. programs try 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.

If you were running the DIRSIG4-era make_adb tool:

If you were running the DIRSIG5-era atm_builder, fourcurve_builder, etc. tools:

A MODTRAN simulation fails with a message indicating that the "spectral resolution is too fine" (normally output by the CHKRES function in MODTRAN):

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 in the tape6 (or 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:

A MODTRAN simulation fails with a message indicating that it "needs more spectral points" (normally output by the CHKRES function in MODTRAN):

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 in the tape6 (or xxx.tp6) output file.

When this error is generated, it most likely means that the spectral bandpass requested in the MODTRAN input file had no width or defines a single spectral sample. MODTRAN cannot run when the minimum and maximum wavelength (or wavenumber) are the same (zero width) or with a single spectral sample.

This is most likely because the DIRSIG sensor model was configured to have the respective minimum and maximum wavelength be the same or the spectral sampling results in a single point (i.e., the spectral sampling interval or delta is equal to the difference between the minimum and maximum). DIRSIG and MODTRAN are inherently spectral models, so requesting more than a single spectral sample is required. In most cases, we want 10s or 100s of spectral samples to capture the variability in a channel.

The resolution to the problem is to define spectral bandpasses in the configured sensors with more than 1 (ideally many more than 1) spectral samples. Since each DIRSIG sensor plugin has its own way of defining the spectral bandpass, there is no universal solution. However, the following quick guidance is provided for the most commonly used sensor plugins:

A MODTRAN simulation fails with a message indicating that the "tangent cannot be reached" (normally output by the FINDMN function in MODTRAN):

When this error is generated, it means that the requested path in MODTRAN never intersected the atmosphere. This usually indicates that the user has configured an exo-atmospheric sensor that has a FOV that includes the earth limb (an off nadir view that sees both the earth and space). This specific (but terse) error is indicates that a path was requested from H1 to H2 but the tangent height of the path (lowest altitude) wasn’t reachable.

There is no resolution to this problem, because MODTRAN is not intended to be used to view the limb of the earth or the day/night terminator. Due to MODTRAN’s internal round earth model and path refraction it is difficult for DIRSIG to accurately predict which paths that will intersect the earth, skim the horizon, skim the top of the atmosphere, etc. Hence, DIRSIG is currently unable to detect these conditions prior to sending them to MODTRAN and tell the user that the viewing geometry is unsupported.

During the building of a new atmospheric database using the atm_builder tool, an error similar to that below is generated:

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 modtran_runs0 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 tmp.7sc file 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:

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 modtran_runs0/127 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 atm_builder tool.

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_stderr.txt and/or 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:

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_stderr.txt and 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.

If the modtran_stderr.txt and modtran_stdout.txt files do not contain any useful error messages, then you should look in other locations.

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 in the modtran_stderr.txt and modtran_stdout.txt files. In this case, we suggest you manually run MODTRAN from the command-line to observe any warnings or errors produced.

During the execution of the simulation, the following (or similar) error is generated:

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 atmospheric database needs to be reconstructed to reflect the additional spectral and/or temporal states required by the sensor plugin(s) in the simulation.

During a spectral state change during the simulation, the following (or similar) error message is generated:

This is considered an error and will halt execution.

The error indicates that the atmospheric database being used for the simulation only supports 0.35 → 2.55 microns and the simulation contains a sensor that is trying to model 8.00 → 12.50 microns. In this case, the user was most likely using the default database, which only supports the VIS/NIR/SWIR wavelengths (as indicated by the 'Database wavelength range' in the error) with a LWIR sensor (as indicated by the 'State wavelength range' in the error). Since the database doesn’t contain the data necessary to support the simulation, the error resulted. Note that this error would have also been encountered with an MWIR sensor since that is also outside of the VIS/NIR/SWIR wavelengths supported by the database being used.

To resolve this error, the user needs to select or generate another database that supports the MWIR and LWIR. Alternative databases that support alternative altitudes and alternative wavelength ranges are available in the DIRSIG downloads.

At the end of a simulation, the following warning message appears:

During the simulation, one of the sensor plugins requested data from the FourCurveAtm plugin from an altitude that was more that 110% higher than the nominal altitude of the database being used.

To resolve this error, the user needs to select or generate another database that supports the desired altitude (see the nominal_altitude configuration option). Alternative databases that support alternative altitudes and alternative wavelength ranges are available in the DIRSIG downloads.

During the setup of a sensor plugin, the following (or similar) error message is generated:

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.400 to 0.705. Specifically, we could see that if we start computing the wavelengths starting at the minimum (e.g., 0.400, 0.410, 0.420 …​) that when we get to the end of the bandpass the samples don’t include the supplied maximum (e.g., 0.680, 0.690, 0.700 and 0.710 does not include 0.705).

There are two ways to resolve this problem:

During the setup of a sensor plugin, the following (or similar) warning message is generated:

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:

The Red channel is the highlighted Gaussian shaped channel to the far left and you can see that the 0.400 to 0.730 bandpass is clipping off the leading tail of that channel.

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 Red channel. Below shows the channel plot with the bandpass minimum adjusted from 0.400 down to 0.370 and which resolves the issue:

When a simulation starts, you receive an error that resembles the following:

The error indicates that the scene HDF file being supplied to DIRSIG was created with an older version of the scene2hdf scene compiler, and the file is incompatible with the current version of DIRSIG.

On rare occasions, a limitation of the compile scene data model must be addressed by changing the layout of the HDF file When that happens, the version of the scene HDF is updated to reflect the change. When a scene is loaded into DIRSIG, one of the first things that is checked is the version stored in the HDF file. If it does not match the version(s) supported by DIRSIG, then the above error is generated.

To resolve the issue, the scene must be recompiled with the companion version of scene2hdf distributed with DIRSIG:

When a simulation starts, you receive an error that resembles the following:

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:

When a simulation runs using the debug log, you receive a warning that resembles the following:

This is only a warning and will not halt execution.

The Earth core is a construct meant to act as a backstop to catch rays that pass through gaps in geometry or simply enter areas of the simulation where no geometry exists, but the Earth is expected to be present. It is an ellipsoid based on the global WGS84 datum that has a constant altitude of the lowest altitude on Earth (roughly 430 meters below sea level). Note that in-water simulations are not affected since the "core" is never checked for paths within a medium other than the atmosphere.

When a DIRSIG path encounters the core, it is treated as a perfectly absorbing body and most truth values are set to NaN (Not a Number). The reason for this is that its a good indication that the simulation is not properly bound and rays that escape the world as it is defined may have a detrimental effect on the radiometry. It also has practical benefits, such as preventing paths that would otherwise pass through the Earth …​ and interface with the atmosphere on the other side …​ from needing to be handled in another way.

There are a variety of ways to resolve this situation depending on the underlying cause: