UXarray

UXarray#

UXarray is a Python package that was created to support scalable data analysis and visualization functionality on high-resolution unstructured grids. It is built around the UGRID conventions and provides Xarray-styled functionality for working directly with unstructured grids.

UXarray is the product of a collaborative effort between Project Raijin, funded by an NSF EarthCube award between NSF NCAR and The Pennsylvania State University, and the SEATS project, funded by DOE.

Learning Goals#

With this notebook, we aim to:

  1. Clarify why UXarray can be useful

  2. Provide self-learning resources about UXarray

  3. How to access UXarray?

  4. Give you a sense of how simple I/O and visualization with UXarray can be

1. Why UXarray?#

UXarray can simplify your workflows with unstructured grids because it:

  • Enables significant data analysis and visualization functionality to be executed directly on unstructured grids

  • Adheres to the UGRID specifications for compatibility across a variety of mesh formats

  • Provides a single interface for supporting a variety of unstructured grid formats including UGRID, MPAS, SCRIP, and Exodus

  • Inherits from Xarray, providing simplified data using familiar (Xarray-like) data structures and operations

  • Brings standardization to unstructured mesh support for climate data analysis and visualization

  • Builds on optimized data structures and algorithms for handling large and complex unstructured datasets

  • Supports enhanced interoperability and community collaboration

2. UXarray Resources#

The following are some UXarray resources that you can leverage to further learn about UXarray, get started with it, see demonstrations of its analysis and visualization capabilities, and learn how to contribute to it:

UXarray Documentation Website#

The UXarray documentation website is the to-go place for you to access fundamental information about the tool such as:

UXArray’s Project Pythia Cookbook#

This cookbook is a comprehensive showcase of workflows & techniques for visualizing Unstructured Grids using UXarray with its several notebooks.

These notebooks can be executed online, without locally setting them up, with the help of the Binder interface provided.

3. How to access UXarray?#

In addition to installing UXarray locally by following the instructions in the above Installation guide, if you are a user of the NSF NCAR’s HPC clusters, you can access UXarray via the NPL-2024a (or a newer version) conda environment.

4. Minimal UXarray visualization#

BEFORE BEGINNING THIS EXERCISE - Check that your kernel is minimum NPL-2024a. This should be the default kernel, but if it is not, click on that button and select NPL-2024a or a newer version.

Data paths#

# Set your username here:
username = "PUT_USER_NAME_HERE"

# Here we point to an imaginary location for a ne30x8 directory
monthly_output_path = f"/glade/derecho/scratch/{username}/ne30x8_dir/"

grid_filename = "ne30x8_np4_SCRIP.nc"
data_filename = "ne30x8_220105.nc"

UXarray Code#

import uxarray as ux

uxds_ne30x8 = ux.open_dataset(base_path + grid_filename, base_path + data_filename)

# Let's examine the grid:
uxds_ne30x8.uxgrid

<uxarray.Grid>
Original Grid Type: Scrip
Grid Dimensions:
  * n_node: 1184802
  * n_edge: 2601516
  * n_face: 710858
  * n_max_face_nodes: 10
  * two: 2
  * n_nodes_per_face: (710858,)
Grid Coordinates (Spherical):
  * node_lon: (1184802,)
  * node_lat: (1184802,)
  * face_lon: (710858,)
  * face_lat: (710858,)
Grid Coordinates (Cartesian):
Grid Connectivity Variables:
  * face_node_connectivity: (710858, 10)
  * edge_node_connectivity: (2601516, 2)
Grid Descriptor Variables:

# Visualization
clim = (uxds_ne30x8['soilw'][0].values.min(), uxds_ne30x8['soilw'][0].values.max()) # colorbar limits
uxds_ne30x8['soilw'][0].plot.rasterize(method='polygon', dynamic=True, clim=clim)

/glade/u/home/oero/conda-envs/uxarray-dask/lib/python3.12/site-packages/uxarray/grid/geometry.py:95: UserWarning: Converting to a GeoDataFrame with over 1,000,000 faces may take some time.
  warnings.warn(
Contents