The UM uses Oasis3 as its coupler to communicate with other models.

In order to use Oasis3 couplings with the UM you'll need:

  • A list of variables from each model that you want to couple
  • Oasis ancillary files grids.nc and masks.nc to define grids
  • The Oasis configuration file namcouple for the coupling

ACCESS Coupled Variables


The variables output by the ACCESS atmosphere model in a CMIP configuration include:

The variables are processed by the STASH system before they are exported to Oasis, allowing you to send mean fields to the coupler. Oasis can also process fields itself if needed.

Ancillary Files


Oasis requires a few ancillary files to define the grids that variables are defined on. This makes sure that variables are sent to the correct locations, as well as providing information for interpolation if necessary. Models may be set up to generate these ancillary files themselves, or they may require them to be generated externally.

Grids have a 4-character identifier, within the files the meaning of variables is identified by a suffix, e.g. 'n48t.lon' is the longitude variable for grid 'n48t'. The number of grid points is NX x NY - grids don't have to be regular, though Oasis expects each grid cell to have 4 corners.

The ancillary files contain the following variables for each grid used in the model:

grids.nc


  • float GRID.lat(NX, NY): Latitude of every grid point
  • float GRID.lon(NX, NY): Longitude of every grid point
  • float GRID.clat(4, NX, NY): Latitude of each corner of the grid cell (in a counter-clockwise sense). Optional, only used for some interpolations
  • float GRID.clon(4, NX, NY): Longitude of each corner of the grid cell. Like 'clat' this is optional

masks.nc


  • int GRID.msk(NX, NY) : Coupling mask for the grid. Values > 0 indicate [coupled or uncoupled] points, while values = 0 are [the opposite]

namcouple File


The namcouple file is Oasis' configuration file, it defines which fields are sent to which model.


This file can be rather fiddly to get right, if there are any errors the run will crash. It can be helpful to run Oasis stand-alone to check it's working (e.g. just run oasis3.MPI1.x without mpirun). Totalview can also help to check what's happening when it reads the file.

