This tutorial is part of viskex.

Customizing the pyvista backend when running in jupyter notebooks

import dolfinx.mesh
import mpi4py.MPI
import pyvista

import viskex

Generate a mesh of the unit square by dividing each edge of the square in 6 segments.

square = dolfinx.mesh.create_unit_square(mpi4py.MPI.COMM_WORLD, 6, 6)

The interactive plots rendered in jupyter notebooks are prepared by trame, which is integrated in pyvista. The available backends are:

• the client backend (interactive), which renders the scene on the client side using vtk.js,
• the server backend (interactive), which runs a VTK render window on the server and sends back a compressed image,
• the html backend (partially interactive), which generates a static HTML representation of the scene,
• the trame backend (interactive or partially interactive), a default among client, server and html,
• the static backend (not interactive), a static image of the scene.

viskex automatically chooses the default backend as follows:

• if an environment variable VISKEX_PYVISTA_BACKEND is provided, then the default client is its value; otherwise
• if running on Google Colab or on Kaggle, the default client is html, as the other backends are not functional there; otherwise
• if running elsewhere, the default backend is client.

The simplest way to set the plotting backend is by setting the variable VISKEX_PYVISTA_BACKEND in the environment before running the notebook. The chosen backend will be used in every plot.

If a more fine grained control is needed (e.g., setting a different backend for each plot), users can change the backend in one of the following ways:

1. Use the lower level viskex.DolfinxPlotter class instead of the viskex.dolfinx functions. The functions in the viskex.dolfinx module delegate the preparation of the pyvista plotter to the viskex.DolfinxPlotter class, and then automatically call .show() on the prepared pyvista plotter. Instead, by using the lower level class the jupyter_backend can be passed as keyword argument to the pyvista plotter. The choice of the backend will only be applied to the current plot.

plotter_client = viskex.DolfinxPlotter.plot_mesh(square)
plotter_client.show(jupyter_backend="client")

plotter_html = viskex.DolfinxPlotter.plot_mesh(square)
plotter_html.show(jupyter_backend="html")

plotter_static = viskex.DolfinxPlotter.plot_mesh(square)
plotter_static.show(jupyter_backend="static")

2. Overwrite the jupyter_backend in pyvista's global theme. The typical suggested workflow however would be to simply use the VISKEX_PYVISTA_BACKEND environment variable, which sets that same theme option.

backup_jupyter_backend = pyvista.global_theme.jupyter_backend

pyvista.global_theme.jupyter_backend = "client"
viskex.dolfinx.plot_mesh(square)

pyvista.global_theme.jupyter_backend = "html"
viskex.dolfinx.plot_mesh(square)

pyvista.global_theme.jupyter_backend = "static"
viskex.dolfinx.plot_mesh(square)

pyvista.global_theme.jupyter_backend = backup_jupyter_backend

What's next?

• repeat this step with firedrake