Connectivities in different UGRID file reads can have different dimensions

[dylannelson]

Version

2026.7.1

How did you install UXarray?

Source

What happened?

We encountered an instance while exploring #1717 that lead to different connectivity dimensions existing on the grid after reading in the file located at test/meshfiles/ugrid/fesom/fesom.mesh.diag.nc. Like we saw the dimensions of face_edge_connectivity as (n_face, n_max_face_nodes) vs it normally being (n_face, n_max_face_edges). Below is a few examples of other meshfiles being read in, and looking at their connectivity. All other examples were read in as expected, with one exception that had a different outcome.

Relation to 1717

This is a seemingly separate but related concern to what we saw with n2 being read in instead of two. We want to decide and document this behavior, where n_max_face_nodes can take the place of n_max_face_faces or n_max_face_edges, and if this can cause downstream problems.

This is what we saw with this file (face_X_connectivity ->n_max_face_nodes):

This is what we expected, and saw in other files (face_X_connectivity -> n_max_face_X):

File location / Attributes

This was a file in the FESOM folder, within the existing ugrid folder, as opposed to the standalone FESOM folder. It was read in as a UGRID file following the UGRID pathway within the grid creation pipeline, not the FESOM pipeline.

We attempted to look into whether this is a FESOM problem, or a UGRID problem, and it showed to be a little hard to narrow down and decide where to go from here. Given this was very unexpected, we need to do more testing to narrow down.

More examples

Here's more examples from both different and similar files:

They each varied a lot, and were shown to contain a multitude of different connectivities, but none had the wrong names or had different dimensions like we saw in the original example.

• Some had many connectivities existing on load
• Some had nearly none or 1
• Some were UGRID, some were not
• A regular FESOM2 file was read fine fesom/soufflet-netcdf/grid.nc

After notes:

1. Ugrid connectivity names exist in uxarray/blob/main/uxarray/conventions/ugrid.py and are defined as

    face_node_connectivity -> ('n_face', 'n_max_face_nodes')
    face_edge_connectivity -> ('n_face', 'n_max_face_edges')
    face_face_connectivity -> ('n_face', 'n_max_face_faces')
    edge_node_connectivity -> ('n_edge', 'two')
    edge_face_connectivity -> ('n_edge', 'two')
    node_edge_connectivity -> ('n_node', 'n_max_node_edges')
    node_face_connectivity -> ('n_node', 'n_max_node_faces')

2. This MPAS file is also read in as UGRID, which was unexpected:

• mpas/dyamond-30km/gradient_grid_subset.nc

3. You can use grid.source_grid_spec to look at which path the grid was read in though: (MPAS, UGRID, ICON, FESOM2, ESFM, Exodus, Scrip)

What did you expect to happen?

All files to be read in and have their connectivities and their dimensions to match the conventions described above

Can you provide a MCVE to repoduce the bug?

MESHFILES = "../../uxarray/test/meshfiles/"
mesh_diag = ux.open_grid(MESHFILES + "ugrid/fesom/fesom.mesh.diag.nc")
mesh_diag

[Sevans711]

Thank you for this detailed writeup!

Ugrid connectivity names exist in uxarray/blob/main/uxarray/conventions/ugrid.py and are defined as…

This is a great find find, to me it reads as uxarray implying that those should be the dimension names for those connectivity variables, regardless of the data source. If that is the correct interpretation, it would mean that either (1) the resulting fesom ux.Grid's dimension names are indeed wrong and this is a bug that should be fixed, or (2) the ugrid.py file needs to be updated with comments / maybe a docstring at the top, to clarify that those will not actually always be the dimension names.

For the non-fesom cases, where dimensions of the resulting ux.Grid object match the pattern implied by uxarray/conventions/ugrid.py, do you know if any of the source files originally shared dimension names amongst connectivity variables? I remember seeing that when I opened the fesom file directly using xarray, the data_vars which eventually got renamed to the relevant connectivities all shared the dimension "n3" (as well as "elem", but uxarray is correctly renaming "elem" to "n_face" already when converting to ux.Grid). I am curious if any other source file also shares dimensions amongst connectivity vars like that, and is being handled "properly" already (i.e., this is a fesom-specific issue) or not (i.e., this could happen in other kinds of source files as well, if constructed in a similar way).