Merge pull request #459 from davidhassell/ugrid-2

Reference UGRID conventions in CF

appa.adoc

@@ -4,8 +4,8 @@
 [appendix]
 == Attributes
 
-All CF attributes are listed here except for those that are used to describe grid mappings.
-See Appendix F for the grid mapping attributes.
+All CF attributes are listed here except for those that are used to describe grid mappings and mesh topologies.
+See Appendix F for the grid mapping attributes, and Appendix K for mesh topology attributes.
 
 The "Type" values are **S** for string, **N** for numeric, and **D** for the type of the data variable.
 The "Use" values are **G** for global, **Gr** for applying to groups, **C** for variables containing coordinate data, **D** for data variables, **M** for geometry container variables, **Do** for domain variables, and **-** for variables with a special purpose.
@@ -75,8 +75,8 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 | **`cf_role`**
 | S
 | C
-| <<coordinates-metadata>>
-| Identifies the roles of variables that identify features in discrete sampling geometries.
+| <<coordinates-metadata>>, and <<mesh-topology-variables>> 
+| Identifies the roles of variables that identify features in discrete sampling geometries; and the roles of mesh topology and location index set variables.
 
 | **`climatology`**
 | S
@@ -228,13 +228,31 @@ The index variable indicates that the indexed ragged array representation is bei
 | Provides an example of a leap year for a user defined calendar.
 It is assumed that all years that differ from this year by a multiple of four are also leap years.
 
+| **`location`**
+| S
+| D, Do
+| <<mesh-topology-variables>>, and <<appendix-mesh-topology-attributes>>
+| Specifies the location type within the mesh topology at which the variable is defined.
+
+| **`location_index_set`**
+| S
+| D, Do
+| <<mesh-topology-variables>>, and <<appendix-mesh-topology-attributes>>
+| Specifies a variable that defines the subset of locations of a mesh topology at which the variable is defined.
+
 | **`long_name`**
 | S
 | C, D, Do
 | link:$$http://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"], and <<long-name>>
-| A descriptive name that indicates a variable"s content.
+| A descriptive name that indicates a variable's content.
 This name is not standardized.
 
+| **`mesh`**
+| S
+| D, Do 
+| <<mesh-topology-variables>>, and <<appendix-mesh-topology-attributes>>
+| Specifies a variable that defines a mesh topology.
+
 | **`missing_value`**
 | D
 | C, D

appd.adoc

@@ -431,7 +431,7 @@ No `standard_name` has been defined for `z1`, `z2`, `a`, `href` or `k_c`.
 // But AsciiDoctor will wrap an image title, so assign the title to a 1-pixel transparent image,
 // and put the table immediately thereafter, with its own title:
 [[table-computed-standard-names]]
-.Consistent sets of values for the standard_names of formula terms and the computed_standard_name needed in defining the ocean sigma coordinate, the ocean s-coordinate,  the ocean_sigma over z coordinate, and the ocean double sigma coordinate.
+.Consistent sets of values for the standard_names of formula terms and the computed_standard_name needed in defining the ocean sigma coordinate, the ocean s-coordinate, the ocean_sigma over z coordinate, and the ocean double sigma coordinate.
 image::NFFFFFF-1.0.png[caption=""]
 
 [options="header",cols="1,3,2,3",caption="Table D.1. "]

appi.adoc

@@ -78,6 +78,12 @@ CF-netCDF element
 | Ancillary data variable
 | Metadata that depends on the domain
 
+| Mesh topology variable
+| One or more related domains with cell connectivity
+
+| Location index set variable
+| A domain with cell connectivity
+
 | Formula terms attribute
 | Vertical coordinate system
 
@@ -134,6 +140,12 @@ CF construct
 | Cell measure
 | Cell size or shape
 
+| Domain topology
+| Geospatial topology of domain cells
+
+| Cell connectivity
+| Connectivity of domain cells
+
 | Field ancillary
 | Ancillary metadata which varies within the domain
 
@@ -192,12 +204,24 @@ The domain construct contains properties to describe the domain (in the same sen
 * Coordinate reference constructs.
 * Domain ancillary constructs.
 * Cell measure constructs.
+* Domain topology constructs.
+* Cell connectivity constructs.
 
 All of the constructs contained by the domain construct are optional (as indicated by "0.." in <<figure-field>>).
 
 In CF-netCDF, domain information is stored either implicitly via data variable attributes (such as `coordinates`), or explicitly in a domain variable.
 In the latter case, the domain exists without reference to a data array.
 
+* implicitly via data variable attributes (such as `coordinates`);
+
+* explicitly in a domain variable;
+
+* explicitly in a mesh topology variable, in which case the domain may be one of multiple domains defined by the same variable (for instance, a single mesh topology variable could contain different domains defined respectively at node, edge, and face mesh elements);
+
+* explicitly in a location index set variable that references a subset of another domain defined by a mesh topology variable.
+
+For the explicit cases, the domain exists without reference to a data array.
+
 [[data-model-domain-axis-construct-and-the-data-array]]
 ==== Domain axis construct and the data array
 
@@ -242,7 +266,7 @@ If a domain axis construct does not correspond to a continuous physical quantity
 For example, this is the case for an axis that runs over ocean basins or area types, or for a domain axis that indexes a time series at scattered points.
 These axes are discrete axes in CF-netCDF.
 In such cases cells may be described with one-dimensional auxiliary coordinate constructs for which, provided that there is a cell bounds array to describe the cell extents, the coordinate array is optional, since coordinates are not always well defined for such cells.
-A CF-netCDF geometry container variable is used to store cell bounds without coordinates for a discrete axis.
+A CF-netCDF geometry container variable or mesh topology variable is used to store cell bounds without coordinates for a discrete axis.
 
 In CF-netCDF, when a geometry container variable is present it explicitly describes the geometry type and identifies the node coordinate variables that contain the cell vertices.
 The geometry container variable also identifies a node count variable that contains the number of nodes per cell when more than one cell is present, and a part node count variable that contains the number of nodes per cell part when cells are composed of multipart lines, multipart polygons, or polygons with holes.
@@ -348,6 +372,80 @@ The properties must contain a "measure" property, which indicates which metric o
 It is assumed that the metric does not depend on axes of the domain which are not spanned by the array, along which the values are implicitly propagated.
 CF-netCDF cell measure variables correspond to cell measure constructs.
 
+[[data-model-domain-topology]]
+==== Domain topology construct
+
+A domain topology construct defines the geospatial topology of cells arranged in two or three dimensions in real space but indexed by a single (discrete) domain axis construct, and at most one domain topology construct may be associated with any such domain axis.
+The topology describes topological relationships between the cells - spatial relationships which do not depend on the cell locations - and is represented by an undirected graph, i.e. a mesh in which pairs of nodes are connected by links.
+Each node has a unique arbitrary identity that is independent of its spatial location, and different nodes may be spatially co-located.
+
+The topology may only describe cells that have a common spatial dimensionality, one of:
+
+* Point: A point is zero-dimensional and has no boundary vertices.
+* Edge: An edge is one-dimensional and corresponds to a line connecting two boundary vertices.
+* Face: A face is two-dimensional and corresponds to a surface enclosed by a set of edges.
+
+Each type of cell implies a restricted topology for which only some kinds of mesh are allowed.
+For point cells, every node corresponds to exactly one cell; and two cells have a topological relationship if and only if their nodes are connected by a mesh link.
+For edge and face cells, every node corresponds to a boundary vertex of a cell; the same node can represent vertices in multiple cells; every link in the mesh connects two cell boundary vertices; and two cells have a topological relationship if and only if they share at least one node.
+
+[[figure-mesh-example]]
+[caption="Figure {doc-part}.{counter:figure}. ", reftext=Figure {doc-part}.{figure}]
+[.text-center]
+.A topology defined by a mesh with five nodes and six links.
+image::images/mesh_figure.svg[,100%,pdfwidth=25vw,align="center"]
+
+For example, the mesh depicted in <<figure-mesh-example>> may be used with any of three domain topology constructs for domains comprising two face cells (one triangle and one quadrilateral), six edge cells, and five point cells respectively.
+
+A domain topology construct contains an array defining the mesh, and properties to describe it.
+There must be a property indicating the spatial dimensionality of the cells.
+The array values comprise the node identities, and all array elements that refer to the same node must contain the same value, which must differ from any other value in the array.
+The array spans the domain axis construct and also has a ragged dimension, whose function depends on the spatial dimensionality of the cells.
+
+For each point cell, the first element along the ragged dimension contains the node identity of the cell, and the following elements contain in arbitrary order the identities of all the cells to which it is connected by a mesh link.
+
+For each edge or face cell, the elements along the ragged dimension contain the node identities of the boundary vertices of the cell, in the same order that the boundary vertices are stored by the auxiliary coordinate constructs.
+Each boundary vertex except the last is connected by a mesh link to the next vertex along the ragged dimension, and the last vertex is connected to the first.
+
+When a domain topology construct is present it is considered to be definitive and must be used in preference to the topology implied by inspection of any other constructs, which is not guaranteed to be the same.
+
+In CF-netCDF a domain topology construct can only be provided for a UGRID mesh topology variable.
+The information in the construct array is supplied by the UGRID "edge_nodes_connectivity" variable (for edge cells) or "face_nodes_connectivity" variable (for face cells).
+The topology for node cells may be provided by any of these three UGRID variables.
+The integer indices contained in the UGRID variable may be used as the mesh node identities, although the CF data model attaches no significance to the values other than the fact that some values are the same as others.
+The spatial dimensionality property is provided by the "location" attribute of a variable that references the UGRID mesh topology variable, i.e. a data variable or a UGRID location index set variable.
+
+A single UGRID mesh topology defines multiple domain constructs and defines how they relate to each other.
+For instance, when "face_node_connectivity" and "edge_node_connectivity" variables are both present there are three implied domain constructs - one each for face, edge and point cells - all of which have the same mesh and so are explicitly linked (e.g. it is known which edge cells define each face cell).
+The CF data model has no mechanism for explicitly recording such relationships between multiple domain constructs.
+Whether or not two domains have the same mesh may be reliably deternined by inspection, thereby allowing the creation of netCDF datasets containing UGRID mesh topology variables.
+
+The restrictions on the type of mesh that may be used with a given cell spatial dimensionality excludes some meshes which can be described by an undirected graph, but is consistent with UGRID encoding within CF-netCDF.
+UGRID also describes meshes for three-dimensional volume cells that correspond to a volume enclosed by a set of faces, but how the nodes relate to volume boundary vertices is undefined and so volume cells are currently omitted from the CF data model.
+
+[[data-model-cell-connectivity]]
+==== Cell connectivity construct
+
+A cell connectivity construct defines explicitly how cells arranged in two or three dimensions in real space but indexed by a single domain (discrete) axis are connected.
+Connectivity can only be provided when the domain axis construct also has a domain topology construct, and two cells can only be connected if they also have a topological relationship.
+For instance, the connectivity of two-dimensional face cells could be characterised by whether or not they have shared edges, where the edges are defined by connected nodes of the domain topology construct.
+
+The cell connectivity construct consists of an array recording the connectivity, and properties to describe the data.
+There must be a property indicating the condition by which the connectivity is derived from the domain topology.
+The array spans the domain axis construct with the addition of a ragged dimension.
+For each cell, the first element along the ragged dimension contains the unique identity of the cell, and the following elements contain in arbitrary order the identities of all the other cells to which the cell is connected.
+Note that the connectivity array for point cells is, by definition, equivalent to the array of the domain topology construct.
+
+When cell connectivity constructs are present, they are considered to define the connectivity of the cells.
+Exactly the same connectivity information could be derived from the domain topology construct.
+Connectivity information inferred from inspection of any other constructs is not guaranteed to be the same.
+
+In CF-netCDF a cell topology construct can only be provided by a UGRID mesh topology variable.
+The construct array is supplied either indirectly by any of the UGRID variables that are used to define a domain topology construct, or directly by the UGRID "face_face_connectivity" variable (for face cells).
+In the direct case, the integer indices contained in the UGRID variable may be used as the cell identities, although the CF data model attaches no significance to the values other than the fact that some values are the same as others.
+
+Restricting the types of connectivity to those implied by the geospatial topology of the cells precludes connectivity derived from any other sources, but is consistent with UGRID encoding within CF-netCDF.
+
 [[data-model-field-ancillary]]
 ==== Field ancillary constructs
 

appk.adoc

@@ -0,0 +1,148 @@
+
+[[appendix-mesh-topology-attributes, Appendix K, Mesh Topology Attributes]]
+
+[appendix]
+== Mesh Topologies
+
+The CF attributes listed here may be used to define mesh topologies (<<mesh-topology-variables>>).
+This list is intended as a summary of the attributes that have been standardized via the UGRID conventions <<UGRID>>, which should be consulted for further details.
+UGRID attributes that are not currently recognised by the CF convensions are included in the list.
+
+The "Type" values are **S** for string and **I** for integer.
+The "Use" values are **MT** for mesh topology variables, **LIS** for location index set variables, **D** for data variables, **Do** for domain variables, and **Con** for connectivity index variables.
+
+[[table-mesh-topology-attributes]]
+.Mesh topology attributes
+[options="header",cols="6,2,4,12",caption="Table K.1. "]
+|===============
+|{set:cellbgcolor!}
+Attribute
+| Type
+| Use
+| Description
+
+| **`boundary_node_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying the nodes that define where boundary condtions have been provided. Not currently recognised by the CF conventions.
+
+| **`cf_role`**
+| S
+| MT, LIS
+| Specifies the roles of mesh topology or location index set variables.
+
+| **`coordinates`**
+| S
+| LIS
+| Specifies the auxiliary coordinate variables associated with the characteristic locations of the subset of mesh topology locations.
+
+| **`edge_coordinates`**
+| S
+| MT
+| Specifies the auxiliary coordinate variables associated with the characteristic location of the edges (commonly the midpoint).
+
+| **`edge_dimension`**
+| S
+| MT
+| Specifies the dimension used to index the nodes in the edge connectivity variable.
+
+| **`edge_face_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying all faces that share the same edge, i.e. are neighbours to an edge. 
+
+| **`edge_node_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying for every edge the indices of its begin and end nodes.
+
+| **`face_coordinates`**
+| S
+| MT
+| Specifies the auxiliary coordinate variables associated with the characteristic location of faces. 
+
+| **`face_dimension`**
+| S
+| MT
+| Specifies the dimension used to index the edges in the face connectivity variable.
+
+| **`face_edge_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying for every face the indices of its edges.
+
+| **`face_face_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying all faces that share an edge with each face, i.e. are neighbours. 
+
+| **`face_node_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying for every face the indices of its corner nodes.
+
+| **`location`**
+| S
+| D, Do, LIS
+| Specifies the location within the mesh topology at which the variable is defined.
+
+| **`location_index_set`**
+| S
+| D, Do
+| Specifies a variable that defines the subset of locations of a mesh topology at which the variable is defined.
+
+| **`mesh`**
+| S
+| D, Do, LIS
+| Specifies a variable that defines a mesh topology.
+
+| **`node_coordinates`**
+| S
+| MT
+| Specifies the auxiliary coordinate variables representing the node locations (latitude, longitude, or other spatial coordinates, and optional elevation or other coordinates).
+
+| **`start_index`**
+| I
+| LIS, Con
+| Indicates whether 0- or 1-based indexing is used to identify connected geometric elements; connectivity indices are 0-based by default.
+
+| **`topology_dimension`**
+| I
+| MT
+| Indicates the highest dimensionality of the geometric elements.
+
+| **`volume_coordinates`**
+| S
+| MT
+| Specifies the auxiliary coordinate variables associated with the characteristic location of volumes. Not currently recognised by the CF conventions.
+
+| **`volume_dimension`**
+| S
+| MT
+| Specifies the dimension used to index the faces in the volume connectivity variable. Not currently recognised by the CF conventions.
+
+| **`volume_edge_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying for every volume the indices of its edges. 
+
+| **`volume_face_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying for every volume the indices of its faces. Not currently recognised by the CF conventions.
+
+| **`volume_node_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying for every volume the indices of its corner nodes. Not currently recognised by the CF conventions.
+
+| **`volume_shape_type`**
+| S
+| MT
+| Specifies a flag variable that specifies for every volume its shape. Not currently recognised by the CF conventions.
+
+| **`volume_volume_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying all volumes that share a face with each volume, i.e. are neighbours. Not currently recognised by the CF conventions.
+|===============

bibliography.adoc

@@ -19,3 +19,4 @@ OGC document 12-063. 1st May 2015.
 - [[[W3C]]]  link:$$http://www.w3.org/$$[World Wide Web Consortium (W3C)].
 - [[[XML]]]  link:$$http://www.w3.org/TR/1998/REC-xml-19980210$$[Extensible Markup Language (XML) 1.0]. T. Bray, J. Paoli, and C.M. Sperberg-McQueen.  10 February 1998.
 - [[[CFDM]]]  link:$$http://doi.org/10.5194/gmd-10-4619-2017$$[A data model of the Climate and Forecast metadata conventions (CF-1.6) with a software implementation (cf-python v2.1)]. Hassell, D., Gregory, J., Blower, J., Lawrence, B. N., and Taylor, K. E.: _Geosci. Model Dev._, 10, 4619-4646, 2017.
+- [[[UGRID]]]  link:$$https://ugrid-conventions.github.io/ugrid-conventions$$[UGRID Conventions for storing unstructured (or flexible mesh) data in netCDF files]