Users Guide

From Foam
Jump to: navigation, search


The Fast Ocean Atmosphere Model (FOAM) is a coupled climate model for simulating the earth's climate system. The users guide is good for FOAM 1.5.46 and later versions only.

Quick Start


Many coupled systems come with one massive shell script which combines the build system and run system: it compiles the code, copies data files and executables into place, and runs the model. FOAM keeps the compile and run systems separate. This makes development somewhat easier because the build system consists of just makefiles and source code. For runtime, FOAM does not provide a one-script-does-all shell script because the parallel platforms FOAM runs on offer so many different choices for queue software, filesystems, mass store, etc. that we feel an all purpose script, if it was possible to build, would be excessively long and hard to debug. We describe the steps below and you can, if you wish, put these in to a script appropriate for your system.

Setting up the model run directory and obtaining input data

This example assumes you're running a R15_128x128 case.

1.Choose a directory to run the model. We'll call it "foamrun". It should have plenty of disk space for the output.

2. Decide if you want to run with NetCDF or binary I/O.

3. Obtain the boundary/initial condition data.

Select the appropriate file above and untar it in the foamrun directory. A directory called "f1.5data" will be created.

4. Use "mkdir" to create the following subdirectories to hold the history and restart output. (FOAM expects this directory structure to exist)

  • history
    • history/atmos
    • history/coupl
    • history/ocean
  • restart
    • restart/atmos
    • restart/coupl
    • restart/ocean

5. RESTART RUN ONLY: place the example restart data set from the ftp site:

in the restart subdirectory and untar. There is a separate file for each model (two for the atmosphere). The coupler restart contains restart data for the land, sea-ice, and river models.

6. Place the files run_params, atmos_params (samples available at the ftp site: atmos_params, run_params) and the foam executable (foam1.5) in foamrun.

Edit the run_params file

7. Edit the file run_params and change the default PREFIX with the complete path to your foamrun directory. replace TIME_INV with the complete path to the f1.5data directory created above.

8. Check the value of FINISHED in run_params. For a restart run, it should be the same number as at the end of the restart files. For an initial run, it should be set to 0000000.

9. Edit HISTFRQ and RESTFRQ in run_params to adjust the history and restart frequency to what you want.

10. For a restart run, set INITIAL and FILTPHIS in run_parmas to F. For an initial run, set INITIAL to T and set FILTPHIS to T if using data from Slarti or some other source where the PHIS field has not been spectrally truncated. Set FILTPHIS to F if using the files supplied in the f1.5data tar files above.

You are now ready to run. See below for information on how to start the model.

OPTIONAL: Moving the history/restart directories

You may have the history and restart data in a different directory (or filesystem) than the run directory. Suppose you create a directory called storedir. Create "history" and "restart" subdirectories and the atmos,coupl,ocean subdirectories as indicated above. Move your restart files to the new location. Use the UNIX command "ln" to set a link from the run directory to the new location of "history" and "restart". Example: While in the run directory, type: "ln -s <storedir>/restart" and "ln -s <storedir>/history"


Its possible to locate "foamrun", the "f1.5data" directory and the history and restart directories each on different file systems. For "foamrun" and "f1.5data", just enter the complete path in run_params.

Summary of FOAM run directory contents:

Before starting a run, the run directory contents should be:

  • atmos_params
  • run_params
  • foam1.5*
  • history/
    • history/atmos/
    • history/coupl/
    • history/ocean/
  • restart/
    • restart/atmos/restart.atmos.xxxxxx (if doing a restart run)
    • restart/atmos/restart.atmos.xxxxxx.A (if doing a restart run)
    • restart/ocean/restart.ocean.xxxxxx (if doing a restart run)
    • restart/coupl/restart.coupl.xxxxxx (if doing a restart run)

Building and Running the Model


The makefile by default will compile:

  • a 32 processor executable,
  • single precision
  • R15 atmosphere and 128x128 ocean/land surface.
  • binary format input and output

FOAM useres GNU Makefiles for its build system. To build, type "make" in the top level directory of the source code.

You will need GNUmake or a compatible make version. GNUmake is sometimes called "gmake" on non-Linux systems. The source code for GNUmake is available here.

Compiling with NetCDF