Comments in the file begin with a hash (#). Significant lines should begin with a space character, blank lines are not allowed. The namcouple file is split up into a number of sections, whose names are in all-caps and begin with a dollar sign.

A sample namcouple file follows, with explanation below:
# Max SEQ value
 $SEQMODE
    1
#
# MPI information
 $CHANNEL
# MPI version 1 & unbuffered sends
    MPI1 NOBSEND
# nprocs, coupled procs & args
    1 1 a
    1 1 b
#
# Number of fields to couple
 $NFIELDS
    2
#
# Name of the job
 $JOBNAME
    TEST
#
# Submodel count, names and output streams
 $NBMODEL
    2 a b 100 100
#
# Number of seconds to run for
 $RUNTIME
    2
#
# Starting date
 $INIDATE
    10000101
#
# Info in binary files
 $MODINFO
    NOT
#
# Max log level
 $NLOGPRT
    2
#
# Gregorian calendar
 $CALTYPE
    1
#
# Coupled fields
 $STRINGS
    Bbt Abt 1 1 4 rest.nc EXPOUT
    n96t n48t
    P 0 P 0
        LOCTRANS CHECKIN SCRIPR CHECKOUT
        INSTANT
        INT=0
        CONSERV LR SCALAR LATLON 10 FRACAREA FIRST
        INT=0
    Aat Bat 1 1 4 rest.nc EXPOUT
    n48t n96t
    P 0 P 0
        LOCTRANS CHECKIN SCRIPR CHECKOUT
        INSTANT
        INT=0
        CONSERV LR SCALAR LATLON 10 FRACAREA FIRST
        INT=0

$SEQMODE


Oasis allows you to explicitly order communications by giving them a sequence index, otherwise communication has to happen in the order that fields are defined in the namcouple file. The value here is the maximum sequence number used.

$CHANNEL


CMIP Fields

namcouple file /short/w97/ACCESS1.3_EXP_CMIP5/work/um_coupled/hPI-c01a/CPL_RUNDIR/namcouple

atm -> ice

Source
Dest
CF Index
CF Name
Unit
heatflux
thflx_i
5
surface_downward_heat_flux
W m-2
pen_sol
pswflx_i
38
surface_net_downward_shortwave_flux
W m-2
runoff
runoff_i
32
water_flux_into_ocean_from_rivers
kg m-2 s-1
wme
wme_i
37
surface_energy_flux_into_ocean_due_to_wind_mixing
W m-2
train
rain_i
27
rainfall_flux
kg m-2 s-1
tsnow
snow_i
40
snow_fall_flux
kg m-2 s-1
evap2d
evap_i
25
water_evaporation_flux
1
lhflx
lhflx_i
355
surface_downward_latent_heat_flux
W m-2
tmlt01
tmlt01_i
467
no_467_unknown_field_currently
xxx
tmlt02
tmlt02_i
467
no_467_unknown_field_currently
xxx
tmlt03
tmlt03_i
467
no_467_unknown_field_currently
xxx
tmlt04
tmlt04_i
467
no_467_unknown_field_currently
xxx
tmlt05
tmlt05_i
466
no_466_unknown_field_currently
xxx
bmlt01
bmlt01_i
466
no_466_unknown_field_currently
xxx
bmlt02
bmlt02_i
466
no_466_unknown_field_currently
xxx
bmlt03
bmlt03_i
466
no_466_unknown_field_currently
xxx
bmlt04
bmlt04_i
466
no_466_unknown_field_currently
xxx
bmlt05
bmlt05_i
466
no_466_unknown_field_currently
xxx
taux
taux_i
23
surface_downward_grid_eastward_stress
Pa
tauy
tauy_i
24
surface_downward_grid_northward_stress
Pa
swflx
swflx_i
367
surface_net_downward_shortwave_flux
W m-2
lwflx
lwflx_i
366
surface_net_downward_longwave_flux
W m-2
shflx
shflx_i
362
surface_downwelling_shortwave_flux
W m-2
press
press_i
33
surface_air_pressure
Pa

ice -> ocn

Source
Dest
CF Index
CF Name
Unit
strsu_io
u_flux
170
downward_eastward_stress_at_sea_ice_base
Pa
strsv_io
v_flux
175
downward_northward_stress_at_sea_ice_base
Pa
rain_io
lprec
27
rainfall_flux
kg m-2 s-1
snow_io
fprec
28
snow_fall_flux
kg m-2 s-1
stflx_io
salt_flx
454
water_flux_into_ocean
kg m-2 s-1
htflx_io
mh_flux
42
downward_heat_flux_in_sea_ice
W m-2
swflx_io
sw_flux
367
surface_net_downward_shortwave_flux
W m-2
qflux_io
q_flux
452
water_evaporation_flux
kg m-2 s-1
shflx_io
t_flux
362
surface_downwelling_shortwave_flux
W m-2
lwflx_io
lw_flux
366
surface_net_downward_longwave_flux
W m-2
runof_io
runof
297
runoff_flux
kg m-2 s-1
press_io
p
33
surface_air_pressure
Pa
aice_io
aice
44
sea_ice_area_fraction
1

ocn -> ice

Source
Dest
CF Index
CF Name
Unit
t_surf
sst_i
1
sea_surface_temperature
K
s_surf
sss_i
312
sea_surface_salinity
1e-3
u_surf
ssu_i
181
eastward_sea_water_velocity
m s-1
v_surf
ssv_i
261
northward_sea_water_velocity
m s-1
frazil
pfmice_i
441
upward_sea_ice_basal_heat_flux
W m-2
dssldx
sslx_i
203
height
m
dssldy
ssly_i
310
sea_surface_elevation
m

ice -> atm

Source
Dest
CF Index
CF Name
Unit
isst_ia
ocn_sst
1
sea_surface_temperature
K
icecon01
ofrzn01
31
sea_ice_area_fraction
1
icecon02
ofrzn02
31
sea_ice_area_fraction
1
icecon03
ofrzn03
31
sea_ice_area_fraction
1
icecon04
ofrzn04
31
sea_ice_area_fraction
1
icecon05
ofrzn05
31
sea_ice_area_fraction
1
snwthk01
osnwtn01
373
surface_snow_amount
kg m-2
snwthk02
osnwtn02
373
surface_snow_amount
kg m-2
snwthk03
osnwtn03
373
surface_snow_amount
kg m-2
snwthk04
osnwtn04
373
surface_snow_amount
kg m-2
snwthk05
osnwtn05
373
surface_snow_amount
kg m-2
icethk01
ohicn01
468
no_468_unknown_field_currently
xxx
icethk02
ohicn02
468
no_468_unknown_field_currently
xxx
icethk03
ohicn03
468
no_468_unknown_field_currently
xxx
icethk04
ohicn04
468
no_468_unknown_field_currently
xxx
icethk05
ohicn05
468
no_468_unknown_field_currently
xxx
uvel_ia
sunocean
47
surface_grid_eastward_sea_water_velocity
m s-1
vvel_ia
svnocean
47
surface_grid_eastward_sea_water_velocity
m s-1

KPP Fields

/data/projects/access/ancil/kpp/namcouple

atm -> ocn

Source
Dest
CF Index
CF Name
Unit
heatflux
HEATFLUX
5
surface_downward_heat_flux
W m-2
solar
SOLAR
38
surface_net_downward_shortwave_flux
W m-2
runoff
RUNOFF
32
water_flux_into_ocean_from_rivers
kg m-2 s-1
wme
WME
37
surface_energy_flux_into_ocean_due_to_wind_mixing
W m-2
train
TRAIN
27
rainfall_flux
kg m-2 s-1
tsnow
TSNOW
40
snow_fall_flux
kg m-2 s-1
evap2d
EVAP2D
25
water_evaporation_flux
1
lhflx
LHFLX
355
surface_downward_latent_heat_flux
W m-2
tmlt01
TMLT01
467
no_467_unknown_field_currently
xxx
bmlt01
BMLT01
466
no_466_unknown_field_currently
xxx
taux
TAUX
23
surface_downward_grid_eastward_stress
Pa
tauy
TAUY
24
surface_downward_grid_northward_stress
Pa

ocn -> atm

Source
Dest
CF Index
CF Name
Unit
OCN_SST
ocn_sst
1
sea_surface_temperature
K
OFRZN01
ofrzn01
31
sea_ice_area_fraction
1
OSNWTN01
osnwtn01
373
surface_snow_amount
kg m-2
OHICN01
ohicn01
468
no_468_unknown_field_currently
xxx
SUNOCEAN
suncoean
47
surface_grid_eastward_sea_water_velocity
m s-1
SVNOCEAN
svnocean
48
surface_grid_northward_sea_water_velocity
m s-1

CICE/KPP


ice->ocn


Source
Dest
CF Index
CF Name
Unit
strsu_io
TAUX
170
downward_eastward_stress_at_sea_ice_base
Pa
strsv_io
TAUY
175
downward_northward_stress_at_sea_ice_base
Pa
rain_io
TRAIN
27
rainfall_flux
kg m-2 s-1
snow_io

28
snow_fall_flux
kg m-2 s-1
stflx_io

454
water_flux_into_ocean
kg m-2 s-1
htflx_io

42
downward_heat_flux_in_sea_ice
W m-2
swflx_io
SOLAR
367
surface_net_downward_shortwave_flux
W m-2
qflux_io

452
water_evaporation_flux
kg m-2 s-1
shflx_io

362
surface_downwelling_shortwave_flux
W m-2
lwflx_io

366
surface_net_downward_longwave_flux
W m-2
runof_io

297
runoff_flux
kg m-2 s-1
press_io

33
surface_air_pressure
Pa
aice_io

44
sea_ice_area_fraction
1

HEATFLUX
5
surface_downward_heat_flux
W m-2

RUNOFF
32
water_flux_into_ocean_from_rivers
kg m-2 s-1

WME
37
surface_energy_flux_into_ocean_due_to_wind_mixing
W m-2

TSNOW
40
snow_fall_flux
kg m-2 s-1

EVAP2D
25
water_evaporation_flux
1

LHFLX
355
surface_downward_latent_heat_flux
W m-2

TMLT01
467
no_467_unknown_field_currently
xxx

BMLT01
466
no_466_unknown_field_currently
xxx

ocn->ice


OCN_SST
sst_i
1
sea_surface_temperature
K
OFRZN01

31
sea_ice_area_fraction
1
OSNWTN01

373
surface_snow_amount
kg m-2
OHICN01

468
no_468_unknown_field_currently
xxx
SUNOCEAN
ssu_i
47
surface_grid_eastward_sea_water_velocity
m s-1
SVNOCEAN
ssv_i
48
surface_grid_northward_sea_water_velocity
m s-1

sss_i
312
sea_surface_salinity
1e-3

pfmice_i
441
upward_sea_ice_basal_heat_flux
W m-2

sslx_i
203
height
m

ssly_i
310
sea_surface_elevation
m


See also

Oasis 3 documentation at ENES