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:

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

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 (esm)"]
    B & E --> G[pyglvis];
    Ext2[jupyter] --> G;

pyglvis is most directly dependent 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]())