Skip to content

Clarify in docs: UXarray supports only spherical 2D grids with convex faces #1626

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Sevans711 wants to merge 1 commit into
base: main
Choose a base branch
from
+30 −2
Open

Clarify in docs: UXarray supports only spherical 2D grids with convex faces #1626

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion docs/getting-started/freq-asked-questions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,14 @@
Frequently Asked Questions
==========================

Coming soon!
What does UXarray assume about grids?

@erogluorhan erogluorhan Jul 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There might be many more assumptions that are not covered here, so maybe call this "What foundational assumptions does UXarray have about grids and geometries?" or something similar?

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
UXarray assumes that each grid spans some or all of a 2D spherical surface, and contains only convex faces.

@erogluorhan erogluorhan Jul 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean by this first sentence, global and regional grids?

I think I'd open this first sentence about the most foundational assumption, something like:

"UXarray assumes horizontally unstructured grids with vertical levels, compliant with the UGRID conventions' 3D layered mesh topology, i.e. no fully 3D unstructured topology, either spanning regionally or globally, and consisting only of convex grid faces/cells."

Then, I'd have a 2nd paragraph like:

"UXarray assumes Spherical (latitude/longitude) coordinates by default even though it supports Cartesian (x, y, z) coordinates as well. However, its geometry algorithms assume a spherical surface - unit sphere by default."

While other dimensions such as time or elevation can be represented easily enough,
the unstructured part of the grid cannot vary across those dimensions.

@erogluorhan erogluorhan Jul 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is a bit hard to read, and I think it could be dropped if you accept the previous one.

UXarray also assumes that the grid can be represented using UGRID conventions,
even if it isn't input directly in UGRID format.

@erogluorhan erogluorhan Jul 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similarly, this phrase could be dropped if you accept the previous one.

See also: `Supported Models & Grid Formats <user-guide/grid-formats.rst>`_.

@erogluorhan erogluorhan Jul 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rendered version throws 404 for this link.



Other questions coming soon!
6 changes: 6 additions & 0 deletions docs/getting-started/overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@erogluorhan erogluorhan Jul 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please rephrase accordingly with the suggestions above



Core Data Structures
====================
Expand Down
14 changes: 13 additions & 1 deletion docs/user-guide/grid-formats.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@erogluorhan erogluorhan Jul 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please rephrase accordingly with the suggestions above



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:
Expand Down