Using Oasis

Revision as of 22:57, 29 January 2020 by S.wales (talk | contribs)

Using Oasis

Oasis3-MCT is available as a module in the ACCESS environment. To load the module run

module use ~access/modules
module load oasis3-mct

There are different versions available compiled for different MPI libraries

To make use of Oasis you'll need to add these libraries to the link command (e.g. LDLIBS if you use a makefile)

-lpsmile.MPI1 -lmpp_io -lnetcdff -lnetcdf

Note that Oasis is very restrictive with the naming of fields, strings used in library calls and entered in the namcouple file have fixed widths, if you exceed these you're going to get errors.

Namcouple File

To run a coupled model with Oasis you'll need to create a 'namcouple' file describing the fields. The first column of every line in this file must be a space, blank lines are not permitted. Oasis is also very restrictive with how you can name things: Field and file names are up to 8 characters long, model, grid and job names are 4 characters. Exceeding these limits will cause errors in Oasis. Field names defined in the namcouple file also have to match the names defined in the model code.

Here is an example namcouple file for a simulation with two components, 'atm' and 'ocn'. Ocn sends sea surface temperatures to the atmosphere model, atm sends radiation values to the ocean. You can refer to the Oasis user guide for more information on transformation types.

 $SEQMODE
     # Maximum SEQ value for the coupled fields
     2
 $END
 $CHANNEL
     # Use buffered sends
     MPI1 BSEND
     # Number of processors for each component
     6 6 atm
     1 1 ocn
 $END
 $NFIELDS
     # Number of fields to couple
     2
 $END
 $JOBNAME
     # 3-character job name
     aaa
 $END
 $NBMODEL
     # Number and names of models (name has to match what's specified in the model code)
     2 atm ocn
 $END
 $RUNTIME
     # Model runtime in seconds
     1000
 $END
 $INIDATE
     # Initial simulation date (used in some transformations)
     19500201
 $END
 $MODINFO
     # Related to Oasis' binary files, not relevant
     NOT
 $END
 $NLOGPRT
     # Log level: 0- none; 2- full
     2
 $END
 $STRINGS
     # Coupled fields
     # Source fieldname, target fieldname, index for cf name, coupling period, number of transformations, restart filename, coupling type
     ocn_sst atm_sst 1 100 4 o_rst_o.nc EXPORTED
     # Source grid, target grid, coupling lag, coupling sequence
     ocnt atmt LAG=0 SEQ=1
     # Transformations to perform
     LOCTRANS CHECKIN NOINTERP CHECKOUT
         # Transformation parameters
         INSTANT
         INT=0
         INT=0
     # Next coupled field
     atm_sol ocn_sol 1 100 4 rst_a.nc EXPORTED
     atmt ocnt LAG=10 SEQ=2
     LOCTRANS CHECKIN NOINTERP CHECKOUT
         INSTANT
         INT=0
         INT=0
 $END

Lag and sequence

Three values specify at what times fields are sent between models - the coupling period, the lag, and the sequence.

The coupling period is the interval in seconds between when the field is sent to the target model. This doesn't have to be every timestep, but should be an integer multiple of it. For instance if model A has timesteps of 1 hour, but the coupling period is 12 hours, the field will only be sent at 12, 24, 36, &c hours.

Models cannot progress if they're waiting to receive data. If both models are waiting to receive data at the same time the simulation will deadlock, with neither component able to progress. Oasis provides two features to avoid this, lag and sequence.

When lag is defined for a field, instead of receiving the current value of the field at time T Oasis retrieves the value it was at time T-LAG. You can use this to retrieve the value of the field in the source model at a previous timestep. At the start of the simulation run Oasis will get the previous value from a restart file that you will need to provide.

The sequence value is used to give an explicit order to fields exchanged at the same timestep, for instance if model A needs to get fields before it can process them and send them back to model B.

Ancillary files

Oasis requires two types of ancillary files to function. Firstly it requires a file defining the grid layout, secondly it requires a restart file to initialise any lagged fields at the start of the simulation. See the documentation for the required file format.