4 Grid data file definition

Grid data files are required by OASIS3-MCT for specific operations, see sections 4 and 5.1. These grid data files can be created by the user before the run or can be written directly at run time by the components with the following routines. If a grid data files does not exist, the corresponding routine will create it; if the grid data file exists, the routine can be used to add grid definition fields but it will not overwrite grid definition fields already existing in the file with the same grid name.

These routines can be called only by one component process to write the whole grid or by each process holding a part of a grid. In the former case, optional argument il_part_id is not needed and the arrays handling the longitudes of the grid points or corners (lon, clon), the latitudes of the grid points or corners (lat, clat), the masks (mask), fracs (frac), and areas (area) of the grid cells need to cover the whole grid; in the later case, the il_part_id returned by oasis_def_partition needs to be provided as input argument and the arrays need to cover only the local partition of the grid.

The field names in the grids.nc, masks.nc, and areas.nc follow a well-defined convention. The fields are normally two-dimensional, and each field name consists of a grid acronym followed by a string that identifies the field. For instance, the center latitudes for the grid torc will be called torc.lat and the center longitudes will be called torc.lon in the netcdf file. The grids.nc file contains the center latitudes (.lat) and longitudes (.lat) as well as the corner latitudes (.cla) and corner longitudes (.clo). The corner fields have a third dimension associated with the number of corners per gridcell. The area.nc file constains the area field (.srf). The masks.nc file contains the mask (.msk) and frac (.frc) fields.

• CALL oasis_start_grids_writing (flag) or
• CALL prism_start_grids_writing (flag)
  • flag [INTEGER; OUT]: always 1
  Must be called to start the grid writing process.

  
  

• CALL oasis_write_grid (cgrid, nx_global, ny_global, lon, lat, il_part_id)
• CALL prism_write_grid (cgrid, nx_global, ny_global, lon, lat, il_part_id)
  • cgrid [CHARACTER; IN]: grid name prefix (see 3.3 and 5.1); maximum length of 64 characters (4 are usually used for historical reasons)
  • nx_global [INTEGER; IN] : first dimension of the global grid
  • ny_global [INTEGER; IN] : second dimension of the global grid (=1 if the grid is expressed as a 1D vector)
  • lon [REAL, DIMENSION(nx,ny); IN] : single or double real array of longitudes covering the whole grid (nx=nx_global, ny=ny_global) or only the local partition (degrees East).
  • lat [REAL, DIMENSION(nx,ny); IN] : single or double real array of latitudes covering the whole grid (nx=nx_global, ny=ny_global) or only the local partition (degrees North)
  • il_part_id [INTEGER, OPTIONAL; IN]: partition ID returned by oasis_def_partition, see 2.2.3; needed if each component task holding a part of a decomposed grid writes its own part of the grid.

  Writes the component grid longitudes and latitudes. Longitudes must be given in degrees East in the interval -360.0 to 720.0. Latitudes must be given in degrees North in the interval -90.0 to 90.0. Note that if some grid points overlap, it is recommended to define those points with the same number (e.g. 90.0 for both, not 450.0 for one and 90.0 for the other) to ensure automatic detection of overlap by OASIS3-MCT (which is essential to have a correct conservative remapping SCRIPR/CONSERV, see section 4.3).

  
  

• CALL oasis_write_corner (cgrid, nx_global, ny_global, nc, clon, clat, il_part_id))
• CALL prism_write_corner (cgrid, nx_global, ny_global, nc, clon, clat, il_part_id))
  • cgrid , nx_global , ny_global , il_part_id : as for oasis_write_grid

  • nc [INTEGER; IN] : number of corners per grid cell (can be any number)
  • clon [REAL, DIMENSION (nx,ny,nc);IN] : single or double real array of corner longitudes covering the whole grid (nx=nx_global, ny=ny_global) or only the local partition (in degrees_East)
  • clat [REAL, DIMENSION (nx,ny,nc);IN] : single or double real array of corner latitudes covering the whole grid (nx=nx_global, ny=ny_global) or only the local partition (in degrees_North)

  Writes the grid cell corner longitudes and latitudes (counterclockwise sense). Longitudes must be given in degrees East in the interval -360.0 to 720.0. Latitudes must be given in degrees North in the interval -90.0 to 90.0. Note also that cells larger than 180.0 degrees in longitude are not supported. Writing of corners is optional as corner information is needed only for SCRIPR/CONSERV (see section 4.3). If called, needs to be called after oasis/prism_write_grid.

  
  

• CALL oasis_write_mask (cgrid, nx_global, ny_global, mask, il_part_id, companion)
• CALL prism_write_mask (cgrid, nx_global, ny_global, mask, il_part_id, companion)
  • cgrid , nx_global , ny_global , il_part_id : as for oasis_write_grid
  • mask [INTEGER, DIMENSION(nx,ny) ;IN] : mask array covering the whole grid (nx=nx_global, ny=ny_global) or only the local partition. Be careful about OASIS3-MCT historical convention (!): 0 = not masked (i.e. active), 1 = masked (i.e. not active).
  • companion [CHARACTER ;IN; OPTIONAL] : the character string value associated with the mask field attribute coherent_with_grid'. This will be written to the masks.nc netcdf file with the mask field. It is purely informational and used in cases where the mask field is derived from or consistent with another grid.
  Writes the component grid mask. The mask field should be consistent with the frac field (see below) and will define the 0/1 mask of the grid cell. The mask field is used by both the SCRIPR map generation function and in the global CONSERV operations if defined. The mask field is written to the masks.nc file.

  
  

• CALL oasis_write_frac (cgrid, nx_global, ny_global, frac, il_part_id, companion)
• CALL prism_write_frac (cgrid, nx_global, ny_global, frac, il_part_id, companion)
  • cgrid , nx_global , ny_global , il_part_id : as for oasis_write_grid
  • frac [REAL, DIMENSION(nx,ny) ;IN] : single or double real frac array covering the whole grid (nx=nx_global, ny=ny_global) or only the local partition.
  • companion [CHARACTER ;IN; OPTIONAL] : the character string value associated with the frac field attribute “coherent_with_grid”. It should refer to the acronym of the grid which mask was used to define the fraction of the current grid (see section 4.4). This will be written to the masks.nc NetCDF file with the fraction field. It is purely informational and used in cases where the frac field is derived from or consistent with another grid mask.

  Writes the component grid cell fractions. This should be consistent with the mask field and defines the fraction of the grid cell that is active (i.e. not masked). The fraction field is only used in the global CONSERV operations. Either the mask or fractions must be defined for that operation. If both are defined, they must be consistent; OASIS3-MCT will abort if they are not coherent or if both are missing. Note that by OASIS3-MCT conventions for the mask, a gridcell with mask=0 (active) should have a fractions greater than 0 and a gridcell with mask=1 (inactive) should have a fractions equal to 0. The fraction field is written to the masks.nc file.

  
  

• CALL oasis_write_area (cgrid, nx_global, ny_global, area, il_part_id)
• CALL prism_write_area (cgrid, nx_global, ny_global, area, il_part_id)
  • cgrid , nx_global , ny_global , il_part_id : as for oasis_write_grid
  • area [REAL, DIMENSION(nx,ny); IN] : single or double real array of grid cell areas covering the whole grid (nx=nx_global, ny=ny_global) or only the local partition
  Writes of the component grid cell areas. Needed for some SCRIPR options and for the CONSERV operation (see section 4.4). The area field is written to the areas.nc file. The surfaces may be given in any units but they must be the same on the source and target sides. Furthermore they must be in square radians if the True Area (TR) correction is activated, see section 4.3.

  
  

• CALL oasis_write_angle (cgrid, nx_global, ny_global, angle, il_part_id)
• CALL prism_write_angle (cgrid, nx_global, ny_global, angle, il_part_id)
  • cgrid , nx_global , ny_global , il_part_id : as for oasis_write_grid
  • angle [REAL, DIMENSION(nx,ny); IN] : single or double real array of grid cell angles covering the whole grid (nx=nx_global, ny=ny_global) or only the local partition
  Writes of the component grid cell angles. The angle field is written to the grids.nc file. This field does not play a role in OASIS3-MCT implementation and is never needed.

  
  

• CALL prism_terminate_grids_writing() or
• CALL oasis_terminate_grids_writing()

The creation of the different grid data files is completed in the routine oasis_enddef.