Coupling in UM 8.5


The Met Office Unified Model uses the Oasis coupler to interact with other climate models (e.g. ocean & sea ice). Oasis handles sending fields between different models, and automates converting between different grids and processor decompositions.

The way that the UM handles coupling has changed since the version that was used in ACCESS 1.x. It is now able to control what fields are coupled through annotations in the Oasis namcouple file.

Coupling Setup


Coupling is configured within the UMUI under 'Sub-Model Choices and Coupling -> OASIS Coupling Switches and Options'. This panel configures a number of options, some are specific to coupling to the NEMO model however most are generic.

Important settings here are:

- Coupling Frequency: How often the UM will send and recieve fields to/from Oasis
- Standard Coupling Macro: A STASH namelist file configuring how the coupled fields are processed
- OASIS3 namcouple: Location of the Oasis configuration file, which specifies which fields get sent where
- Grid files: NetCDF files that tell Oasis what the UM grid looks like

In addition coupling to new component models will require some editing of the UM run scripts, particularily OASIS3_ctl and OASIS_conf to set up the namcouple process count and the mpirun MPMD options.

UM Coupling Code


The UM code to interact with Oasis is located under src/control/coupling. Control flow looks like:

um_shell():
    oasis3_atmos_init()       # Start Oasis
    oasis_read_translist()    # Configure coupled fields
    u_model():
        initial():
            oasis3_grid()         # Setup oasis grids & decomposition
            oasis_inita2o():      # Setup pointers to fields in STASH
                oasis_process_translist()
                oasis_point_translist()
        while t < tend:         # Main timestep
            oasis_geto2a()        # Get remote fields at time t from Oasis
            oasis_puta2o()        # Send atmosphere fields at time t to Oasis
            atm_step()
            oasis_updatecpl()     # Save updated atmosphere fields to send at time t+1
            dumpctl()
    prism_terminate_proto()   # Oasis cleanup call

The fields that the UM can send/recieve with Oasis are hardcoded in the coupling code, they correspond to (multiple IDs represent different ice categories):

Send:

Output fields come from the STASH system under processing TAG 10

Field            | ID                 | STASH
---              | ---                | ---
Heat Flux        | 1                  |
 - Longwave Rad  |                    | 2203
 - Sensible Heat |                    | 3228
Blue Rad         | 2                  | 1204 (1260)
Solar Rad        | 54                 | 1203
10m Wind         | 4                  | 3230
Total Rain       | 5                  |
 - LS Rain       |                    | 4203
 - Conv Rain     |                    | 5205
Total Snow       | 6                  |
 - LS Snow       |                    | 4204
 - Conv Snow     |                    | 5206
River Outflow    | 3                  | 26004
Surface Evap     | 7                  | 3232
TOPMELTM (1:5)   | 8, 9, 10, 11, 12   | 3257
FCONDTOPM (1:5)  | 13, 14, 15, 16, 17 | 3256 (3510)
Sublim (1:5)     | 18, 19, 20, 21, 22 | 3231 (3353, 3509)
Tau X            | 23                 | 3219 (3392)
Tau Y            | 24                 | 3220 (3394)

Recieve:

Recieved fields get put into prognostic arrays in `atm_fields_mod.f90`. The fields are processed after the recieve and may contribute to multiple prognostics, check `oasis3_geto2a.F90` for full details.

Field               | ID                 | Prognostic Field
---                 | ---                | ---
ocn_sst             | 25                 | tstar_sea
ocn_freezen(1:5)    | 26, 27, 28, 29, 30 | ice_fract_cat
ocn_snowthickn(1:5) | 31, 32, 33, 34, 35 | snodep_sea_cat
ocn_hicen(1:5)      | 36, 37, 38, 39, 40 | ice_thick_cat
ocn_icetn(1:5)      | 41, 42, 43, 44, 45 | ti_cat
ocn_icekn(1:5)      | 46, 47, 48, 49, 50 | ice_k_cat
ocn_u               | 51                 | u_sea
ocn_v               | 52                 | v_sea

