Metadata-Version: 2.4
Name: gwbpy
Version: 0.1.0a2
Summary: Gravitational-wave visualizations for Blender (alpha)
Author: Ellis Eisenberg
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy

# 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.
