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

• PSMILe_def_horigrid
• PSMILe_def_vertgrid

• PRISM_def_grid
• PRISM_set_center_xx
• PRISM_set_xcorners_xx
• PRISM_set_mask
• PRISM_set_scalefactor
• PRISM_set_angle

>WP3a: Our comments on this section on the grid declaration will be pretty basic and we will make no proposition, as we feel we still need more (joint wp3a-wp4a) thinking on this delicate aspect of the PSMILe.
>IPSL : Yes we too. Alexandre needs to think it through as well for the PMIOD content.
>WP3A: We now make a more detailed proposition below.

The function for the definition of the grids are based on the assumption that all grids in geophysical models are decomposed in horizontal, vertical and time coordinates. This should be pretty general as in all cases we deal with stratified fluids and there is little reason to work with grids which are fully 3D.
>WP3a: We should allow,  in the description of a 3D grid, for the case in which the grid can be simply expressed as a 2D grid reproduced over a vertical axis. But even in this case, we think that only one grid Id should be given to identify this 3D grid.

Horizontal grids :

Name :

PSMILe_def_horigrid() interface for :

PSMILe_def_horigrid_ortho(name, long_name, size_inx, lon, lon_bounds, lon_units, size_iny, lat, lat_bounds, lat_units [mask], [area], horiGridId)
PSMILe_def_horigrid_rect(name, long_name, size_inx, lon, lon_bounds, lon_units, size_iny, lat, lat_bounds, lat_units, [mask], area, horiGridId)
PSMILe_def_horigrid_gen(name, long_name, nb_points, nb_corners, lon, lon_bounds, lon_units, lat, lat_bounds, lat_units, [mask], neighbors, area, horiGridId)

Description :

These function allow to define and describe a grid. These grids will then be used latter as a basis for the definition of variables.

This system clearly favors rectangular grids on the global. A stereographic grid, or other projects which do not fit into a rectangular presentation will need to switch to the general interface.

>WP3a: OK

A question remains opens here, is the mask a property of the grid and/or the variable. In fact the grid here is a geophysical entity which exists whether the model simulates something over it or not and thus no masking is justified. The consequence here is that it obliges all variables which will come will need to be masked if they do not cover the entire domain. If on the contrary if the mask is a property of the grid then it will not be able to evolve with time.

>WP3a: we favour use of separate function to define the mask.

>IPSL : In general we believe it would be a good substitute to have 'Optional subroutine' instead of 'optional arguments' but this requires a clear definition of dependences. i.e. A mask can not be defined if the grid does not yet exist and so on.

>WP3a: Yes; our proposition below follows this principle.

A flow diagram for the PSMILe_def_horigrid function

Arguments:

name: Name of the horizontal grid.

>WP3a: We do not understand this argument. What is its use?
>IPSL : Well this is the argument which allows us to link the information from the model to the one in the SMIOC. As a matter of principle we believe that the model should provide two pieces of information which should also be in the SMIOC. The first one would be to identify the variables (or element) and the other to verify that there is no mistake. More redundancy would be better but it would obviously make the interface more complex.
>WP3A: ??? (Sophie: I personally still do not understand this argumentation)

long_name (IN) : Long name of the horizontal grid.


>WP3a: We do not understand this argument. What is its use? A check of coherence between this information given by the "model" to the PSMILe and the information in the PMIOD/SMIOC will in fact check only the ability of the model developer to be coherent between what he indicates as argument in the PSMILe functions and what he indicates in the PMIOD. We think that these types of coherence checks are not usefull.
>IPSL : well this is discussed above, we need to be able to confirm the identification of a variable.
>WP3A: ??? (Sophie: I personally do not understand this argumentation)

size_inx (IN) : Size of the grid in the longitude direction
lon (IN) : The longitude values of grid central points
lon_bounds (IN) : The longitude of the boundary between this point and the preceding and this point and the next one.


>WP3a: More information on the mesh description is needed here. The mesh borders can be described by a number of points/vertices (usually 4 for the corners but sometimes 8 for the corners + the middle of each mesh segment) and the coordinates of these points/vertices.
>IPSL : As shown below all the information can be in an array if we add an extra dimension. See table below.
>WP3a: We propose additional routines (see PRISM_set_2corners_1D, PRISM_set_8corners_3D, PRISM_set_4corners_2D below)

