PyGLVis

\ PyGLVis is an interactive Jupyter widget for visualizing finite element meshes and functions, built on-top of the GLVis library.

📦 Installation

The GLVis Jupyter widget is installed using pip. To install the latest version from the repository:

git clone https://github.com/GLVis/pyglvis.git
cd pyglvis
pip install .

Or, install directly from PyPi,

pip install glvis

PyGLVis requires the Python wrapper for MFEM, PyMFEM, which can be installed with

pip install mfem

🚀 Usage

Basic usage

from glvis import glvis

# Create a `glvis` object
g = glvis(data, width=640, height=480)

# Run a cell with `g` as the last statement to display the widget
g

The data object can be one of:

Mesh, defined in PyMFEM
(Mesh, GridFunction) tuple, defined in PyMFEM
str, in the format of *.saved files used by MFEM and GLVis. See examples/basic.ipynb for an example.

Customization with key commands

GLVis has many keyboard commands that can be used to customize the visualization. A few of the most common are listed below. See the GLVis README for a full list.

r - reset the view
c - toggle the colorbar
j - toggle perspective
l - toggle the light
g - toggle the background color (white/black)
a - cycle through bounding box axes states
m - cycle through mesh states
p - cycle through color palettes
t - cycle through materials and lights
0 - begin rotating around z-axis
. - pause rotation
*// - zoom in/out

These can be set using the keys argument when creating a glvis object.

glvis(data, keys='rljgac//0')

This combination of keys would: r reset the view, l toggle the light, j toggle perspective, g toggle the background color to black (default is white), a show the bounding box, c show the colorbar, // zoom out twice, and 0 begin rotating around the z-axis:

pyglvis_preset_keys

Alternatively, keys can be typed directly into the widget after it has been created:

pyglvis_using_keys

Other methods

Once you have a glvis object there are a few methods that can used to update the visualization, besides using keys:

# Show a new Mesh/GridFunction, resets keys
g.plot(data)
# Show an updated visualization with the same data, preserving keys
g.update(data)
# Change the image size
g.set_size(width, height)
# Force the widget to render. If the widget isn't the last statement in a cell it
# will not be shown without this. See ex9.ipynb
g.render()

See the examples directory for additional examples. To test those locally, start a Jupyter lab server with

jupyter lab

🐛 Troubleshooting

This widget was originally developed using the jupyter widget cookiecutter; however, recent changes to the Jupyter ecosystem have broken a lot of functionality, leading to a rewrite using anywidget. If you encounter any problems, please consider supporting development by opening an issue.

🤖 Development

PyGLVis dependencies

graph TD;
    A[mfem] --> B[pymfem];
    A --> C[glvis];
    C --> D[glvis-js];
    Ext1[emscripten] --> D;
    D-.-E["glvis-js\n(npm/esm mirror)"]
    B & E --> G[pyglvis];
    Ext2[jupyter] --> G;

pyglvis is most directly depednent on PyMFEM and glvis-js. PyMFEM is a Python wrapper of the finite element library, MFEM, while glvis-js is a JavaScript/WebAssembly port of glvis.

glvis-js is hosted on github and mirrored on npm. esm.sh allows pyglvis to pull the latest version of glvis-js directly from npm. This can be seen in the first line of glvis/widget.js:

import glvis from "https://esm.sh/glvis";

You can specify a different version of glvis-js by adding @x.y.z to the end of this import statement, where x.y.z matches a version number available on npm, e.g.

import glvis from "https://esm.sh/glvis@0.6.3";

Releasing a new version of glvis on NPM:

To publish a new version of glvis-js, follow the instructions on the repo.

Releasing a new version of glvis on PyPI:

Update __version__ in glvis/__about__.py
git add and git commit changes

You will need twine to publish to PyPI, install with pip.

python -m hatch build
twine upload dist/*
git tag -a X.X.X -m 'comment'
git push --tags

🌐 Links

MFEM (website, github)
PyMFEM (github, pypi)
GLVis (website, github)
glvis-js (github, npm, esm)
pyglvis (github, [pypi]())

GLVis / pyglvis

readme