Metadata-Version: 2.4
Name: gwbpy
Version: 0.1.0a1
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 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

| Parameter | Meaning |
|---|---|
| `m1`, `m2` | Masses in solar masses |
| `f_lower` | Starting GW frequency in Hz. Higher means fewer orbits |
| `initial_separation_km` | Alternative to `f_lower` (converted with Kepler's law) |
| `merge_frame` | Frame at which the dynamics end (merger) |
| `frames` | Total clip length (default `merge_frame + 50`) |
| `meters_per_unit` | Real meters per Blender unit; scales orbit and spheres together |
| `close_merger` | Schematically close any remaining gap (default True) |
| `show_paths` | Show motion-path trails |

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.