lon_units (IN) : Units of the longitude coordinates.
>WP3a: It can be discussed here if the units should be imposed (e.g. degrees East). If not imposed, this information should be obtained by the PSMILe in the SMIOC. Once again, a check of coherence between this information given by the "model" to the PSMILe and the information in the PMIOD/SMIOC will in fact only check the ability of the model developer to be coherent between what he indicates as argument in the PSMILe functions and what he indicates in the PMIOD. Let's take the case in which the developer in a further version of the code modifies the units of the variable, but forgets to change them in the PSMILe function and in the PMIOD. The check of coherence will indicate that everything is fine even if it is not! This all comes down to the fact that the model itself does not know intrinsically the units of a variable!
>IPSL : No the units can not be imposed, or at least it would be unwise to do so. A LES for instance runs in meters from the origin and not in lon/lat ! You also have models which run from 0 to 360 starting at the date line and are thus not 'degrees East'. I even saw a model in Radians ! We could leave this information in the SMIOC and there is a case to be made for such a choice.
>WP3a: ??? (Sophie: Isn't PRISM about standardization. I personally think that we could impose the units.)

size_iny (IN) : Size of the grid in the latitude direction
lat (IN) : The latitude values of grid central points
lat_bounds (IN) : The latitude of the boundary between this point and the preceding and this point and the next one.
>WP3a: see comment on lon_bounds above.

lat_units (IN) : Units of the latitude coordinates.
>WP3a: It can be discussed here if the units should be imposed (e.g. degrees North). If not imposed, this information should be obtained by the PSMILe in the SMIOC.

nb_points (IN) : Number of points on the grid  nb_corners (IN) : Number of corners to define the grid box (3 = triangles, 4 = rectangles, ...)

mask (IN) : Points of the grid for which no values can exist in this model.
>WP3a: The mask should be allowed to evolve independently of the grid (e.g. drying lakes or seas). For each grid, it should be possible to define different masks. Furthermore, the horizontal mask may vary with the vertical dimension (e.g. ocean mask). It should therefore be possible to define a full 3D mask. For all these reasons, we favour use of separate routine to define the mask.
>IPSL : Yes but we need to distinguish between two things : A grid related mask which is based on the definition of the grid and can only change if the grid changes it will exist for all variables in this grid. A variable related mask which can change over time and will also change from one variable to the other.
>WP3a: <Rene> We already allow for defining many masks per grid. Thus different variables living on the same grid can have its individual masks. If the grid changes (grid points are added or removed) the mask will have to change accordingsly like the area or volume information.
 

neighbors (IN) : index of points neighboring the current grid box. They will be counted from the northern-most one rotating to wards the east, south and then west.

area (IN) : Area of the grid box. It can only be computed from the data available if we are on a orthogonal grid.
>WP3a: Instead of the area, the scaleFactors should be given. The scaleFactors is a vector of two elements giving a (pseudo-) dimension of the grid in i and j directions.
>IPSL : Yes indeed, it is much better to give the size in each direction (can be more than two elements) and let the user do the multiplication if the area is needed.
>WP3a: see PRISM_set_scalefactor below.

horiGridId (OUT) : ID for the horizontal grid.

 

Variable	Orthogonal grid	Regular grid	Unstructured grid
lon	size_inx	size_inx, size_iny	nb_points
lat	size_iny	size_inx, size_iny	nb_points
lon_bounds	size_inx, 2	size_inx, size_iny, 2	nb_points, nb_corners
lat_bounds	size_iny, 2	size_inx, size_iny, 2	nb_points, nb_corners
mask, area,	size_inx, size_iny	size_inx, size_iny	nb_points
neighbors	-	-	nb_points, 2*nb_corners

 
Name :


PSMILe_def_vertgrid() interface for :

PSMILe_def_vertgrid_fixed(size_inz, name, long_name, units, levels, level_bounds, vertGridId),
PSMILe_def_vertgrid_linear(size_inz, name, long_name, units, A, B, var , operation, vertGridId)


Description :
These functions allow the user to define a vertical axis. This definition of the axes will return an ID which should be used to refer a variable to this axis.

Arguments :

size (IN) : Size of the vertical grid.
name (IN) : Name of the vertical grid.
>WP3a: We do not understand this argument. What is its use?

long_name (IN) : Long name of the vertical axis.
>WP3a: We do not understand this argument. What is its use?

units (IN) : Units of the vertical coordinates.
>WP3A: Should this information should be obtained by the PSMILe in the SMIOC?

levels (IN) : Values of the vertical coordinates.

level_bounds (IN) : Boundaries of the vertical axis.

A (IN) : multiplicative component of linear transformation

B (IN) : additive component of linear transformation

var (IN) : The variable which will be used to build the vertical grid as A*var + B

vertGridId (OUT) : ID for the vertical grid.


Notes:

Z-grid are covered by PRISM_def_vertgrid_zfixed.
Sigma-grid are covered by PRISM_def_vertgrid_linear
Isopycnal grids are not covered. For this type of grid, for which the z-levels change at each timestep and cannot be calculated linearly by A*var + B, two solutions exist: 1-Offer a PRISM_def_vertgrid_function with, as argument, a function that has to be called to calculated the z-level; 2-Impose that the model will have to calculate and give to the PSMILe the z-levels at each I/O or coupling timestep, with a function PRISM_def_vertgrid_zchanged(vertGridId, indexList, units(?), levels, [level_bounds=level_bounds]).
>IPSL : There is a need to have the possibility to define a grid but without specifying the coordinate points initially. The definition would only point to a variable which will be declared later and provided with a PRISM_put during execution. There are many instances where we will need this.
>WP3a: <Rene> I clearly see that this approach is tempting for I/O issues. For coupling this will be very costly. We would than have to check with every call to PRISM_put/PRISM_get whether the grid etc. has changed in order to recalculate the interpolation matrices and to check whether the neigborhood relation has changed. In this case we also have to redefine the MPI communicators and reestablish the whole communication pattern. Furthermore there were objections against the approach to pass pointers to the interface from ECMWF.

Please bear in mind that the handling of changing grids for coupling is not straightforeward and that there are many dependencies that need to be covered.

>Sophie: The PSMILe interface must provide the possibility of redefining the grid everytime step, as it is clearly needed for I/O,
  even if coupling models of such type will maybe not be supported within the next PRISM 3 years (this was clearly stated in ARCDI, but we must keep that door open however)

------------------------------

>WP3A: Our new proposition for the definition of the grid and related variables is the following. More information on the wp3a discussions that led to this proposition can be found in http://www.cerfacs.fr/PRISM/MTCI/grid_def.html.

Note: We have to make the distinction here between the rank of a variable (i.e. the number of informatic dimensions) and the number of physical dimensions covered by the variable. Hereafter, I will respectively use the words "rank" and "physical dimensions". Each physical dimension will be described by one coordinate array.

For example, an unstructured grid covering a 2D physical space will be a grid of physical dimension 2 but the localisation of the grid points will be expressed with arrays of rank 1, e.g. longitude(nbr_pts), latitude(nbr_pts).

Note: We suppose below that each 3D grid is identified by one grid_id.
Sophie: Even if we finally decide to work with 3D grids decomposed in a 2D horizontal grid and a 1D vertical axis, (personally I tend to prefer that option as I think it is more intuitive for our type of geophysical codes) the 1D and 2D routines below would still be relevant. In that case, the 3D mask could be given by a  a 2D array given the number of unmasked level for each horizontal grid point.

Grid definition:

Name:
PRISM_def_grid (grid_id, comp_id, grid_valid_shape, grid_nodims, grid_type, ierror )
Responsible: NEC-CCRLE/CERFACS

Description :
     This routine announces a grid and describes its structure. The localisation of the grid points and other characteristics will be described by other routines. The link will be made through the grid identifier.

Arguments:
 

grid_id	[OUT]	unique identifier of the grid
comp_id	[IN]	component Id as given by PRISM_init_comp
grid_valid_shape	[IN]	ilow,ihigh,[jlow,jhigh],[klow,khigh] of valid range, without halo regions
grid_nodims	[IN]	indicates the rank of the arrays describing the grid (e.g. grid_valid_shape)
grid_type	[IN}	PRISM integer named parameter describing the structure of the grid

Note 1: We need to describe the minimum and maximum index values of each dimension for the "valid" part of the array that is effectively treated by the process, without the halo region (for example, if the extent of the first dimension is 100, it may be that the "valid" part of the array goes from 2 to 98); that information is in our xxx_valid_shape arguments above.
Furthermore, we will need also to describe the minimum and maximum index values of each dimension of the "actual" data array including the halo region (for example, if the extent of the first dimension is 100, it may be that the index goes from 0 to 99, or from 1 to 100); that information is in our xxx_actual_shape arguments below.

Note 2: Some examples of grid_type and the related way of describing the grid point localisation could be:
-"1D_lon" for a 1D grid expressed as a vector of longitudes, center_1stcoord_array(i) -see below.
-"2D_reglonlat" for a  2D grid expressed as vectors of longitudes and latitudes, center_1stcoord_array(i) and center_2ndcoord_array(j).
-"2D_irrlonlat" for a  2D grid expressed as arrays of longitudes and latitudes, center_1stcoord_array(i,j) and center_2ndcoord_array(i,j).
-"2D_reglondep" for a  2D grid expressed as vectors of longitudes and depths, center_1stcoord_array(i) and center_2ndcoord_array(k).
-"2D_unstruclonlat" for a  2D grid expressed as vectors of longitudes and latitudes, center_1stcoord_array(nbr_pts), and center_2ndcoord_array(nbr_pts).
-"3D_reglonlatdep" for a  3D grid expressed as vectors of longitudes, latitudes and depths, center_1stcoord_array(i) and center_2ndcoord_array(j), and center_2ndcoord_array(k).

>Sophie 26/07/02:
Note 3: A more complete list of grid_type supported by the PSMILe could be.

x denotes Longitudes (lambda, -180 to 180 )
y denotes Latitude   (phi,     -90 to  90 )
z denotes Depth      (m, positive up from sea surface)

1-dimensional grids

• 1D_lon      x(i)
• 1D_lat      y(j)
• 1D_dep      z(k)

2-dimensional grids

• 2D_irrlonlat  x(i,j), y(i,j)
• 2D_reglonlat  x(i), y(j)
• 2D_reglatdep  y(j), z(k)
• 2D_reglondep  x(i), z(k)
• 2D_reglat_irrdep  y(j), z(j,k)
• 2D_irrlon_reglat  x(i,j), y(j) (>Sophie ???)
• 2D_reglon_irrlat  x(i), y(i,j) (>Sophie ???)
• 2D_reglon_irrdep  x(i), z(i,k)
• 2D_irrlat_regdep  y(i,k), z(k) (>Sophie ???)
• 2D_irrlon_regdep  x(i,k), z(k) (>Sophie ???)
• 2D_unstructlonlat  x(nbr_pts), y(nbr_pts)

3-dimensional grids

• 3D_reglonlatdep          x(i  ), y(j  ), z(k  )
• 3D_irrlonlat_regdep      x(i,j), y(i,j), z(k  )
• 3D_reglon_irrlatdep      x(i  ), y(j,k), z(j,k)  (>Sophie ???)
• 3D_reglat _irrlondep     x(i,j), y(j  ), z(i,k)  (>Sophie ???)
• 3D_irrlonlat_sigmadep  x(i,j), y(i,j), z(i,j,k)
• 3D_reglonlat_sigmadep    x(i  ), y(j  ), z(i,j,k)
• 3D_unstructlatlon_regdep       x(nbr_pts_hor), y(nbr_pts_hor), z(k)
• 3D_unstructlatlondep x(nbr_pts_hor), y(nbr_pts_hor), z(nbr_pts_hor,k)

Grid center localisation:
 

Name:
PRISM_set_center_1D (grid_id, center_actual_shape, center_1stcoord_array, ierror )
Responsible: NEC-CCRLE/CERFACS

Description:
This routine defines the localisation of the center coordinate array of a grid covering a 1D physical space.

Arguments:
 

grid_id	[IN]	value received from PRISM_def_grid
center_actual_shape	[IN]	array containing minimum and maximum index values for the informatic dimension (1). This must cover at least the grid_valid_shape region but can also include halo regions.
center_1stcoord_array	[IN]	Describe the coordinate of the grid centers (the shape this array depends on  grid_type)

Name:
PRISM_set_center_2D (grid_id, center_actual_shape, center_1stcoord_array, center_2ndcoord_array,  ierror )
Responsible: NEC-CCRLE/CERFACS

Description:
This routine defines the localisation of the center 2 coordinate arrays of a grid covering a 2D physical space.

Arguments:
 

grid_id	[IN]	value received from PRISM_def_grid
center_actual_shape	[IN]	array containing minimum and maximum index values for each informatic dimension (1, 2). This must cover at least the grid_valid_shape region but can also include halo regions.
center_1stcoord_array	[IN]	Describe the longitude of the grid centers (the shape this array depends on  grid_type)
center_2ndcoord_array	[IN]	Describe the latitude of the grid centers (the shape this array depends on grid_type)

Name:
PRISM_set_center_3D (grid_id, center_actual_shape, center_1stcoord_array, center_2ndcoord_array, center_3rdcoord_array, ierror )
Responsible: NEC-CCRLE/CERFACS

Description:
This routine defines the localisation of the center 3 coordinate arrays of a grid covering a 3D physical space.

Arguments:
 

grid_id	[IN]	value received from PRISM_def_grid
center_actual_shape	[IN]	array containing minimum and maximum index values for each informatic dimension (1, 2 or 3). This must cover at least the grid_valid_shape region but can also include halo regions.
center_1stcoord_array	[IN]	Describe the longitude of the grid centers (the shape this array depends on  grid_type)
center_2ndcoord_array	[IN]	Describe the latitude of the grid centers (the shape this array depends on grid_type)
center_3rdcoord_array	[IN]	Describe the depth of the grid centers (the shape this array depends on grid_type)

Grid corner localisation:
 

We propose to have one call to define the 2 "corners" of a 1D grid, one call to define the 4 "corners" of a 2D grid, and one call to define the 8 "corners" of a 3D grid.  In this case, each dimension of corner_1stcoord_array, corner_2ndcoord_array and corner_3rdcoord_array has one more element as compared to the dimensions of center_1stcoord_array and center_2ndcoord_array of the PRISM_set_location_xx, except for unstructured grid for which other specific routines should be defined.

We would define other routines if we ever need to specify more than 4 corners for 2D grids, or more than 8 corners for 3D grids.

Name:
PRISM_set_2corners_1D  (grid_id, corner_valid_shape, corner_actual_shape, corner_1stcoord_array, ierror)
Responsible: NEC-CCRLE/CERFACS

Description:
This routine defines the localisation of the corner coordinate array of a grid covering a 1D physical space.
Note: The "valid_shape" needs to be redefined as it may be different for the grid_valid_shape (the arrays do not have the same shape)

Name:
PRISM_set_4corners_2D  (grid_id, corner_valid_shape, corner_actual_shape, corner_1stcoord_array, corner_2ndcoord_array, ierror)
Responsible: NEC-CCRLE/CERFACS

Description:
This routine defines the localisation of the corner coordinate arrays of a grid covering a 2D physical space.

Name:
PRISM_set_8corners_3D  (grid_id, corner_valid_shape, corner_actual_shape, corner_1stcoord_array, corner_2ndcoord_array, corner_3rdcoord_array, ierror)
Responsible: NEC-CCRLE/CERFACS

Description:
This routine defines the localisation of the corner coordinate arrays of a grid covering a 3D physical space.

Mask definition
 

Name:
PRISM_set_mask (grid_id, mask_id, mask_actual_shape, mask_array, ierror)
Responsible: NEC-CCRLE/CERFACS

Description:
This routine defines the mask related to the grid with id grid_id. The mask will be attached to a variable in the PRISM_def_var call.
 

grid_id	[IN]	value received from PRISM_def_grid
mask_id	[OUT]	handle to the defined mask
mask_actual_shape	[IN]	actual range of coordinates, must cover at least grid_valid_shape but can also include halo regions
mask_array	[IN]	The rank of mask_array can be 1, 2, or 3 (defined by grid_type associated with the grid_id)

Name:
PRISM_set_scalefactor(grid_id, scalefactor_actual_shape, scalefactor_array, ierror)
Responsible: NEC-CCRLE/CERFACS

Description:
This routine defines the scale factors describing the area of the meshes of the grid with id grid_id.
 

grid_id	[IN]	value received from PRISM_def_grid
scalefactor_actual_shape	[IN]	Array containing the minimum and maximum index values for each informatic dimension (1, 2 or 3). This must cover at least the grid_valid_shape region but can also include halo regions.
scalefactor_array	[IN]	This array will have one extra dimension (as compared to the shape of center_array), this extra dimension being of extent 2 for 2D grids -2 scale factors are needed) or of extent 3 for 3D grids -3 scale factors are needed.

Local rotation angle definition
 

Name:
PRISM_set_angle (grid_id, angle_actual_shape, angle_array, ierror)
Responsible: NEC-CCRLE/CERFACS

Description:
This routine defines the local rotation angle at the center of the grid with id grid_id.
Arguments:

grid_id	[IN]	value received from PRISM_DefineBlock
angle_actual_shape	[IN]	Array containing the minimum and maximum index values for each informatic dimension (1, 2 or 3). This must cover at least the grid_valid_shape region but can also include halo regions.
angle_array	[IN]	The rank of angle_array can be 1, 2, or 3 (defined by grid_type associated with the grid_id)