Oasis Coupling with the UM

Template:Pre UM10 This information is only for versions of the UM before 10.0
Template:Duplication This is a duplicate article of Oasis_coupling_in_UM_8.5

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