Gent-Cane Sigma Model User's Reference

(1) Introduction

The Gent-Cane model (Gent and Cane, 1989) is a primitive equation ocean circulation model. The model equations include the hydrostatic approximation and the rigid-lid approximation. The model uses fourth-order centered differencing in the horizontal, and a second-order Lorenz N-cycle for time differencing. Model calculations are performed on an A-grid. The user is referred to Gent and Cane, 1989 for the model equations and a detailed discussion of the discretizations chosen.

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).

History

...and on the seventh day, god said let there be a fourth order ocean model with a sigma vertical coordinate ...

...mention senya's recent revisions to the code...

Comparison With Other Models

How does this model differ from other models? One significant advantage that this model offers is its high accuracy and low numerical diffusivity. This can be attributed to the fourth-order centered differencing scheme employed by the model.

(2) Tutorial: a simple example

The best way for a new user to become acquainted with the model is to follow the example that has been set up in the following directory:

     /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.

(3) Using the Model

Once the user has become somewhat familiar with the model, the next step is to outline how the model is run and how to get useful information from it. The user must first create all the input files that are needed for the model. These include a parameter file that specifies the appropriate equations and the model grid. The model also needs the forcing files for zonal and meridional wind stress. The wind stress that is used can be either a constant over the basin, annual mean winds or monthly winds calculated from data, or real winds from observed data sets.

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).

Setting up a model run

Structure of model's control file

Choosing horizontal/vertical grid

The model is designed to allow the user to prescribe the shape of the domain. The domain geometry is not wired into the model at compilation time, but is rather read in at the start of a run. This information is contained in an ascii input file, which also contains other information to be used by the model, i.e. the time step, the pathnames of binary data files which will be used during the run, as well as various switches and parameters that the user may want to change.

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.

Running the Model

note: should include an elementary discussion of model cpu time (time per day represents machine time rather than real time), memory requirements,interpreting model error messages,...

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

Data Post-Processing and Visualization

Data post-processing: plotting etc. The model produces output binary files which contain the user-specified fields (i.e. zonal velocity, temperature,...) on the user-specified subdomains. As mentioned before, the user has specified the information to be outputted by the model in the ".tios" file, which is read by the model at execution time (as opposed to at compilation time). The model outputs this information as it calculates; thus if one does a 40 year model run with output ever five years, one need not wait for the model to complete its run before accessing the output.

(4) User Model Extensions (for masochists only)

A motivated user can introduce new physics/tracers/etc. into the code. Unlike the changes discussed earlier, these will involve changes in the *.f and/or the *.h files, and recompiling. Thus a description of the logical structure of the fortran code is in order.

Adding Variables

In order to add new variables to the input parameter file to be read by the model, it is necessary to make changes to the subroutine model_input within the file dyn_io.f

Adding Tracers

(5) Technical Description

Model Equations and Discretizations

Guide to Fortran code and Subroutines

The "main" file is dyn_main.f. Files containing fortran code are:

     dyn_main.f
     dyn_tios.f
     dyn_io.f
     dyn_dens.f
     dyn_new.f
     dyn_subs.f
     dyn_filt.f

Discussion of utilities: remap, tios, ss, and ingrid

The model uses tios for i/o, as well as by the user for post-processing. Since tios writes binaries in 32 bit ieee format, any machine that writes 32 bit ieee binaries can be used to run the model, and the results can be ported to an SGI marchine for postprocessing/visualization. Although netcdf is used by the model for reading the forcing files (winds etc.), it was decided that netcdf would be inappropriate for output, since it only allows one unlimited dimension.

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

(6)Current Applications

Regional runs

Current regional applications include the Red Sea, the Atlantic, and the Pacific. Because each of these studies focuses on different scales/processes, the resolution and parameters chosen for each will be quite different. For example, studies which focus on the Equatorial Pacific oftentimes ignore salinity, since the density stratification of the Equatorial Pacific thermocline is determined to first order by temperature. This will not be true for the Red Sea, where salinity plays a much more important role.

Red Sea

The model study of the Red Sea is currently being conducted by Gidon Eschel (gidon@rainbow). This study uses the model at eddy-permitting resolution.

Atlantic

A series of model runs for the Atlantic have been conducted by Naomi Naik (naomi@ldeo.columbia.edu). For a 2 degree Atlantic run with salinity, she integrated for 100 years.

Pacific

Runs for the Pacific have been conducted by Senya Basin (senya@rainbow) and Keith Rodgers (keithr@rainbow).

Global runs

(7) Tutorial: an example from the Tropical Pacific

Here we consider the parameter file for the run done by Chen et. al. (1994) for the Equatorial Pacific. This example utilizes more advanced features of the model than the simple example discussed previously. It includes a stretched horizontal grid, boundary restoration, and includes a dynamic mixed layer model.

     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;
     

(8) Contacts

The model is maintained by Senya Basin (senya@rainbow.ldeo.columbia.edu).

(9) References