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

• PRISM_def_var
• PRISM_def_restvar

It might be discussed if the long_name belongs into the declaration of the grids and the variables. If we include it we allow for a further test of coherence between the information in the SMIOC and the model. But it strongly limits the flexibility of the system as it will require the long_name to be exactly the same in the SMIOC and the code and thus the SMIOC/PMIOD can not be adapted to the local language and so on.
>WP3a: We are not in favour of including long_name as an argument (this is not knowledge of the code).

What should we do about undefined values ?

Name :

PSMILe_def_var( ) interface for :

PSMILE_def_var_byname (name, long_name, units, nb_grids, grid_ids, rank, size, [minimal_operation], varid)
PSMILE_def_var_byid (varid, name, long_name, units, nb_grids, grid_ids, rank, size, [minimal_operation])


>WP3a: We do not see the need to define a variable byid.

>IPSL : We agree with you but UKMO insisted to have the possibility of giving ID's to variables. This is for historcal reasons and does not do any harm in the interface !
>WP3a: Well, yes it harms the interface by adding one more routine, and it makes us develop and maintain two routines instead of one. Furthermore, I am a little bit worried if we have to take into account all historical reasons of all PRISM groups!!!

The interface is designed in such a way that the variable can be identified with it's description in the SMIOC and with sufficient redundancy so that coherence checks can be performed.
A flow diagram for the PSMILe_defvar function

Arguments :

name (IN) : In the "_byname" version of the subroutine this name will be used to identify this declaration with the entry in the SMIOC. In the "_byid" version it will be used for a coherence check.
>WP3a: 'name' is what makes the relation between the variable given or requested by the code and all user's instructions given in the SMIOC or SCC for one particular variable. So, even in the byid version, it will serve for much more than only coherence checks. (Note: this was equivalent to our 'dataId' or 'dataKeyword' in PRISM_DefineField)

varid (IN or OUT) : In the "_byid" version it will allow to link this declaration with the entry in the SMIOC. In the other case it is the output of the declaration and the ID (or handle) by with the variable will be recognized in the rest of the model.
>WP3a: As we do not see the need for a _byid function, we would say that varid is always OUT.

long_name (IN) : ?
>WP3a: we are not in favour of including long_name as an argument

units (IN) : Units of the variable, will be tested against the content of the SMIOC.
>WP3a: As above; as this is not a knowledge of the code, we would not put this as an argument but get this information in the SMIOC/SCC.
>IPSL : The situation is more complex than it looks here :For one we have in the model a variable and it's units (take evaporation in mm/dt, a very common unit for fluxes but which does not make any sense outside of an executing model as one also needs to know the time step.)
Then you have the model administrator who wishes to let the user only see the variable with a more physical set of units (here evaporation in mm/d). He thus needs to provide a minimal set of operations and the resulting units and variable description.
Finally you have the user who wishes to see another units because it corresponds better to his knowledge (that could be here mm/month for instance).
In the PMIOD one would only see the variable as it is intended for the user and in the SMIOC only what the user actually wants. Thus there is no redundancy between both information. We thus drop the information on the variable as it is inside the model and keep the PMIOD info in the interface. It is a complex issue but it is needed.
>WP3a: ??? Sophie: I certainly do not get this point. The variable will be always given to the PSMILe in the unit specified by the developer in the PMIOD. If the user wants the PSMILe to transform the variable into other units, he/she will have to specify the appropriate transformation in the SMIOC (or SCC if it is a coupling variable). I am not sure if IPSL supposes here any automatic conversion in the PSMILe but I would certainly leave them out, at least for the next 3 years of PRISM! However, I agree that the unit could be included just to check if they are the same as the one indicated in the PMIOD and SMIOC but I doubt it is really usefull...

 
nb_grids (IN) : Number of grids needed to describe the variable.
>WP3a: not necessary as we favour the approach of only one grid par variable.

grid_ids (IN) : vector of size nb_grids giving the IDs describing the grids on which to place this variable. For a 2D horizontal variable we will have one ID, for a 3D variable 2 IDs, and so on.


>WP3a: As we favour the approach of only one grid par variable, grid_id isonly one integer value

