The setup of the subdirectory MAIN is analogous to that of PREP.
Although there are many more options that can be invoked when
compiling and running main.F, the goal here is to give an
overview of the procedure and what is available. The discussion
will be kept brief.
main.F
Just as prep.F was the central routine in PREP, main.F is the central routine in MAIN. All other routines within this directory and its subdirectories are used to provide information to main.F. Input/Output and time-stepping are the principal tasks performed in MAIN. The executable file main is compiled from MAIN/ Makefile by typing ``make". The routine main reads the information that was stored away by prep plus some parameter values that are defined locally, makes a few last minite, run-specific preparations and then begins the time-stepping procedure. As the model marches forward in time, it periodically stores away data for later analysis.
The detailed nature of a run is controlled by the specification of parameter values and C-preprocessor directives. Parameter values are passed to main by the file Runtime_parm.tag where tag is an identifier for the particular run. Note that there can be many different runs of main initiated from the same set of data prepared by a single run of prep, and each of these runs will be identified by its own distinct user-specified tag. The code is presently set up to accept any alpha-numeric string up to 20 characters long for the tag.
AN_ID.h and Define.h
The C-preprocessor directives used by main are determined by the local files AN_ID.h and Define.h. The file MAIN/ AN_ID.h supplies the case name that is used within Define.h to determine which C-preprocessor directives are invoked. It will be the same case name as given in the PREP/ AN_ID.h file. There are many more options for main.F than for prep.F, but the methodology is identical and need not be repeated here. Most of the options available should be obvious upon looking at the Define.h file supplied with the routines. Near the beginning of this file, the user will find a long list of #undef statements which are included solely to record the list of options that are available. The names are generally self-explanatory, but more detailed information can be found in the section of this document entitled Subroutines and Include Files or by studying the code invoked for a given option.
Diecast.h and Local_Arrays.h
Both Diecast.h and Local_Arrays.h are used to set up parameter definitions, arrays and common blocks for main.F. The file Diecast.h is copied from the PREP subdirectory to minimise the possibility of the dimensions specified in MAIN being inconsistent with those used in PREP. Note that the major parameters contolling array dimensions, I0, J0, and K0 are specified in Diecast.h. Some of the arrays in Diecast.h are not needed by main.F and these are automatically excluded by isolating them with #ifdef PREP_ARRAYS within Diecast.h so that they will not be included in main.F unless the user were to define PREP_ARRAYS in Define.h (which should never be necessary).
Other arrays required by main.F are not included in Diecast.h. Any such ``local'' arrays are specified in the file SUBS/ Local_Arrays.h. If the user adds code to main.F which requires new arrays, these should generally be specified in the file Local_Arrays.h so that they will be widely available throughout the subroutines of main.F (assuming of course that they are placed in a common block).
main.F cont'd
The first part of main.F is set up as a contoller routine that contols the forward integration in time but calls on other subroutines to do almost all of the work. The program main.Fstarts out by requesting a name tag that will be used to identify the present run. This tag tells main.F which Runtime_parm.tag file to read parameters from and is used to identify the output from this particular run. Next, main.F requests the tag_root from which it will read in the information prepared for it by prep. If the run is to be restarted from the end of a previous run, then the user must also supply the name of the local tag of the run from which it is to be restarted. Note that the run being restarted must have the same tag_root as that run from which it is being continued, because both runs must have the same initialization.
When the program main is executed and receives the local run tag and preparation tag_root names as input, a new subdirectory called OUTPUT.tag_root/tag is automatically created. Any information stored within the directory OUTPUT.tag_root will necessarily have initiation parameters consistent with tag_root, and the SETUP subdirectory within OUTPUT.tag_root is intended to serve as a reminder to the user about the setup of this root run. Similarly, main.F creates a subdirectory called OUTPUT.tag_root/tag/SETUP in which setup information for the new run identified by the local tag is placed. Again, this information can serve as a reminder to the user of the setup of the new run.
The first significant routine called in main.F is INITFS (which stands for ``initialize Free Stream"), the code for which is stored in SUBS/ initfs.F. This routine is responsible for reading in the information that was stored by prep, reading in parameter values from Runtime_parm.tag, determining several arrays that depend on the information provided by prep but were not determined by this routine, and reading in the information required to restart from the end of a previous run if this is required.
Once the initialization is complete, main begins marching forward in time with the iteration counter ITF = 1, 2,..., MXIT. The real work associated with a forward timestep, is done by calling the free stream subroutine FS. Subroutine FS is the real workhorse of the main program. Its purpose is to update all model variables to the next time level. After FS is called, any output that the user has specified is saved, and the routine then checks to see if it is time to stop. If it is not time to stop, the main routine loops back and initiates another time step. The procedure repeats until the run is completed.
There are two ways that the main routine can finish. The first possibility is that the number of timesteps to be taken, as specified by the parameter MXIT in file Runtime_parm.tag, has been reached. This is the most obvious way that a run will end, but sometimes the user may wish to stop execution before this time is reached. This possibility is allowed for by the file stoprun.tag. Periodically (presently every 10 time steps), main opens this file and checks its contents. If it contains a 0, then stoprun.tag is simply closed and the run continues. If stoprun.tag contains a 1, then a restart file is immediately created and stored in the local file fort.99 and the run is terminated. Note that the restart file is not stored in the file OUTPUT.tag_root/tag/ RESTART.tag where it would normally be stored. This is done just in case the user is stopping the run because the output reveals that problems are developing. In this case, the user may prefer to restart a future run from the restart file saved at an earlier time. If the user wishes to restart from the latest output, then fort.99 must be copied to OUTPUT.tag_root/tag/ RESTART.tag before the new run is initiated.
The file stoprun.tag can also be used to change the value of MXIT so that a controlled termination is done either sooner or later than originally specified by the value of MXIT in Runtime_parm.tag. This type of termination is accomplished simply by entering the new value of MXIT as the single entry in stoprun.tag.
