A visualization code for gravitational wave data I created in 2020 with Python and ParaView, published under the MIT license.

This Python package uses the ParaView scientific visualization toolkit to produce 3D renderings of gravitational wave data from a numerical simulation or a waveform model.

From in the nilsleiffischer/gwpv GitHub repository:


Render gravitational waves from waveform data with ParaView

Table of contents


Option 1: Pre-built Docker container

  1. Install Docker.
  2. docker run nilsleiffischer/gwpv:latest

Docker will pull the latest pre-built image and run it. The container runs the entrypoint automatically (see Usage). To make your scene configuration files and data available in the container you can mount directories using Docker’s -v option, e.g.:

docker run \
  -v /path/to/Examples:/Examples \
  nilsleiffischer/gwpv:latest \
  scene /Examples/Rainbow/Rainbow.yaml \
  -o /Examples/Rainbow/dist

Option 2: Native environment

  1. Create a virtual environment with ParaView’s Python. With Python 3 you could do this:
    path/to/python3 -m venv path/to/new/env

    Make sure to set up the environment with the same Python installation that ParaView uses. If you are unsure, try this:

    # Start interactive ParaView Python shell
    # Output path to the Python executable
    >>> import sys
    >>> sys.executable

    The displayed executable may be named vtkpython, in which case you can look for the python2 or python3 executable in the same directory or a bin subdirectory.

  2. Give ParaView access to the environment. For example, append the following line to path/to/env/bin/activate (adjusting the Python version appropriately):
    export PYTHONPATH="$VIRTUAL_ENV/lib/pythonX.Y/site-packages/:$PYTHONPATH"

    This will allow ParaView’s Python to pick up the packages installed in the environment once the environment is activated. You may also want to add the ParaView executables such as pvpython to your PATH when the environment is activated for convenient access. To do so you can append the following line to path/to/env/bin/activate as well:

    export PATH="path/to/paraview/bin/:$PATH"

    On macOS you may also need to append this line to pick up the paraview GUI executable:

    export PATH="path/to/paraview/MacOS/:$PATH"

    Note that the path/to/paraview on MacOS is likely something like /Applications/ if you installed the standard GUI application.

  3. Install the following packages in the environment, making sure to use ParaView’s HDF5 when installing h5py:
    . env/bin/activate
    HDF5_DIR=path/to/paraview/hdf5/ pip install --no-binary=h5py h5py
    pip install scipy spherical_functions numba pyyaml tqdm
    pip install [-e] path/to/this/repository

    Note that the HDF5_DIR should have include and lib directories with ParaView’s HDF5. Add the -e flag when installing this repository’s Python package to install it in “editable” mode, i.e. symlink instead of copy it so changes to the repository are reflected in the installation.


Explore waveform data in the ParaView GUI application

  1. We need to make ParaView aware of our Python environment and the plugins in this repository. This is easiest done from the command line. Before launching the ParaView GUI, make sure the Python environment is activated and the PYTHONPATH is set as described in the section above. Then launch ParaView like this:
    PV_PLUGIN_PATH=path/to/paraview_plugins path/to/paraview

    You will now find the plugins provided by this repository in the ParaView GUI when you select ‘Tools’ > ‘Manage Plugins’.

  2. Open a waveform data file in ParaView and select the Waveform Data Reader to load it. Waveform data files in SpEC’s output format are currently supported.
  3. Add the Waveform To Volume filter to the loaded data.
  4. Change the representation to Volume and adjust the following properties:
    • Volume Rendering Mode (try GPU Based and enable Shade)
    • Scalar Opacity Unit Distance (try a quarter of the domain size)
    • Transfer function (select Edit color map)

Render without the ParaView GUI

With your Python environment activated (see Installation), run like this: \
  scene Examples/Rainbow/Rainbow.yaml \
  --render-movie-to-file path/to/output/filename \
  --num-jobs NUM_JOBS \

You find examples for scene configuration files in Examples/.

Feel free to turn up the NUM_JOBS to render the frames in parallel.

If you get import errors, make sure you have activated the virtual environment and the PYTHONPATH contains a reference to its site-packages.

Licensing and credits

This code is distributed under the MIT license. Please see the LICENSE for details. When you use code from this project or publish media produced by this code, please include a reference back to the nilsleiffischer/gwpv repository.

Copyright (c) 2020 Nils Leif Fischer