Recent extensions of the model physics include the heat flux formulation of Seager (1988), the heat flux formulation of Seager and Blumenthal (1994) and the mixed layer formulation of Chen et. al. (1994).
...mention senya's recent revisions to the code...
/home/senya/work/model/MC_PG/NEW
on the local system. A file simple.README within this directory
contains instructions for setting up one's own working directory,
linking to the NEW directory, and performing the example
run for the Pacific domain. The parameter file which is to be
used for the example run is simple. This is an ascii parameter
file that is read by the model at execution time. It prescribes
the shape of the horizontal domain, the vertical grid chosen,
and the numerous parameter choices for the model run.
First we focus on the specification of the horizontal domain, which is specified near the end of the file simple:
%%%% GEOMETRY Parameters %%%%%%%%%%%%%
+NX 81 {# of zonal gridpoints}
+NY 30 { " meridional " }
+South -29 {S. Bndry: degrees North}
+North 29 {N. Bndry: degrees North}
+West 124 {W. Bndry: degrees East}
+East 284 {E. Bndry: degrees West}
+Grid_mask [
w61,z20, {61 ocean pts., 10 land pnts.}
w61,z20,
w62,z19,
w63,z18,
w66,z15,
...and so on...
z15,w66,
]
%%%%% End Of GEOMETRY %%%%%%%%%%%%%%%%
A plot of this domain can be seen [launch external viewer].
The first six parameters here specify the geometry of a rectangle by giving the number of zonal points, the number of meridional points, and the bounding latitudes and longitudes. Since there are 81 zonal points and the model extends for 124E to 284E (or 76W), and the 30 meridional gridpoints run from 29S to 29N, we can deduce that our grid is 2x2 degrees within a rectangle which is 160x58 degrees in extent.
Next the distribution of land/ocean gridpoints within the rectangle are specified. This information is given within the +Grid_mask, and is demarcated by square brackets. Within the grid mask, w represents ocean points and z represents land points. Each line corresponds to a particular latitude starting at the southern most latitude of the domain. For that latitude (in this case, 29S), the distribution of ocean and land points is given by
w61,z20
which specifies that beginning at the western boundary and moving
eastward, there are 61 consecutive ocean points followed by 20
land points. Since the second line is identical to the first,
the same will be true along the next latitude, namely 27S.
For the northernmost latitude (29N), we see that there are 15 land
points followed by 66 consecutive ocean points as one moves from
west to east. For each line, the total number of points should
be equal to NX, and the total number of lines should be
equatl to NY.
For this example, the grid is evenly spaced in both the zonal and meridional directions. Later on, we shall describe stretched grids, which allow variable resolution over different portions of the grid. For example, it is not uncommon for runs in the Equatorial Pacific to use higher meridional resolution close to the equator and lower resolution at higher latitudes. Next, we document the remainder of the model settings contained within simple:
Trace : specifies whether a .tr file should be generated
(i.e. file which specifies which parameters were
used during a run, including all default values)
0 - don't create file
1 - create file
Restart : 0 - completely new run
1 - continue run with same .tios up to +Run_time
often useful after a machine crash, when this
is the only parameter that needs changing to set
the run on its way again;
2 - restart from a previous run and continue for
+Run_time more (in this case, the .tios file
cannot be changed, assuming that the diagnostic output
will be continued as scheduled)
3 - restart from a previous run creating the new "tios"
output; clock is reset, and model goes for
"+Run_time" longer
Time_step : Time step used (hours) when integrating; this will usually
be less than or equal to one hour, due to the explicit
treatment of the coriolis force in the momentum eqns;
If needed, a longer step can be rigged for coarse
resolution runs;
Run_time : number of days/months/years of study; 1yr by default
Mixing : 0 - no mixing
1 - Convective adjustment
2 - Richardson # dependent mixing
3 - combines both 1 & 2
4 - Dake Chen's mixing; computes depth of mixed layer
using Kraus-Turner (won't work with z-coordinate)
5 - D.Chen's implementation of (1);doesn't mix momentum
Mix_step : frequency of mixing
Vert_Top :model treatment of surface layer
1 - constant depth
2 - sigma layer
3 - true layer (w=0 at interface between 1st&2nd layers)
Vert_Bot : model treatment of bottom layer
1 - constant depth
2 - sigma layer
3 - motionless layer
Vert_Fix : prescribes overall depth of domain
0 - depth of domain not fixed in time
1 - fixed depth to domain
Vert_Sys : 0 - filter h
1 - don't filter h (appropriate for z-run)
Shap_vel_order :
Shap_vel_type : 3 - "old" reduced
Shap_vel_step :
Shap_scl_order :
Shap_scl_type : 3 - "old" conservative
Shap_scl_step :
Wind_forc : Wind forcing of surface ocean
1 - climatological winds; linear interpolation in time;
can also be time series (i.e. FSU winds)
2 - same as (1) but with cubic interpolation in time
3 - annual mean winds; if climatological data set is
supplied by the user, the model will use this
to calculate the annual mean
5 - cosine winds
Wind_tauxy: only appropriate when Wind_forc=5;
Temp_init : initializing temperature profiles
0 - temperature from t_in of parameter file
1 - linear:T(z)=a*z+b ; with T(top)=SST,T(bot)=T(nz)
3 - all layers from data
Heat_forc : Thermodynamic forcing of surface ocean
[note that options 0-3 represent Newtonian cooling,
with a one month restoration timescale]
0 - Restore to scalar (same TEMP value for all X,Y,T);
Currently the value of this scalar is hardwired
to be 30 degrees Celsius
1 - restore to TEMP which is constant in time but varies
in X and Y [first entry if SST forcing is time series]
2 - restore surface temperature to model-calculated
annual mean [model will calculate annual mean
if given a climatology]
3 - restore surface temperature to climatology
4 - heat flux treatment of Seager, JGR '88
5 - Seager and Blumenthal, '94
7 - ???? see rose/p11b ???
NZ : total number of vertical layers; note that if the user
chooses to use a layer of no motion, it will be
included in NZ
Bint : vertical diffusivity for momentum (units of m^2/s)
Cint : vertical diffusivity for temperature/tracers (m^2/s)
BC_type :
BC_bot_temp:
Grid_type : choosing spherical means ~10% greater computing time
It should be noted that many of these parameters have default settings,
so that if they were to be deleted from simple, the
model would automatically assign a value for them. An example
is Run_time, whose default value is one year. In fact,
there are several parameters which have been omitted from simple
which will be discussed later. Suffice to say that an input parameter
file will typically include only a subset of all parameters used by the
model, since the default value for a particular parameter can sometimes
be appropriate.
It is also possible to activate or deactivate the default setting by utilizing the (+/-) sign which preceeds each parameter in simple.
For those parameters which specify a time interval (Time_Step,Run_time, Mix_step,...), the interval can be specified in hours, days, months, or years. On the other hand, those variables which specify a step (Mix_Step, Shap_vel_step, shap_scl_step) are in units of (small) model timesteps.
Also included in the NEW directory is the file simple.tios which specifies the variables to be written to the output file, the subdomain(s) on which they are to be output, and the frequency with which they are to be output. The file contains the following text:
%------------------------------------------------
DEFINE LABEL [Pacific Simple]
DEFINE TIME_FMT [month]
RANGE 1 [T first last 1]
RANGE 2 [T first last 12]
STREAM STR_XY Z [all] 1 DEPTH U_VEL V_VEL W_VEL TEMP
STREAM MEANS Z [all] 2 D_MEAN U_MEAN V_MEAN W_MEAN T_MEAN
%------------------------------------------------
There are three types of statements: DEFINE, RANGE,
and STREAM. For this file, RANGE is used to specify the time sampling intervals of output. The syntax here is
RANGE n [T TLO THI TSKIP]
Here T represents the time grid, TLO and THI represent the lower
and upper limits, and TSKIP is the sampling interval. The units
for TLO, THI, and TSKIP are determined by TIME_FMT, which can be
in days, months, years (or d, m, or y, since only the first letter
is read).
The label n associated with each RANGE is used to
distinguish between different sampling frequencies for model output.
A stream is best understood as a set of variables which have the
same set of spatial grids and will be ouput at the same time
intervals, which means they share the same time grid.
Thus each variable can be thought of as having three four grids
associated with it, three spatial and one temporal.
In the file simple.tios, two streams are specified. They
are STR_XY and MEANS. STR_XY contains snapshots
of its variables, and MEANS contains monthly averages.
Syntactically streams should be defined as follows:
STREAM STREAM_NAME Z [VALUES] n VARIABLE1 VARIABLE2 ...
where
STREAM_NAME : chosen by the user.
Z [VALUES] : specifies which vertical layers are to be output
n : associates the RANGE # with the stream
Thus STR_XY will contain
the variables: layer depth, zonal velocity, meridional velocity, vertical
velocity, and temperature, and will be output every month for the
entire domain.
Depending on the heat flux formulation, observed SST's, cloudiness, solar forcing,... can be used.
Other input files that are needed are the restart files which describe the original state of the model run: layer thickness, temperature, zonal and meridional velocity, and if specified, tracer distributions. These files are data files created at the end of a previous run. The entire grid for all levels are output at 5 day intervals into datafiles. These are known as restart datafiles since these are sufficient for restarting the model.
The user interface is also intended to achieve a level of machine independence. Using the model requires the following software: f77,cpp,netcdf libraries,... The model has been tested on the following platforms: SGI, Cray, IBM RISC, DEC,...
Typically, performing a model run involves three steps: preparing data files, running the model, and visualizing the output. Both the preparation of data files and the visualization of model currently rely on homebrew sofware (ingrid,remap, and tios).
The data files that are typically used to calculate surface fluxes during a model run (i.e. climatological winds, climatological sea surface temperature, etc) are read as input files at the start of a run. They are usually contained in the
To create a new domain, the user needs to specify the distribution of land and sea points over a rectangular grid. This is most easily accomplished with remap, which reads high resolution global bathymetry data to create a domain with user specified resolution. remap provides a graphical point-and-click interface which allows the user to modify the grid generated from bathymetry to suit the needs of the model study.
This is often necessary since the model cannot accomodate grids of arbitrary shape. One consideration is that the finite-differencing scheme requires that there are always at least four contiguous points in each direction.
As for the vertical grid, there are two general types of model runs: (a) those which employ the reduced gravity approximation, and (b) those for which the total depth which is fixed in time, which do not use the reduced gravity approximation. Within the second choice there are two options, namely runs which do or do not use a floating interface. The Z-coordinate case should be considered as a special case of (b), i.e. a fixed total depth with a flat bottom. The simple example discussed earlier utilizes the reduced gravity approximation.
Three options are available for the surface layer: (a) a constant thickness mixed layer, (b) a sigma layer, and (c) Dake Chen's hybrid mixed layer model.
Once the user has created their own directory following the instructions in the simple.README file, an executable file can be created by typing:
% pmake
within that directory. This will create the file new.
To perform a model run, one then types
% new -i simple -t simple.tios
Here "new" is the executable, "simple" is an input parameter file,
and "simple.tios" is a file which specifies which fields (i.e. layer
thickness, velocity components, temperature,...) are to be written
to an output file, as well as gridding information for these fields.
The file simple.tios specifies which model variables are to be output. Typically only a subset of the available fields are output for a run. A list of fields which are available for output (for a run without salinity) are given. First we consider model variables:
DEPTH (meters) - depth of layer interface
U_VEL (m/s) - zonal velocity
V_VEL (m/s) - meridional velocity
W_VEL (m/s) - verical velocity
TEMP (degrees C)- temperature
D_MEAN (m) - mean fields (time-averaging interval
U_MEAN (m/s) should be set in .tios;
V_MEAN (m/s) calculation are performed
W_MEAN (m/s) w/ the function out_mean)
T_MEAN (degrees C)
HFLX - heatflux at air/sea interface
DEFICIT - deficit in heat flux which is necessary to bring
SST to climatological values
CONVN -
ENRG - X=1: measure of k.e.
X=2: measure of k.e.
X=3: potential energy
X=4: heat content
X=5: mass
SEALEV - units of meters;
RI - richardson # computed for each point; used for
studies of mixing
and model surface forcing fields, both thermodynamic:
SST - data (model calculated SST's are in TEMP)
SOLAR - units of W/m^2
LATENT - W/m^2
SENSIBLE - W/m^2
LONGWAVE - W/m^2
CLD - fraction cloud cover (0 < cld < 1)
and momentum forcing:
TAUX - zonal wind stress
TAUY - meridional wind stress
The general rule for units is that MKS units apply for the model's
internal representation and output. However, when using windfiles
the use should keep in mind that the model expects to read wind
data-files in cgs units, but converts them to mks for internal use.
For the case of Newtonian cooling (i.e. simple), SST will be
the only relevant output field for
dyn_main.f
dyn_tios.f
dyn_io.f
dyn_dens.f
dyn_new.f
dyn_subs.f
dyn_filt.f
For the implementation of tios used within the model, tios is only being used to write files. Thus the model uses a subset of all tios calls. Before entering the model's main loop, the subroutine init_data_out is called. Within this subroutine, the variables and grids available for output are defined. Recall that within the file simple.tios, U_VEL refers to the zonal velocity and TEMP refers to temperature. Within the fortran code, the variables u and t are used to represent these quantities, and it is within init_data_out that u is associated with U_VEL. Another way of saying this is the U_VEL is a tag used within a .tios file to refer to this variable.
tios_init: specifies which files will be used
1st argument: .tios file (used for instructions)
2nd argument: data file name
tios_grid: Define spatial "grids";
a grid has three dimensions (xx,yy,zz).
Within the subroutine init_data_out,
note that idg_1 is defined for fully
three dimensional fields such as U,V,T,etc. whereas
idg_0 is defined for 2-D fields such as wind
stress or surface heat flux, since the third grid will
only have one value;
tios_map: Define "maps";
Used when there is compression; tios assumes
all variables are declared as t(nx,ny,nz) in their
uncompressed form. It is through this subroutine
call that the program first associates a compression
scheme with the variable arrays. ( -> imap)
{mention iox}
tios_var: Define variables;
Specifies which fortran array will be used to get
values for a particular variable; For example,
associates tios tag TEMP with fortran array t;
tios_idvar:Define variables
Although this function defines a tag (i.e. DEPTH)
for output, the tag is not associated with a particular
memory location. To refer to this variable later on,
the id returned by the function (i.e. iddp)
is stored in a common block (i.e. tios_id), which
will be referred to again in the subroutine data_out.
tios_read: Reads .tios input file
Once within the program's mainloop, there are only 2 functions which need
to be called to write to output:
tios_putvar: just uses variable names
tios_putidvar: uses id returned from previous call
to tios_putidvar
For both of these functions, the last argument passed to the function
follows:
0: ignored
function name: will call function, but not every time routine
is called since tios checks whether it is time
to do output
In addition, the function call returns one of two values:
0: no output took place
1: some data was written to output
Salinity
0: no density
1: salinity as passive tracer
2: (equivalent to 1)
3: density as linear function of p,T,S
4: density as 12-term polynomial function of p,T,S
5: density as 17-term polynomial funciton of p,T,S
6: UNESCO formulation: slow!!!
Clim_init:
0: won't read data
1: will read static data, but won't necessarily use it
2: will read climatology, but won't neceessarily use it
Clim_type:
0: assume climatological z-grid is same as
initial h-distribution
1: will read mixed layer depth and thermocline
depth (both static)
2: will read mixed layer depth and thermocline
depth, and both vary in time
Clim_Top:
0: use thermocline data, but don't use mixed layer data
1: use both thermocline data and mixed layer data
Clim_nlat: units of degrees north; the model will restore from this
latitude to the northern boundary
Clim_slat: units of degrees north; the model will restore from this
latitude to the southern boundary
Solar_Penrad: determines whether solar radiation will
penetrate below the surface layer
EP_forc: salinity forcing; similar to Heat_forc, except this
parameter includes a provision for freshwater flux data;