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/2] 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/2] 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