mpas_plot is a python utility for easy, configurable plotting of native-grid output fields of the Model for Prediction Across Scales (MPAS), with particular emphasis on bulk creation of large numbers of plots, especially for HPC applications. It was developed at the Developmental Testbed Center, a collaborative partnership between the National Oceanic and Atmospheric Administration (NOAA), US Air Force, and the National Science Foundation (NSF) National Center for Atmospheric Research (NCAR). It is powered by the UXarray python library, 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 the Department of Energy.

This README contains instructions for using mpas_plot utilities, including setting up the environment

For detailed examples of different plotting functions, see the GitHub wiki: https://github.com/dtcenter/mpas_plot/wiki/mpas_plot-config-examples-and-use-cases

Environment setup

Setting up conda and mpas_plot conda environment

This utility includes a script that will set up a local install of conda to set up the needed python environment. If you would rather use an existing conda install on your machine, an environment.yml recipe file is provided for you to create your own environment, skipping these steps.

This script can only be used with bash or bash-like (e.g. ksh) shells. To use a different login shell, you must configure conda manually.

source setup_conda.sh

Running the plotting script

The plotting script is built with argparse, so you can see a summary of the arguments by running with the --help (-h) flag:

$ python plot_mpas_netcdf.py -h
usage: plot_mpas_netcdf.py [-h] [-c CONFIG] [-d] [-p PROCS]

Script for producing plot files from MPAS input and/or output in native NetCDF format

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        File used to specify plotting options
  -d, --debug           Script will be run in debug mode with more verbose output
  -p PROCS, --procs PROCS
                        Number of processors for generating plots in parallel

The config file is where you will specify all the various options for what you want to plot, including which files, variables, levels, etc you want to plot. To setup the script to use your specific options, you’ll need to create a configuration file (config_plot.yaml). An example file config_plot.yaml.example is provided for reference, and you can view all available options in the default_options.yaml file.

Detailed examples of configuration files, with links to staged data on NCAR HPC (Capser/Derecho), are available here: https://github.com/dtcenter/mpas_plot/wiki/mpas_plot-config-examples-and-use-cases

Once you have modified config_plot.yaml with all the settings you want, simply run the script:

$ python plot_mpas_netcdf.py
INFO     Loading user config settings
INFO     Loading data from netcdf files
INFO     Setting up plot tasks
INFO     Submitting to starmap
INFO     Starting plotit() for var='t2m', lev=0
INFO     PlateCarree does not use standard_parallels; ignoring
INFO     One or more latitude/longitude range values were not set; plotting full projection
INFO     Done saving plot tutorial_data/t2m_lev0_2025-05-08_00:00:00.png. Plot generation 10.880536556243896 seconds
INFO     Starting plotit() for var='precipw', lev=0
...
...

It may take some time to produce plots, depending on the size of your domain and number of fields plotted. For large numbers of plots, using the parallel capability (python plot_mpas_netcdf.py -p #) is highly

Custom colormaps

Some custom colormaps have been set up to mimic the typical way of displaying certain data. These colormaps are specified in YAML format files in the colormaps/ subdirectory. These custom colormaps may overwrite some user settings from config_plot.yaml, so if you want different settings you will have to modify the files there.

For example, colormaps/radar_refl.yaml is designed to mimic the typical display scheme for radar reflectivity data, so the following settings are included:

vmin: 5
vmax: 75
plot_under: False

This limits the color range to data between 5 and 75 (dBz), and plot_under: False specifies that data below vmin (5) should not be plotted at all; data above vmax (75) will be plotted if present but will have the same color value as 75.

Limitations

This plotting utility has no funding for technical support, and has several known limitations:

1. The user must know the name of the variable(s) they want to plot.
2. Interpolating to projections other than PlateCarree (lat-lon projection) is very resource-intensive and slow.
3. Certain variables that have additional dimensions such as grid property values (e.g. kiteAreasOnVertex) may not work out-of-the-box.