This is the README file for SPEM version 5.2. There is a SPEM User's Guide describing SPEM 3.9, available either via anonymous ftp (pub/kate/manual.ps.Z), the world wide web, or from kate@ahab.rutgers.edu. Anyone using SPEM 5.2 should obtain this manual. This file attempts to describe what has changed since the manual was written.

To run the spem examples:

1. Make sure you have built libspem3.a in the precision you desire.

2. Edit spemdefs.h, pick a Makefile, and check its FFLAGS, etc.

3. Run things:
   make ezgrid ezgrid # makes fort.3 _ make mask \ mask < mask.in # makes fort.24 \ for masking only make cmatrix / cmatrix # makes fort.25 _/ make spem spem < spem.in or (time spem < spem.in >! spem.out) >&! spem.time &

What is different in SPEM 5.0:

• The sigma coordinate has been replaced with an "s-coordinate", a generalized topography following coordinate, as described in Song and Haidvogel (1994). This particular stretched coordinate system was designed to retain resolution in the upper ocean even over deep water so that the mixed-layer can be uniformly resolved independent of local depth. The s-coordinate has some parameters which are set in user1.F:
  theta - measure of stretching, set to .0001 for sigma coordinate. theta_b - bottom resolution variable. Tcline - depth above which higher resolution is desired. If hmin is smaller, it will be used instead.
• We have replaced the vertical spectral expansion with staggered finite differences. It is staggered in that the "w" points are offset from most of the other variables:
  __________ w(k=N) ____ u,t(k=N) __________ w(k=N-1) ____ u,t(k=N-1) __________ w(k=3) ____ u,t(k=3) __________ w(k=2) ____ u,t(k=2) __________ w(k=1) ____ u,t(k=1) __________ w(k=0)

  The reason for this change is that finite differences are less sensitive than is a spectral expansion to rapid transitions which occur (e.g.) at the base of the wind mixed layer. Second-order (centered) finite difference approximations are used in the s- coordinate.

• There is now a third example problem, so the available examples are:
  Tasman Sea - wind-driven basin with one island, representing an idealized New Zealand in the Tasman Sea. This was provided by Jim Mansbridge and John Wilkin and is simpler than the problem discussed in <CITE> Wilkin et al. (1994)</CITE>. Upwelling/Downwelling - periodic channel with a shelf on each side. There is wind forcing which drives upwelling on one shelf and downwelling on the other. This example comes from Anthony Macks and Jason Middleton. Equateur - equatorial beta-plane with wind forcing. This example was provided by Anne-Marie Treguier.
• The floats and rotated mixing tensors do *not* work yet. These will be fixed in future patches. This version produces sensible results in all three examples, but should be considered as still potentially having bugs, and subject to change. One change which we will be investigating is the addition of an implicit free surface.
• The logical variables uflags, vflags, tflags and sflags are now C preprocessor flags. This is done so that the code can be made slightly more efficient, and also so that the logic with the rotated mixing tensor flags is more straighforward.

What is new in SPEM 5.1:

• There are options for doing implicit timesteps on the vertical viscosity and diffusion, called VERT_IMPLICIT_TS and VERT_IMPLICIT_UV. These options call some vectorized lapack routines which are in an updated spemlib. I had help from Dale Haidvogel and Anne Marie Treguier.
• There are options for computing the vertical diffusion and viscosity coefficients (which are now arrays) from the velocity and density fields, thanks to Anne Marie Treguier and Scott Durski. The PP_MIXING option implements a Pacanovski-Philander algorithm and MY_MIXING implements a Mellor-Yamada algorithm.
• Jim Mansbridge has provided a netCDF input/output option for the history files. This is controlled with the NETCDF C preprocessor variable. The spem.in file can optionally provide filenames for any number of files - see the comments in read_in.F for more details.

  NOTE: the netCDF files get created with dimensions built in, so that you have to change output filenames or delete the old ones when going from one problem to another.

• srhs and trhs have been merged to aid in the building of the rotated mixing tensors. This required the addition of some 2-D arrays for surface and bottom fluxes of T and S. Both T and S use the same horizontal and vertical diffusion coefficients. The S_FLAGS variables are gone.
• John Wilkin has provided rotated mixing tensors. These are controlled by the C preprocessor variables MIX_GP_TS, MIX_EN_TS, MIX_GP_UV, and MIX_EN_UV. MIX_GP mixes along geopotential surfaces (constant z) while MIX_EN mixes along epineutral surfaces (constant in-situ density). Here are some of his notes:

  The scheme is implemented so that MIX_EN_TS and/or MIX_EN_UV can be defined. One does not require the other. The same applies for MIX_GP_*, but as before, MIX_EN_* requires MIX_GP_*.

  MIX_EN_* does not require vertical diffusion. Explicit vertical diffusion is handled separately, and can still be treated implicitly if that spem5.1 option is enabled. Remember though, that isopycnal mixing automatically implies some vertical z mixing. The explicit vertical diffusivity (akt,akuv) is being interpreted as diapycnal under this arrangement.

  About get_rhosxe.F:

  This is a new routine that computes the density surface slopes. It is executed if either MIX_EN_TS or MIX_EN_UV is defined. It is only called once each timestep. During execution it is called *before* rhocal. This follows a suggestion from Anne-Marie Treguier that the slopes should be computed using rho values at the same time level as the linear mixing terms. The only trick here is that at initialisation the slopes can't be calculated before rhocal is called. This is why I separated get_rhosxe from rhocal. A Shapiro filter is applied to the slopes. Why? It seemed like a good idea a long time ago.

• There are start_plot and end_plot subroutines for initializing the plots uniformly in one place. I once had to change fonts and disliked having to change them in every single source file. Also, spval and dspval are global parameters.
• The bogus include files will no longer produce a warning when using the new sfmakedepend (which requires perl 5).
• The file spem5.1.h has been broken up into spem5.1.h, plot.h, and mask.h.
• The Cray and SGI were dying in vvcurv when trying to draw tiny vectors. There is a new variable called minvec which should be set larger than the tiny trouble value. For quantities of order one, 1.e-9 will not work while 1.e-3 will.
• There is a Makefile.CF90 for the Cray f90 compiler. You may want to avoid this because of C preprocessor difficulties. The cpp solution I am using is to compile the version from der Mouse and install it in $(HOME)/bin. If you do this, make sure that "#ifdef cray" tests true on a Cray.
• I got bold and ran everything through some of my perl filters for reformatting Fortran. Specifically:
  redo -E # change do-continue to do-enddo findent -n 3 # indent by 3 spaces relabel # relabel after all the continue labels go ifspace # put spaces around if tests

  Some of the C preprocessor code in SPEM confuses these perl scripts, so some manual intervention is required after the fact.

What is new in SPEM 5.2:

• It now reads netCDF grid and forcing files in the same as used by SCRUM.
• It has open boundary conditions contributed by Patrick.

Kate Hedstrom Last changed on: 24 August 1999