Introduce rasterized plotting

[mkavulich]

This PR revamps mpas_plot to use the latest and greatest UXarray version 2026.04.1, which includes rasterized plotting rather than constructing polygons from the original grid. Rasterized plotting is an order of magnitude (or more) faster than the polycollection method, especially for large domains and alternate projections where it was essentially impossible to produce plots in a reasonable amount of time.

I was able to obtain a fairly large, 3km regional domain to run some tests with. These plots took the better part of an hour to make with the previous polycollection method:

$ python plot_mpas_netcdf.py 
INFO     Loading user config settings
INFO     Loading data from netcdf files
INFO     Setting up plot tasks
INFO     Starting plotit() for var='t2m', lev=0
INFO     PlateCarree does not use standard_parallels; ignoring
INFO     scale=50m is not supported for boundaries:detail:2
INFO     Setting scale to 10m
INFO     File exists: debby_data/t2m_lev0_2024-08-08_18:00:00.png
INFO     Saving to debby_data/t2m_lev0_2024-08-08_18:00:00-0.png instead
INFO     Done saving plot debby_data/t2m_lev0_2024-08-08_18:00:00-0.png. Plot generation 2442.3214452266693 seconds
INFO     Starting plotit() for var='precipw', lev=0
INFO     PlateCarree does not use standard_parallels; ignoring
INFO     File exists: debby_data/precipw_lev0_2024-08-08_18:00:00.png
INFO     Saving to debby_data/precipw_lev0_2024-08-08_18:00:00-0.png instead
INFO     Done saving plot debby_data/precipw_lev0_2024-08-08_18:00:00-0.png. Plot generation 2292.6452717781067 seconds
INFO     Starting plotit() for var='rainnc', lev=0
INFO     PlateCarree does not use standard_parallels; ignoring
CPU time limit exceeded

Rasterization for this large domain resulted in a nearly 1000x speedup for some plots!

$ python plot_mpas_netcdf.py 
INFO     Loading user config settings
INFO     Loading data from netcdf files
INFO     Setting up plot tasks
INFO     Starting plotit() for var='t2m', lev=0
INFO     PlateCarree does not use standard_parallels; ignoring
INFO     scale=50m is not supported for boundaries:detail:2
INFO     Setting scale to 10m
INFO     Overwriting existing file debby_data/t2m_lev0_2024-08-08_18:00:00.png
INFO     Done saving plot debby_data/t2m_lev0_2024-08-08_18:00:00.png. Plot generation 6.374860525131226 seconds
INFO     Starting plotit() for var='precipw', lev=0
INFO     PlateCarree does not use standard_parallels; ignoring
INFO     Overwriting existing file debby_data/precipw_lev0_2024-08-08_18:00:00.png
INFO     Done saving plot debby_data/precipw_lev0_2024-08-08_18:00:00.png. Plot generation 2.5822012424468994 seconds
INFO     Starting plotit() for var='rainnc', lev=0
INFO     PlateCarree does not use standard_parallels; ignoring
INFO     Overwriting existing file debby_data/rainnc_lev0_2024-08-08_18:00:00.png
INFO     Done saving plot debby_data/rainnc_lev0_2024-08-08_18:00:00.png. Plot generation 2.536332130432129 seconds
INFO     Starting plotit() for var='refl10cm_1km', lev=0
INFO     PlateCarree does not use standard_parallels; ignoring
INFO     Color map radar_refl selected; using custom settings from colormaps/radar_refl.yaml
INFO     Overwriting existing file debby_data/refl10cm_1km_lev0_2024-08-08_18:00:00.png
INFO     Done saving plot debby_data/refl10cm_1km_lev0_2024-08-08_18:00:00.png. Plot generation 2.3598949909210205 seconds
INFO     Done plotting all figures! Total time 17.56370449066162 seconds

Tests with smaller datasets resulted in a more modest speedup, but still typically 10x or more.

New settings

New setting polycollection

False by default, the polycollection option will allow users to use the old method of plotting that plots the true polygons of the input unstructured grids. This is retained for back-compatibility (and the retaining of a few features that are not yet supported for rasterization, such as plotting the grid edges) but is not recommended due to its slowness, and due to a known issue with the faster, default option periodic_elements='exclude' (activated with periodic_bdy: False in config) in the latest UXarray libraries; see UXARRAY/uxarray#1507 for more details

Pixel ratio

Rasterization is an inherently lossy process, but we can control the quality of the output using the setting pixel_ratio. The default value is 1, which will result in very good plots for most domains, but may look "pixelated" at small scales for very large/high resolution domains. Increasing this value will result in finer quality images, resolving the true polygons of the native grid data, but will take longer to create. Conversely, for plots where fine detail is not important, you can decrease pixel_ratio for an increase in plotting speed.

maxval and minval

New in this PR, maxval and minval are added as substitutable keys in plot titles, names, etc. This is the maximum and minimum numerical values respectively for the given plotted domain.

New custom function: sum_of_magnitudes

This new function allows the input of a u and v wind vector (or any two perpendicular vector fields) and outputs the magnitude of the vector field (wind speed from wind vectors, for example).

Other changes

• Re-add line mpl.use("Agg") that was accidentally removed in an earlier PR; this fixes some memory problems when creating large numbers of of plots.
• Only use starmap when parallel processing is used
• Automatically load mpas_plot conda environment when sourcing setup script
• Add a check that the latrange and lonrange are valid
• Fixes Allow Ctrl+C to kill execution and return to prompt #17
• Attempts to detect existing conda installations before installing a new one, prompting the user with options on where to install the mpas_plot environment.

Example plot

dataset:
  vars:
    wind10m:
      source: derived
      function: sum_of_magnitudes
      inputs:
        - "u10"
        - "v10"
      attrs:
        long_name: "10-meter wind magnitude"
        units: "m s^{-1}"
      plot:
        colormap: gsl_wind_speed
        colorbins: 20
        vmax: 40
        vmin: 0
plot:
  title:
    text: 'Plot of {varln}, level {lev} for {date} {time}, Max: {maxval}, Min: {minval}'

Issues

• Resolves Update UXarray when release including rasterized graphics comes out #12
• Resolves Allow Ctrl+C to kill execution and return to prompt #17

[mkavulich]

Important note: I have not yet fixed global plots with alternate projections; hopefully I will find time to add this in later.

[mkavulich]

@willmayfield If you're interested in trying this out, I think it's finally ready.