Setting Up the Model Domain, Viewing In/Output, Etc.



To make data files and the land-sea mask for the Lamont Ocean-Atmosphere Model (LOAM), one uses remap. Remap is a utility which uses ingrid, i.e.: it accepts a control file which is essentially an Ingrid script. The syntax is: remap -c your_file.in -x where the -x is an optional parameter which tells remap NOT to route output to a display window. Remap has two basic modes of operation: interactive, which is useful to create a model geometry; and batch, which is useful to pre-process the data which will be used as input to the LOAM model.

The the remap control file has three essential sections, which are bounded by beginning and ending tags: begin{remap} . . . end{remap}, begin{INPUT} . . . end{INPUT}, and begin{OUTPUT} . . . end{OUTPUT}.

The {remap} section us used to set some of the control parameters for remap. The {INPUT} section specifies input dataset. The {OUTPUT} section is optional: it specifies the output dataset, if one is required.

Making a Land-Sea Mask

To make the land-sea mask, one issues a command like:

remap -c mk_pole.in

where mk_pole.in is a file of ingrid commands. This file needs a bathymetry file as input to create your "first" mask. Once you have a mask you can take the mask itself as input and use remap to edit it. A typical remap control file, for making a land-sea mask would begin:

\begin{Remap}
\begin{ingrid}

/win_type 1 def % 0 - small; 1 - normal(dflt); 2 -screen;
/win_geom [ 800 900] def

/INPUT_FORMAT 3 def % 0 -Ingrid/dflt/; 1 -Dir.Acc.;2 -MCPG ascii; 3-mask (no bathy); 6 -model input
/OUTPUT_FORMAT 3 def % 0 -Ingrid; 1 -Dir.Acc./dflt/; 2 -MCPG ascii; 3 - mask; 6 - model input
/in_file (arctest2.map) def
/out_file (arctest3.map) def

/out_vname (sst) def

/description (Levitus94 Monthly SST) def

\end{ingrid}
\end{Remap}

Here INPUT_FORMAT specifies the format of the bathymetry file. At Lamont we use ingrid for data retrieval and analysis, including the bathymetry file on which the land-sea masks are typically based. The following section is ingrid input to create the input bathymetry file for remap to make the land-sea mask. This script segment would be in the same command file, following the remap script.

\begin{INPUT}
\begin{ingrid}
/Pole_shift 1 def
/Pole_alpha 0. def
/Pole_beta -90. def
/Pole_gamma 0. def

/Pole_X [ -24 30 3.0 ] def
/Pole_Y [ -30 20 3.0 ] def

/INPUT
SOURCES >WORLDBATH >bath
def

\end{ingrid}
\end{INPUT}

\begin{OUTPUT}
\begin{ingrid}

/XOVY 1 def out_file setplotname
/PLOTGRID -1 def

OUTPUT -1. mul sqrt 0 mul /missing_value NaN def /fullname (Mask) def

X Y CONTOUR
\end{ingrid}
\end{OUTPUT}


The Pole_xxxxx parameters are used to rotate the model grid so that one can model the Arctic Ocean without having a singularity in the grid at the North Pole. They are only needed if one is running a global or an Arctic domain. Three rotations are used: first, one rotates the earth zonally about its axis. Then one rotates about a meridional axis through the equator, and perpendicular to the plane of the prime meridion -- so that the pole moves south along the prime meridian. Finally, one rotates a second time along the earths axis. For an arctic run, the first rotation winds up changing the orientation of the domain, while the second two locate the latitude/longitude of the center of the domain. The rotation routine is in the source file: dyn_xir.f, and can easily be adapted to generic tasks, such as rotating model output or station data so that the two can be compared.

/Pole_X (and _Y) give the size of the domain, in degrees longitude (latitude). For example, /Pole_X [ -24 30 3.0 ] def sets the domain from -24 to +30 degrees longitude, in 3 degree increments.

