1.0.0

1.0.0#

Released on 2026-05-19

Improved support for multiple grids#

In previous releases emsarray made the assumption that variables were primarily defined on some grid of polygons. This is true for rectilinear grids, curvilinear grids, spherical multiple cell grids, and unstructured grids from COMPAS models. This is not true for the unstructured grids from SCHISM models however which define many variables on the vertices of the polygons, not the polygons themselves. This assumption of polygons was limiting the datasets that emsarray could support.

With this update each grid kind is treated equally with no assumptions around face grids. Each dataset can have multiple grid kinds, and each of these grid kinds is represented by a Grid instance. The set of grids for a dataset is available at Convention.grids, and the grid for a variable can be found using Convention.get_grid().

The externally facing API is mostly backwards compatible although many methods have been deprecated in favour of methods on the Grid class. These methods will continue to be supported for this release at least. Convention.get_index_for_point and SpatialIndexItem have been dropped instead of deprecated. These methods were little used and backwards compatibility was complicated. To make the transition smoother the assumption of a default polygon grid has been maintained, however this default may be removed in future releases.

Improved plotting API#

The plotting API has been improved to achieve the goals:

  • The ability to plot variables defined on non-polygonal grids,

  • Make customisation of artist properties easier, such as colour maps and data limits,

  • Provide a consistent API for updating the data for an artist, to make animated plots simpler,

  • Support plotting on multiple axes in a figure, and

  • Support more kinds of artists, such as contour plots over polygonal grids.

A new method Convention.make_artist() has been added which will pick the correct matplotlib Artist to plot a given variable. This method will pass any kwargs on to the underlying artist allowing for easy customisation (see Plot with specified data limits). This method takes an Axes instance allowing for multiple axes on one figure (see Multiple plots in one figure). It will return a GridArtist instance which has a GridArtist.set_data_array() method. Users can call this method to update the data being plotted in an animation without the artist-specific handling previously required in animate_on_figure() (see Animated plot).

More examples are being added over time to demonstrate how to make more customised plots.

Changelog#

Contents