3. Transformer functionalities

This paragraph gives, in the first section, some definitions and, in the second section, the preferred design option for the PRISM coupler Transformer. In the third section, an exhaustive list of transformations and grids on which these transformations should be performed is presented, together with other specific requirements, and associated priority and calendar.

3.1 - Definitions

• Point-wise transformation: an operation that can be completed on each grid point without any external information, neither from the model neighbouring grid points, neither from another model, such as time averaging or addition of coupling fields given on the same grid.
• Local transformation: an operation that can be completed in a model without any information from another model, such as finding the maximum value of a field.
• Non-local transformation: an operation that requires information  from another model, such as interpolation.

The preferred design option  is that the non-local transformations are performed in a separate transformation entity, as it requires information coming from different models. For point-wise and local transformations, it should be possible to perform them in the PRISM Model Interface Library (PSMILe) linked to the model; in some cases, this is recommended to avoid extra communication.
However, point-wise and local transformations should also be available in the separate transformation entity (for example, combination of coupling fields coming from different source models after their interpolation on the target grid).

3.3 - List of transformations, grids, and associated priority and calendar
 

3.3.1 Transformations

A list of relevant transformations that could be provided by the PRISM coupler is given hereafter. For each transformation, it is specified whether the transformation is "point-wise", "local" or "non-local".
 

• 1D, 2D, and 3D spatial interpolations

All these transformations are non-local.

• S1 - Nearest-neighbour interpolation function:

For each target grid point, the n nearest neighbours on the source grid, weighted or not by their distance, are averaged.
 
• S2 - Nearest-neighbour gaussian weighted interpolation function:

For each target grid point, the n nearest neighbours on the source grid, weighted by the value of a gaussian function at their distance from the target point are averaged.
 
• S3 - 1st order interpolation function:

Standard 1st order bilinear interpolation.
 
• S4 -  2nd order interpolation function:

Standard 2nd order bicubic interpolation.
 
• S5 - First order conservative remapping:

This scheme will guarantee that the line (1D)-/area (2D)-/ volume (3D)-integrated field (e.g. water or heat flux) is conserved between the source and the target grid.
 
• S6 - Second order conservative remapping:

This scheme will also guarantee that the line (1D)-/area (2D)-/ volume (3D)-integrated field (e.g. water or heat flux) is conserved between the source and the target grid.
 
• S7 - Remapping using user-defined remapping info (ex: MOZAIC)

 
• Other 1D, 2D, and 3D spatial transformations

 
 
• S8- Conservation:
This non-local operation ensures global energy conservation between source and target grids (ex: CONSERV).
 
• S9- Combination or merge:

This local and point-wise operation combines different parts of different coupling fields or of other predefined external data given on the same grid (ex: FILLING). This operation may involve the smoothing of the fields near the different domain borders; in that case, the operation is still local but not point-wise.
 
• S10- Masking:

With this local and point-wise operation, only the points listed in index have meaningful data and the others are changed to missing (ex: MASK).
 
• S11- Scattering:

This local operation scatters the model data onto the points listed in an index.
 
• S12- Gathering:

This local operation gathers from the input data all the points listed in an index.
 
• S13- Collapse:

This local operation results in the collapse of any dimension or combination of dimensions by various, possibly weighted, statistical operations, such as mean, max, min, etc. (possibly relative to a threshold, e.g. maximum of positive values). (ex: CHECKIN, CHECKOUT)
 
• S14- Subspace:

This local operation results in the extraction of subspaces or hyperslabs in any combination of spatial dimension.
 
• S15- Algebraic operations:

Local and point-wise operations, such as addition, substraction, multiplication, etc., with possibly different coupling fields or predefined external data (given on the same grid) and numbers as operands (+, -, X, SQRT, ^2, SIN, LOG, ...) (Ex: BLASOLD, BLASNEW, SUBGRID, CORRECT)
 
• S16a - 1st order  extrapolation function

 
• S16b - 2nd order extrapolation function:

This transformation is required to address the specific problem of the wind curl along the coast.
• Time operations

 
• T1- Time integration, average, variance, extrema, linear interpolation

Local and point-wise operations.


  3.3.2 List of grids

The following grids should be supported for the above scheme. These grids have the following common characteristics:
 

• The grids may have masked grid points.
• The grids may have "holes" (i.e. they do not cover the whole sphere, e.g. regional grids).
• The grids may be global or regional (except H3 reduced grid which is always global).
• The grids may have overlapping grid points (except H3).

