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.
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.
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.
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.
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
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');
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.
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.
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: