[Deprecated] Reference UGRID conventions in CF

appa.adoc

@@ -5,8 +5,8 @@
 == 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.
+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
@@ -79,9 +79,9 @@ Attribute
 
 | **`cf_role`**
 | S
-| C
-| <<coordinates-metadata>>
-| Identifies the roles of variables that identify features in discrete sampling geometries
+| C, -
+| <<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
@@ -231,11 +231,29 @@ formula in the definition.
 | <<calendar>>
 | 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. This name is not standardized.
+| 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

appi.adoc

@@ -115,6 +115,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
 
@@ -177,6 +183,9 @@ CF construct
 | Cell measure
 | Cell size or shape
 
+| Domain topology
+| Connectivity of domain cells
+
 | Field ancillary
 | Ancillary metadata which varies within the domain 
 
@@ -282,14 +291,23 @@ construct) and relates the following metadata constructs
 
 * Cell measure constructs.
 
+* Domain topology constructs.
+
 All of the constructs contained by the domain construct are optional
 (as indicated by "0.." in <<figure-field, Figure I.2>>).
 
-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.
+In CF-netCDF, domain information may be stored in a number of ways:
+
+* 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 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
 
@@ -326,7 +344,7 @@ of the domain axis constructs, properties to describe the coordinates
 (in the same sense as for the field construct), an optional data array
 of cell bounds recording the extents of each cell, and any extra
 arrays needed to interpret the cell bounds values. The data array of
-the coordinate values is required, execpt for the special cases
+the coordinate values is required, except for the special cases
 described below.
 
 There are two distinct types of coordinate construct: dimension
@@ -596,6 +614,47 @@ 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 describes the connectivity of domain cells indexed
+by a subset of the domain axis constructs. When two cells are
+connected, operations on the data stored on them may be assumed to be
+continuous across their common boundary. A domain topology construct
+(<<figure-field, Figure I.2>>) describes logically and explicitly the
+domain topology of cells indexed by a single domain axis construct.
+
+A domain topology construct contains a connectivity array that spans a
+single domain axis construct with the addition of an extra dimension
+of the same size, such that each dimension indexes the cells. The
+array is symmetrical, and each element indicates whether the pair of
+cells to which its indices refer are connected. The connectivity of a
+cell to itself is undefined, so the diagonal elements of this array
+are ignored. A domain construct may contain at most one domain
+topology construct.
+
+For any subset of the domain axis constructs, excluding a domain axis
+construct for which there is a domain topology construct, there is an
+implicit domain topology that is defined by a function of the physical
+contiguousness of the cells, and/or the nature of the real world or
+simulated processes that produced the data. For example, in a field
+which contains both land and ocean cells, connections between land and
+ocean cells might be excluded for some physical processes. The
+description of such an implicit network topology may require metadata
+that is external to CF.
+
+In CF-netCDF a domain topology can only be provided for a domain
+defined by a UGRID mesh topology variable. In this case, the
+connectivity array is supplied by a UGRID connectivity variable, such
+as a "face_face_connectivity" variable, that is referenced from a mesh
+topology variable. The information represented by the symmetrical
+connectivity array of the domain topology construct in the CF data
+model is stored in a different but equivalent way in UGRID. The
+trailing dimension of a UGRID connectivity variable's data records,
+for each cell, the indices of the other cells to which it is connected
+(padded with missing data if a cell has fewer connections than some
+others).
+
 [[data-model-field-ancillary]]
 ==== Field ancillary constructs
 

appk.adoc

@@ -0,0 +1,149 @@
+
+[[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.
+
+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, and **Do** for domain 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 each boundary element (i.e. the nodes that defin each edge of a face, or the nodes that define each face of a volume).
+
+| **`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`**
+| I
+| MT
+| Specifies the position of 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`**
+| I
+| MT
+| Specifies the position of 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
+| LIS, D, Do
+| 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
+| LIS, D, Do
+| 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
+| MT
+| 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. 
+
+| **`volume_dimension`**
+| I
+| MT
+| Specifies the position of the dimension used to index the faces in the volume connectivity variable.
+
+| **`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. 
+
+| **`volume_node_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying for every volume the indices of its corner nodes.
+
+| **`volume_shape_type`**
+| S
+| MT
+| Specifies a flag variable that specifies for every volume its shape.
+
+| **`volume_volume_connectivity`**
+| S
+| MT
+| Specifies an index variable identifying all volumes that share a face with each volume, i.e. are neighbours.
+|===============

bibliography.adoc

@@ -30,3 +30,4 @@
 - [[[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, https://doi.org/10.5194/gmd-10-4619-2017, 2017. 
+- [[[UGRID]]]  link:$$https://ugrid-conventions.github.io/ugrid-conventions$$[UGRID Conventions for storing unstructured (or flexible mesh) data in netCDF files]

ch01.adoc

@@ -180,3 +180,15 @@ The CF conventions define attributes which enable the description of data proper
 
 * Data compression for variables with missing values.
 
+
+[[ugrid-conventions, Section 1.6, "UGRID Conventions"]]
+=== UGRID Conventions
+
+These conventions implicitly incorporate the UGRID conventions for storing unstructured (or flexible mesh) data in netCDF files using mesh topologies <<UGRID>>.
+Only version 1.0 of the UGRID conventions is allowed.
+The UGRID conventions description is referenced from, rather than rewritten into, this document, i.e. the canonical description of how to store mesh topologies is only to be found at <<UGRID>>.
+However, a summary with examples can be found in <<mesh-topology-variables>>, and to reduce the chance of ambiguities arising from their accidental re-use, all of the UGRID standardized attributes are specified in <<appendix-mesh-topology-attributes>> and <<attribute-appendix>>.
+
+The UGRID conventions have their own conformance document, which
+should be used in conjunction with the CF conformance document when
+checking the validity of datasets.