Why UXarray?

Why UXarray?#

UXarray aims to address the geoscience community’s need for tools that enable foundational data analysis techniques to operate directly on unstructured grids. It extends upon and inherits from the commonly used Xarray Python package to provide a powerful and familiar interface for working with unstructured grids in Python. UXarray provides Xarray-styled functions to better read in and use unstructured grid datasets from the most common model outputs, including MPAS, CAM-SE, ICON, ESMF, GEOS, and HEALPix, which follow the commonly used formats such as UGRID, SCRIP, and Exodus. Furthermore, UXarray provides basic support for generating unstructured grid topology from structured grid or point-cloud inputs to enable model intercomparison workflows.

Unstructured Grids#

The “U” in UXarray stands for “Unstructured Grids”. These types of grids differ from typical Structured Grids in terms of complexity, requiring explicit information to be stored to represent the geometry, e.g. cell to node connectivity. However, these types of grids are extremely flexible and scalable.

UXarray uses the UGRID conventions as a foundation to represent Unstructured Grids. These conventions are intended to describe how these grids should be stored within a NetCDF file, with a particular focus on environmental and geoscience applications. We chose to use a single convention for our grid representation instead of having separate ones for each 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 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 UGRID conventions’ 3D layered mesh topology.

Note

While 3D grids with vertical levels are supported, fully 3D unstructured topology is not. 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).

Core Data Structures#

UXarray’s core API revolves around three primary types, which extend Xarray for unstructured-grid workflows:

uxarray.Grid

Represents the unstructured grid itself, housing grid-specific methods and topology variables. Encapsulates a xarray.Dataset for storing the grid definition.

uxarray.UxDataset

Extends xarray.Dataset to operate on unstructured grids; linked to a Grid instance via its uxgrid property.

uxarray.UxDataArray

Similarly extends xarray.DataArray and exposes a uxgrid accessor for grid-aware operations.

Core Functionality#

In addition to loading and interfacing with Unstructured Grids, UXarray provides computational and analysis operators that operate directly on those grids. Some of these include:

  • Visualization

  • Remapping

  • Subsetting

  • Cross-sections

  • Aggregations

  • Zonal averaging

  • Vector calculus

A more detailed overview of supported functionality can be found in our API Reference and User Guide sections.