• 2D grids

 
• H1 - Lat-lon grids:

The grid is given by the intersection of meridians and parallels. Each (i,j) grid point can be described by the value for the indices i and j of two 1-D arrays, latitude(j) and longitude(i).
• The latitudinal mesh sizes can be regular or irregular, i.e. latitude(j) is or not constant.
• The longitudinal mesh size can be regular or irregular,  i.e. longitude(i) is or not constant.
• The grid may overlap in longitude with N overlapping grid points.
• The grid may have grid points at the pole and/or at the equator.
• The border of the meshes can be approximately placed half-way between two grid points, but the exact location of the border meshes should be given with the grid.
•  H2 - Cartesian and streched and/or rotated grids (logically rectangular):

Each (i,j) grid point can be described by the value for the indices i and j of two 2-D arrays, latitude(i,j) and longitude(i,j).
• The grid may overlap itself in the i and/or j direction.
• The exact location of the border meshes should be given with the grid.
• H3 - Reduced grids

The grid is composed of a certain number of latitude circles, each one being divided into a varying number of longitudinal segments. The grid can be described by the number of latitude circles, N_lat, the latitudinal position of each circle npos(N_lat) and by an 1-D array giving the number of longitudinal segments for each latitude, n_seg(N_lat). The total number of grid points, N_tot, is the sum of all elements of n_seg. The grid can also be described by two 1-D arrays, latitude(N_tot) and longitude(N_tot). This grid may be considered as one particular case of unstructured grids
• There is no overlap of the grid.
• There is no grid point at the equator nor at the poles.
• There are grid points on the Greenwich meridian.
• The exact location of the border meshes should be given with the grid.
• H4 - Unstructured grids

The grid, with N_tot number of grid points, has no logical structure.  The grid must be described by two 1-D arrays, latitude(N_tot) and longitude(N_tot)
• The grid may overlap itself for some grid points.
• There may be a grid point at the equator or at the poles.
• There may be grid points on the Greenwich meridian.
• The mesh can have an arbitrary number of sides. The exact location of the border meshes should be given with the grid.
• 3D grids
• V1 - Reproduction of the same horizontal grid at different levels

