Reference UGRID conventions in CF

[rsignell-usgs]

As discussed in Trac ticket 171 we would like to associate a specific version of UGRID with each version of CF.

We propose to simply add a section 1.5 to the Conventions Document called "Relationship to the UGRID Conventions" which would say:

UGRID is a convention for unstructured (e.g. triangular) grids that supplements the CF Conventions, including specification of grid topology and location of data on grid elements. Each version of CF is associated with a particular version of UGRID through the Conventions attribute in 2.6.1.

Then in Section 2.6.1, modify the beginning to read:

We recommend that netCDF files that follow these conventions indicate this by setting the NUG defined global attribute Conventions to the string value "CF-1.8" which also implies "UGRID-1.0".

[davidhassell]

I support this change. The aim (mentioned on the Trac ticket) of "ensuring they [CF and UGRID] remain consistent and complementary" is a very good goal. A couple of questions:

How will UGRID ensure that it is up to date with CF? I presume that this would not be the responsibility of proposers of changes to CF. And vice versa.

What would be the policy of matching versions of CF and UGRID? CF-1.8 and UGRID-1.0 are proposed for now - when CF-1.9 arises, would the latest UGRID version be specified by default, or would it it stay at 1.0?

Thanks, David

[rsignell-usgs]

@davidhassell thanks for the comments. I think this would be worked out on a case-by-base basis with joint approval by the CF and UGRID Governance committees.

[davidhassell]