>IPSL : We do not think we can maintain 'one grid per variable' philosophy as it will generate too much grids. If you have an atmospheric model with a staggered grid in the horizontal and in the vertical then you have :
With grid combinations : 3 x 3Dgrids + 2 x 1Dgrids
One grid per variable : 6 x 3Dgrids
If you take more complex grids the difference becomes even greater. I think we will be drowned by the grids with this philosophy. Thus we would advocate for per variable combination of grids.
>WP3a: ??? Sophie: I tend to agree with Jan on that point.
<Rene> Here I follow Huberts argumentation: Below we have to rebuilt complete 3d grid for interpolation purposes. Therefore we would like to deal with one grid Id per grid.
Furthermore the distinction between horizontal and vertical grids as we have it right now would only work for level models. Sigma-coordinate models are not covered by this approach as well as isopycnic models.

Another remark: For coupling we clearly need the information about the location of the variable with respect to phi, lambda and z (or any other), while e.g. isopycnic coordinate models probably write out the field in their own coordinate system (phi, lambda, rho) plus information about the height of the isosurface.
 

rank (IN) : Number of dimensions of the variable as it will given to the PSMILe later on.


>WP3a: equivalent to our 'no_dims(1)' (note: the information contained in no_dims(2) -number of coupling fields, i.e. vector components or bundles, is missing here).

size (IN) : Vector of size rank giving the size of the variable in each dimension of the variable. We need to check here if it is consistent with the dimensions of the associated coordinates.
>WP3a: OK, but it is included in our field_shape (see below)

minimal_operation (IN) : Here we can specify a minimum set of operation which allow to project the model representation of the data onto the grid specified above. This would include scattering and gathering operations or if the components of a vector field is stored in the model in different arrays. In any case no operations which modify the values of variable should be allowed so that this set of minimum operations can be used for the variables in the restart file. These operations should not be specified in the SMIOC and this can be checked. It is important to list here the set of operations we allow, as said above it is really just a minimum.
> WP3a:??? Needs to be re-discussed as it complexifies the interface.
>IPSL : As I said above it is needed and does not complexify the interface very much. We do that already with IOIPSL and it would be a pity (well, unacceptable for IPSL !) to lose this facility with PSMILe.
>WP3a:??? Sophie: I still do not understand this point, and I still do not understand why these operations could not be specified in the SMIOC but I am certainly willing to learn about!

 
> WP3a: Therefore, we suggest for the transient variables declaration (Note: this may have to be adapted depending on how the grids, masks, ... are finally described.)
Name :PRISM_def_var(name, grid_id, mask_id, no_dims, field_shape, var_id, ierror)
Responsible: NEC-CCRLE
Argument not described above:
field_shape: array of integer describing the local partition of the field (with respect to the global grid?) (may be different from the local partition of the grid)


IPSL : field_shape sounds reasonable.

>WP3a: We now would have an extra argument comp_id:

Name:
PRISM_def_var (var_id, name, grid_id, mask_id, comp_id, var_nodims, var_actual_shape, var_type, ierror)
Responsible: NEC-CCRLE

 

var_id	[OUT]	return handle later use for calls to PRISM_Put/Get
name	[IN]	character identifier for the variable
grid_id	[IN]	value received from PRISM_def_grid
mask_id	[IN]	mask ID as given by PRISM_def_mask
comp_id	[IN]	component Id as provided by PRISM_init_comp
var_nodims	[IN]	var_nodims(1): the overall number of dimensions of array that is going to be transferred with var_id, i.e. same than grid_nodims except for bundle variables for which it is one more. var_nodims(2): number of bundles
var_actual_shape	[IN]	as for center_actual_shape but for the data arrays that are going to be transferred with PRISM_put or PRISM_get.
>Sophie 01/08: var_type	[IN]	type of array

Further remark for bundles: If an array is defined as a bundle only one handleId will be returned. This implies that the complete bundle will be transferred (send) to the remote component. The remote component has to be able to treat these bundles. Both components have to agree on the the precise sequence of the physical variables contained in this bundle.

There is no need to define the number of vector component as each component will be transferred through a separate call (the information on the number of vector components will come from the PMIOD/SMIOC).

>Sophie 24/07: Do we cover the cases of arrays having a time dimension  e.g array(i,j,k,t,n) (cf Navarra's mail 21 Jun 2002) ?
 

Name :

PSMILe_def_restvar()

Responsible: IPSL

Description : What should be different from defining a transient variable ?

Arguments :

IPSL : Should be the same as defining transient variables so that the user can use it for coupling as well or archive it to the I/O. We might have a special subroutine so that developer can indicate clearly that there are some restrictions to this variable when it is intended for the restart.

>WP3a: We leave it up to you to decide!