The /INPUT in this instance is taken from the Lamont Climate Group's data catalogue:

SOURCES >WORLDBATH >bath

specifies the pathname in that catalogue.

If one is not modeling a polar region, one might typically extract a region from the bathymetry dataset, with a command like:

/INPUT
SOURCES >WORLDBATH >bath
X 0 360 2 RANGESTEP
Y -50 50 2 RANGESTEP
def

which will extract the bathymetry file for a zonal strip, extending around the world, between 50 North and 50 South, with a resolution of 2 degrees in each direction.

Remap will display a window with an interactive interface. One clicks on the left and middle mouse buttons to change land to sea and vice-versa. When one has a mask one likes, one can "EXIT" and save the file. The main rule is that for our fourth-order numerical scheme, one must have at least 4 sea points in a row, in both the x and y directions. One should also bear in mind that with a rigid lid and no-slip boundary the specification of a net circulation around each island is required to integrate the barotropic stream function around the island. It may be better to "sink" islands with insignificant or unknown net circulation. This would mean tagging the island as sea in the mask, and then giving it a very shallow depth in the bathymetry file.

Making Data Files

One also uses remap to make the data files which LOAM will read for its initial and boundary conditions. The scripts to make the data required to run LOAM are typically named mk_varname.in or make_varname.in. A workable structure for one of these files, which are ingrid scripts, is mk_example.in .

These mk_xxxxx.in files are actually called through a makefile called Makefile , which is called with the command: pmake varname, which will take an argument, and call remap using the appropriate mk_ file.

USING THE pmake UTILITY:

For example:

% pmake bath

Uses the Makefile script to submit the mk_bath.in file to remap.

The command line variables (e.g.: "bath") can be found toward the end of Makefile. Each one is followed by a list of @pmake statements, which refer to command lines found earlier in the file. For example, "pmake atm" finds 4 @pmake statements, which call on 10 variables, which can be found earlier in Makefile to identify 10 mk_varname.in files which should be submitted to remap. For each of these files, one must specify (by editing the Makefile) which mask to use.

An example of the Makefile commands:

tau_DSL.x: $(DATA_MAP) remap -x -c mk_taux.in -r $> -w $@ -i 2 -o $(MAKE_PICTURES)

Here, tau_DSL.x will be the output filename -- i.e. here's where remap will put your data. $(DATA_MAP) tells remap to use the mask identified at the beginning of Makefile, e.g.: DATA_MAP = arcdat2.map. remap calls remap. -x means don't open an X-window for remap. -c mk_taux.in identifies the remap control file to use. -r $> refers to an entry in the mk_var.in file where the input data file is specified. For LDEO users this is typically a file extracted from the Climate Group data library. -w $@ specifies the output filename. In the Makefile, one can see that the variable name, e.g.: tau, is an alias for the command @pmake datasets (e.g.: @pmake tau_HEL.x tau_HEL.y tau_DSL . . . ). The variables following to the @pmake utility are the output filenames. -o $(MAKE_PICTURES) determines whether remap makes postscript pictures of the output files. MAKE_PICTURES is set near the top of the Makefile. 1 means make them, 0 means don't. -i 2 refers to an "input_variant" which is set in the mk_varname.in file. In this case, the input variant is DASILVA, which is one of the several wind-stress files available in the data library:

input_variant 2 eq {
/description(DASILVA successive correction mapping of COADS corrected data) def
/DATASET(/Data/data1/DataCatalog/entries/DASILVA/SMD94/climatology.cdf) readCDF
>taux3 10 mul def
}if

input_variant 3 eq {
/description (Trenberth: ECMWF analyses Monthly Means 1980-1989) def
/DATASET SOURCES >TRENBERTH >Monthly >taux def
}if

and so on.

STRUCTURE OF THE mk_varname.in FILES

In the mk_xxx.in files:

\begin{ }
\end{ }

