gwbpy

Gravitational-wave and pulsar visualization for Blender.

Status: alpha (0.1.0a2). Expect rough edges. Pre-release on PyPI.

What it does

• animate_binary_physical(): two bodies (black holes or neutron stars) that spiral together and merge, driven by SEOBNRv5HM effective-one-body dynamics, or that sit on a steady circular orbit (for continuous-wave sources).
• animate_gw_polarization(): a ring, or a tube of rings, of free test particles deformed by a gravitational wave. Standalone, or linked to a circular binary.
• animate_pulsar(): a spinning neutron star with lighthouse beams, optionally aimed at an observer.
• animate_pta(): several pulsars around one observer, with pulses traveling along the lines of sight.

Each function documents its options: in Blender's Python console, run help(gwbpy.animate_pta) and so on. The console also prints what it did, including warnings, so keep Window > Toggle System Console open.

Tested on

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

Not tested: macOS, other Linux distributions, Windows without WSL, and installing the PyPI release into Blender's own Python.

What needs the physics environment

Only animate_binary_physical(..., inspiral=True), the default. 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) with pyseobnr and lalsuite. Animation calls run a small worker there, read the result back, and keyframe it. Everything else (the circular orbit, polarization ring, pulsar and PTA scenes) runs in Blender's own Python with numpy, with no setup step.

Install

1. Get the gwbpy folder where Blender can import it. The route that has been tested is to put the folder somewhere on disk (a wheel from PyPI is a zip file, so you can unpack one) and add its parent folder to Blender's path, in the Scripting tab:

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

2. For inspiral binaries only, 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
   

3. Then build the physics environment, once:

    gwbpy.setup()
   

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

Examples

A merging pair of black holes:

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

A neutron star and a black hole (m1 is the black hole for "BHNS"):

gwbpy.animate_binary_physical(m1=5, m2=1.4, system="BHNS", f_lower=300,
                              merge_frame=250, meters_per_unit=500.0)

A steady circular binary with two polarization rings around it:

gwbpy.animate_binary_physical(m1=30, m2=30, inspiral=False,
                              initial_separation_km=2000, period_frames=60,
                              frames=240, meters_per_unit=300000.0)
gwbpy.animate_gw_polarization(h=0.25, inclination_deg=0, name="face_on")
gwbpy.animate_gw_polarization(h=0.25, inclination_deg=90, name="edge_on")

A pulsar timing array scene:

gwbpy.animate_pta(n_pulsars=5, seed=1)

What is physics and what is not

Binary (inspiral=True)

• Orbital separation and phase come from the SEOBNRv5HM effective-one-body dynamics. Separation is the EOB radial coordinate, not a literal horizon position. Non-spinning only.
• Black holes are drawn at their Schwarzschild radius. Neutron stars are drawn at a fixed radius (ns_radius_km, default 12 km), and their glow is styling.
• For systems with neutron stars the orbit still comes from a binary-black-hole model, stopped at contact. Tides, disruption and matter effects are not modeled.
• Time is stretched; the slowdown factor is printed. If the data end slightly short of contact, a short schematic closing step finishes the merger; it is a visual stand-in, and the ringdown is not modeled (close_merger=False removes it).

Circular binary (inspiral=False)

• Newtonian Kepler orbit with no decay. A warning is printed below about 10 M.

Polarization ring

• Leading-order quadrupole radiation from a circular binary, transverse-traceless gauge, first order in the strain. The strain is greatly exaggerated (the console prints the factor); real strains are of order 1e-21.
• The phase offset between the ring and the orbit follows a hand derivation and has not been checked against a reference.
• The tube length and wave delay are a cartoon.

Pulsar and PTA

• The lighthouse geometry is real; everything else is a cartoon. Spin periods, light travel times and distances are not to scale, the beams are opaque cones, and the signals are uniform stylized spikes (or spheres).
• No gravitational wave acts on the pulses yet.

Known limits

• SEOBNRv5HM 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, so every run has at least about 5 orbits.
• Systems with long inspirals (for example two neutron stars from tens of Hz) are refused above max_orbits, since they alias and create huge numbers of keyframes.
• If the console warns about more than half a turn per frame, the motion will look aliased. Raise merge_frame, or use a higher f_lower.
• Colors and glow show in Material Preview or renders, not in the Solid viewport.

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

For the polarization pictures, M. Isi, "Parametrizing gravitational wave polarizations" (2022) and its animations at https://maxisi.github.io/gwpols/ (CC-BY-SA 4.0) are a good reference, and for the quadrupole formulas see Maggiore, Gravitational Waves, Vol. 1.

Citations were copied or recalled by hand. Check them before use.

License

No license has been chosen yet. pyseobnr, which the physics environment installs, is GPL-3.0-or-later.