gwbpy

Gravitational-wave visualization for Blender.

Status: alpha (v0.1.0). Not on PyPI yet. Expect rough edges.

Currently one function, animate_binary_physical(): two black holes spiral together and merge, driven by SEOBNRv5HM effective-one-body dynamics.

Tested on

• Blender 5.0 on Windows, with Ubuntu 24.04 under WSL2
• The setup script on Ubuntu 24.04

Not tested: macOS, other Linux distributions, Windows without WSL.

How it works

Blender's Python cannot run the physics libraries, so gwbpy builds a separate Python 3.11 environment at ~/.gwbpy/dynamics-env (inside WSL on Windows) containing pyseobnr and lalsuite. Animation calls run a small worker in that environment, read the result back, and keyframe it in Blender.

Install

1. Install system packages once, in a Linux or WSL terminal:

    sudo apt update && sudo apt install -y python3-venv libgsl-dev swig build-essential libfftw3-dev libhdf5-dev
   

2. Make gwbpy importable in Blender. Until it is on PyPI, clone this repository and, in Blender's Scripting tab, run (with the folder that contains gwbpy/):

    import sys
    sys.path.insert(0, r"PATH_TO_FOLDER_CONTAINING_gwbpy")
    import gwbpy
   

3. Build the physics environment, once:

    gwbpy.setup()
   

   The first run builds from source and takes about 10 minutes. Blender may look frozen meanwhile. Window > Toggle System Console shows progress. If system packages are missing, setup stops and prints the exact command to run. Use gwbpy.setup(force=True) to rebuild.

Example

gwbpy.animate_binary_physical(m1=30, m2=15, merge_frame=100, frames=200,
                              f_lower=80.0, meters_per_unit=20000.0)

Main parameters

The console reports the real inspiral duration, the slowdown factor, the number of frames per orbit at the start, and how long any schematic closing step is. Read these before putting numbers on a slide.

What is physics and what is not

• Orbital separation and phase come from the SEOBNRv5HM effective-one-body dynamics. Separation is the EOB radial coordinate, not a literal horizon position.
• Sphere sizes are the Schwarzschild radii of the two masses. The bodies are non-spinning and do not deform.
• Each body sits at its Newtonian center-of-mass fraction of the separation.
• Time is stretched. The slowdown factor is printed.
• If the data ends slightly short of the horizons touching, a short schematic closing step finishes the merger. It is a visual stand-in, not physics. close_merger=False removes it. The ringdown is not modeled.
• Non-spinning only for now.

Known limits

• The model never starts closer than a separation of 10 M. A requested start frequency above about 2044 / (m1 + m2) Hz (masses in solar masses) is lowered to that value, and a note is printed. Every run therefore has at least about 5 orbits.
• Frames per orbit matters. If the console warns about more than half a turn per frame, the motion will look aliased. Raise merge_frame, or reduce the number of orbits with a higher f_lower.

Citing

pyseobnr asks that results made with it acknowledge the software and the model papers:

• Mihaylov et al., "pySEOBNR: a software package for the next generation of effective-one-body multipolar waveform models", arXiv:2303.18203
• Pompili et al., "Laying the foundation of the effective-one-body waveform models SEOBNRv5", arXiv:2303.18039

(Citations copied from the pyseobnr PyPI page. Check them before use.)

License

To be decided. pyseobnr is GPL-3.0-or-later.