perform the obvious functions. Between the brackets might go ingrid or Grid or OUTPUT . . . Generally, they are nested, with the inner pair referring to {ingrid} since that is the software actually doing the processing.
One specifies the input and output formats with:

/INPUT_FORMAT 3 def % 0 - Ingrid/default/;
/OUTPUT_FORMAT 6 def % 0 - Ingrid;


where 3 is remap output, 6 is LOAM model input.


To make the data, the "/in_file ( )" should specify the land-sea mask being used. This should be a data type 3. If one is calling these files through the Makefile, then the mask being used is specified in the Makefile script, and the value for /in_file in the mk_ file is not used. In Makefile, the variable is set as, for example:

DATA_MAP = arcdat2.map
MODEL_MAP = arctest3.map


For each variable then, the Makefile sets which of these two masks is used. The MODEL_MAP is the land-sea mask used for the model run. The DATA_MAP might be different. For example, it is often better to define the data at every cell in the domain, not just the ocean cells. Then if one changes land/sea points (e.g.: 'sinking' islands) one doesn't have to re-make the data input files.

input_variant is a variable from the Makefile which is used to associate different variants of the same type of data with different filenames. If several variants are used, then the mk_varname.in file will have several

input_variant # eq { . . . . }if

statements. Within the brackets the input data is described: /description it is located: /DATASET and any manipulations which should be done are defined, e.g.: " . . . >taux 0.75 mul" places taux and 0.75 on the stack and then multiplies them. Each statement within the brackets is a definition, and should end with def.
Many of the files commonly used as LOAM input have been located in the LDEO climate group data library using a pathname: SOURCES. These can be located using a line like:

/DATASET SOURCES >HELLERMAN >taux def

where the UNIX path is ingrid.ldeo.columbia.edu/SOURCES/.HELLERMAN/.taux/

One can simply identify data files for remap. NetCDF files can be read using the ingrid command readCDF:

/DATASET(/Data/data1/DataCatalog/entries/DASILVA/SMD94/climatology.cdf) readCDF

In this case, one still has to put the desired variable on the stack:

>taux3 10 mul def

MAKING PICTURES OF THE INPUT DATA

make_picture = 1 or 0, is a switch, set within the .in (or .ing) file which tells remap to make (or not to make) postscript pictures of the data fields which are being created. The pictures may either be shaded or contoured. The shaded plots are very readable on color terminals, but a bit obscure in black and white -- where contour plots are more useful. To specify contour, use the line:

output_variant 1 eq {MAPPED_DATA X Y CONTOUR}if

for shading, use the line:

output_variant 1 eq {MAPPED_DATA X Y COLOR}if

To set up a file so that making pictures can be specified from the command line, use the PS command inside the "if" brackets conditioned by the output_variant:

output_variant 1 eq{
PS /XOVY 1.7 def out_file setplotname
/PLOTCOAST 1 def
MAPPED_DATA X Y CONTOUR}if

(I think that) The output_variant can be specified at runtime with the -o flag, which can be set in Makefile.

In the mk_var.in file, one can specify an output file name, e.g.:

/out_file (prcp_DSil) def

If one is using the Makefile, then the output data file will be taken from the Makefile, even if an /out_file line is present in the mk_var.in file. However, even if the Makefile is used, pmake will still look to the /out_file variable to name the picture files. So, if you are making pictures, and if you are using the Makefile (especially if making more than one variant) be sure to eliminate the /out_file line.

Viewing NetCDF (LOAM Input) FIles in Matlab

NetCDF files produced by remap as input for LOAM have the data compressed in [XY] chunks so that the land points with missing data are eliminated. One can preview such files making plots in remap or in matlab using the simple ODB interface to read NetCDF files (even compressed as described above).

The sequence of matlab commands to read such a data file would be:

