Oasis is available as a module on Vayu. To load the module run
module use ~access/modules module load oasis
Note also that oasis depends on netcdf to write output files.
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.
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.
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.