Unstructured Grid Visualization Cookbook

This Cookbook is a comprehensive showcase of workflows & techniques for visualizing Unstructured Grids using UXarray, also providing foundational information on unstructured grids.

Motivation

The ability to natively visualize unstructured grids is much needed within the Scientific Python Ecosystem, which poses multiple challenges and needs to:

Not regrid the source unstructured grid to structured grid
Take advantage of grid information, such as connectivity variables
Limit the amount of pre-processing needed to prepare the data for Python visualization tools

UXarray enables such visualization methods that operate directly on unstructured grid data, providing Xarray-styled functionality to better read in and use unstructured grid datasets that follow standard conventions.

UXarray supports a variety of unstructured grid formats and file types including UGRID, MPAS, ICON, CAM-SE, SCRIP, Exodus, ESMF, GEOS, and FESOM2, and is extensible for other formats.

This cookbook covers an introduction to unstructured grids and UXarray from a visualization standpoint, providing foundational information about unstructured grids, visualization methods and libraries, and introducing UXarray, and showcasing several UXarray visualization functions and workflows.

Authors

Philip Chmielowiec (NSF NCAR)

Orhan Eroglu (NSF NCAR)

Rajeev Jain (Argonne National Laboratory)

Ian Franda (University of Wisconsin-Madison)

Rachel Tam (University of Illinois Urbana-Champaign)

Contributors

Structure

This cookbook is split up into several chapters to communicate the content efffectively with different levels of readers:

1. Foundations

Here, we cover overview of the foundational topics necessary to understand the content in this cookbook, e.g. what unstructured grids are and how they are different than structured grids, what plotting libraries and visualization techniques exist that can be helpful for unstructured grid visualization, and we briefly mention how UXarray is related to these.

2. Introduction to UXarray

In this chapter, we provide an overview of UXarray: An Xarray-extension for unstructured grid-formatted climate and global weather data analysis and visualization.

3. Plotting with UXarray

We provide an overview of the UXarray plotting API along with several visualization functionality, and cases and examples that can be realized using such UXarray functionality; Grid visualization, Data visualization, Geographic projections and features, to name a few. Also in this section, customization and interactivaity with UXarray plotting and considerations with high-resolution plotting are also provided.

4. Visualization Recipies

In this last chapter, we offer to the interested readers a set of focused workflows that can be realized with UXarray, including visualizations of MPAS and E3SM model output.

Running the Notebooks

You can either run the notebook using Binder or on your local machine.

Running on Binder

The simplest way to interact with a Jupyter Notebook is through Binder, which enables the execution of a Jupyter Book in the cloud. The details of how this works are not important for now. All you need to know is how to launch a Pythia Cookbooks chapter via Binder. Simply navigate your mouse to the top right corner of the book chapter you are viewing and click on the rocket ship icon, (see figure below), and be sure to select “launch Binder”. After a moment you should be presented with a notebook that you can interact with. I.e. you’ll be able to execute and even change the example programs. You’ll see that the code cells have no output at first, until you execute them by pressing Shift+Enter. Complete details on how to interact with a live Jupyter notebook are described in Getting Started with Jupyter.

Running on Your Own Machine

If you are interested in running this material locally on your computer, you will need to follow this workflow:

Clone the https://github.com/ProjectPythia/unstructured-grid-viz-cookbook repository:

 git clone https://github.com/ProjectPythia/unstructured-grid-viz-cookbook.git

Move into the unstructured-grid-viz-cookbook directory
```
cd unstructured-grid-viz-cookbook
```

Create and activate your conda environment from the environment.yml file

conda env create -f environment.yml
conda activate unstructured-grid-viz-cookbook-dev

Move into the notebooks directory and start up Jupyterlab
```
cd notebooks/
jupyter lab
```