idf = odb('open', 'temp_LEVs.cdf');
x = odb(idf, 'var', 'X');
y = odb(idf, 'var', 'Y');
temp = odb(idf, 'var', 'temp', [1 1]);
surf (x, y, temp');
view (2);
shading flat;

For more info about ODB interface in matlab type:
> help odb
> odb('help');
> odb('example');


USING A TIOS FILE TO CONTROL MODEL OUTPUT

The LOAM model uses the tios (transparent i/o system) format to save fields for viewing. This is an operating-system independent binary format. The fields to be saved, and their format, is controlled by an ingrid file, such as example.tios. The main goal of the .tios file is to define "STREAMS" of model output. The file has two sections, a "tios" section at the beginning of the file contains any general ingrid definitions which will be used in defining the streams. These are optional, except for the definition of RANGEs. The model works in a 4-dimensional system of coordinates: X,Y,Z and T(ime). The ranges set the coordinate restrictions for outputting model fields. for example:

RANGE 3 [X * * 2] [Y * * (50)] [T first last 10]

creates a range identified as range 3. Range 3 will be saved on the whole range of X coordinates, but only every second grid-point; on the whole range of Y but only on 50 points which will be evenly divided among the total number of Y grid-points; and for the whole time range ("first last" is the same as "* *") at intervals equal to 10 times the time format. The time format, along with various other things such as degubbing options can be set with the "SET" definition;

SET [fmt=day]

sets the default time unit to days (not in the model, but in the tios subsystem).

Another example:

RANGE 4 [T 360 480 100 fmt = day]

sets the time range from the 360th "el nino" month to the 480th, saving the results on every 100th day. El nino time starts on January 1, 1960, so the example prints out model results from 1990 to 2000. If you're here on the Lamont climate group machines, the utilities "enso" and "rltm" will convert between calander and enso times.

The second section of the .tios file defines the STREAMs for the model run.

STREAM STR_XY Z [ all ] 1 TEMP U_VEL V_VEL W_VEL SALT DENS

creates a stream named "STR_XY". The stream will be saved for all levels in the model domain, "Z [all]". One might also have used "Z [1 2 3]" to print out the first 3 levels in the model domain. The example will use range 1. And it will include the variables TEMP U_VEL V_VEL W_VEL SALT and DENS. As the example shows, one can set the range either in a RANGE definition or when defining the STREAM. The custom here is to define the X Y and T ranges in the RANGE, but to define the Z range with the STREAM. One may encounter L(ayer) in place of Z(coordinate) to specify the vertical range. Either should work.

One can save as many variables as one likes within a single STREAM. However, tios can only handle up to seven STREAMS at once. Also, the model uses certain variables, called 'base' variables, as switches in the output routine. If the first variable in the stream is not a base variable, then none of the variables in the stream will be saved. To make a variable a base, one has to use it in the model output routine, dyn_tios.f. For example, 'call tios_putvar (wnd, tenso, 0)' identifies 'wnd' as a base variable. The call to tios_putvar is expensive, so one doesn't want to make all variables base variables.

If one fails to use a proper vase variable in a stream, the model will run, but the tios job (i.e.: the job which creates plots from your output data) will bomb.

Also: some variables are saved over the entire domain: air temperture, snow temperture, humidity, . . . generally any variables which are calculated or used by the atmospheric P.B.L. component. Other variables are only saved over the part of domain which is ocean: ice thickness, ice concentration, u, v, . . . . When setting up the streams, these variables should be grouped together. I.e.: don't mix whole-domain variables with ocean-only variables. If in some of your plots the domain seems to have shifted over, this may be your problem.

The same variables may be used in multiple streams, for example to sample along different transects or at different timesteps.

LOOKING AT MODEL OUTPUT

The model output is viewed using the command:

where model_name is the name given to the control file which was used to run the model, and model.ing is an ingrid command file which is used to control the output. output/ is the directory containing the model output files. The .tios file, which was submitted with the main model control file when the model was run, specified which model outputs were saved, where, and at what frequency. Now, the ingrid file, model.ing will specify which of those saved variables are actually plotted for viewing. The variables to be plotted are specified in sets called STREAMS. These streams were created in the .tios file and saved during the LOAM run. In the .ing file, they can be further manipulated to some extent and plotted in a variety of ways. The .ing file has two sections. It begins with a tios section, which contains general definitions which may be used to manipulate the strings. For example, to view model output on depth-levels instead of model layers, one can use the definition:

/to_Z {
L /Z /m ordered
[12 36 68 109 153.6 221.4 300 389.4 489.6 600.6 722.4 855.0
998.4 1152.6 1317.6 1493.4 1680. 1877.4 2085.6 2304.6 2534.4 2775 3026.4
3288.6 3561.6 3845.4 4140 4400 4700 5000]
NewGRID replaceGRID Z last first RANGE
} def


one can also create a file of useful ingrid definitions, and include (in the same sense as in C or COBOL) it in the current ingrid file:

(/home/senya/work/model/MC_PG/senq/Inew.rc) run

The second section in the .ing file is the {STREAMS} section, where one lists the streams to be plotted, and for each variable in a stream, identifies the dimensions (X Y for example) and the format (CONTOUR, COLOR or VECTOR for example).

\begin{STREAMS}

ATM1
HFLX X Y CONTOUR
SOLAR_qisw X Y CONTOUR
LATENT_rlh X Y CONTOUR
SENSIBLE_sh X Y CONTOUR
LONGWAVE_qlw X Y CONTOUR


/PLOTCOAST 1 def
ATM3
PBLHUM_qa X Y CONTOUR
PBLTEM_th X Y CONTOUR
AIRHUM_q X Y CONTOUR
AIRTEM_t X Y CONTOUR
\end{STREAM}


ICE1
CICE X Y COLOR
HICE X Y COLOR
THICE X Y COLOR


\end{STREAMS}


Here ATM1, ATM3, and ICE1 are streams, each containing several variables (HFLX, SOLAR_qisw, etc.) "X Y" specifies that these are to be plotted in the horizontal plane. "CONTOUR" specifies a black and white line contour plot; "COLOR" specifies a color shaded plot. One could also specify "X Y VECTOR" to plot values such as velocity as arrows:

U_VEL T last VALUE V_VEL T last VALUE X Y VECTOR

"/PLOTCOAST 1 def" tells ingrid to draw the coastline on the plots defined in that stream.

As many variables as you like may be grouped into a single stream, but ingrid will only accept up to 7 streams at one time.

CONVERTING MODEL OUTPUT TO STANDARD FILE FORMATS

At Lamont, users can use one of Senya's utilities, tios2cuf, to convert LOAM model output files into "standard" CUF, NetCDF or HDF formats. The utility is written as machine independent so you can use it to access the model data on *any* platform.

This utility takes model output files and creates one file in any of the abovementioned formats.

Please note that default is to create CUF file which is the best to use with our Data Catalogue Browser, it's also smaller in size due to built-it compression and it works much faster than NetCDF (or HDF), ex:

A 15MB global domain model file was converted to "CUF" in 5 sec vs. 60 sec to "NetCDF"(!), while the file size was reduced to 10 MB.

Another advantage of the new format is that you can ran Ingrid directly on CUF or NetCDF (HDF) file.

The command syntax is:

tios2cuf [-Oth][-f ][-o ][-s|v name]
-t - prints (only) the table of contents for
-f - Input file
-o - Output file
-s STREAM - Dump this stream only
-v VAR - Dump this variable only
-N - Dump in NetCDF format (default: in CUF
http://rainbow.ldgo.columbia.edu/~senya/docs/cuf.html)
-O - recognize a very old TIOS format
-h - prints this help page
defaults: :
:


Questions: senya@rosie.ldeo.columbia.edu

Model Output Variables

For a complete list of the model output variables which may be saved for viewing, look at the file: