GENIE Gridspec

Ian Henderson ([mailto:I.R.Henderson@reading.ac.uk I.R.Henderson@reading.ac.uk])

Gridspec introduction
The gridspec is a way of describing the grids used in Earth system models. It is intended to provide a standard format (or 'schema') for describing grids. The gridspec will have several advantages:


 * The gridspec is a formalised description of grid topography, making it suitable for use by computer programs.


 * Tools used to analyse model output data can use the information supplied in a gridspec to provide more advanced visualisation and analysis functionality to scientists, without requiring model-specific customisation.


 * Frameworks of Earth system models must transfer coupling fields between model grids. Increasingly, standard tools are being developed for model framework construction, running and coupling.  The gridspec makes it easier for couplers (for instance the PRISM coupler, OASIS) to transform fields from one grid to another by providing a standard grid description that many models can be expected to use.


 * Regridding of model input or output data will be more straightforward, as it will be standards-based rather than bespoke.


 * The gridspec is designed to be extensible so that it can be used to describe many different types of grid, both extant and future.

The gridspec should be able to describe grids at different spatial resolutions, and of different shapes and structures. It should be able to cover, or be easily extended to cover, as wide a range of grids as possible. The gridspec should also be of use for both model control (coupling) and output (reporting).

Gridspec proposal
A gridspec proposal is currently being worked on by V. Balaji (GFDL). The proposal currently consists of a document that describes the proposed standard, implemented as an extension to the NetCDF Climate and Forecast (CF) conventions, and a couple of UML class diagrams that provide a diagrammatic overview of the proposed grid schema.

As part of the work to create a version of the GENIE ESM framework using the PRISM coupler (OASIS) using the Bespoke Framework Generator (BFG) tool, a working implementation of Balaji's grid schema proposal is being developed. This gridspec implementation will be used to describe the grids used by individual GENIE models, allowing BFG to generate automatically the PRISM grid initialisation code for each model required for OASIS coupling. A draft of this gridspec is presented below.

The gridspec has been implemented as an XML schema in preference to NetCDF to fit in with the XML metadata implementation used by BFG; eventually the gridspec should be available in both NetCDF/CF and XML formats, making it accessible to a wide range of Earth system modelling tools and programs.

Draft gridspec
The XML gridspec implementation below is based very closely on Balaji's gridspec proposal. For more detailed information please refer to the gridspec proposal itself.

The draft XML gridspec implementation is available for download here (the example is very simple at the moment - it doesn't illustrate the more advanced features of the gridspec):


 * Gridspec schema file (gridspec.xsd)
 * Example gridspec instance (igcm_gridspec.xml)

The draft XML gridspec implementation is outlined in the following diagrams:


 * Top-down view of the gridspec with diagrams and descriptions for the following types:
 * Gridspec - top-level element in a gridspec
 * Mosaic - groups tiles into grids, or "child" grids into "parent" grids
 * Mosaic grid descriptor - sample grid mosaic types
 * Tile - contiguous and distinct area of grid cells
 * Tile discretisation - sample grid tile discretisations
 * Horizontal coordinate system - description of horizontal coordinate system and axes for tile
 * Vertical coordinate system - description of vertical coordinate system and axes for tile
 * Unstructured cell - possible cell type for unstructured discretisations
 * Contact region - describes where and how grid tiles are connected
 * Overlap - describes grid tiles connected by an overlap
 * Boundary - describes grid tiles that meet but do not overlap

Element cross-referencing
Cross-referencing is used to avoid duplicate or redundant data in the XML gridspec. The gridspec uses "ID" attributes to identify elements that might be referenced from elsewhere in the gridspec. The attributes use the XML schema xs:ID type, which ensures that IDs are unique across a gridspec instance file. Note that this will only work as intended once the gridspec is split up into "child" schemas and instance files for mosaics, tiles and contact regions - see "Known issues". The following elements currently have ID attributes (not shown in the diagrams):


 * Mosaicgrids - i.e. tiles and mosaics
 * Cells - e.g. Unstructured cell
 * Points - e.g. the vertices used by unstructured cells
 * Tilespecs - used when describing contact regions

Elements with IDs are referenced by other elements using the XML schema xs:IDREF type. The following elements contain references to elements elsewhere in the schema:


 * Edges - contain references to vertices - see "Unstructured cell"
 * Tilespecs - a "fully-qualified tile ID" consisting of a reference to a single tile together with references to all the tile's parent mosaics - see "Contact region"
 * Parent cells - contain a reference to the tilespec and a reference to the cell within the tile - see "Overlap"

Cross-referencing should also be used to avoid duplication of vertices shared between unstructured cells (see "Known issues"), and may be used elsewhere in the gridspec in future.

Known issues
Please [mailto:I.R.Henderson@reading.ac.uk contact me] with any issues or suggestions; there are bound to be many things that can be improved at this stage in development! The following issues have been identified so far:


 * Splitting up the gridspec into different files for each mosaic/tile, more modular, better for point/cell IDs which are constrained to be unique across a gridspec instance file (therefore only have to be unique for the tile, rather than across tiles). Balaji says there should be separate files for each mosaic, tile and contact region, e.g. "grid_mosaic.xsd", "grid_tile.xsd", "contact_region.xsd".
 * Version data should be associated with each of the gridspec files. Currently the XML gridspec only has one version number - an attribute of the top-level gridspec element.


 * Cell vertex data is potentially duplicated - many cells may share vertices. A list of vertices should be associated with a tile rather than a cell, then each cell contains references to these vertices rather than the vertices themselves, as is done currently for cell edges (defined by refs to two vertices, rather than duplicating the vertices themselves).


 * How and where should halo regions be described for grids that are split up into multiple "tiles" for parallel processing? (Is this something the gridspec should cover?)


 * How should exchange grids be specified for grid tiles where coordinate axes are specified instead of individual cells (e.g. for regular grids like those used by IGCM and GOLDSTEIN)? Currently, exchange grid cells consist of references to individual "parent" cells in the overlapping grids.  A similar problem may exist for boundary anchor points.


 * Gridspec needs to be extended - e.g. missing cell types for different discretisations. The use of base types/base classes should make the gridspec easy to extend.  This is best done by people who are experts on the different grids in question.


 * Horizontal coordinate systems are represented by an enumeration; vertical coordinate systems by a type hierarchy. This is as in the "gridspec details" UML diagram provided by Balaji.  It may be more consistent and flexible to use type hierarchies for both.