Add VTK plotting for unstructured meshes

.github/workflows/_nox.yml

@@ -80,7 +80,7 @@ jobs:
         uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3
         if: startsWith(matrix.leg.os, 'ubuntu')
         with:
-          packages: gfortran gcc graphviz pandoc
+          packages: gfortran gcc graphviz pandoc libosmesa6 libegl1
           execute_install_scripts: true
 
       # dot -c is for registering graphviz fonts and plugins
@@ -91,6 +91,11 @@ jobs:
           sudo dot -c
           sudo apt-get install libopenblas-dev
 
+      # VTK off-screen GIF export needs a software OpenGL backend on headless runners.
+      - name: Prefer OSMesa for VTK on Linux
+        if: startsWith(matrix.leg.os, 'ubuntu')
+        run: echo "VTK_DEFAULT_OPENGL_WINDOW=vtkOSOpenGLRenderWindow" >> "$GITHUB_ENV"
+
       # Kept separate and opt-out: texlive-latex-extra is large and uncached.
       - name: Install TeXLive for Linux
         if: ${{ startsWith(matrix.leg.os, 'ubuntu') && inputs.texlive }}
@@ -114,6 +119,15 @@ jobs:
         if: startsWith(matrix.leg.os, 'windows')
         run: winget install --id Graphviz.Graphviz --exact --accept-source-agreements --accept-package-agreements
 
+      # VTK save_gif needs OSMesa on headless Windows runners (osmesa.dll on PATH).
+      - name: Setup headless OpenGL on Windows
+        if: startsWith(matrix.leg.os, 'windows')
+        uses: pyvista/setup-headless-display-action@5bc8de3bc71fcda7a96439571287a554901541a0 # v4
+        with:
+          pyvista: "false"
+          mesa3d-release: "24.3.0"
+          install-mesa3d-offscreen: "true"
+
       - name: Set up Python ${{ matrix.leg.python }}
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:

CHANGELOG.md

@@ -8,6 +8,7 @@
 
 ## Features
 
+- Added VTK-based plotting (`VTKQuickPlot`) for unstructured mesh solutions, including headless CI OpenGL setup. ([#5689](https://github.com/pybamm-team/PyBaMM/pull/5689))
 - Added `FiniteVolumeUnstructured` spatial method and unstructured processed-variable support for cell-centered data on arbitrary meshes. The TPFA Laplacian carries an implicit non-orthogonal correction (`"non-orthogonal correction"` option: `"over-relaxed"` or `"minimum"`) and gradients use a least-squares reconstruction, so both are exact on linear fields and second-order on skewed triangle and tetrahedral meshes. Diffusion coefficients reach faces through the distance-weighted harmonic mean, as in `FiniteVolume`, so material interfaces carry the exact series flux. ([#5688](https://github.com/pybamm-team/PyBaMM/pull/5688))
 - Added unstructured mesh support (`UnstructuredSubMesh`, generators, and interface coupling) for arbitrary 2D/3D domains. Hexahedra must have planar faces (warped hexes raise a `GeometryError`), and `UserSuppliedUnstructuredMesh` accepts tetrahedral, triangular, and quadrilateral cells only. ([#5687](https://github.com/pybamm-team/PyBaMM/pull/5687))
 - Generalised `VectorField` to N components and added `Component`/`Norm` operators for multi-dimensional vector fields. ([#5686](https://github.com/pybamm-team/PyBaMM/pull/5686))

docs/source/api/plotting/index.rst

@@ -10,3 +10,5 @@ Plotting
   plot_summary_variables
   plot_3d_cross_section
   plot_3d_heatmap
+  plot_vtk
+  unstructured_plot_grid

docs/source/api/plotting/plot_vtk.rst

@@ -0,0 +1,5 @@
+VTK Quick Plot
+==============
+
+.. autoclass:: pybamm.VTKQuickPlot
+    :members:

docs/source/api/plotting/unstructured_plot_grid.rst

@@ -0,0 +1,5 @@
+Unstructured plot sampling
+==========================
+
+.. automodule:: pybamm.plotting.unstructured_plot_grid
+    :members:

packages/pybamm/pyproject.toml

@@ -66,11 +66,13 @@ bpx = ["bpx>=1.1.1,<1.2.0"]
 # Low-overhead progress bars
 tqdm = ["tqdm"]
 jax = ["jax>=0.7.0, <0.9.0; python_version >= '3.11' and (sys_platform != 'darwin' or platform_machine != 'x86_64')"]
+# VTK-based interactive visualization for unstructured meshes
+vtk = ["vtk>=9.0.0"]
 # Contains all optional dependencies, except for jax, and dev dependencies
 all = [
     "scikit-fem>=12.0.2",
     "meshio>=5.3.0",
-    "pybamm[examples,plot,cite,bpx,tqdm]",
+    "pybamm[examples,plot,cite,bpx,tqdm,vtk]",
 ]
 
 [dependency-groups]

packages/pybamm/src/pybamm/__init__.py

@@ -237,6 +237,7 @@
 from .plotting.dynamic_plot import dynamic_plot
 from .plotting.plot_3d_cross_section import plot_3d_cross_section
 from .plotting.plot_3d_heatmap import plot_3d_heatmap
+from .plotting.plot_vtk import VTKQuickPlot
 from .plotting.nyquist_plot import nyquist_plot
 
 # Simulation

packages/pybamm/src/pybamm/plotting/dynamic_plot.py

@@ -11,12 +11,34 @@ def dynamic_plot(*args, **kwargs):
     The key-word argument 'show_plot' is passed to the 'dynamic_plot' method, not the
     `QuickPlot` class.
 
+    Pass ``backend="vtk"`` to use the VTK-based viewer for unstructured
+    mesh solutions instead of matplotlib.
+
     Returns
     -------
-    plot : :class:`pybamm.QuickPlot`
-        The 'QuickPlot' object that was created
+    plot : :class:`pybamm.QuickPlot` or :class:`pybamm.VTKQuickPlot`
+        The plot object that was created
     """
-    kwargs_for_class = {k: v for k, v in kwargs.items() if k != "show_plot"}
+    backend = kwargs.pop("backend", "matplotlib")
+    show_plot = kwargs.pop("show_plot", True)
+
+    if backend == "vtk":
+        from pybamm.plotting.plot_vtk import VTKQuickPlot
+
+        output_variables = kwargs.pop("output_variables", None)
+        options = kwargs.pop("options", None)
+        interpolate_time = kwargs.pop("interpolate_time", False)
+        plot = VTKQuickPlot(
+            *args,
+            output_variables=output_variables,
+            options=options,
+            interpolate_time=interpolate_time,
+            **kwargs,
+        )
+        plot.dynamic_plot(show_plot)
+        return plot
+
+    kwargs_for_class = {k: v for k, v in kwargs.items()}
     plot = pybamm.QuickPlot(*args, **kwargs_for_class)
-    plot.dynamic_plot(kwargs.get("show_plot", True))
+    plot.dynamic_plot(show_plot)
     return plot