OK - in that case, I think an explicit addition to the governance rules (https://github.com/cf-convention/cf-convention.github.io/blob/master/rules.md) would be useful.

I've been thinking about the similar issue that arises when considering if a change to CF is compatible with the CF data model, for which I will soon be suggesting these additional rules (just think "UGRID" instead of "CF data model"):

* All new proposals will be assessed to see if the new features defined in the proposal map onto the CF data model.

* The assessment will be carried out by a member of the conventions committee or another suitably qualified person. If no-one volunteers, the chairman of the committee will ask someone to do it.

For the CF data model case, there are more rules than this, about what to do depending on the result of the assessment - which I'm happy to share - but you get the drift.

UGRID also has the issue (unlike the CF data model) that it may change independently of CF, so there needs to be some sort of a symmetry in these rules, too.

These rules may seem at bit over the top, but they're not really more draconian than the existing rules for changes to CF, and only a very few people will ever need to worry about them, i.e. the UGRID (or CF data model) experts, and it gives those people a checklist to make sure that we don't wander off piste.

Thanks, David

[rsignell-usgs]

@davidhassell, that sounds reasonable. It's also a reminder to us at UGRID that we need to add rules similar to https://github.com/cf-convention/cf-convention.github.io/blob/master/rules.md. I've raised the issue here.

[davidhassell]

I think that the biggest issue concerning versioning is that every enhancement to CF needs to be checked for UGRID inconsistencies, and every enhancement to UGRID needs to be checked for CF inconsistencies.

How much a proposer of a change needs to know about this is up for discussion.

For the CF data model, I have suggested (cf-convention/cf-convention.github.io@a170505) that the proposer does not need to know about data model issues - the default someone will look at the proposal on their behalf and decide if any action needs to be taken. Action could mean changing the proposal or changing the data model. This approach could also work for how CF changes might affect UGRID, and vice versa, but there might be alternative approaches that are better suited to the UGRID (and CF data model) case - I would welcome any thoughts on this.

For the most part, I imagine the no action would be required - all 28 tickets that contributed to CF-1.7 had no impact on the CF data model.

That said, there are two issues for CF-1.8 that will require changes to the data model - geometries and UGRID. These changes have been worked out and are backwards compatible (more on that another time), so all is well! Such structurally challenging changes are unusual, though.

Thanks, David

[davidhassell]

Hello,

I have been looking at the Finite Element based CF proposal for Unstructured Grid data model (https://publicwiki.deltares.nl/display/NETCDF/Finite+Element+based+CF+proposal+for+Unstructured+Grid+data+model) which was written up some time ago by Bert. This proposes an encoding for the information required for a consistent spatial interpretation of the values.

Given that UGRID is going to be incorporated into CF [1], I was looking at this to see if backward incompatible changes could occur if this new proposal (or something like it) become part of UGRID at a later date.

[1] it seems like this will indeed happen, once the management side is sorted out ...

My conclusion from a quick read of Bert's document was that adding the "Function Space" capability, would not impact on files encoded using UGRID 1.0 - which would be good. However, the proposal does suggest renaming certain special attributes (e.g. face_node_connectivity becomes element_vertex_connectivity). This could be bad for CF backwards compatibility, but, I presume, is easily avoided with a little thought at this stage.

Does all this sound like a reasonable assessment?

Thanks,
David

[dham]

I think that this is essentially correct. The naming issues are also not insurmountable. Finite element has its own conventions, but they are just naming conventions. If UGRID has finite difference naming then this will merely be a bit confusing for finite element users.

In the specific cases above, there are two relevant differences to note:

1. Vertex vs node. Node means something quite different in finite element (a node is a basis function in the dual space to the finite element space), which is why finite element codes usually talk about vertices when discussing the mesh topology.

2. face vs element or cell. node, edge, face, volume are names for mesh entities of a given dimension. Finite element is often more concerned with codimension, which counts downwards from the mesh dimension. A cell (or element) is an entity of codimension 0, i.e. an entity of maximal dimension. On a 3D mesh the cells are volumes and on a 2D mesh they are faces (cell is also defined for 2D or 1D meshes). A facet is an entity of codimension 1. Facets form the boundaries between cells. On a 3D mesh, the facets are faces while on a 2D mesh they are edges, and on a 1D mesh they are nodes. Given that a UGRID mesh knows its dimension, it is possible for software to identify the cells or facets so the difference in naming convention is not so significant.

[davidhassell]

Hello,

Some colleagues were asking after the status of this proposal. As far as I'm aware, there are no outstanding objections other than the requirement to spell out some rules for the co-management of the two conventions: CF and UGRID.

The CF data model has now been accepted, and the rules for its management will be in CF-1.9. I think there are some similarities between the requirements rules for evolving the data model, and for evolving UGRID.

I am happy to draft some rules for UGRID, if that helps to get the ball rolling.

Thanks,
David

[JonathanGregory]

Yes, please. That would be most helpful. Jonathan

[davidhassell]

Here are my proposed additions to https://github.com/cf-convention/cf-convention.github.io/blob/master/rules.md. I probably haven't quite got it yet, but it's a start.

A key thing to note is the second line: "The assessment will be carried out by a member of the conventions committee or another suitably qualified person. If no-one volunteers, the chairman of the committee will ask someone to do it."

What this means is that every enhancement proposal must be "signed off" for any UGRID issues. Almost always this will be a trivial task (e.g. the introduction a new grid mapping attribute parameter - no problem!), but it needs to be done.

For simple cases, as in the example just mentioned, someone who is familiar (rather than expert) with UGRID could take care of this, but for more complicated proposals, the opinion of an expert from the UGRID community must be available.

The first and last sentences covers how to increment the version of UGRID that is acceptable to a give version of CF.

---

Additional rules relating to the UGRID conventions

All new proposals will be assessed to see if the new features defined in the proposal are compatible with the named version of UGRID that is defined for the current version of the CF conventions.

The assessment will be carried out by a member of the conventions committee or another suitably qualified person. If no-one volunteers, the chairman of the committee will ask someone to do it.

If the proposal is deemed to be not compatible with UGRID in some way, then an attempt must be made to modify the proposal so that its new features are compatible with UGRID, and in such a way that the proposal's intent is not compromised.

If the proposal cannot be acceptably modified to conform to the UGRID conventions, then UGRID will need to be modified to accommodate the new features. If UGRID is extended or generalized in some way that allows the new features but does not affect its existing structure and functionality, the proposal is considered backwards compatible. This is the preferred solution.

Any such changes to UGRID must be defined in general terms, and preferably with a detailed description of the UGRID alterations. However, to facilitate the progress of a proposal that requires UGRID changes, it is sufficient for the general nature of the UGRID modifications to be identified, on the understanding that the UGRID conventions will be updated in detail at a later date, possibly after the proposal has been accepted in all other aspects. Final acceptance will always rely on the completion of changes to the UGRID conventions, which is at the discretion of the UGRID community.

The UGRID conventions exist independently from CF and have their own repository and governance. Therefore the acceptance of a new version of UGRID, whether it arises from a change to CF or from an independent change to UGRID itself, must be raised and discussed in its own enhancement proposal in the usual manner. It follows that a change to CF that requires a change to UGRID will be associated with two GitHub issues - one for the change to CF and one for accepting the new version of UGRID.

---