PSMILe interface proposal

-in green: IPSL last comments
-in red: WP3A new comments or WP3a old comments that still need to be discussed,
-in orange: modifications that wp3a/wp4a agreed on.
-in black and small characters: WP3a old comments on issues that are solved
-in magenta and small character: text that wp3a/wp4a agreed that should be removed
 

Using functions :

We wish to use integer functions which will return error codes. The values which need to be returned will be in/out arguments of the function. This choice is guided by the fact that we wish to have in the PSMILe a full error handling capability with the possibility for the model which uses the PSMILe to react to any miss-functioning. A function will be provided to translate the error code into a message which can be understood by the user !

>WP3a: We would prefer to use routines instead of functions. H. Ritzdorf has had a particular bad experience with functions in interface: during the first phase of the MPI1 definition, people tried to follow the "function" approach, instead of providing a library of fortran subroutines.This c-like approach was not accepted by the Fortran programmer community and was therefore rejected. For this reason, we would prefer the "routine" approach even if there is no technical advantage to it.

>IPSL : Is fine with us and we trust those with more experience.

>WP3a: OK routines will be used

Using interfaces :

In order to ensure an ease of use all groups of functions, i.e. providing the same functionality, should have a generic name by which they can be called. This feature of modern programing languages facilitates the use of a library and increases it's acceptability by users.

>WP3a: OK

We will also use optional arguments. They are indicated in the interfaces presented below by squared brackets.

>WP3a: We do not favour the use of optional arguments. The main reasons for this are:

-we should, at a later stage, be able to support C with our interface as well.

-we should try to minimize to keep the number of (possible) actions below a call to a specific subroutine as small as possible and to confront a user of the library with as little complexity as possible.

-wp2b (coding rules) recommend NOT to use optional argument in interfaces (internal use within PSMILe would be OK) (Luis Kornblueh personal communication).

-we still are of the opinion  that the parameter list for each of the calls should be as short as possible, and that a higher number of routines each one having a shorter list of arguments is better.
>IPSL : OK it is true that it is very F90 trick which takes some time to get used to.
>WP3a: OK, we conclude that optional argument will not be used.

Naming convention :

The naming convention for functions will split the name in a number of items separated by underscores. The items will have the following order :

name of library, here it will be PSMILe.
>WP3a: We propose PRISM_ for routines used by the developer in the model code, and we propose to keep PSMILe_ for routines internal to the PSMILe.
>IPSL : We still prefer the PSMILe name because PRISM is the name of a project while PSMILe includes some information on what the library is supposed to achieve. We let you decide.
>WP3a: PRISM_ is still our prefered choice for interface routines, and PSMILE_ should be used for internal routines and include files.

name describing the action.

qualifiers for the action (The qualifiers will also be separated by underscores and go from the more general to the more specific.).
Ideally with the use of interfaces we should be able to do with with only three components for each function name. Example can be found in the list of functions below.
>WP3a: OK

Handling errors :

Still fuzzy ... The library should not stop on an error. It should minimize the damage and report an error code. But still, after a number of errors we should go into a panic mode in which we would print all we know and stop everything. This is because we have to assume that the model calling the PSMILe did not do the error check and thus did not stop the carnage !

>WP3a: Some errors should be fatal in any case. Above a certain number non-fatal errors the code will automatically  abort; the number is a parameter specified by the user in the SCC.

>IPSL : OK

Variable types :

All names should be strings while error codes or IDs for variables and axes should be integers. For the variables we should probably not only allow for real values but also integers.

>WP3a: OK

Some efficiency considerations :

Not all elements of the PSMILe design will need to be equally efficient from a computational point of view. The diagram of the PSMILe, the details of which is explained below, has elements which will be used very often while other will only get used once.

 

>WP3a: a parameter defined by the user in the SCC should be available to turn off non essential functionalities, like coherence checks, for operational runs.

>IPSL : Coherence checks will be done during the initialization phase and thus should be done in all cases and there should be no possibility to turn this off. If we should one day require coherence checks during the time stepping then obviously the user should be able to switch it off.

>WP3A: We still think that it should be possible to turn off coherence checks. For example, if you run a simulation of 1000 years per chuncks of 30 days (you may have to do this to fit in an appropriate batch queue). The initialization phase will be performed at the beginning of each 30-day run but there is no need to perform all the coherence checks everytime!

The transformation library, the data management, the Input/Output and coupling will perform some demanding computations. These should thus be optimized and the management overhead should be as small as possible.