These tutorials are meant to allow the user to become familiar with the basics of a MODTRAN run. In all cases, the relevant input files will be provided, as well as any resulting output files. Before beginning, it is encouraged that the user look in particular at the values (and their definitions) in the tape5 editor GUI. It is important to note, that in some cases, the definition of some terms can be changed by the value of another. And in some cases, the very existence or non-existence of entire cards hinges on single parameter values.
For example, if you want to set up MODTRAN so that you can control the location of the source (sun or moon), and the observer via latitude and longitude inputs, you must enter in the parameters in card 3A2. At first glance, the tape5 editor may not show a "Card3A2". If IEMSCT in Card1 (the "Mode of program execution") is set to anything but "Thermal and Solar/Lunar Radiance", these cards do not appear in the window. Unfortunately, situations like this are very common in MODTRAN. Fortunately, the MODTRAN user's manual does cover this very well, with procedures for the activation and use of every parameter. The user should keep handy the MODTRAN4 User's manual.
Now, lets get back to the example. You still want to be able to set the location of the source and the observer through the use of latitude and longitude points. Now that card 3A2 is in the window, double click on it. This brings up a separate window, in which there are 8 entries. For now, we are concerned with the four on the left, PARM1, through, PARM4. These should control the observer latitude, observer longitude, source latitude, and source longitude, respectively. However, if the value of IPARM (in card 3A1), is set to "2" or "12", then the definitions of PARM1-4 are not what you would expect or need them to be. This example was just to show the user that there are many subtle interactions between the parameters based on their values. These interactions are not always intuitive, and can lead to the enabling or disabling of various parameters and abilities within MODTRAN. As stated before, keep the MODTRAN user's guide handy, because this can save a lot of time and frustration.
This first tutorial will consist of a very basic tape5 file (the input to MODTRAN). This is a simple ASCII file, whose values trigger different modes, functions, or values in MODTRAN at run time. (Although the tape5 file may be viewed directly, it is advised that the user make use of the tape5_edit command to launch the GUI, and load in the tape5 file this way.)
To launch the GUI, type tape5_edit at the command prompt. (Note: In order to continue working at the same window, type in "tape5_edit &".) The window should contain a list of cards. The default list is "Required Cards" . Now, in order to make a MODTRAN run, we must first enter in a few values. If we run it with just the default values, it will crash.
The first values we must enter are found in CARD1. To access this, simply, double-click on "CARD1", and a separate window titled "CARD1" will appear. Notice that there are many pull-down menus. If you roll your mouse over a box, a tab should pop up momentarily, and inform you of what this particular box does. The first thing we must define is the type of atmosphere we are modeling. This can be done by clicking and holding on the box labeled "MODEL". A list of options will be in the pull down menu. Select "Midlatitude Summer". Directly below this should be a similar pull-down menu marked "ITYPE". Select "Slant Path H1 to H2". This defines the inputs for the geometry we will enter later. Right below that is another box marked "IEMSCT". This sets the mode at which MODTRAN will run. The default is Transmittance, which we will leave for now. The rest of these values can remain the same for this exercise. When you are done, press the "OK" button in the GUI.
The next parameters we must change involve the geometry of the MODTRAN run. These are in CARD3. Again, the message that appears when the mouse is rolled over the box should tell you what that box does. Go to the box marked "H1". This is the observer's altitude. For this value, enter 10. The units for this box are kilometers. "H2" is the target's altitude. For this exercise, we can leave it set at zero. This means that so far, we should have set up a run where we are measuring the transmittance of the atmosphere from 0km up to 10 km. However, there is one more thing we must add in to the CARD3: the viewing zenith angle. There is a big difference between looking straight down at a target, and looking at a target with the same altitude, but at a much higher viewing angle. That difference is the path length. The amount of atmosphere that is between the observer and the target varies as the zenith angle increases. This increase in path length for the higher viewing angles leads to a decreased transmission. So we must set the value of ANGLE in CARD3. The convention used is that the zenith angle is measured from directly overhead. So, the default value, 0.0, would mean that the observer is looking directly up. MODTRAN expects that the observer will see the target (located at an altitude of 0 km), and will crash if this is not the case. So, if we set the "ANGLE" box equal to 170.0, we get an observer-zenith orientation that looks downward. Now, MODTRAN's observer is oriented in the proper way such that it will be able to see down to the the target's altitude.
Now, the last card that we must alter to get a successful MODTRAN run is CARD4. This allows us to define the spectral range and resolution. Double-click on "CARD4" in the window. The first thing to do is to set the units that our spectral range will be in. Go the the pull-down menu labeled "FLAGS1". This is where you can change the input units. The default setting is frequency, so lets leave it for now. Next, roll over the box labeled "V1". the tab should read, we see "Initial frequency or wavelength". Enter in 15152.000 to this box. Enter 22727.000 into the box right below it, labeled "V2". This, as the roll-over tab can tell you, is the "Final frequency or wavelength".
The next set of boxes are also required. These are labeled "DV" and "FWHM". "DV" is the spectral interval, which can be set to 100.000 for this exercise. This basically sets how many spectral points there will be in the output. The next value is the "FWHM" (Full-width at half-max). The value in this box can not be set less than the value in "DV", to prevent undersampling. According to the MODTRAN4 User's Manual, the recommended "FWHM" value is twice that of the spectral interval ("DV"). So, set "FWHM" to 200.000. As well, we must set the value in "FLAGS4" to "degrade all components".
Now, the tape5 file should be complete. Save this current set-up in the working directory as tutor_1.tp5. To run MODTRAN with this input, type:
prompt> modtran4r01.exe tutor_1.tp5
After not too long, depending on your computer speed, the program should finish, creating a set of output files. Among these, should be the "tape7" and "tape7.scn" files. These hold the results of the MODTRAN run. Looking at "tape7", we see a header section, followed by a list of spectral points with corresponding transmissions. Each column has a different component of the transmission. The total is found in the second column.
If we take a look at the "tape7.scn" file, we see data laid out in a similar format, but the spectral values have been convolved with the slit function we defined in CARD4.
DIRSIG does make use of the transmission values calculated from MODTRAN, however, it also needs to know about the light that is scattered by the atmosphere. To make a run that will calculate the path radiance, we must further alter the tape 5 file.
First, we open up the tape5 editor once again. Open the file "tutor_1.tp5". The first parameter to change is in CARD1. This is the "IEMSCT" box. It should still read "Transmittance". Change it to "Thermal and Solar/Lunar Radiance". Press "OK", and you should notice that there are two additional sub-cards in the window now, "CARD3A1" and "CARD3A2". These cards will allow more flexibility in defining geometrical values. More flexibility is needed to calculate the radiance, because now, direction matters. In the Transmittance mode, the source-target-sensor angle made no difference to the output data. When we deal with path radiance, there is directional scattering to account for. This depends greatly on the relative positions of the source, target, and sensor.
Now, the first of the notable entries for these new cards is in CARD3A1. This is the "IPARM" value briefly mentioned before. This controls the method of defining the positions of the source and the observer. Leave this set to zero. Next, go to CARD3A2. "PARM1" and "PARM2" control the latitude and longitude, respectively, of the observer (H2). As well, "PARM3" and "PARM4" are the latitude and longitude of the source (projected straight down on the Earth's surface). Leaving these at the default of 0.0 will make the source and the sensor be in a straight line, directly above the target, which is fine for this demonstration.
Now, if we look again at the resulting "tape7" and "tape7.scn" files, you will notice that their format has changed. There is a similar header to the file, but the columns are different. There is still the total transmission in the first column, but the subsequent columns have values for thermal scattering, surface emissions, solar scattering, etc. This format of the tape5 file was included in the tutorial because this is the mode in which DIRSIG runs MODTRAN.
Now, of course, there are limitless options to customizing the atmosphere. This tutorial was designed to get the user at least introduced to the whole process. As this applies to DIRSIG, we are only concerned with the cards that DIRSIG doesn't change automatically as it runs. These are, essentially, cards 1, 1A, and 2. (Although, technically, DIRSIG does change the "ITYPE" parameter in CARD1 depending on if the run is going in the upwelling or downwelling section of the ADB, but it is a minor point.)
This section will walk through the steps needed to create an atmospheric database for DIRSIG. The first step is to define a path and a atmospheric database name in the DIRSIG configuration file. It should not matter where your ADB is in relation to your working directory, just that the path that is defined in the .cfg file correctly points to the proper file name.
Next, you must also define a path and a file name for your tape5 file. This can be thought of as a "prototype" MODTRAN run. Remember which parameters will be changed and which will not. (As a general rule, the parameters in CARD1, CARD1A, and CARD2 are not changed by DIRSIG). You also must customize your tape5 file to whatever atmospheric specifications are needed.
The program that creates the atmospheric database is called make_adb. To build the atmospheric database for the simulation described in the tutor.cfg configuration file, run the following command:
prompt> make_adb tutor.cfg
The program then goes into the tutor.cfg file and gets all of the geometric information in the sensor section of the file, and creates the ADB, storing it as the filename specified in the configuration file.
If DIRSIG crashes in this stage, and it is an atmosphere related problem, there will be a printout saying that MODTRAN crashed for some unknown reason. This could be because of a faulty input in the configuration file that caused MODTRAN to run in an illegal manner. For example, if the DIRSIG sensor is initially pointing above the horizon, then MODTRAN will crash. This is similar to our problem in an earlier tutorial; DIRSIG is telling MODTRAN to look up, when MODTRAN expects to look down.
Another common cause of MODTRAN errors when making the ADB is improper spectral data. DIRSIG can pass a bad value of the spectral resolution to MODTRAN, causing a crash. In this case, these values should be checked.
Please consult the make_adb Troubleshooting Tips section of the manual for tips on how to resolve such problems.