A meeting gathering wp3a (coupler) and wp2c/4a (I/O) partners was organised as one of the Topic Sessions during the SSW meeting in Hamburg on February,21, 2002. The objective was to discuss the issue of a common  Model Interface Library for I/O and coupling data, also called "common Data Management Shell (DMS)". People who participated in the discussions are: from wp3a, Jean Latour (Fujitsu/FECIT), Rene Redler (NEC-CCRL), Sophie Valcke (CERFACS); from wp2c/4a, Jan Polcher (IPSL) and Mick Carter (Hadley Centre); and Nils Wedi from ECMWF.

Summary:

A list of common characteristics and a list of differences between I/O and coupling data were first established. Then, the classes of routines required for both types of data in the Model Interface Library were discussed. Finally, implementation details were discussed on how to group variables to send or receive at once, how to generate, for each component model, the list of available and requested data, and on how to ensure use of integers (and not character strings) as arguments for the Model Interface sending and receiving instructions.
In conclusion, it was decided that the I/O and coupler workpackage partners will first define separately their respective specifications for such a Model Interface Library. They will meet again in Toulouse on April 19th, 2002 to see how/if a common Model Interface Library could be established.

1- What do I/O and coupling data have in common

The following list of characteristics shared by both I/O and coupling data was established:

• Data requested or made available by a model. Some data may be I/O and coupling data at the same time.
• For available data, not all will be effectively delivered by the model. For each particular simulation, the user has to activate some of them externally through a configuration file created with a GUI or any other mean.
• Data for which the "end-point data exchange" principle is applicable.The model itself does not know where the data comes from or where  they go to. The source/target models (for coupling data) or the source/target files (for I/O data) are defined externally by the user for each particular simulation.
• Data for which local transformations may be required. These transformations are prescribed externally by the user for each particular simulation. By local, we mean transformation which do not require information from neighboring points or from another model. Thus they can be done locally without geographical knowledge and with any domain decomposition.
• Data for which non-local transformation may be required. By non-local we mean transformation which require information from neighboring points or from another model.
• Some data required from another model in the coupled mode, may in fact be forcing data read directly from files. In that case,  the coupling library is faced with the same parallel I/O and metadata interpretation difficulties.
• Same classes of routines required for the Model Interface library (see below)

2- What are the differences between I/O and coupling data

The following list of differences was established:

• List of coupling fields is generaly smaller that the list of diagnostic output .

• One PRISM objective is to define a standard physical coupling interface between any two components, i.e. the nature of the coupling fields exchanged; standardisation of the nature of the diagnostic output will be much more limited.

• Some local transformations required for I/O may not be required for coupling, and vice-versa.

 
• I/O may require more or different metadata to be transferred from the model.

 
• I/O data needs some mechanism to translate metadata given by the model into CF-style description. This is required for coupling data only if the coupler is asked to generate its own coupling diagnostics files.

3-Classes of routines required in the Model Interface library

A first list of classes of routines, required both for I/O and coupling data, in the Model Interface Library was discussed. These classes  are:

1) Initialisation

2) Declaration of data:

For each data, the user's choices indicated in the configuration file are analysed to identify if the data is to be exchanged with another model (coupling data) and/or retrieved or written to a file (I/O data). If the user changes the configuration file, no recompilation of the codes is required as the configuration file is read at run time. The declaration of data may also include the definition of  the relevant metadata  identificators (see below)


3) Definition of the metadata associated with the data

The metadata, i.e. the description of the data, include for example units, grid co-ordinates and mask, partitioning, etc. For each coupling data, the corresponding metadata are known in the model and have to be transferred to the Model Interface library with the appropriate call. An identificator could be defined for each type of metadata defined. During the simulation, the metadata will be associated to the corresponding data thanks to this identificator. The metadata could also be used to check that the configuration file corresponds to the model and that variables exchanged between models are in agreement with the requests of the user.


4) Sending and receiving of the data:

The first action below the sending and receiving instructions is to identify the nature of the data (I/O and/or coupling) and the local transformations prescribed by the user and recorded in the declaration phase. If the data is I/O and coupling data, and if some transformations are required in both cases, these common transformations should be performed in the second phase. Then, in a third phase, the coupling and/or I/O specific actions could be performed under if-endif conditions:
if (coupling data) then
-> keep on with coupling actions
endif
if (I/O data) then
 -> keep on with I/O actions
