The above discussion deals with the case of a realistic simulation of
the North Atlantic circulation. It is set up on a lon/lat grid from
input specifications in file Prep_parm.tag_root.
Such runs require the use of
spherical coordinates, horizontal and vertical grids that cover the
region of interest, real bottom topography, initial temperature and
salinity, and realistic forcing terms. The requirement for realistic
conditions in such runs requires that the code be able to access
appropriate data files and interpolate the data to the model grid.
This is the default set up proceedure for file prep.F.
In contrast to such realistic simulations, numerical models are also used to do highly idealized tests for which real data is not required. The setup for such cases is generally considerably simpler than for a realistic simulation and it is convenient to substitute a large section of prep.F with alternative, simplified code supplied by the user. This is done by choosing the C-preprocessor SPECIAL_TEST option in file Def_prep.h. The substitution of this simplified code in prep.F is the only thing ``special'' about a SPECIAL_TEST. There is no difference whatsoever in the routines within MAIN that are used to actually perform a run.
As the code is presently configured, the following arrays must be supplied separately by the user when SPECIAL_TEST option is selected:
It should also be noted that when the SPECIAL_TEST option is selected, prep does not read any information from the Prep_parm.tag_root file. The user is expected to locally define any of these parameters that are necessary to set up the problem. It is convenient to supply this code in a file for your test case PREP/SUBS/ my_test_case.h, which will be included in file prep.F. See steps 4 and 5 below.
The steps in setting up an application with the SPECIAL_TEST option are very similar to the steps in setting the NA application in section 5.2.1 above:
1. Choose or define the new application case name in the file PREP/ AN_ID.h. For example, it could by MY_TEST_CASE. Comment out all other preprocessor #define statements with an initial C, just as was done for the NA case, so that the only uncommented line is
#define MY_TEST_CASE
2. Add the desired directives to file Def_prep.h within an #ifdef -#endif block for the case name, just as was done in section 5.2.1. For example:
#ifdef MY_TEST_CASE
#define SPECIAL_TEST
...
(Choose the basic model set up features appropriate to your problem.)
...
#endif /* MY_TEST_CASE */
Note that the SPECIAL_TEST option must be defined within this block.
3. Set the user defined resolution parameters as was done in section 5.2.1.
4. Create a file that defines the new arrays required by the SPECIAL_TEST option for your case, for example PREP/SUBS/ my_test_case.h. The easiest way to set up the file containing the arrays for a new SPECIAL_TEST is to copy a file created for a different test case to the new file name, and then edit it. Several such files are provided with the code and can be found in PREP/SUBS. Most of these use a simple rectangular grid, but the dhem_test_case.h provides an example that uses spherical coordinates. Add this file name to the target list of the PREP/ Makefile as discussed below in item 7.
5. Edit prep.F to say what file holds the information for this particular SPECIAL_TEST (search for SPECIAL within prep.F to determine where this information gets fed in). The first part of the program of prep.F is conceptially of the form:
#ifdef SPECIAL_TEST
...
(Includes code for the various SPECIAL_TEST options. You may need to add
the information for your case, as shown below.)
...
#ifdef MY_TEST_CASE
#include "SUBS/my_test_case.h"
#endif /* MY_TEST_CASE */
...
#else
...
(Here is the code to set up the model from a lon/lat grid, including
the world bathymetry, winds, and temperature and salinity initialization
files, as was described for the NA case above.)
...
#endif /* !TEST_CASES */
6. Edit Diecast.h if you want to introduce additional arrays unique to this test case in an appropriate #ifdef MY_TEST_CASE block of code.
7. Compile and run the program prep.F as discussed in section 5.2.1. For cases with the SPECIAL_TEST option, it is probable that new files were created, so be sure to add these file names to the target list of the PREP/ Makefile,. For example, to add the file PREP/ my_test_case.h to the PREP/ Makefile, add the code:
I14=SUBS/my_test_case.h
and
$(I14).o: $(I14).h
cp $(I14).h $(I14).o
Be sure that the line with the cp command starts wth a keyboard tab.
