PSMILe interface proposal

link to 26/07/2002 version

-in green: IPSL last comments (02/07/02)
-in red: WP3A new comments or WP3a old comments that still need to be discussed (16/07/02 or 26/07/02)
-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
- in purple: comments from Stephanie Legutke

• 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.
>SL: I agree , I do not see how  'reproduced' horizontal grid layers can be brought together: not only land/sea etc. masks are different for different layers in ocean models but also the vertical scale factors (in each cell!). And for the latter a simple rule as for the masks (no. of valid values from the surface downward) does not exist.

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.

> SL:To be exact, extendible, and flexible, one would have to define a land mask, a sea mask, an ice sheet mask, an SST mask, etc. A mask must not necessarily have only values 1 or 0. Any value between 0 and 1 could be allowed if the mask is a 'present/non-present' flag. This is an extension to the normal mask definition. To call it land/sea mask, the sum of the mask-value of both must be 1.
>WP3a: Yes; our proposition below follows this principle. Each variable can have a different grid.

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)
> SL: nor do I. Redundancy (in particular a redundancy in the action a model deployer has to do) is something I would not accept. I welcome every consistency check, even when it goes with a computational overhead (since this will be compensated in most cases by avoiding unneccessary simulations). To put the same variable at two places and not forget to change the second if the first is changed, however, is not a consistency check, as Sophie detailed below.
The proposed name/long_name parameters remind me of NetCDF conventions.  Does it come from this direction? I think this can make sense since the masks will be output and then must be documented in the output record. In any case, I vote to force the model deployer to type the information only once or not at all. It might make sense however to lay down the name of the masks (source and target grid) in the SCC (unchangable there)  and use this entry/definition to give the masks the appropriate name at run time. The gridID might be lost after the run or if saved it is not as 'explanatory' as the name. Also it might change between runs.

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.
>SL: what is this needed for? Nearest neighbor interpolation weights can be calculated without that. Linear/cubic interpolation need neighbors 'on a line'.  For all polygons  it can be calculated easily (the cell which shares the corners of the side separating the neighbors).

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
> SL: why is this needed? Why not pass z=A*var+B
in ECHAM the hybrid sigma/p coordinates are defined by A(k)*P(surface)+ B(k) where k=0,NLEV counts the levels and units are pressure. Is that covered by your function?

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)

> SL: In the ocean the sigma coordinates are in depths and the 'surface field' used for the calculation is the water depth which does not change so easily (as I understood).The isopycnal surface values are not changed during the run, and sigma coordinates are depth coordinates and these change from cell to cell but not in time.
> for the atmosphere, z values of sigma coordinates do change since the surface pressure and the pressure profile changes. I do not see that a function exists even for pure sigma-coordinates for conversion into z-levels (besides the way it is done in the model)
> we should ask the atmosphere people whether there are vertical coordinates defined in other units than Pa. If no, there is not need to pass through the z-levels;the interpolation is in pressure coordinates in all three deimension (or perhaps as proposed below, vertical after horizontal). If yes, it might be a good idea to always do the exchange on z-levels.
>Sophie 12/09: I just had a look: all atmospheric and atmospheric chemistry models in PRISM have sigma-hybrid coordinates vertically.
> was it discussed whether we need 'real' 3D interpolation or whether interpolation can/should be done for the horizontal first and than for the vertical?
E.g. in isopycnal models, eddy diffusion and advection is mainly along isopycnal surfaces, and therefore it might be allowed to first interpolate on the isopycnals of the global grid onto the (finer regional) grid and then vertically onto the isopycnal/z/sigma levels of the regional model. Isopycnal2isopycnal should be easy. Isopycnal2z should be available in the isopycnal model. We should ask experts on isopycnal models. There is nobody in Hamburg available since Joseph quit. I already tried to find one.
For atmospheric global2regional models interpolation there are experts in PRISM.
If the interpolation can be done horizontally first and then vertically, Rene's concerns are obsolete, am I right? Interpolation would be local to the processor if the domain decomposition does not allow to distribute a profile to several cpus.
Now we need to do both: (i) interpolation and (ii) output.
(i) will/can/should be done as Rene proposes (fully 3D on z coordinates) or pseudo-3d as described above
(ii) the I/O cases simple:  A variable on an isopycnal/sigma grid must be output (for later diagnostics) on the original grid, i.e. the iopycnal one in the example case. Isopycnal and sigma coordinates are not prognostic.
When diagnostics are to be done later an interpolation may be useful. But this is the task of the diagnostic library.

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

