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/NEWon 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,z20which 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 timeIt 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 streamThus 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:
% pmakewithin that directory. This will create the file new. To perform a model run, one then types
% new -i simple -t simple.tiosHere "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 mixingand 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 stressThe 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 fileOnce 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_putidvarFor 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 outputIn 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;