In the Makefile, add -DNETCDF to FOAM_OPTS and uncomment the three lines for the NetCDF libraries and include paths. You will need to edit the two paths below FOAM_OPTS

  • NETCDF_INC= -I/soft/apps/packages/netcdf-3.6.0-p1-pgi-5.2/include
  • NETCDF_LIB= -L/soft/apps/packages/netcdf-3.6.0-p1-pgi-5.2/lib

to point to your local installation of NetCDF. Do a "make clean" and "make". This will activate both the NetCDF input and output.

Compiling different model configurations

See the top level Makefile for an explanation of model configuration options. Type "make help" to see what targets are available.

How to run a fixed-sst configuration Fixed-sst runs are accomplished using a version of the slab model.

1. Edit the top-level Makefile and add the following -DSST_FROM_FILE -DSIMSICE to the FOAM_OPTS variable.

2. type "make clean; make foamslab"

When the build is finished you will have an executable called "foam1.5.slab". With the options above, this version of the model will force the atmosphere with SST's from the file "sstshea5c" which is found in the f1.5data directory. Sea-ice extent is determined by the SST field. Sea ice is placed whereever the SST is below freezing. The simple sea ice model is used to predict temperatures in the sea ice. "sstshea5c" contains 12 monthly averages of observed SST's. The slab ocean will interpolate between between each month to provide SST values at each ocean time step. Land and river models operate exactly as in fully-coupled mode.

Compiling on Different Platforms

The Makefile uses "uname" to discover what platform it is on and set appropriate compiler settings. IBM, SGI, Linux and Sun are recognized. To add a new platform, add a section to the top level Makefile similar to those for the supported platforms.

Linux platforms often have many different compilers. FOAM's Makefile assmes the Portland Group Fortran compiler is used. To switch to the Intel compiler, you will have to edit the Makefile and comment/uncomment the appropriate lines for the compiler flags.

Compiling for different Processor Decompositions

Only certain decompositions are allowed for the standard configuration of R15 and 128x128. You'll need to edit the FOAM_OPTS string in the Makefile accordingly and recompile for the changes to take effect.

The number of processors in each direction (lat and lon) must always be a power-of-two.

Note that the land, sea-ice, river model and coupler always run on the same processors as the atmosphere in the default FOAM compile. This is called "colocated" mode.

Non-Colocated options (ocean and atmosphere-coupler-land-ice on two distinct sets of processors)are allowed. Note: you can add more processors to the ocean for each non-colocated case but each number (lat and lon) must be a power-of-two.

List of FOAM processor configurations

Compiling for different atmosphere resolutions

To change the atmosphere resolution, change -DPP_RHOMB_TRUNC=15 in FOAM_OPTS in the Makefile to

1. PP_TRIANG_TRUNC=31 for T31

2. PP_TRIANG_TRUNC=42 for T42

Your atmosphere restart won't work if you change resolutions so you'll have to do an initial run. #Boundary Data for T31 and T42 are available.


Basic run command

