Compiling and running TOYOA4

TOYOA4, which sources, input files, data and running script are in directory oasis4/examples/toyoa4, is a toy coupled model providing a practical example of the coupling and I/O exchanges that can occur in a real coupled model. It is a `toy' coupled model in the sense that the components atmoa4, oceoa4, and lanoa4 do not contain any real physics or dynamics but their coupling and I/O exchanges are realistic (i.e. the grids and the coupling fields have realistic dimensions and the exchanges and transformations performed by OASIS4 are realistic). NetCDF data files needed for running TOYOA4 are found in directory /data. The description and configuration XML files are found in directory /input. Note that the toy model available in oasis4/examples/tutorial1 reproduces ping-pong exchanges between model1 and model2 (see the readme_tutorial1.pdf therein); this is probably the simplest toy model available to start learning about OASIS4.

Compiling is done with the Makefile in this directory. Running is done by adapting the ``User's section'' of the running script oasis4/util/runscripts/run_examples_all and by invoking it from the oasis4/examples/toyoa4 directory (i.e. with ../../util/runscripts/run_examples_all). The working directory rundir defined in run_examples_all is created; all files and executables needed for running are first copied into this working directory and the TOYOA4 coupled model is executed.

Figure 7.1: TOYOA4 toy coupled model coupling and I/O configuration

Figure 7.1 illustrates the coupling and I/O exchanges occuring between the 3 toy component models atmoa4, oceoa4, and lanoa4.

Both atmoa4 and lanoa4 work on a T31 Gaussian grid, but their parallel partitioning is a function of their number of processes which can be different. The third model, oceoa4 uses a real ocean model stretched and rotated grid with spherical polar coordinates of 182 x 149 grid points.

All coupling and I/O fields are scalar fields. The model atmoa4 declares 1 input field SISUTESU, and 4 output field CONSFTOT, COSENHFL, COWATFLU, ATWINSTS as is listed in its PMIOD file atmoa4_atmos_pmiod.xml. The model lanoa4 declares 2 input fields LAWATFLX and SOSENHFL, and 1 output field LARUNOFF as is listed in its PMIOD file lanoa4_land_pmiod.xml. The model oceoa4 declares 4 input fields SONSHLDO, SOWAFLDO, SORUNOFF and OCWINSTS, and 1 output field SOSSTSST.

At run-time, the OASIS4 Driver/Transformer and the PSMILe model interface linked to the component models act according to the specifications written by the user in the configuration SMIOC XML files.

In the atmoa4 SMIOC file atmoa4_atmos_smioc.xml, it is specified that ATWINSTS will be sent to oceoa4, COSENHFL to lanoa4, COWATFLU both to oceoa4 and lanoa4, while CONSFTOT is not sent at all; it is also specified that SISUTESU will come from oceoa4. The lanoa4 SMIOC file
lanoa4_land_smioc.xml specifies that LARUNOFF will both go to oceoa4 and be written to a file LARUNOFF.nc and that LAWATFLX and SOSENHFL will be received from atmoa4. Finally, in the oceoa4 SMIOC file oceoa4_ocean_smioc.xml, it is specified that OCWINSTS and SOWAFLDO will be received from atmoa4, SORUNOFF from lanoa4, while SONSHLDO will be read from a file SONSHLDO.nc; SOSSTSST will be sent to atmoa4.

Different operations are performed by the PSMILe model interface on the coupling or I/O fields such as statistics, time accumulation time averaging, as specified in the SMIOC files. The exchanges of the coupling fields between atmoa4 and lanoa4 (and vice-versa) are direct, involving possibly some repartitioning if their parallel partitioning are different. As atmoa4 and oceoa4 do not have the same grid, their exchanges of coupling fields go through the Transformer (not illustrated on figure 7.1) where a linear interpolation is performed. The different coupling and I/O periods are also specified in the different SMIOC files.

TOYOA4 also illustrates the use of a coupling restart file for field COSENHFL for which a positive lag of 1 is defined. The first time TOYOA4 is run, the variable run should be set to start in run_examples_all. In that case, the file scc.xml.start is copied in scc.xml and used, TOYOA4 is run for 3 days starting January $1^{st}$ 2000, and the first field COSENHFL received by lanoa4 comes from the restart file COSENHFL_atmoa4_atmos_rst.2000-01-01T00_00_00.nc; at the end of the run, the restart file for the next run, COSENHFL_atmoa4_atmos_rst.2000-01-04T00_00_00.nc, is created by the last call to prism_put for COSENHFL in atmoa4. A next run of 3 days starting January $4^{th}$ 2000 can then be run by changing run=restart in run_example_all and running it again.

A successfull execution of TOYOA4 (with run set to start in run_examples_all) produces files that can be compared to results in oasis4/examples/toyoa4/outdata. In particular, files containing standard output from the different components (e.g. atmoa4.0, lanoa4.0, oceoa4.0) should end with lines like

  -------------------------------------
  --- Note: MPI_Finalize was called ---
  ---       from prism_terminate.   ---
  -------------------------------------