From 509898bd1f856d91e67519713b900d05ad276fd6 Mon Sep 17 00:00:00 2001 From: Sam Evans <47793072+Sevans711@users.noreply.github.com> Date: Mon, 27 Jul 2026 16:29:19 -0400 Subject: [PATCH 1/6] Clarify in docs: spherical, 2D grid; convex faces --- docs/getting-started/freq-asked-questions.rst | 12 +++++++++++- docs/getting-started/overview.rst | 6 ++++++ docs/user-guide/grid-formats.rst | 14 +++++++++++++- 3 files changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/freq-asked-questions.rst b/docs/getting-started/freq-asked-questions.rst index 7d3e60d95..58ef7b26c 100644 --- a/docs/getting-started/freq-asked-questions.rst +++ b/docs/getting-started/freq-asked-questions.rst @@ -4,4 +4,14 @@ Frequently Asked Questions ========================== -Coming soon! +What does UXarray assume about grids? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +UXarray assumes that each grid spans some or all of a 2D spherical surface, and contains only convex faces. +While other dimensions such as time or elevation can be represented easily enough, +the unstructured part of the grid cannot vary across those dimensions. +UXarray also assumes that the grid can be represented using UGRID conventions, +even if it isn't input directly in UGRID format. +See also: `Supported Models & Grid Formats `_. + + +Other questions coming soon! diff --git a/docs/getting-started/overview.rst b/docs/getting-started/overview.rst index d72fdad11..bf14067bc 100644 --- a/docs/getting-started/overview.rst +++ b/docs/getting-started/overview.rst @@ -34,6 +34,12 @@ defined by the 2D Flexible Mesh Topology in the UGRID conventions, which can con mix of triangles, quadrilaterals, or other geometric faces. These types of Unstructured Grids may have structured vertical levels. +.. note:: + UXarray focuses on 2D unstructured grids which lie entirely on the surface of a sphere, + and contain only convex faces. Data spanning extra dimensions such as time or elevation + can be represented easily enough, as long as the grid does not vary across them. + Other types of grids are not supported. + Core Data Structures ==================== diff --git a/docs/user-guide/grid-formats.rst b/docs/user-guide/grid-formats.rst index 021f04786..6a3ac576a 100644 --- a/docs/user-guide/grid-formats.rst +++ b/docs/user-guide/grid-formats.rst @@ -46,10 +46,22 @@ References * https://cf-convention.github.io/Data/cf-conventions/cf-conventions-1.13/cf-conventions.html#ugrid-conventions * https://cf-convention.github.io/Data/cf-conventions/cf-conventions-1.13/cf-conventions.html#mesh-topology-variables + +Additional Assumptions of UXarray +================================= + +UXarray additionally assumes that the unstructured parts of a grid +span some or all of a 2D spherical surface, and that all faces are convex. +Additional dimensions such as time or elevation can be represented easily enough +by including corresponding extra dimensions on the data variables. +However, the faces, nodes, and edges of each unstructured grid must lie entirely +on the surface of a sphere. + + Projected (Non-Spherical) Coordinates -------------------------------------- -UGRID does not assume a sphere — some regional and coastal models write UGRID +UGRID itself does not assume a sphere — some regional and coastal models write UGRID files with **projected coordinates** (e.g. a Lambert Conformal or Albers Equal Area projection) in units of meters rather than degrees. UXarray detects this automatically from the CF metadata already present on the coordinate variables: From 51da9cc4a73fd23baccd223627d5c89a6537a1d3 Mon Sep 17 00:00:00 2001 From: Sam Evans <47793072+Sevans711@users.noreply.github.com> Date: Tue, 28 Jul 2026 09:56:06 -0400 Subject: [PATCH 2/6] clarify docs: spherical, 2D, convex -- update Updates in response to PR review (see #1626) --- docs/getting-started/freq-asked-questions.rst | 24 ++++++++++++------- docs/getting-started/overview.rst | 10 ++++---- docs/user-guide/grid-formats.rst | 14 ++++++----- 3 files changed, 29 insertions(+), 19 deletions(-) diff --git a/docs/getting-started/freq-asked-questions.rst b/docs/getting-started/freq-asked-questions.rst index 58ef7b26c..023e5e84d 100644 --- a/docs/getting-started/freq-asked-questions.rst +++ b/docs/getting-started/freq-asked-questions.rst @@ -4,14 +4,22 @@ Frequently Asked Questions ========================== -What does UXarray assume about grids? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UXarray assumes that each grid spans some or all of a 2D spherical surface, and contains only convex faces. -While other dimensions such as time or elevation can be represented easily enough, -the unstructured part of the grid cannot vary across those dimensions. -UXarray also assumes that the grid can be represented using UGRID conventions, -even if it isn't input directly in UGRID format. -See also: `Supported Models & Grid Formats `_. +What foundational assumptions does UXarray make about grids and geometry? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +UXarray assumes horizontally unstructured grids, consistent with the +`UGRID conventions' 2D flexible mesh topology `_, +with the extra assumption that all grid faces/cells are convex (all angles less than 180 degrees). +UXarray supports extra dimensions such as elevation or time by treating them separately. +For example, grids with vertical levels are treated as per the +`UGRID conventions' 3D layered mesh topology `_. +Fully 3D unstructured topology is not supported. + +UXarray's geometry algorithms assume the horizontal portion of the grid lies on a spherical surface, +spanning either globally (the entire sphere) or regionally (only a portion of the sphere). +The sphere radius can be adjusted but a unit sphere is assumed by default. +Coordinates default to spherical (latitude/longitude), but Cartesian coordinates (x, y, z) are supported as well. + +See also: `Supported Models & Grid Formats <../user-guide/grid-formats.rst>`_. Other questions coming soon! diff --git a/docs/getting-started/overview.rst b/docs/getting-started/overview.rst index bf14067bc..40972ca67 100644 --- a/docs/getting-started/overview.rst +++ b/docs/getting-started/overview.rst @@ -32,13 +32,13 @@ UGRID conventions at the data loading step. Specifically, our core functionality is built around horizontally Unstructured Grids as defined by the 2D Flexible Mesh Topology in the UGRID conventions, which can contain a mix of triangles, quadrilaterals, or other geometric faces. These types of Unstructured -Grids may have structured vertical levels. +Grids may have structured vertical levels, as described by the +3D Layered Mesh Toplogy in the UGRID conventions. .. note:: - UXarray focuses on 2D unstructured grids which lie entirely on the surface of a sphere, - and contain only convex faces. Data spanning extra dimensions such as time or elevation - can be represented easily enough, as long as the grid does not vary across them. - Other types of grids are not supported. + While 3D grids with vertical levels are supported, fully 3D unstructured topology is not. + Also, UXarray additionally assumes the horizontal portion of the grid lies on a spherical surface, + and that all grid faces/cells are convex (all angles less than 180 degrees). Core Data Structures diff --git a/docs/user-guide/grid-formats.rst b/docs/user-guide/grid-formats.rst index 6a3ac576a..cfdcd1a06 100644 --- a/docs/user-guide/grid-formats.rst +++ b/docs/user-guide/grid-formats.rst @@ -50,12 +50,14 @@ References Additional Assumptions of UXarray ================================= -UXarray additionally assumes that the unstructured parts of a grid -span some or all of a 2D spherical surface, and that all faces are convex. -Additional dimensions such as time or elevation can be represented easily enough -by including corresponding extra dimensions on the data variables. -However, the faces, nodes, and edges of each unstructured grid must lie entirely -on the surface of a sphere. +UXarray assumes horizontally unstructured grids, consistent with the +UGRID conventions' 2D flexible mesh topology, +with the extra assumption that all grid faces/cells are convex (all angles less than 180 degrees). +Fully 3D unstructured topology is not supported, but grids with vertical levels are supported +as described by the UGRID conventions' 3D layered mesh topology. + +UXarray's geometry algorithms also assume the horizontal portion of the grid lies on a spherical surface. +The sphere radius can be adjusted but a unit sphere is assumed by default. Projected (Non-Spherical) Coordinates From 6804e791d95802d57ce6dd5305c74730088e3d5f Mon Sep 17 00:00:00 2001 From: Sam Evans <47793072+Sevans711@users.noreply.github.com> Date: Tue, 28 Jul 2026 13:32:31 -0400 Subject: [PATCH 3/6] clarify docs: spherical, 2D, convex -- update 2 Updates in response to PR review 2 (see #1626) --- docs/getting-started/overview.rst | 8 +++---- docs/user-guide/grid-formats.rst | 35 +++++++++++++++---------------- 2 files changed, 21 insertions(+), 22 deletions(-) diff --git a/docs/getting-started/overview.rst b/docs/getting-started/overview.rst index 40972ca67..d2eee4ac6 100644 --- a/docs/getting-started/overview.rst +++ b/docs/getting-started/overview.rst @@ -29,11 +29,11 @@ single convention for our grid representation instead of having separate ones fo grid format, meaning that we encode all supported unstructured grid formats in the UGRID conventions at the data loading step. -Specifically, our core functionality is built around horizontally Unstructured Grids as -defined by the 2D Flexible Mesh Topology in the UGRID conventions, which can contain a -mix of triangles, quadrilaterals, or other geometric faces. These types of Unstructured +Specifically, our core functionality is built around horizontally Unstructured Grids as defined by the +`UGRID conventions' 2D flexible mesh topology `_, +which can contain a mix of triangles, quadrilaterals, or other geometric faces. These types of Unstructured Grids may have structured vertical levels, as described by the -3D Layered Mesh Toplogy in the UGRID conventions. +`UGRID conventions' 3D layered mesh topology `_. .. note:: While 3D grids with vertical levels are supported, fully 3D unstructured topology is not. diff --git a/docs/user-guide/grid-formats.rst b/docs/user-guide/grid-formats.rst index cfdcd1a06..6618edb83 100644 --- a/docs/user-guide/grid-formats.rst +++ b/docs/user-guide/grid-formats.rst @@ -22,10 +22,11 @@ models have their own grid format (e.g. MPAS, ICON). Below is a list of support * FESOM2 * HEALPix -UGRID -===== +UGRID in UXarray +================ -The UGRID conventions are a standard for for storing unstructured grid (a.k.a. unstructured mesh, +The `UGRID conventions `_ +are a standard for for storing unstructured grid (a.k.a. unstructured mesh, flexible mesh) model data in a Unidata Network Common Data Form (NetCDF) file. These conventions are focussed on representing data for environmental applications, hence the motivation for @@ -39,27 +40,25 @@ The standard was developed over a period of several years through the UGRID Goog different unstructured grid modeling communities (including SELFE, ELCIRC, FVCOM, ADCIRC). From these discussions Bert Jagers (Deltares) created the first draft of this document, and the community worked to develop version 1.0. -References ----------- +UXarray in particular assumes horizontally unstructured grids, consistent with the +UGRID conventions' 2D flexible mesh topology, +with the extra assumption that all grid faces/cells are convex (all angles less than 180 degrees). +UXarray also supports grids with vertical levels as described by the +UGRID conventions' 3D layered mesh topology, +but it does not support fully 3D unstructured topology. + +.. note:: + UXarray's geometry algorithms also assume the horizontal portion of the grid lies on a spherical surface. + The sphere radius can be adjusted but a unit sphere is assumed by default. + +UGRID References +---------------- * https://ugrid-conventions.github.io/ugrid-conventions/#ugrid-conventions-v10 * https://github.com/ugrid-conventions/ugrid-conventions * https://cf-convention.github.io/Data/cf-conventions/cf-conventions-1.13/cf-conventions.html#ugrid-conventions * https://cf-convention.github.io/Data/cf-conventions/cf-conventions-1.13/cf-conventions.html#mesh-topology-variables -Additional Assumptions of UXarray -================================= - -UXarray assumes horizontally unstructured grids, consistent with the -UGRID conventions' 2D flexible mesh topology, -with the extra assumption that all grid faces/cells are convex (all angles less than 180 degrees). -Fully 3D unstructured topology is not supported, but grids with vertical levels are supported -as described by the UGRID conventions' 3D layered mesh topology. - -UXarray's geometry algorithms also assume the horizontal portion of the grid lies on a spherical surface. -The sphere radius can be adjusted but a unit sphere is assumed by default. - - Projected (Non-Spherical) Coordinates -------------------------------------- From b550b1cc1899191d34f5bac5263e0fa4cf9c882b Mon Sep 17 00:00:00 2001 From: Sam Evans <47793072+Sevans711@users.noreply.github.com> Date: Tue, 28 Jul 2026 13:59:16 -0400 Subject: [PATCH 4/6] remove "horizontal" in "grid lies on sphere" docs --- docs/getting-started/freq-asked-questions.rst | 2 +- docs/getting-started/overview.rst | 2 +- docs/user-guide/grid-formats.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/freq-asked-questions.rst b/docs/getting-started/freq-asked-questions.rst index 023e5e84d..4e6fa3024 100644 --- a/docs/getting-started/freq-asked-questions.rst +++ b/docs/getting-started/freq-asked-questions.rst @@ -14,7 +14,7 @@ For example, grids with vertical levels are treated as per the `UGRID conventions' 3D layered mesh topology `_. Fully 3D unstructured topology is not supported. -UXarray's geometry algorithms assume the horizontal portion of the grid lies on a spherical surface, +UXarray's geometry algorithms assume the grid lies on a spherical surface, spanning either globally (the entire sphere) or regionally (only a portion of the sphere). The sphere radius can be adjusted but a unit sphere is assumed by default. Coordinates default to spherical (latitude/longitude), but Cartesian coordinates (x, y, z) are supported as well. diff --git a/docs/getting-started/overview.rst b/docs/getting-started/overview.rst index d2eee4ac6..5f1e8ef56 100644 --- a/docs/getting-started/overview.rst +++ b/docs/getting-started/overview.rst @@ -37,7 +37,7 @@ Grids may have structured vertical levels, as described by the .. note:: While 3D grids with vertical levels are supported, fully 3D unstructured topology is not. - Also, UXarray additionally assumes the horizontal portion of the grid lies on a spherical surface, + Also, UXarray additionally assumes the grid lies on a spherical surface, and that all grid faces/cells are convex (all angles less than 180 degrees). diff --git a/docs/user-guide/grid-formats.rst b/docs/user-guide/grid-formats.rst index 6618edb83..806634c09 100644 --- a/docs/user-guide/grid-formats.rst +++ b/docs/user-guide/grid-formats.rst @@ -48,7 +48,7 @@ UGRID conventions' 3D layered mesh topology, but it does not support fully 3D unstructured topology. .. note:: - UXarray's geometry algorithms also assume the horizontal portion of the grid lies on a spherical surface. + UXarray's geometry algorithms also assume the grid lies on a spherical surface. The sphere radius can be adjusted but a unit sphere is assumed by default. UGRID References From e6cb900c3acbcc76387c96a93578e755ae925362 Mon Sep 17 00:00:00 2001 From: Sam Evans <47793072+Sevans711@users.noreply.github.com> Date: Tue, 28 Jul 2026 14:03:53 -0400 Subject: [PATCH 5/6] fix minor docs typo, restore old section titles as per review comments on #1626 --- docs/user-guide/grid-formats.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/grid-formats.rst b/docs/user-guide/grid-formats.rst index 806634c09..3f426fdab 100644 --- a/docs/user-guide/grid-formats.rst +++ b/docs/user-guide/grid-formats.rst @@ -22,11 +22,11 @@ models have their own grid format (e.g. MPAS, ICON). Below is a list of support * FESOM2 * HEALPix -UGRID in UXarray -================ +UGRID +===== The `UGRID conventions `_ -are a standard for for storing unstructured grid (a.k.a. unstructured mesh, +are a standard for storing unstructured grid (a.k.a. unstructured mesh, flexible mesh) model data in a Unidata Network Common Data Form (NetCDF) file. These conventions are focussed on representing data for environmental applications, hence the motivation for @@ -51,8 +51,8 @@ but it does not support fully 3D unstructured topology. UXarray's geometry algorithms also assume the grid lies on a spherical surface. The sphere radius can be adjusted but a unit sphere is assumed by default. -UGRID References ----------------- +References +---------- * https://ugrid-conventions.github.io/ugrid-conventions/#ugrid-conventions-v10 * https://github.com/ugrid-conventions/ugrid-conventions * https://cf-convention.github.io/Data/cf-conventions/cf-conventions-1.13/cf-conventions.html#ugrid-conventions From 08f0370db1f72fcb936fe9cee8e33b4c1ba982e6 Mon Sep 17 00:00:00 2001 From: Sam Evans <47793072+Sevans711@users.noreply.github.com> Date: Tue, 28 Jul 2026 16:42:59 -0400 Subject: [PATCH 6/6] docs fix UGRID section typos; add "UGRID is in CF" --- docs/user-guide/grid-formats.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/grid-formats.rst b/docs/user-guide/grid-formats.rst index 3f426fdab..c4d0ebf58 100644 --- a/docs/user-guide/grid-formats.rst +++ b/docs/user-guide/grid-formats.rst @@ -29,16 +29,17 @@ The `UGRID conventions `_ are a standard for storing unstructured grid (a.k.a. unstructured mesh, flexible mesh) model data in a Unidata Network Common Data Form (NetCDF) file. -These conventions are focussed on representing data for environmental applications, hence the motivation for -starting from the Climate & Forecasting (CF) Metadata Conventions, -The CF Conventions have been the standard in climate rx`earch for many years, and are being adopted by others as the metadata +These conventions are focused on representing data for environmental applications, hence the motivation for +starting from the Climate & Forecasting (CF) Metadata Conventions. +The CF conventions have been the standard in climate research for many years, and are being adopted by others as the metadata standard (e.g. NASA, Open Geospatial Consortium). The CF conventions allow you to provide the geospatial and temporal coordinates -for scientific data, but currently assumes that the horizontal topology may be inferred from the i,j indices of structured -grids. The UGRID Conventions outline how to specify the topology of unstructured grids. +for scientific data, but currently assume that the horizontal topology may be inferred from the i,j indices of structured +grids. The UGRID conventions outline how to specify the topology of unstructured grids. The standard was developed over a period of several years through the UGRID Google Group which had members from many -different unstructured grid modeling communities (including SELFE, ELCIRC, FVCOM, ADCIRC). From these discussions Bert +different unstructured grid modeling communities (including SELFE, ELCIRC, FVCOM, ADCIRC). From these discussions, Bert Jagers (Deltares) created the first draft of this document, and the community worked to develop version 1.0. +CF conventions versions 1.11 and later include the UGRID conventions by reference. UXarray in particular assumes horizontally unstructured grids, consistent with the UGRID conventions' 2D flexible mesh topology,