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

6.1 Get persistent variables

• PRISM_get_persist

• PRISM_def_startdate
• PRISM_calc_newdate
• PRISM_calc_nbtstp

• PRISM_query_var

• PRISM_error

• PRISM_timestamp
• PRISM_restartsaved
• PRISM_message

6.1 Get persistent variables

Name :

PSMILe_get_persist(key_word, units, values)

PRISM_get_persist(keyword, units, value, ierror)

>Sophie 26/07/02: Responsible: IPSL

Description :

This function allows the user to retrieve a persistent variable from the SMIOC. This variable can be of any type (Integer, float, string, boolean) and rank (scalar or vector).

A flow diagram for the PSMILe_get_persist function

Arguments :

key_word (IN) : This keyword identifies the variable in the SMIOC and matches the name of the persistent variable.

>WP3a: OK

units (IN) : The units here allow for a coherence check of the requested variable.

>WP3a: This still needs discussion

1) For input parameters that are not "universal" parameters:

The required units and default value will be indicated by the developer in the PMIOD and if the user wants to change the value of this parameter in the SMIOC, then he should sure that he keeps the required units. In that case, the units could still be kept as an [IN] argument and the PSMILe would only verify that these units indicated as [IN] argument are the same than the units indicated in the SMIOC.
2) For "universal" input parameters:
Shouldn't the units of universal parameters be imposed/standardised once for all? In that case, the units could still be kept as [IN] argument, indicating in fact the units that the model consider as the standard units. The PSMILe would verify that these are really the standard units indicated in the SMIOC or SCC. Then the model would have to do always the same conversion if it does not use this parameter with the standard units.

>IPSL : As we said above we need a second information to verify the identification of the variable. If there is a unit mismatch then it could either be that the PSMILe mixed up some variables or the user goofed. If we do not have the information we can not warn the user and ask him to check. Keep in mind that it can also be problems in the PSMILe, especially at the beginning, thus the redundancy is also for us !

>WP3a: OK let's keep the units as argument, but we still need to discuss how they will be used in the PSMILe (only check of coherence or not?)

values (OUT) : The value returned by the PSMILe.

>WP3a: OK
>WP3a: We had PRISM_Inquire_Integer (gloParamId, int_value, ierror) and PRISM_Inquire_Real (gloParamId, real_value, ierror). We suggest:
Name:

Responsible: IPSL

IPSL : OK

---

6.2 Get time coordinate information (calendar tool):

These functions will allow the model to count it's own time in accordance with the PSMILe. The entire interface is based on the assumption that the model provides real time stamps with the data and not relative times. This allows the model to change it's time step at will.
>WP3a: OK

The time interfaces here are only some standards to access the calendar library which will be chosen by PRISM. i.e. the PSMILe will not have it's own calendar, it will just use the standard chosen for PRISM.
>WP3a: OK

Most of the information regarding the calendar and the start date will be provided to the model through the PSMILe as it needs to be coordinated between the various models.
>WP3a: OK

Still we insist that the model confirms this information by using the functions provided here so that we can be sure that it will be used.

As we have not yet decided on the time representation we wish to choose some of the aspects of this interface are still fuzzy. In the end we might allow different date representations.

Name :
PSMILe_def_cal(calendar_name)
Description :

Defines the calendar to be used. It allows the model to impose it's calendar if there is no other constraint. In a coupled mode obviously the constraint will come from the driver or any other higher authority.

The problem here is that some models may not be able to use all models. Thus we might instead of a name provide a list of calendars supported by the models. This list would be in order of preference.

A flow diagram for the PSMILe_def_cal function
Arguments :
calendar_name (IN) : Name of the calendar to be used.
>WP3a: We do not agree with this routine. The calendar will be externally defined in the SCC and a PRISM model will have to obtain the calendar by calling a PRISM_get_persist('calendar', value). If the model is not written to run with that calendar then it should abort with an error message.
>IPSL : OK

 
Name :
PSMILe_def_startdate(start_date, axe_type)
>Sophie 26/07/02: Responsible: IPSL


Description :

This function allows the user to set the start date of the simulation. It has to be kept in mind that this is not the date of the first time step but the date of the beginning of the interval covered by the first time step.


This distinction is very important and will be used for regular time axes to know which period is covered by the data sent to the PSMILe. It is the assumption of a regular axis which allows the PSMILe to compute the extra information needed. For irregular axes some extra information will need to be provided with the put and get functions.
This figure should help understand why this distinction is needed.
A flow diagram for the PSMILe_def_startdate function

Arguments :
start_date (IN) : This is the date of the start of the simulation and not the time of the first time step.
axe_type (IN) : Gives the type of time axis used. For the moment the only choices seen are regular and irregular axes.

>WP3a: We do not really understand this function, but the conclusion on the 21st was that we could forget about it !?

>IPSL : No we need the subroutine but there might be a case for turning it around : PRISM_get_startdate. That is the model asks for the starting date of the simulation which the PSMILe will get from the SMIOC. I would not favor to use the general _get_persist for this (as you suggested above) as these are key words for both the models and the PSMILe. Thus the tag <calendar> or <start_date> should not be treated just as any persistent variable. Else we have no way of knowing what has happened if some stupid user (French for instance !) decided to write ''calendrier'' instead of 'calendar'.

>WP3a: ??? The initial date of the run should be obtained from the SCC when there is more than one component (as they certainly need the same initial date) or from the SMIOC when there is  only one component (there is no SCC in that case). The way how to get it (PRISM_get_startdate or PRISM_get_persist with a keyword 'calendar') needs to be rediscussed. I would not say that the developers are so stupid that we cannot count on them using the right (english) keyword, but that is my personal opinion!