Coupling Macro


The coupling macro is an addition to the STASHC namelist file that sets up processing for fields sent to the coupler. The only difference from the regular STASH namelist generated by the UMUI is that all the fields in the macro have `IUSE` set to a special value to signify the coupler.

The easiest way to generate this macro is to copy your UMUI job then set up STASH to generate your desired coupling fields (e.g. outputting 3-hour mean values if your coupling frequency is 3-hourly). You can do a test run with coupling disabled & STASH writing to a file to make sure the output is correct.

Once you're satisfied with the STASH fields create a new 'Couple' usage profile, setting it to 'Dump store with user specified TAG' and setting the TAG to 10. Add this usage profile to all of your STASH fields, then process the UMUI job. This will create a STASHC file under `~/umui_jobs/RUNID`. The coupling macro is a script that adds this file to the end of another job's STASHC, for instance:

#!/bin/bash
cat << EOF >> STASHC
### Start of coupling requests for ATMOS ###
 &STASHNUM NUM_REQ= 1, NUM_DOM=1,  NUM_TIM=1, NUM_USE=1 /
 
 &STREQ IMOD= 1, ISEC=2, ITEM=203, IDOM=1, ITIM=1, IUSE=1 /
 
 &TIME NAME="TDAYMN", ITYP=3
 INTV=1,UNT1="DA",IOFF=0,ISAM=1,UNT2="T ",
 IOPT=1,
 ISTR=1,IEND=-1,IFRE=1,UNT3="DA",
 /
 &DOMAIN NAME="DIAG", IOPL=5
 PLT=0,
 IOPA=1,
 IMSK=1, IMN=0, IWT=0,
 TS="N",TSNUM=0,
 /
 &USE NAME="Couple", LOCN=1
 IUNT=10,
 /
EOF

Namcouple file


The format of the 'namcouple' config file is beyond the scope of this article. Documentation can be found in the Oasis user guide. Some pointers are:

- The UM expects to have the component ID 'ATM'
- Ordering of coupling calls is important to avoid deadlocks (e.g. both components waiting to recieve fields rather than one sending & one recieving)
- Oasis is very picky about the format of the namcouple file - fields have limited widths and Oasis will happily truncate numbers that go over them.
- The easiest way to debug strange behaviour is to run the model with a small number of processors under Totalview and follow the function calls

Configuring Fields


The UM selects what fields get sent to the coupler by reading annotations in the namcouple file. The run script `OASIS_fields` reads the namcouple file, finding lines that look like:

## TRANSDEF: mmmg nnnh i f

and converting them to a namelist to be read by `oasis_read_translist()`. As an example, the line:

## TRANSDEF: ATMU OCNU 2 23

tells the UM to send the field TAUX (field 23 from `oasis_atm_data_mod.F90`), from component 'ATM' (the UM) to component 'OCN', using the 'U' grid, as the second field sent by the UM to Oasis. It's important to specify the send order as otherwise Oasis can deadlock as one model waits to send field A while the is waiting to get field B.

Grid Files


Oasis needs to know what the model grids look like in order to correctly interpolate between different grids. While Oasis does have functions for writing out the grid files from within the model the UM doesn't use this, instead relying on you to manually set up the grid files.

The contents of the grid files are described in chapter 7 of the Oasis manual. The UM uses the grid names 'ATMT', 'ATMU', 'ATMV' for its theta, U and V grids. The grid layout is an Arakawa C grid, behaviour at the poles differs between the New Dynamics and ENDGAME cores:

New Dynamics:
t u t .. u    +90 lat
v   v ..
t u t .. u
v   v ..
..  ..
t u t .. u    -90 lat

ENDGAME:
v   v ..      +90 lat
t u t .. u
v   v ..
t u t .. u
..  ..
v   v ..      -90 lat