Design the coupling/forcing interface

[timspainNERSC]

NextSIM_DG will need some way of ingesting data from external sources, either climatological data or by coupling to other models.

A common interface needs to be designed that will be implemented by classes providing this data via OASIS or similar coupling software.

• What fields are needed?
• How are the different implementations specified (ModuleLoader?)
• How closely do we tie the design to OASIS? What is the trade off between ease-of-use with OASIS and future generality?

[timspainNERSC]

• How does it deal with the shorter timestep of most atmospheric models?

[timspainNERSC]

The ExternalData class currently provides:

• air temperature
• dew point and/or water vapour mixing ratio
• sea level pressure
• snowfall
• inbound shortwave flux
• inbound longwave flux
• mixed layer depth.

The PrognosticData class provides:

• sea surface temperature
• sea surface salinity,
  but probably shouldn't. These values are prognostic in the NextSIM slab ocean.

An obvious absentee is:

• surface winds.

[timspainNERSC]

Old NextSIM defines the following fields as external_data:

• surface wind
• 2 m temperature
• water vapour mixing ratio
• atmospheric pressure
• incoming short-wave radiation
• incoming long-wave radiation (twice)
• total precipitation
• snowfall rate
• precipitation snow fraction
• 2 m dew point
• specific humidity of the air
• geostrophic ocean currents
• sea surface height
• sea surface temperature
• sea surface salinity
• mixed layer depth
• fraction of short-wave radiation absorbed by the mixed layer
• bathymetry.

[timspainNERSC]

More general design thoughts:

• The interface should be flexible enough to couple using OASIS or the American (CESM) coupling software.
• The code should be able to be built even if the OASIS headers are not present.
• How the partition logic of OASIS ends up accessing the ModelArray data may inform (me) how that data should be partitioned.
• A preprocessing, post restart file read step will probably be necessary. Can this be done within the nextsimdg binary, or will an independent process also need to read the restart file for the array sizes and shapes, do some processing and them start the nextsimdg and OASIS binaries?
  • If preprocessing is necessary, the same script could be the place to set the DG grid parameters and the MPI array partitioning.

One possible way of implementing the independence of the code to OASIS might be to compile the OASIS code to a dynamic library. This entirely separates the OASIS code from the core code base. A second, stub version of the library could be compiled for when OASIS is absent.

Since the model will have to be compiled at least on a per-machine basis (if not a per-user, per-machine) basis, then the selection between OASIS implementation and stub implementation can be done at compile time. The Module code could even be altered to include or exclude the OASIS implementation of the coupling modules. And similarly for any other libraries that might or might not be present.

[timspainNERSC]

Design by doing:
Write simple atmosphere and ocean "models" on the same grid as the 30x30 nextsim test. They provide the same data as used in that test, except the ocean responds to the simple presence/absence of ice.
Write sufficient interface to couple these together without hard-coding anything.
(Optional) throw it all out when you realize it doesn't work as hoped. Redo from Start.

[timspainNERSC]

1. Rename the AtmosphericState and OceanState update() functions so that one class can implement both.
2. Move the calls to these update*() functions from deep in the IceGrowth call tree to be the first thing that the PrognosticData update() function does.
3. Add a data export Component which can be implemented by the coupling class or by a dummy class.
4. What OASIS initialization needs to go where? The coupling class needs a configure() function or something like it.

[timspainNERSC]

A possible design:

If OASIS is selected in the configuration, then there is an OASIS class that performs all the necessary configuration. It also selects the OASIS implementations of IDataExport, IAtmosphereState and IOceanState and assigns them over any other configured classes for these modules.
Since the key functions are the get and put functions, which require very little state from the central OASIS class, there is little point in a single coupler class that does everything.
The OASIS implementations will include almost all their code within a conditional preprocessor directive. If OASIS is not compiled, the classes will be almost entirely non-functional but still selectable as implementations of IDataExport, IAtmosphereState and IOceanState. I really wouldn't recommend using them though.
Other future couplers would then consist their own implementations of the relevant functions along with any classes needed to set up and communicate with the external coupler program.

The Coupler class is the only one that CMake sees. The code within is included or not, based on preprocessor directives, allowing the inclusion of exclusion of the OASIS and any other coupler code. The actual code can be stored in individual coupler specific source files that are included as requested by the pre-processor.

In Model::configure() call Coupler::configure(). This (after the grid is set up from the restart file) uses the MPI information to configure Oasis and its grids. This information is then available for the OASIS implementation classes.

The OASIS implementations themselves will require selection in the configuration files as the implementations of the relevant interfaces. This allows coupling to only one of an atmosphere or ocean model. The OASIS configuration module should select the OASIS implementation of the DataExport class if at least one of the model coupling implementations are selected.

[timspainNERSC]

Resolving issue #154 will impact this issue.