Start the model with a command like (assuming you're using the 32 proc configuration):

mpirun -np 32 foam1.5 run_params

run_params is an argument that foam expects. The above command assumes the executable, foam1.5, and run_params are in the same directory. You can use a full pathname for run_params.

Other versions:

mpirun -np 32 foam1.5 run_params >& std_out. The redirection (>&) sends stdout and stderr from mpirun to a file called std_out.

If you are using a queue system you will need to create a "run script". Consult the local documentation. A line like the above will need to be in the script to start the model.

Initial Run

By default, FOAM is always in restart mode and will try to read a set of restart files when starting. If you want to change the boundary conditions, you will need to do an initial run. See below for how to change the boundary conditions. Here's how to do an initial run:

1. edit run_params and add or change the following line: INITIAL: T

2. If your new topography file is from Slarti or from another source and it has not been spectrally filterd, add the following line to run_params FILTPHIS: T

Note: If you are using the original NCAR-supplied initial files, those have PHIS already filtered.

NOTE: Be sure to set FILTPHIS back to F for a restart run. Otherwise, PHIS will be filtered again and again.

INITIAL: T forces all models to do an initial run. It will override the value of NSREST in atmos_params. NSREST is now ignored.

Om3 initial state: Om3 will initialize its temperature and salinity from om3.salt and om3.temp in the f1.5data directory. Velocities will be 0 everywhere.

slab ocean initial state: The slab will initialize its temperature from the file sstinit.ascii in the f1.5data directory. Velocities will be 0 everywhere.

Atmosphere initial state: The atmosphere will try to read initial data from the file NCDATA in atmos_params. Typically this is SEP1* in the f1.5data directory. NOTE: If you are using the original NCAR-supplied SEP1 files for initial data, you will need to set -DFORCEHY in FOAM_OPTS in the Makefile to force the correct vertical level values. These values are correct in Slarti output.

Land/Sea Ice/River initial state: The initial state for the land, sea ice and river models are set within FOAM and not read from a file. Land temperature has a zonally uniform cosine profile that is constant with depth. Soil moisture and snow depth are set to 0. Sea ice is absent everywhere. Rivers are empty.

At the end of the initial run, each model should output restart files which can then be used in subsequent restart runs.

Continuing a Run

To continue the run, change FINISHED in run_params to the day number of the last-written restart set. If you started with an initial run, change INITIAL and FILTPHIS to F. Then reissue the mpirun command or resbumit the run script.

Running with NetCDF

In your run directory, edit atmos_params and change the 4 input files to NetCDF versions:

  • NCDATA = '',
  • BNDTI = '',
  • BNDTVS = '',
  • BNDTVO = '',

Note that BNDTVS is not needed in FOAM; only in the standalone atmosphere. NCDATA is only read during an initial run.

You can make NetCDF versions of the atmosphere data by running "ccm2nc" on the binary input files and leaving them in your f1.5data directory.

You will also need the NetCDF versions of the land/river boundary data. These can be made with the program CplBC2nc.tar.gz

NetCDF versions are also available from the ftp site.

You can switch to the NetCDF input version and maintain bit-for-bit identical results with the binary input.

Runtime options

Changing atmospheric constants

Gas concentrations , the solar constant and aerosal optical depth can now be changed at runtime through the atmosphere model's namelist, atmos_params. Since these values are not saved in the atmosphere restart file, they will take effect in both restart and inital runs. Other runtime atmosphere parameters, such as timestep and diffusion, can only be changed with a new inital atmosphere run.

Example of what you would change or add in atmos_params to change all gas constants to Pre-industrial conditions.

CO2VMR = 2.80e-4,
N2OVMR = 0.275e-6,
CH4VMR = 0.7e-6,
F11VMR = 0.,
F12VMR = 0.,

Example of 1975 conditions.

CO2VMR = 3.35e-4,
N2OVMR = 0.302e-6,
CH4VMR = 1.500e-6,
F11VMR = 0.13e-9,
F12VMR = 0.30e-9,

An example of changing the solar constant and aerosal optical depth. SCON = 1.360e6,
TAUVIS = 0.10,

NOTE TAUVIS is not really the aerosol optical depth. Read this note before adjusting this parameter.

Orbital Paramaters

An example of setting the orbital parameters for modern times (and what they mean):
ECCEN = .016724, Eccentricity of orbit
OBLIQ = 23.4463, Earth's obliquity angle
MVELP = 77.9610, Degree's between vernal equinox and perihelion
DAYP = 2.0, number of day from jan1 (modern) to date of perihelion

Add any of the above lines to atmos_params to change the orbital parameters.

Other possible changes

         mvelp     eccen    obliq    dayp
3K: 128.9253, 0.017824, 23.8205, 310.767
6K: 179.1304, 0.018682, 24.1054, 258.993
8K: 212.2577, 0.019110, 24.2092, 224.649
11K: 261.5920, 0.019529, 24.2012, 174.280
21K: 65.5750, 0.018994, 22.9490, 14.4850
126K: 248.7659, 0.039710, 23.9281, 185.037

These values are calculated from formulas in
"Textbook on Spherical Astronomy" WM Smart, Sixth Edition Revised by RM Green (1977), Cambridge University Press, 431pp.

Changing atmospheric history file number and contents

In PCCM3 terminology, the main history file output by the atmosphere, history.atmos.*, is the "primary" history file. You can have up to 5 auxiliary files with different content and frequencies (I've only tried 2 auxiliary files).

To turn on auxiliary files, you need to edit atmos_params. In this example, we'll add 1 auxiliary file for daily PSL and SHFLX with 30 writes per file.

First, in atmos_params, change:

MFILT = 1,30,

MFILT sets the number of history writes per file. The first number is for the primary history file and the second is for the first auxiliary file.

Now add the following:

NHTFRQ = -24, -24,
AUXF = '1','PSL','SHFLX',

The integers in NHTFRQ set the history write frequencies. The first number is for the primary file and is ignored in favor of HISTFRQ in run_params. The second number sets the auxiliary file frequency at once per 24 hours (negative = hours, positive = timesteps). You could also set NHTFRQ as:

NHTFRQ = ,-24,

Finally, AUXF = '1','PSL','SHFLX' sets the content of the auxiliary file to PSL and SHFLX.

The output files in history/atmos will be called ha0001, ha0002, etc. You can convert these to netcdf with ccm2nc.

Ex: For two auxiliary files with PSL daily and every timestep and one file each per year:

MFILT = 1,360,17280
NHTFRQ = -24,-24,1
AUXF = '1','PSL','2','PSL'

Output will be ha0001, hb0001, ha0002, hb0002, etc.

A summary of the AUXF settings will also be reported in pccm.out.*

The contents of the primary history file are initially set in the code. You can alter those contents at runtime with the PRIMARY and EXCLUDE variables in atmos_params. PRIMARY will *add* fields to the history file wile EXCLUDE will remove them.

Example. To remove omega and add relative humidity and the longitude pressure gradient to the primary atmosphere history, add the following lines to atmos_params: PRIMARY = 'RELHUM','DPSLON',

Default runtime parameters

NOTE: The model will use default values for each of these variables not present in atmos_params. Default values are: CO2VMR = 3.55e-4,
N2OVMR = 0.311e-6,
CH4VMR = 1.714e-6,
F11VMR = 0.280e-9,
F12VMR = 0.503e-9,
SCON = 1.367e6,
TAUVIS = 0.14,
ECCEN = .016724,
OBLIQ = 23.4463,
MVELP = 77.9610,
DAYP = 2.0

Input and Output Data

Input files

Text input files

run_params is used to control the overall model integration.

run_params contents:

  • PREFIX: path for the run directory
  • STORAGE: Currently ignored. Use same path as run directory.
  • TIME_INV: path to the data directory.
  • RESTFRQ: Frequency of restart writes in days.
  • HISTFRQ: Frequency of history writes in days.
  • FINISHED: The day postfix of the restart file to start from
  • RUNLNG: The number of days to run.
  • INITIAL: T or F. Indicate initial run
  • FILTPHIS: T or F. Filter topography. Use only for initial run.

Note: RUNLNG should be a multiple of RESTFRQ but the model doesn't check for this. Also RESTFRQ should be a multiple of HISTFRQ.

For a 5 year restart run with monthly histories and annual restarts, run_params would look like:

  • RESTFRQ: 360
  • HISTFRQ: 30
  • PREFIX: dir
  • STORAGE: dir
  • TIME_INV: dir
  • FINISHED: 0001440
  • RUNLNG: 1800

(NOTE: 1800 = 5*360. FOAM uses a 360-day year.)

atmos_params controls parameters for the atmosphere model.

Boundary Data

Location of files

Get the boundary/initial condition data from the ftp site:

Data is available for the standard FOAM ocean resolution and three atmosphere resolutions. All files include NetCDF versions of the data. -- Single precision, big endian (SP and Origin)

foam1.5datR15_128.single.le.tar -- Single precision, little endian (Intel Linux)

foam1.5datT31_128.single.le.tar -- Single precision, little endian (Intel Linux)

foam1.5datT42_128.single.le.tar -- Single precision, little endian (Intel Linux)

We also have files that contain only the NetCDF and other portable data.

Contents of Boundary/Intial Condition data

The "f1.5data" directory created by the foam1.5datR15_128.single.*.tar file contains both boundary and initial condition data. A desciription of each file is below.

atmosphere data:

(CCM2 = CCM2 history file format; nc = NetCDF)

  • SEP1.R15 -- single precision Atm initial condition data (CCM2 or nc)Contains:
    • initial 3D temperature field, T
    • initial 3D moisture field, Q
    • initial 3D velocity field, U,V
    • initial 2D surface pressure, PS
    • initial 2D geopotential, PHIS
    • initial 2D surface and sub-surface temperatures, TS1,TS2,TS3,TS4
    • initial 2D land-ocean-seaice mask, ORO
    • initial 2D snow depth, SNOWH

For a FOAM run, SNOWH is not necessary.

  • tibds.R15 -- single precision Atm time invariant boundary condition data (CCM2 or nc)

(only SGH field is needed when coupled with FOAM)

  • tvbds.R15 -- 12 months of single precision SST data to drive atmosphere in standalone mode (CCM2 or nc)

(not used when coupled within FOAM)

  • ozn.R15 -- 12 months single precision monthly lat/height ozone data. (CCM2 or nc)

ocean data:

The files below are written in a compressed format that uses characters to represent floating point numbers. They should be portable across platforms regardless of endian issues (provided a C char is 4 bytes)

  • om3.geometry24 -- combined ocean depth/3D land mask for 24 level ocean

(note: The next three fields are still read but are either written over by values in the restart file (temp and salt) when doing a restart run or not used at all in coupled mode (stress)

  • om3.salt24 -- reference annual average 3D salinity field (Levitus). Used as initial condition.
  • om3.temp24 -- reference annual average 3D temperature field (Levitus). Used as initial condition.
  • om3.stress -- Hellerman annual wind stress

other ocean data:

  • sstshea5c -- the Shea 12 month SST climatology in binary format used for fixed sst integrations with FOAM land surface.

(binary version for little and big endian available.)

  • sstinit.ascii -- initial sst values for the slab ocean.

The remaining fields are available in ASCII and NetCDF format

"128x128" refers to data at the surface resolution. (The surface resolution is set by the ocean model.)

coupler data: used in interpolation/regridding routines

  • weights.r15_128x128 -- maps atmosphere points to ocean points
  • weights.128x128_r15 -- maps ocean points to atmosphere points
  • r15area -- area of an atmosphere grid cell (divided by R^2)
  • area.128 -- area of an ocean grid cell (divided by R^2)

The remaining files all have the format: lon index, lat index, value

  • rdirc.128x128 -- river flow direction. 1=north, 2=NE, 3= east, etc.
  • ddist.128x128-- "downstream distance" Distance in meters from current point to point downstream as determined by river direction.
  • effvel.128x128-- effective velocity of river flow (currently a constant)

The above are grouped together in

  • albnis.128x128 -- near infrared albedo, strong zenith angle dependence
  • albniw.128x128 -- near infrared albedo, weak zenith angle dependence
  • albvss.128x128 -- visible albedo, strong zenith angle dependence
  • albvsw.128x128 -- visible albedo, weak zenith angle dependence
  • frctst.128x128 -- fraction of land with strong zenith angle dependence
  • rghnss.128x128 -- roughness length
  • mask.128x128 -- the land/ocean mask on the surface grid 1 = land, 0 = ocean
  • vegtyp.128x128 -- land model "vegetation" type. Really a surface thermal type.

See CCM2 description for an explanation of values. The above are grouped together in

  • mask.r15 -- the land/ocean mask on the atmosphere grid 1. = land, 0. = ocean

The table below is a summary of the f1.5data directory files and what is needed for each version.
A = Stand alone atmosphere model
C = Full coupled model
I = Initial Run
R = Restart Run

File Binary Version NetCDF Version Special comments
SEP1.R15 A,C,I A,C,I
albnis.128 C,I,R
albniw.128x128 C,I,R
albvss.128x128 C,I,R
albvsw.128x128 C,I,R
area.128 C,I,R C,I,R C,I,R
ddist.128x128 C,I,R
effvel.128x128 C,I,R
frctst.128x128 C,I,R
mask.128x128 C,I,R
mask.r15 C,I,R C,I,R
om3.geometry16 C,I,R C,I,R
om3.geometry24 C,I,R C,I,R
om3.salt16 C,I,R C,I,R
om3.salt24 C,I,R C,I,R
om3.stress C,I,R C,I,R
om3.temp16 C,I,R C,I,R
om3.temp24 C,I,R C,I,R
ozn.R15 A,C,I,R A,C,I,R C,I,R
r15area C,I,R C,I,R
rdirc.128x128 C,I,R
rghnss.128x128 C,I,R
sstinit.ascii C,I C,I Used only for a slab ocean run
sstshea5c C,I C,I Used when the SST_FROM_FILE flag is set for a slab ocean run or when ANNUAL_SST is set for a regular ocean run.
tibds.R15 A,C,I,R A,C,I,R
tvbd.R15 A,C,I A ,C,I
vegtyp.128X128 C,I,R
weights.128x128_r15 C,I,R C,I,R
weights.r15_128x128 C,I,R C,I,R

Output Files

FOAM outputs history and restart files for each model and several files with other information.

Text output files in run directory

When the run finishes, there will be several files in the run directory:

  • Finished -- A 0 size file written to indicate model has finished
  • Restart.xxxxx -- 0 size files written to indicate when a restart set is written
  • pccm.error.xxxx -- Atmosphere model stderr files. One for each processor
  • pccm.out.xxxxxx -- Atmosphere model stdout file.
  • om3.err.xxxx -- Ocean model stderr. One for each processor (In colocated mode, these files are not opened)
  • om3.out.xxxx -- Ocean model stdout
  • std_out -- the redirected mpirun std_out

There will also be soft links to the atmosphere restart files (links are called rest and rest.A)

You should delete all of the above when preparing the run directory for a new run.

Pccm.out output

The pccm.out.* file containts statistics from the atmosphere written every timestep.

example: NSTEP = 4872961 8.889008313417435E-05 7.462289431714453E-06 2.521384124755859E+02 9.847287500000000E+04 2.544476318359375E+01 5.455936193466187E-01

what each number means:

  • NSTEP = 4872961 the total number of timesteps integrated
  • 8.889008313417435E-05 Global RMS Vorticity
  • 7.462289431714453E-06 Global RMS Divergence
  • 2.521384124755859E+02 Global RMS Temperature (Kelvin)
  • 9.847287500000000E+04 Global Mass Integral
  • 2.544476318359375E+01 Global Moisture Integral
  • 5.455936193466187E-01 Maximum Courant number

Restart Files

The number at the end of a restart file is the day the restart was written on. The restart is written at the end of a day. So restart.atmos.0000360 is midnight on the last day of the year. A run starting from that file will begin on 00Z, Jan 1st.

Whats in the restart files from

restart.atmos.0001440 -- binary, single precision data file (PCCM format) restart.atmos.0001440.A -- binary, single precision "master" file. NOTE: PCCM actually write one *.A file per processor. They can be simply catted together and FOAM does this with a system call. Once catted together, you can restart the model on different numbers of processors.

restart.ocean.0001440 -- C binary, single precision in custom OM3 format. ocean restart files can be reused when changing number of ocean processors

restart.coupl.0001440 -- simple Fortran binary write of coupler restart data.

Modifying Boundary and Initial Conditions for a New Initial Run

To run FOAM with different boundary conditions, such as a different continental geometry, you need to consistently modify several files and preform an "initial run" to tell the model about the new boundary conditions.

This explanation will focus on making a consistent set of boundary conditions. "Consistent" means, for example, that files for each model agree on what is land and what is ocean.

In the discussion below, refer to the explanation above of what is in the boundary/initial files. Also see the instructions above on how to do an initial run.

Boundary conditions (BC) are discussed first, then initial conditions (IC).

BC: land/ocean mask and surface values: The most basic file is mask.128x128 which describes the time invariant land/ocean mask (ignoring sea ice) on the surface grid. Land is 1 and ocean is 0.

The land/ocean mask is implied in the following files. "implied" means that they have special values for the ocean which are different from the land. If you change a point from land to ocean in the mask, you need to also change the same point in all of these files:

  • rdirc.128x128
  • albnis.128x128
  • albniw.128x128
  • albvss.128x128
  • albvsw.128x128
  • frctst.128x128
  • rghnss.128x128
  • vegtyp.128x128
  • om3.geometry24

In addition to the interdependence on the mask, the vegetation, albedo and roughness files are all related. FOAM's surface description begins with assigning a Matthews vegetation type to each land point. NOTE: this is "not" the data in vegtyp.128x128. This file has a misleading name. Matthews vegetation types are then grouped into several categories for assignment of albedo, roughness and "vegtyp" (really thermal type) values.

ADDITIONAL NOTE: The current modern data used in FOAM was derived by interpolation from T170 CCM2 initial datasets (SEP1, tibds, etc.)provided by NCAR. There is no Matthews vegetation file for the default moden boundary conditions used in FOAM.

The atmosphere model also needs to know the mask for its initial condition. The field is called ORO in SEP1.R15 and can be a simple interpolation of mask.128x128.

BC: Topography: Topography changes need to be coordinated between rdirc.128x128 and PHIS and SGH in SEP1.R15. Also the initial condition for PS in SEP1.R15 needs to be recalculated if topography changes substantially.

rdirc.128x128 describes the direction a river flows downslope in one of 8 possible directions.

You should have a 128x128 grid description of the topography, in meters, for setting the river directions. PHIS, the geopotential height and the atmosphere's description of the topography, can then be a simple interpolation of that field, multiplied by g.

Ideally, the ORO field should be consistent with PHIS: positive PHIS is land (ORO=1) and PHIS=0 is ocean (ORO=0). But the ORO field in SEP1.R15 is time varying and is only used on the 1st time step in an initial run of the coupled model. After the first step, the coupler sends the atmosphere its ORO field.

SGH is the standard deviation of topography at the atmosphere resolution. It is used in the gravity wave drag subroutine and can also be derived from the 128x128 topography. PHIS and PS are in the SEP1.R15 file and SGH is in the tibds.R15 file.

NOTE: The default modern PHIS in the SEP1.R15 file has been spectrally filtered which is necessary for the dynamics. If you derive a new PHIS from a new topography, you must tell FOAM to filter it during the initial run. This is accomplished by setting -DFILTPHIS in the Makefile and recompiling.

BC: Bathymetry: Bathymetry is confined to om3.geometry24. You can raise and lower below-sea-level points in this file without affecting other files. However, if you change a point for ocean to land, you must go back to the mask and alter all the other files accordingly.

For the slab ocean, om3.geometry is not needed. The slab model obtains the land/ocean mask from the mask.128x128 file.

IC: Atmosphere: In coupled mode, the atmosphere requires an initial condition for the 3D T, U and V fields and the surface pressure PS which are all in SEP1.R15. For stability, the PS field must be in agreement with the topography. Since the initial condition is "forgotten" quickly, the T, U, and V fields could be retained with their modern structure (equivalent to September 1st). You could also replace the initial condition with a simple profile in T, zero V and U caculated from the thermal wind equation. The surface temperature at the atmosphere resolution, TSSUB1 in SEP1.R15, should also be defined with reasonable values but it is only used in the first time step. The other TSSUB fields are ignored in a coupled run. Slarti will also output an initial condition for the atmosphere.

IC: Ocean: The ocean's initial condition for temperature and salinity is obtained from om3.temp24 and om3.salt24. These files currently contain Levitus annual averages. They also contain good values in land areas interpolated in from the ocean basins. Thus, they can be used with other bathymetries although the initial T,S state may be far from equillibrium. The initial velocities in the ocean are 0.

The slab ocean obtains its initial temperature field from sstinit.ascii in the f1.5data directory

IC: Land/Ice/River/Coupler: The land, sea-ice, river model and coupler do not have initial conditions files. Rather they are initialized by the model to an arbitrary but reasonable initial condition.

GOOD NEWS: All of the above is handled by the GUI program Slarti!
Slarti will let you import a basic description of mask or topography or bathymetry and derive a consistent set of boundary conditions using all the correct rules for vegetation, albedo, roughness, etc. You can make small edits to the Matthews vegetation, topography, mask and bathymetry in Slarti Slarti will then derive the required atmosphere fields by interpolation. Slarti will also derive analytic initial condtions or copy them from a specified NetCDF file. See the Slarti help page for more information

How to do a Restart Test

To test the restart ability of FOAM, we recommend the following procedure:

Pick a restart set to start from. Set HISTFRQ and RESTFRQ to 30 days. Set RUNLNG to 60 days. Run the model. This will give you two sets of history and restart data, each 30 days apart. Save the last set of history and restart data to another directory. Now change RUNLNG to 30 days and FINISHED to start from the first set of restart data created from the first run. Run the model again. You now have 2 sets of data, the history/restart from the 2nd run and the set from 1st run saved to a different directory. Each set represents the same time period but were started from two different points in simulated time. Both the history files (averaged over 30 days) and the restart files (snapshots from the end of the run) should be the bit-for-bit (bfb) identical.

Use the unix command "cmp" to test for sameness: Ex: cmp <file from first run> <file from second run> cmp returns nothing if the two files are identical. NOTE: Don't test for bfb on history .atmos.xxxx or restart.atmos.xxxxx. These files contain timestamps and so will never be bfb identical. You can test for bfb on restart.atmos.xxxxx.A

History File content details

The number at the end of a history file is the number of the last day in the averaging period for that history file. FOAM uses a 360 day calendar and typically one chooses output to be every 30 days.

FOAM History File Content