>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_040702.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)

> Sophie 12/09: Do we need a "name" (and a "long name") argument in order to identify the grid in the SMIOC in order to get additional information (e.g. number of overlapping grid points for lat-lon grids)?

Grid center localisation:

>SL: if I am well informed (I put this into question here ) SCRIP needs (as long as interpolation is on a sphere) just the lat/lon of all corners of a cell. And the maximum number of corners a cell can have. Why do we need to give more than that? Do we need to allow the value to lie elsewhere than in the geometrical center (relevant for interpolation only not for averaging)? If  this  is not needed it can be calculated. To avoid the overhead of calculating it repeatedly one could think of a method similar to the one used in OASIS, i.e. let PSMILe calculate it if the information is needed but not available, otherwise take it from a file. This can be made more transparent to the user than is done presently in OASIS.

>Sophie 12/09: Do we need the "units" as argument, or will they be imposed?
>SL: the model can define its grid's lat/lon in radian, in east or west or whatever. But there is no need to provide for all that in the PSMILe parameter variables, since the grid for exchange-fields can be 'transformed' to be in degrees N/E. The question remains whether this grid transformation - if required - is to be done in the model or PSMILe. In any case, the units with which the interpolation is to be done, has to be specified. Since we are talking of earth climate models, I  vote for the unit which is most frequently used, i.e. degree E/N.
It should not be forgetten that the coupler is doing interpolation only, it will not solve the prognostics/diagnostic equations.

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)

** Refer to the above discussion for the vertical coordinates evolving during the run (hybrid, sigma, ...)**
 

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.

> Due to the strong stratification I see the need here, in contrast to the horizontal case, to also specify the vertical coordinate in addition to the upper and lower  boundaries.
 

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]	Real: value between 0 and 1. The rank of mask_array can be 1, 2, or 3 (defined by grid_type associated with the grid_id)

> SL: There are several mask concepts: e.g. the sea mask can take on one of a number of specified integers to indicate to which basin the cell belongs (same for catchment definitions).
For a mask one has to define therefore, what it will be used for.  For interpolation purposes it would be sufficient to indicate whether an interpolation onto a cell of the target grid is needed, and which cells of the source grid to use (i.e. a 1/0 mask will do). Conservative averaging methods depend on the areas of the source and target grids, and therefore for these cases the mask (e.g. for atm<->oce heat flux calculation) should allow for values between 0 and 1. I would not recommend to rely on derived masks (e.g. sea  masks = 1-land mask) since this is not flexible if the cell is partitioned into more surface types later.
Normally the land and sea masks  do not change. And with them e.g. the SST mask does not change either.  However, this is only owned to the fact that small scale tidal drying is not simulated nor longterm  continental drift. Taking this into account, there is no conceptual difference between a land masks and the (gridded) variable describing the sea ice coverage or tracer concentration or the partial coverage of a grid cell by a vegetation type.
It does not make much sense, however, to call the sea-ice concentration a mask, since it is prognosed in the same way as e.g. sea-ice thickness (see the mail). And the same would be true for vegetation-type cell coverage.
Is it a practical way to define a mask to be a function on the grid that takes over values between 0 and 1 but does not change, and call everything else which has a prognostic equation a variable? E.g. the vegetation-type cell coverage is a mask as long as it does not change with time, while in models it is prognosed it is treated as a variable? There are potential conflicts with standard interfaces.
The decision (mask or variable) could also be made dependend on whether the variable is a potential exchange field (which implies that it changes or can change with time). This will go better with the concept of a standard interface.
> We should allow for more than one mask for the same grid: land/sea/lake/ice sheet(if not variable)/vegetation type coverage(if not variable). The latter is not really consistent with a standard interface where a variable should not be treated differently depending on whether it changes or not in a particular model. When the PRISM model is designed to be extendible to new components (ice sheets) then this holds for all masks. And we end up with considering a mask to be a variable with, if the case, exchange frequency 0.

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.

> SL: again I do not see the need to do this by the user. If the interpolation needs it, it can be calculated from the 'corners' . I think the user should be asked to give as little information as possible.

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)