The same horizontal grid is reproduced at different vertical levels. Each level has its particular mask.
The vertical levels can be:
• V1-1 : given at regular or irregular depth or height levels (z co-ordinate)
• V1-2: hybrid: first level follows the topography (atmosphere models or the bathymetry (ocean models), last level follows an isobar(atmosphere) or the surface (ocean), progressive transition in between.
• V1-3 : given at regular or irregular isopycnal (density) levels (r co-ordinate)
• V2 - Different horizontal grids at different levels

The horizontal grid is not reproduced at different vertical levels. The horizontal grid can be rotated, translated, or totally unstructured.


   3.3.3 Other specific requirements
 

• To support scalar coupling data. (For priority see below).
• To support vector coupling data in the standard spherical geographical coordinate system. (For priority see below).
• To support vector coupling data in any set of local coordinate system. (For priority see below).
• To support fields with undefined variables. (2, 3)
• To support coupling fields which characteristics may change over time as simulation develops , e.g. grid, resolution, distribution (CF dynamic simulation). (3)
• To be able to save, at a user-defined frequency, its restart data (e.g. time accumulated data). (2,3)
• To support source and target coupling domains that totally or partially overlap (e.g. global atmosphere with a regional ocean, regional model nested into global model, etc.). (1, 2, 3)


3.3.4 Priority and calendar

The following paragraph gives the priority of development for the different transformations on the different grids listed above. "1" means that the transformation is essential and should be provided for the first version of the  PRISM coupler (D3a1, 12/2002). "2" means highly desirable and should be provided for the second version of the PRISM coupler that will be used for the demonstration runs (D3a2, 12/2003). "3" means that the operation may be provided for the final version of the  PRISM coupler (D3a3, 12/2004). "-" means that this operation is not relevant. When two numbers are given, it means that parts of the functionality will be provided for the respectives coupler versions.

Transformations on 2D scalar coupling fields

 

Transformations on 2D vector coupling fields
 

• Transformations on 2D vector coupling fields given in the standard spherical coordinate system

 
• Transformations S1, S2, S3, S4, S6, S7, S9, S10, S11, S12, S13, S14, S15, S16a, S16b, T1 are given the same priority than for 2D scalar fields.
• Transformations S5, S8 are of priority 3.
• Transformations on 2D vector coupling fields given in any set of local coordinate system

 
• Transformations S1, S2, S3, S4 for H1 and H2, S7, S10, S11, S12, S15, S16a, S16b for H1 and H2 are of priority 2.
• Transformations S4 for H3, S5, S6, S8, S9, S13, S14, S16b for H3 are of priority 3.


Transformations on 3D coupling fields
 

• Interpolations for V1-1 and V1-2 grids
For V1-1 and V1-2 grids, the treatment of 3D coupling fields will be addressed for the second PRISM coupler version. The idea is to proceed with a multiple 2D interpolation (i.e. 2D interpolation on many horizontal or hybrid levels) plus a simple linear interpolation vertically (priority 2). The priority given to the multiple 2D interpolations or extrapolations (S1, S2, S3, S4, S5, S6, S7, S16a and S16b) for scalar or vector fields for the different horizontal grids is 2, or more if a lowest priority is given above for the equivalent (single) 2D interpolation scheme.
• Other transformations for V1-1 and V1-2
For V1-1 and V1-2 grids, the local and point-wise transformations S10, S15, and T1 are given priority 2.
For V1-1 and V1-2 grids, transformations S8, S9, S11, S12, S13, S14 are given priority 3.
• Interpolations and other transformations for V1-3 and V2 grids
These transformations will not be addressed within PRISM 3-year project.


Transformations on 1D coupling fields

All transformations are given priority 3.
 

4. PSMILe functionalities

The  PRISM System Model Interface Library (PSMILe) is the set of routines implemented in a component model code to interface it with the rest of the coupled model. As detailed in the section 4.3 of REDOC II.2 paragraph, I/O and coupling data present many common characteristics. It was therefore decided to develop one common model interface library, the PSMILe, both for coupling and I/O purposes. The PSMILe therefore includes the Data Exchange Library which performs the exchanges with the other component models, the I/O library, and some coherence check and local transformation routines.

4.0 PSMILe general characteristics

• The modifications to implement in the model code are as reduced as possible. (1, 2, 3)

• The PSMILe is layered, and complexity is hidden from the component code. (1, 2, 3)

• Interface routines once defined and implemented are not (or as little as possible) subject to modifications  between the different versions of the PRISM coupler. However new routines may be added. (1, 2, 3)

• A good trade-off is chosen between (I) a concise list of parameters for each subroutine call (more subroutines provided with a shorter list of parameters) and (II) a small number of subroutines, each one having a longer and more complex parameter list. The complexity arises from the need to transfer not only the coupling data but also the meta-data. (1, 2, 3)

• The component models are able to run in a stand-alone model without modifications, with or without an external driver. (2, 3)

I.4-1) A: E, C: E, L: , O: E, B: E, R: E, M: E, CC: M, , CE: D, S: E  (E:7, D:1, M:1, U:0, N:0)

• The description of the data, i.e. the meta-data (e.g. units, grid coordinates, mask, distribution, ...), and the model information (e.g. length of a timestep) is given by the model through the PSMILe and not duplicated externally by the user (2, 3). This information may change during the simulation. (3)

I.4-2) A: M, C: M, L: , O: U, B: M, R: U, M:E, CC: -, , CE: D, S: D (E:1, D:2, M:3, U:2, N:0)

• The PSMILe is extendable to new types of coupling data (e.g. data given on arbitrary grids). (1, 2, 3)

• The PSMILe includes the Data Exchange Library and the I/O library as the most external layers. The PSMILe therefore automatically manages the cases for which input coupling data are not provided by another model but have to be read into a file; this is transparent for the component model. The format of these data files could be a standard PRISM fixed format (2). At a later stage, different formats could be supported for these data files, implying that the I/O instance can interpret their content.(3)

• The PSMILe includes some local transformation routines and performs the transformation required locally before the exchange with the rest of the PRISM System. (2, 3)

• The PSMILe performs some checks of coherence on coupling and I/O data, according to a coherence check level defined by the user in the coupled model configuration file. (3)

 The PSMILe should perform some checks of coherence on coupling and I/O data, according to a coherence check level defined by the user in the coupled model configuration file. The coherence check instance will:

 The PSMILe should perform the following transformations locally before the exchange with the rest of the PRISM System (for associated priorities, refer to section 3.3):