endif


5) Termination

4- Discussion on how to group variables to send or receive at once

In the wp3a first suggestion of possible routines for the coupling Model  Interface library (see http://www.ccrl-nece.de/~redler/MTCI/), it was suggested that a specific instruction could be used in the model to send and receive grouped variables at once (PRISM_Update). It appears that this type of instruction could help reducing the memory requirement. The discussion came to the conclusion that this grouping should not be performed in the geophysical models as the optimal choice does not only depend on the sending model but also on the receiving side. It is only in the Model Interface library that the knowledge on the receiving model, will be available  ; therefore, it is in the Model Interface library that the grouping of variables should be decided and performed. This is already done by most I/O libraries (management of the write buffer) and thus allows to solve this problem without needing the intervention of the developer of the geophysical model. It is suggested that such an approach be also used for the coupler. It has to be verified with other wp3a developers not present at the meeting if this approach would be satisfying regarding memory and performance.
 

5- Discussion on how to generate the list of available and requested data

The principle of end-point data exchange supposes that a model performing a sending instruction in fact offers the data but does not know where it will go to, and that a model performing a receiving instruction in fact requests the data but does not know where the data will come from. Whether or not the sending and receiving instructions will effectively be fulfilled in one particular simulation must be decided by the user externally. The user also has to perform the matching between the different sending and receiving instructions, i.e. define source/target model (for coupling data) or the source/target file (for I/O data). This can be done through an ASCII configuration file generated through a GUI or any other appropriate mean. To make the appropriate choices and matchings, the user has to know the list of all data requested or made available by each component model, which we will call  the model "input and output option file". The following ways to proceed are possible:

• The model input and output option file is established by the model administrator and given with the model code and can be accessed by the user through the UI. The list could be generated:
• by hand
• by using a parsing tool which analyses the sending and receiving instructions implemented in the code. This would be easier for the model administrator but implies some coding restrictions on how the sending and receiving instructions are implemented in the codes.
• by using a parsing tool which analyses some pre-defined comments in the code. This is more flexible regarding the implementation of the sending and receiving instructions but implies that some coding norms on how to write these comments are followed in the codes and adds the possibility of incoherence between the comments and the sending and receiving instructions.
The model input and output option file is kept with the model library so that a coupled model can be built without reparsing the code at each time and in case the source code is not readily available. This raises the requirement to check the coherence between the configuration file (that the user will write based on the different model option files) and the models. The metadata of the variables could be used for that purpose at run-time by the model interface library.
 
• The model input and output option file is established by the user through the UI, when he assembles one particular coupled model, by hand, or by using one of the parsing tool described above. This reduces the possibility of incoherence between the configuration file and the models but supposes that the user has access to all the code sources through the UI at assembling time.

6- Discussion on the sending and receiving instruction arguments
 

Different approaches can be used to identify coupling or I/O data in the sending and receiving instructions and activate them in the input and output configuration file. We will call "keyword" the data identificator, whether it is a string or an integer, and we will refer to the sending/receiving instructions as the PRISM_Send/PRISM_Recv.
For efficiency reasons, it is advisable to use integers keywords to identify the variables in the model and in the Model Interface library; we discuss here the current practice and other possible options.

• Character string keywords (OASIS and IOIPSL approach):

In each model, the data is identified by a character string keyword (cl_key in the example below). For coupling data exchanged between two models, the keywords may be different in the different models.
The activation and the matching is performed by the user by indicating the two keywords on the same line in the configuration file.
Each character keyword  is associated to an integer below an initial declaration call (see 2 of section 3-); the integer is identified and used right below the PRISM_Send or PRISM_Recv instructions.

------------------------------
program model1
character (len=8) :: cl_key
. . .
cl_key='mod1_SST'
call PRISM_Send(cl_key,time,array1,ierr)
. . .
cl_key='mod1_flx'
call PRISM_Recv(cl_key,time,array2,ierr)
. . .
end program model1

------------------------------
program model2
character (len=8) :: cl_key
. . .
cl_key='mod2_flx'
call PRISM_Send(cl_key,time,array1,ierr)
. . .
cl_key='mod2_SST'
call PRISM_Recv(cl_key,time,array2,ierr)
. . .
end program model2

------------------------------
In the input and output configuration file:
. . .
# Choice of coupling fields

# Sea Surface temperature
mod1_SST  mod2_SST . . .

# Solar flux
mod2_flx  mod1_flx . . .
. . .
 

• Standard PRISM pre-defined integer parameter keywords:

All data are associated to a PRISM standard integer parameter, declared in a standard PRISM module (mod_PRISM_param in the example below). These standard integer parameters have to be used in the codes and in the input and output configuration file.
Integers above a certain value could be reserved for non-standard fields; the model developer could either use his integer value directly in the code (as in the example below) or edit the standard PRISM module to declare an additional integer parameter and use this integer parameter in the code.
For standard PRISM coupling data, the matching is automatic, as standard integer parameters have to be used in all PRISM model codes. For non-standard coupling data, the developer has to use the same integer or integer parameter in the two models exchanging the data. The activation is performed by the user by indicating the integer parameter or integer in the configuration file.

------------------------------
module mod_PRISM_param
integer, parameter  :: ip_SST = 1       ! for Sea Surface Temperature
integer, parameter  :: ip_solflx = 2    ! for solar heat flux
. . .

------------------------------
program model1
use mod_PRISM_param
. . .
call PRISM_Send(ip_SST,time,array1,ierr)
call PRISM_Send(1001,time,array2,ierr)
. . .
call PRISM_Recv(ip_solflx,time,array3,ierr)
. . .
end program model1

------------------------------
program model2
use mod_PRISM_param
. . .
call PRISM_Send(ip_solflx,time,array1,ierr)
. . .
call PRISM_Recv(ip_SST,time,array2,ierr)
call PRISM_Recv(1001,time,array3, ierr
. . .
end program model2

------------------------------
In the input and output configuration file:

. . .
# Choice of coupling fields

# Sea Surface temperature
ip_SST . . .

# Solar flux
ip_solflx . . .

#Non-PRISM standard field
1001 . . .

. . .
------------------------------
 

• Pre-processed string keywords, option 1:

 
• The keywords used in the code by the model developer and in the configuration file by the user are character strings starting by a pre-defined character (such as $). The possible mechanisms to establish each model input and output option file are the same as in paragraph 5.
• After the constitution of the input and output configuration file, the user activates some pre-processing mechanism which replaces, in all the codes implied in the coupling and in the configuration file, all keywords by an appropriate integer value or integer parameter. The compilation of the codes is done afterwards.


Compared to the previous options, this one has the advantage to avoid all character string manipulation at run-time and to avoid the use of any pre-defined standard PRISM integer parameters. However, it has the strong disadvantage to impose the compilation of the code by the user at assembling time, and to impose coding restrictions in the codes. Furthermore, it would not work if the same keywords are used for different fields in the different codes.
 

• Pre-processed string keywords, option 2 :

• The keywords used in the code by the model developer are character strings starting by a pre-defined character (such as $). The model administrator activates some pre-processing mechanism which replaces in the codes all keywords by an appropriate integer parameter.
• The model administrator is also responsible for generation of the model input and output option file with one of the possible mechanisms presented in paragraph 5.
• At assembling time, the user has the menu of integer parameters among which he can choose to write his input and output configuration file.


The problem here comes from the fact that the list of integer parameters are generated separately for each code, which implies that the same integer value can be used for two different fields. This means that the coupler should be able to generate one unique number for each field based on the value of the integer parameter and on, for example, an integer related to the model producing the field. As for the previous option, this one imposes coding restriction in the codes.
 

• Run time configured integer keywords:

• The model developer would use integer keys to identify variables send to the data management shell. Globaly or localy declared integer variables would be used for this.
• The initialization of these variables would be left to the Model Interface library which would provide a function to do so. Thus using the configuration file a coherent numbering scheme could be established before run-time for the entire coupled model.
Unlike the other options based on integer keywords, the coupled model could be built using only libraries and without access to the source code. The disadvantage is that the model could have to call a "foreign" subroutine to initialize some of it's own variables.