Name:

PSMILe_calc_newtime(date, increment)

PRISM_calc_newdate(date, increment, ierror).

Responsible: IPSL

Description :

Add a number of seconds toi the date in order to get the new date. This routine only makes sense for complex representations of the dates.

Arguments:

date (IN/OUT) : Date to be incremented

increment (IN) : The time increment in seconds

>WP3a: OK; however, we would propose

Name:

PRISM_calc_newdate(date, increment, ierror).

Responsible: IPSL

IPSL : OK

>Sophie 24/07/02: I think a routine PRISM_calc_newdate(datein, increment, dateout, ierror), with datein being [IN] and date out being [OUT] would be more general.

>Sophie 24/07/02: We may need also

• PRISM_get_numbercouplingdates (nbr_cpldates, ierror)
Returns the number of coupling dates for the run; this can be calculated based on coupling information in SCC
• PRISM_get_couplingdates (coupling_dates, ierror)
Returns coupling_dates will be a vector of integers giving all the coupling dates expressed seconds-since-start_date_of_run
• PRISM_calc_nextcouplingdate(actual_date, coupling_dates, nbr_cpldates, stop_date, ierror)
This routine is part of the calendar tool and calculates the next coupling date, stop_date, based on the actual date, actual_date, and all the coupling dates, coupling_dates.

 

Name :

PSMILe_calc_nbtstp(start_date, end_date, time_step_length, nb_timesteps)

PRISM_calc_nbtstp(start_date, end_date, time_step_length, nb_timesteps, ierror)

Responsible: IPSL

Description :

This function computes for the model the number of time steps needed to go from the start date to the end date given one calendar.

Arguments :

start_data (IN) : Starting date.

end_date (IN) : End date.

time_step_length (IN) : Length of time step the model wishes to use.

nb_timesteps (OUT) : Number of time steps to be computed in order to go from start date to the end date with steps of a given length.

>WP3a: OK; e.g. for size of arrays in dynamic allocations for diagnostic purposes? We propose

Name:

PRISM_calc_nbtstp(start_date, end_date, time_step_length, nb_timesteps, ierror).

Responsible: IPSL

---

6.3 Get transient variable information:

Name :

PSMILe_query_var(varId, date, status)

PRISM_query_var(var_id, date, status, ierror)

Responsible: NEC-CCRLE ??

Description :

This function allows to determine the status of the variable. This function is needed to allow the model to decide if the variable needs to be computed or not or if it can expect to receive it from the PSMILe.

A flow diagram for the PSMILe_query_var function

Arguments :

varId (IN) : ID of variable to be queried.

date (IN) : current date.

status (OUT) : This should be a code table which includes the following possibilities : required now, never required, required later, never provided, can be provided now, can be provided but later.

-varId (IN) : ID of variable to be queried.

-date (IN) : current date (put 0 if the test is for EVER required/provided)

-status (OUT) : This should be a code table which includes the following possibilities : required (at that date or EVER), provided (at that date or EVER)

>WP3a: We had

- PRISM_QuerySend (handleId, absoluteTime, ierror) to check if an output variable was requested at that particular aboluteTime, and

- PRISM_QuerySendVar(handleId, ierror) to check if an output variable was ever requested.

For variables required by the component, as a simple test on the return code of the PRISM_Get for that date can be done; however, it could be usefull to test, at the beginning of the code for example, if that variable will EVER be provided by an external component or file. For variables provided by the model, it could be usefull to test if the variable for that date will be requested (e.g. to avoid extra computation if it is not needed); it can also be usefull to test if that variable will EVER be requested. The simplest solution is probably to have only one call as proposed here. If the developer wants to test if a variable will EVER be required/provided, he just puts date=0.

Therefore, we propose:

Name :

PRISM_query_var(var_id, date, status, ierror)

Arguments:
varId (IN) : ID of variable to be queried.
date (IN) : current date (put 0 if the test is for EVER required/provided)
status (OUT) : This should be a code table which includes the following possibilities : required (at that date or EVER), provided (at that date or EVER)

6.4 Get error code transcription:

Name :

PSMILe_errmsg(error_code, error_message)

Name:

PRISM_error(error_code, error_message, ierror)

Description :

Function which return the error message corresponding to an error code returned by any function of this library.

A flow diagram for the PSMILe_errmsg function

Arguments :

error_code (IN) : The error code provided by another function of the library

error_message (OUT) : The string explaining the error which has occurred.

>WP3a: OK; We propose

Name :

PRISM_error(error_code, error_message, ierror)

>IPSL : OK

>WP3A: Responsible ??? <Rene> Should be joint work between IPSL and WP3a. I would prefer to skip the argument ierror here, since it does not make much sense to check an error of an error routine. If error_code is not defined, this

information will be put into the error_message like "Unkown Error Code".

---

6.5 Interact with the Driver

Name:

PRISM_timestamp ( wall_clock_time)
Responsible: CERFACS

Description:

Returns the wall clock time given by the driver (MPI routine return only local time).

 
Name:

PRISM_restartsaved ( date )
Responsible: CERFACS

Description:

Used by the model to notify the driver that it has saved a restart at date 'date'

Name:

PRISM_message ( char_string )
Responsible: CERFACS

Description:

Depending on a output level chosen by the user in the coupled configuration file calls to PRISM_Message implemented by the code developer are activated. This function transfers information on the state of the model to the driver where it is centralised.