gwbpy 0.1.0a1__tar.gz

gwbpy-0.1.0a1/PKG-INFO

@@ -0,0 +1,120 @@
+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.

gwbpy-0.1.0a1/README.md

@@ -0,0 +1,107 @@
+# 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.

gwbpy-0.1.0a1/gwbpy/__init__.py

@@ -0,0 +1,5 @@
+from .setup_env import setup
+from .animate import animate_binary_physical
+
+__version__ = "0.1.0a1"
+__all__ = ["setup", "animate_binary_physical"]

gwbpy-0.1.0a1/gwbpy/animate.py

@@ -0,0 +1,299 @@
+"""
+gwbpy.animate
+
+Physics-driven animation of a compact binary inspiral in Blender.
+Orbital separation and phase come from the SEOBNRv5HM effective-one-body
+dynamics (via pyseobnr, run in a separate environment; see gwbpy.physics).
+
+Units convention: all masses (m1, m2) are in solar masses (M_sun).
+"""
+
+import numpy as np
+
+try:
+    import bpy
+    import bmesh
+except ImportError:
+    bpy = None
+    bmesh = None
+
+# Physical constants (SI units)
+G = 6.67430e-11
+C = 2.99792458e8
+M_SUN = 1.98892e30  # kg
+
+
+def _schwarzschild_radius_m(mass_solar: float) -> float:
+    """r_sch = 2GM / c^2, in meters, for a mass given in solar masses."""
+    return 2 * G * mass_solar * M_SUN / C ** 2
+
+
+def _f_lower_for_initial_separation(m1: float, m2: float, separation_km: float) -> float:
+    """Convert initial separation (km) to starting GW frequency (Hz)
+    via Newtonian Kepler's third law (f_gw = 2 * f_orb)."""
+    total_mass_kg = (m1 + m2) * M_SUN
+    r_m = separation_km * 1000.0
+    omega_orb = np.sqrt(G * total_mass_kg / r_m ** 3)
+    return omega_orb / np.pi
+
+
+def _make_sphere(name: str, radius: float):
+    mesh = bpy.data.meshes.new(name + "_mesh")
+    bm = bmesh.new()
+    bmesh.ops.create_uvsphere(bm, u_segments=32, v_segments=16, radius=radius)
+    bm.to_mesh(mesh)
+    bm.free()
+    obj = bpy.data.objects.new(name, mesh)
+    bpy.context.collection.objects.link(obj)
+    return obj
+
+
+def _show_motion_path(obj, frame_start: int, frame_end: int):
+    obj.select_set(True)
+    bpy.context.view_layer.objects.active = obj
+    bpy.ops.object.paths_calculate(display_type='RANGE', range='SCENE')
+
+
+def _set_linear_interpolation(obj):
+    """Force LINEAR interpolation on location F-curves. Handles both the
+    old action.fcurves API and Blender 4.4+/5.0 layered actions."""
+    if not (obj.animation_data and obj.animation_data.action):
+        return
+    action = obj.animation_data.action
+    if hasattr(action, "fcurves"):
+        fcurves = list(action.fcurves)
+    else:
+        fcurves = []
+        for layer in action.layers:
+            for strip in layer.strips:
+                for channelbag in strip.channelbags:
+                    fcurves.extend(channelbag.fcurves)
+    for fcurve in fcurves:
+        for kp in fcurve.keyframe_points:
+            kp.interpolation = 'LINEAR'
+
+
+def animate_binary_physical(m1: float = 30.0, m2: float = 25.0,
+                             merge_frame: int = 200,
+                             frames: int = None,
+                             f_lower: float = 40.0,
+                             initial_separation_km: float = None,
+                             meters_per_unit: float = 15000.0,
+                             close_merger: bool = True,
+                             max_close_frames: float = 30.0,
+                             show_paths: bool = True):
+    """
+    Physics-driven binary inspiral from SEOBNRv5HM effective-one-body
+    dynamics (pyseobnr).
+
+    Physics inputs: m1, m2 (solar masses) and f_lower (Hz) OR
+    initial_separation_km. These set how many orbits happen before merger.
+    The model may start the inspiral earlier than requested for short
+    waveforms (it prints a warning); quote the printed start separation.
+
+    Timing inputs: merge_frame is the Blender frame where the dynamics
+    reach their end. frames is the total clip length (default
+    merge_frame + 50). Real time is stretched; the slowdown factor is
+    printed. If frames < merge_frame, the clip ends before the merger.
+
+    Separation is the EOB radial coordinate, not a literal horizon
+    position. Real data is used until the sum of the Schwarzschild radii
+    is reached, or until the data ends. If close_merger is True, any
+    remaining gap is closed by continuing the measured rotation rate and
+    inward speed (minimum 1 frame, at most max_close_frames, sampled at
+    0.1-frame steps). That closing step is a visual stand-in, not
+    physics. The merged state is then held until the end of the clip.
+    If close_merger is False, the bodies hold at their last real position.
+
+    Sphere sizes are real Schwarzschild radii, converted with the same
+    meters_per_unit as the orbit, so relative proportions stay physical.
+
+    Parameters
+    ----------
+    m1, m2 : float
+        Masses, in solar masses (M_sun).
+    merge_frame : int
+        Frame at which the dynamics end (merger).
+    frames : int, optional
+        Total animation length. Defaults to merge_frame + 50.
+    f_lower : float
+        Starting GW frequency (Hz). Higher = fewer orbits, easier to read.
+        Ignored if initial_separation_km is given.
+    initial_separation_km : float, optional
+        Starting separation (km), converted to f_lower via Kepler's law.
+    meters_per_unit : float
+        Real meters per Blender unit (applies to orbit and body size).
+    close_merger : bool
+        Schematically close any remaining gap into one merged object.
+    max_close_frames : float
+        Longest the schematic closing step may take, in frames.
+    show_paths : bool
+        Show motion path trails.
+    """
+    if bpy is None:
+        raise RuntimeError("animate_binary_physical() must be called from inside Blender.")
+
+    from . import physics
+
+    if frames is None:
+        frames = merge_frame + 50
+    merge_frame = max(int(merge_frame), 2)
+
+    if initial_separation_km is not None:
+        f_lower = _f_lower_for_initial_separation(m1, m2, initial_separation_km)
+        print(f"[gwbpy] initial_separation_km={initial_separation_km} -> "
+              f"f_lower={f_lower:.3f} Hz (Kepler approximation)")
+    # pyseobnr never starts closer than a Newtonian separation of 10 M
+    # (orbital omega = 10**-1.5 in units of 1/M). Clamp here so the user
+    # sees the limit explicitly instead of the model changing it silently.
+    t_unit = G * (m1 + m2) * M_SUN / C ** 3
+    f_max_start = 10 ** -1.5 / (np.pi * t_unit)
+    if f_lower > f_max_start:
+        print(f"[gwbpy] NOTE: the SEOBNRv5HM model cannot start closer than "
+              f"a separation of 10 M ({10 * t_unit * C / 1000:.0f} km for "
+              f"M = {m1 + m2:g} Msun), which is a GW start frequency of "
+              f"about {f_max_start:.1f} Hz. You asked for {f_lower:.1f} Hz, "
+              f"so the inspiral starts at {f_max_start:.1f} Hz instead "
+              f"(about 5 orbits before merger). The model cannot show fewer orbits, "
+              f"a larger merge_frame only slows the rotation on screen. ")
+              
+        f_lower = f_max_start * (1 - 1e-9)
+    print("[gwbpy] Requesting EOB dynamics from physics worker...")
+    data = physics.generate_dynamics(m1=m1, m2=m2, f_lower=f_lower)
+    print(f"[gwbpy] Requested start {f_lower:.1f} Hz; model actually started at "
+          f"about {float(data['f_start_hz']):.1f} Hz.")
+    merger_idx = int(data["merger_idx"])
+    times = data["times"][:merger_idx + 1]
+    radius_units = data["radius_m"][:merger_idx + 1] / meters_per_unit
+    orbital_angle = data["orbital_angle"][:merger_idx + 1]
+
+    size1 = _schwarzschild_radius_m(m1) / meters_per_unit
+    size2 = _schwarzschild_radius_m(m2) / meters_per_unit
+    touch_distance = size1 + size2
+
+    # Fixed time mapping: real start -> frame 1, real end -> merge_frame.
+    t0, t1 = times[0], times[-1]
+    real_duration = float(t1 - t0)
+    fps = bpy.context.scene.render.fps / bpy.context.scene.render.fps_base
+    slowdown = (merge_frame / fps) / real_duration
+    print(f"[gwbpy] Real inspiral duration: {real_duration:.4f} s. "
+          f"On screen: {merge_frame / fps:.2f} s at {fps:.0f} fps "
+          f"({slowdown:.0f}x slower than real time).")
+    frame_floats = 1 + (times - t0) / (t1 - t0) * (merge_frame - 1)
+    k = min(5, len(times) - 1)
+    if k > 0 and frame_floats[k] > frame_floats[0]:
+        rate = (orbital_angle[k] - orbital_angle[0]) / (frame_floats[k] - frame_floats[0])
+        if rate > 0:
+            print(f"[gwbpy] At the start, one orbit takes about "
+                  f"{2 * np.pi / rate:.0f} frames.")
+    # Stop real data at the first sample where the horizons touch.
+    below = np.where(radius_units <= touch_distance)[0]
+    touched = len(below) > 0
+    if touched:
+        end_i = int(below[0])
+        frame_floats = frame_floats[:end_i + 1]
+        radius_units = radius_units[:end_i + 1]
+        orbital_angle = orbital_angle[:end_i + 1]
+        times = times[:end_i + 1]
+        print(f"[gwbpy] Horizons touch at frame {frame_floats[-1]:.1f}.")
+    n_real = len(times)
+
+    # Aliasing check: how far do the bodies turn between whole frames?
+    last_whole = max(int(frame_floats[-1]), 2)
+    int_frames = np.arange(1, last_whole + 1)
+    angle_at_frames = np.interp(int_frames, frame_floats, orbital_angle)
+    turn_per_frame = np.abs(np.diff(angle_at_frames))
+    n_bad = int(np.sum(turn_per_frame > np.pi))
+    if n_bad > 0:
+        print(f"[gwbpy] WARNING: in {n_bad} frames the bodies rotate more than "
+              f"half a turn per frame "
+              f"(max {turn_per_frame.max() / (2 * np.pi):.2f} turns/frame), "
+              f"so motion will look aliased/chaotic. Try a higher f_lower, "
+              f"a smaller initial_separation_km, or a larger merge_frame.")
+
+    # Keep samples inside the clip, thinning the dense ones.
+    inside = np.where(frame_floats <= frames)[0]
+    if len(inside) == 0:
+        raise RuntimeError("No samples fall inside the requested frame range.")
+    if frames < merge_frame:
+        print(f"[gwbpy] NOTE: frames ({frames}) < merge_frame ({merge_frame}); "
+              f"the clip may end before the merger.")
+
+    keep = [inside[0]]
+    last_f = frame_floats[inside[0]]
+    for i in inside[1:]:
+        if frame_floats[i] - last_f >= 0.1 or i == inside[-1]:
+            keep.append(i)
+            last_f = frame_floats[i]
+
+    body1 = _make_sphere("gwbpy_body1", size1)
+    body2 = _make_sphere("gwbpy_body2", size2)
+    bpy.context.scene.frame_start = 1
+    bpy.context.scene.frame_end = frames
+
+    frac1 = m2 / (m1 + m2)
+    frac2 = m1 / (m1 + m2)
+
+    def key(frame_val, r, a):
+        body1.location = (frac1 * r * np.cos(a), frac1 * r * np.sin(a), 0)
+        body1.keyframe_insert(data_path="location", frame=float(frame_val))
+        body2.location = (-frac2 * r * np.cos(a), -frac2 * r * np.sin(a), 0)
+        body2.keyframe_insert(data_path="location", frame=float(frame_val))
+
+    for i in keep:
+        key(frame_floats[i], radius_units[i], orbital_angle[i])
+
+    closing_frames = 0.0
+    reached_end = keep[-1] == n_real - 1
+
+    if reached_end and frames > frame_floats[-1]:
+        f_end = float(frame_floats[-1])
+        r_last = float(radius_units[-1])
+        a_last = float(orbital_angle[-1])
+
+        if close_merger and r_last > 0:
+            # Measure rates over (at least) the last whole frame of data.
+            j = int(np.searchsorted(frame_floats, f_end - 1.0))
+            j = min(j, n_real - 2) if n_real >= 2 else 0
+            df = f_end - float(frame_floats[j])
+            if n_real >= 2 and df > 0:
+                omega = (a_last - float(orbital_angle[j])) / df
+                rdot = (r_last - float(radius_units[j])) / df
+            else:
+                omega, rdot = 0.0, -r_last
+            if rdot > -1e-12:
+                rdot = -r_last  # not closing; fall back to 1 frame
+
+            duration = min(max(r_last / abs(rdot), 1.0), max_close_frames)
+            n_steps = max(int(round(duration / 0.1)), 1)
+            last_key_frame = f_end
+            for s_i in range(1, n_steps + 1):
+                s = duration * s_i / n_steps
+                if f_end + s > frames:
+                    break
+                key(f_end + s, r_last * (1 - s / duration), a_last + omega * s)
+                last_key_frame = f_end + s
+            closing_frames = last_key_frame - f_end
+            reached_zero = closing_frames >= duration - 1e-9
+            hold_r = 0.0 if reached_zero else None
+            hold_a = a_last + omega * duration
+        else:
+            hold_r, hold_a = r_last, a_last
+            last_key_frame = f_end
+
+        # Hold the final state until the end of the clip.
+        if hold_r is not None and frames > last_key_frame:
+            key(frames, hold_r, hold_a)
+
+    _set_linear_interpolation(body1)
+    _set_linear_interpolation(body2)
+    bpy.context.scene.frame_set(1)
+
+    if show_paths:
+        _show_motion_path(body1, 1, frames)
+        _show_motion_path(body2, 1, frames)
+
+    print(f"[gwbpy] animate_binary_physical complete: {len(keep)} real keyframes, "
+          f"merger mapped to frame {merge_frame}, clip length {frames}, "
+          f"schematic closing step: {closing_frames:.1f} frames, "
+          f"r_sch = {size1:.3e}/{size2:.3e} units")

gwbpy-0.1.0a1/gwbpy/physics.py

@@ -0,0 +1,133 @@
+"""
+gwbpy.physics
+
+Bridges Blender's Python to the separate physics environment (pyseobnr on
+Python 3.11), located at ~/.gwbpy/dynamics-env.
+
+On Linux/macOS the environment's Python is called directly. On Windows,
+Blender runs natively while the environment lives inside WSL, so calls go
+through wsl.exe, using the default WSL distribution (override with the
+GWBPY_WSL_DISTRO environment variable).
+"""
+
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import numpy as np
+
+WORKER_DIR = os.path.join(os.path.dirname(__file__), "workers")
+IS_WINDOWS = sys.platform == "win32"
+
+ENV_PYTHON_REL = ".gwbpy/dynamics-env/bin/python"
+
+_python_cache = None
+
+
+def _wsl_prefix() -> list:
+    distro = os.environ.get("GWBPY_WSL_DISTRO")
+    return ["wsl.exe", "-d", distro] if distro else ["wsl.exe"]
+
+
+def _to_wsl_path(path: str) -> str:
+    """Convert a Windows path (drive letter or \\\\wsl$ share) to the path
+    WSL itself sees. Returns the input unchanged if it isn't a Windows path."""
+    m = re.match(r"^\\\\wsl(?:\$|\.localhost)\\[^\\]+\\(.*)$", path)
+    if m:
+        return "/" + m.group(1).replace("\\", "/")
+    m = re.match(r"^([A-Za-z]):\\(.*)$", path)
+    if m:
+        return f"/mnt/{m.group(1).lower()}/" + m.group(2).replace("\\", "/")
+    return path
+
+
+def _find_env_python() -> str:
+    """Locate the physics environment's Python (inside WSL on Windows)."""
+    global _python_cache
+    if _python_cache:
+        return _python_cache
+
+    if IS_WINDOWS:
+        res = subprocess.run(
+            _wsl_prefix() + ["-e", "sh", "-c", "echo $HOME"],
+            capture_output=True, text=True, encoding="utf-8",
+            errors="replace", timeout=120,
+        )
+        home = res.stdout.strip()
+        if res.returncode != 0 or not home.startswith("/"):
+            raise RuntimeError(
+                "Could not reach WSL. Install WSL with a Linux distribution, "
+                "or set GWBPY_WSL_DISTRO to the distribution that holds the "
+                "gwbpy physics environment."
+            )
+        python = f"{home}/{ENV_PYTHON_REL}"
+        ok = subprocess.run(
+            _wsl_prefix() + ["-e", "test", "-x", python],
+            capture_output=True, timeout=120,
+        ).returncode == 0
+    else:
+        python = os.path.expanduser(f"~/{ENV_PYTHON_REL}")
+        ok = os.path.exists(python)
+
+    if not ok:
+        raise RuntimeError(
+            f"gwbpy physics environment not found at {python}. "
+            "Run gwbpy.setup() first."
+        )
+
+    print(f"[gwbpy] Using physics environment: {python}")
+    _python_cache = python
+    return python
+
+
+def _run_worker(worker_name: str, args: list) -> None:
+    worker_path = os.path.join(WORKER_DIR, worker_name)
+    if not os.path.exists(worker_path):
+        raise RuntimeError(f"Worker script not found: {worker_path}")
+
+    python = _find_env_python()
+
+    if IS_WINDOWS:
+        cmd = _wsl_prefix() + ["-e", python, _to_wsl_path(worker_path),
+                               *[_to_wsl_path(a) for a in args]]
+    else:
+        cmd = [python, worker_path, *args]
+
+    print(f"[gwbpy] Running physics worker: {worker_name}")
+    process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                                text=True, bufsize=1)
+    if process.stdout:
+        for line in process.stdout:
+            print(f"    {line.rstrip()}")
+    process.wait()
+
+    if process.returncode != 0:
+        raise RuntimeError(
+            f"Physics worker '{worker_name}' failed (exit code {process.returncode})."
+        )
+
+
+def _load_npz(out_path: str) -> dict:
+    data = np.load(out_path)
+    result = {key: data[key] for key in data.files}
+    data.close()  # Windows is strict about open handles before tempdir cleanup
+    return result
+
+
+def generate_dynamics(m1: float, m2: float, f_lower: float = 20.0,
+                       chi1: float = 0.0, chi2: float = 0.0) -> dict:
+    """
+    EOB dynamics (SEOBNRv5HM via pyseobnr): separation and orbital phase
+    vs time. Returns times (s), radius_m, orbital_angle, merger_idx,
+    f_start_hz. m1, m2 in solar masses; chi1, chi2 are aligned
+    dimensionless spins.
+    """
+    with tempfile.TemporaryDirectory() as tmpdir:
+        out_path = os.path.join(tmpdir, "dynamics_result.npz")
+        _run_worker(
+            "dynamics_worker.py",
+            ["--m1", str(m1), "--m2", str(m2), "--f-lower", str(f_lower),
+             "--chi1", str(chi1), "--chi2", str(chi2), "--out", out_path],
+        )
+        return _load_npz(out_path)

gwbpy-0.1.0a1/gwbpy/scripts/install_env.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# gwbpy: create the physics environment at ~/.gwbpy/dynamics-env
+# (pyseobnr + lalsuite on Python 3.11).
+# Run directly or via gwbpy.setup().
+#   usage: install_env.sh [--force]
+# Exit codes: 0 = ready, 1 = failed, 2 = system packages missing.
+
+ENV_DIR="$HOME/.gwbpy/dynamics-env"
+BOOT_DIR="$HOME/.gwbpy/bootstrap"
+APT_LINE="sudo apt update && sudo apt install -y python3-venv libgsl-dev swig build-essential libfftw3-dev libhdf5-dev"
+
+echo "[gwbpy] Checking system requirements..."
+missing=""
+command -v python3 >/dev/null 2>&1 || missing="$missing python3"
+python3 -c "import ensurepip, venv" >/dev/null 2>&1 || missing="$missing python3-venv"
+command -v gsl-config >/dev/null 2>&1 || missing="$missing libgsl-dev"
+command -v swig >/dev/null 2>&1 || missing="$missing swig"
+command -v gcc >/dev/null 2>&1 || missing="$missing build-essential"
+
+if [ -n "$missing" ]; then
+  echo "[gwbpy] Missing system packages:$missing"
+  echo "[gwbpy] Run this once in a Linux/WSL terminal, then call setup() again:"
+  echo "    $APT_LINE"
+  exit 2
+fi
+
+if [ "${1:-}" = "--force" ]; then
+  echo "[gwbpy] --force: removing existing environment"
+  rm -rf "$ENV_DIR"
+fi
+
+if [ -x "$ENV_DIR/bin/python" ] && "$ENV_DIR/bin/python" -c "import pyseobnr" >/dev/null 2>&1; then
+  echo "[gwbpy] Found working environment at $ENV_DIR, skipping setup."
+  echo "[gwbpy] (use setup(force=True) to rebuild)"
+  exit 0
+fi
+rm -rf "$ENV_DIR"   # clear out any broken leftovers
+
+mkdir -p "$HOME/.gwbpy"
+if [ ! -x "$BOOT_DIR/bin/uv" ]; then
+  echo "[gwbpy] Installing the uv helper..."
+  python3 -m venv "$BOOT_DIR" || exit 1
+  "$BOOT_DIR/bin/pip" install --progress-bar off uv || exit 1
+fi
+UV="$BOOT_DIR/bin/uv"
+
+echo "[gwbpy] Creating Python 3.11 environment (downloads Python if needed)..."
+"$UV" venv "$ENV_DIR" --python 3.11 || exit 1
+PY="$ENV_DIR/bin/python"
+
+echo "[gwbpy] Installing packages (first time takes about 10 minutes)..."
+# pygsl-lite (a pyseobnr dependency) has an old build script that breaks
+# under the newest setuptools. Build it without isolation, using the older
+# setuptools installed here, plus setuptools-scm for its version number.
+"$UV" pip install --python "$PY" "setuptools<70" "setuptools-scm[toml]>=3.4.3" wheel numpy || exit 1
+"$UV" pip install --python "$PY" --no-build-isolation-package pygsl-lite pyseobnr lalsuite || exit 1
+
+echo "[gwbpy] Verifying..."
+"$PY" -c "from pyseobnr.generate_waveform import generate_modes_opt" || exit 1
+echo "[gwbpy] Setup complete: $PY"

gwbpy-0.1.0a1/gwbpy/setup_env.py

@@ -0,0 +1,81 @@
+"""
+gwbpy.setup_env
+
+One-time setup of the physics environment at ~/.gwbpy/dynamics-env
+(pyseobnr + lalsuite on Python 3.11). The work is done by
+scripts/install_env.sh, which runs on Linux or inside WSL. On Windows,
+Blender runs natively, so the script is run through wsl.exe.
+
+Supported platforms: Ubuntu, and Windows with WSL (Ubuntu). Other
+platforms are untested.
+"""
+
+import os
+import subprocess
+import sys
+
+from .physics import _wsl_prefix, _to_wsl_path
+
+SCRIPT = os.path.join(os.path.dirname(__file__), "scripts", "install_env.sh")
+
+
+def setup(force: bool = False) -> bool:
+    """
+    Create the physics environment (pyseobnr + lalsuite on Python 3.11).
+    Run once from Blender's scripting tab:
+
+        import gwbpy
+        gwbpy.setup()
+
+    Takes several minutes the first time, and Blender may look frozen
+    meanwhile (Window > Toggle System Console shows the progress).
+    If system libraries are missing, it prints the exact apt command to
+    run once in a Linux/WSL terminal.
+
+    Parameters
+    ----------
+    force : bool
+        Delete and rebuild the environment even if it already works.
+
+    Returns
+    -------
+    bool
+        True if the environment is ready.
+    """
+    if not os.path.exists(SCRIPT):
+        print(f"[gwbpy] ERROR: setup script not found at {SCRIPT}")
+        return False
+
+    extra = ["--force"] if force else []
+    if sys.platform == "win32":
+        cmd = _wsl_prefix() + ["-e", "bash", _to_wsl_path(SCRIPT), *extra]
+    else:
+        cmd = ["bash", SCRIPT, *extra]
+
+    print("[gwbpy] Starting setup...")
+    try:
+        process = subprocess.Popen(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+            text=True, encoding="utf-8", errors="replace", bufsize=1,
+        )
+    except FileNotFoundError:
+        print("[gwbpy] ERROR: could not start the setup command "
+              "(is WSL installed? On Windows, run 'wsl --install' in PowerShell).")
+        return False
+
+    if process.stdout:
+        for line in process.stdout:
+            print(f"    {line.rstrip()}")
+    process.wait()
+
+    if process.returncode == 0:
+        print("[gwbpy] Setup finished. You can now call animate_binary_physical().")
+        return True
+    if process.returncode == 2:
+        print("[gwbpy] Setup stopped: install the system packages listed above, "
+              "then run gwbpy.setup() again.")
+    else:
+        print(f"[gwbpy] ERROR: setup failed (exit code {process.returncode}). "
+              "See the output above. If there is no output at all on Windows, "
+              "WSL may not be installed or set up.")
+    return False

gwbpy-0.1.0a1/gwbpy/workers/dynamics_worker.py

@@ -0,0 +1,100 @@
+"""
+gwbpy.workers.dynamics_worker
+
+Runs inside the pyseobnr environment. Generates the SEOBNRv5HM effective-
+one-body DYNAMICS (separation and orbital phase vs time) and saves it as
+an .npz file.
+
+The raw integrator output is unevenly spaced, so it is resampled to one
+point per 0.1 rad of orbital phase. Otherwise Blender draws each orbit as
+a coarse polygon.
+
+Note: r is the EOB radial coordinate, not a literal horizon position.
+"""
+
+import argparse
+import numpy as np
+from scipy.interpolate import CubicSpline
+from pyseobnr.generate_waveform import generate_modes_opt
+
+G = 6.67430e-11
+C = 2.99792458e8
+M_SUN = 1.98892e30
+
+PHASE_STEP = 0.1  # radians of orbital phase between output samples
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--m1", type=float, required=True)
+    p.add_argument("--m2", type=float, required=True)
+    p.add_argument("--chi1", type=float, default=0.0)
+    p.add_argument("--chi2", type=float, default=0.0)
+    p.add_argument("--f-lower", type=float, default=20.0)
+    p.add_argument("--out", type=str, required=True)
+    a = p.parse_args()
+
+    # pyseobnr wants q >= 1 with the heavier body first.
+    m1, m2, chi1, chi2 = a.m1, a.m2, a.chi1, a.chi2
+    if m2 > m1:
+        m1, m2, chi1, chi2 = m2, m1, chi2, chi1
+    q = m1 / m2
+    total = m1 + m2
+
+    t_unit = G * total * M_SUN / C ** 3   # seconds per unit of M
+    r_unit = G * total * M_SUN / C ** 2   # meters per unit of M
+
+    # f_lower is the requested starting GW frequency; omega0 is the
+    # orbital frequency in geometric units (GW freq = 2 x orbital freq).
+    omega0 = np.pi * a.f_lower * t_unit
+
+    print(f"[worker] q={q:.3f}, M={total} Msun, omega0={omega0:.5f}")
+    _, _, model = generate_modes_opt(q, chi1, chi2, omega0, debug=True)
+    t, r, phi, pr, pphi, H, Omega, _ = model.dynamics.T
+
+    # Starting GW frequency actually used, from the phase's rate of
+    # change over the first few samples (f_gw = 2 * f_orb).
+    n0 = 1
+    f_start_hz = float((phi[n0] - phi[0]) / (t[n0] - t[0]) / (np.pi * t_unit))
+    print(f"[worker] requested start: {a.f_lower:.1f} Hz, "
+          f"model started at about {f_start_hz:.1f} Hz")
+
+    dphi_raw = np.diff(phi)
+    print(f"[worker] raw samples: {len(t)}, phase step per sample: "
+          f"max {dphi_raw.max():.2f} rad, median {np.median(dphi_raw):.2f} rad")
+
+    # Keep only strictly increasing phase so it can be inverted.
+    keep = np.concatenate(([True], np.diff(phi) > 0))
+    t, r, phi = t[keep], r[keep], phi[keep]
+
+    # Resample at uniform steps in orbital phase.
+    phi_grid = np.arange(phi[0], phi[-1], PHASE_STEP)
+    phi_grid = np.append(phi_grid, phi[-1])
+    t_grid = np.interp(phi_grid, phi, t)
+    r_grid = CubicSpline(t, r)(t_grid)
+
+    times = t_grid * t_unit
+    radius_m = r_grid * r_unit
+    merger_idx = len(times) - 1
+
+    np.savez(
+        a.out,
+        times=times,
+        radius_m=radius_m,
+        orbital_angle=phi_grid,
+        merger_time=times[merger_idx],
+        merger_idx=merger_idx,
+        f_start_hz=f_start_hz,
+        m1=a.m1,
+        m2=a.m2,
+    )
+
+    print(f"[worker] resampled to {len(times)} samples, "
+          f"{(phi[-1] - phi[0]) / (2 * np.pi):.1f} orbits")
+    print(f"[worker] separation start/end: {radius_m[0]/1000:.0f} km / {radius_m[-1]/1000:.0f} km")
+    print(f"[worker] horizons touch at: {2*r_unit/1000:.0f} km")
+    print(f"[worker] Saved to {a.out}")
+
+
+if __name__ == "__main__":
+    main()

gwbpy-0.1.0a1/gwbpy.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+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.

gwbpy-0.1.0a1/gwbpy.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+gwbpy/__init__.py
+gwbpy/animate.py
+gwbpy/physics.py
+gwbpy/setup_env.py
+gwbpy.egg-info/PKG-INFO
+gwbpy.egg-info/SOURCES.txt
+gwbpy.egg-info/dependency_links.txt
+gwbpy.egg-info/requires.txt
+gwbpy.egg-info/top_level.txt
+gwbpy/scripts/install_env.sh
+gwbpy/workers/dynamics_worker.py

gwbpy-0.1.0a1/gwbpy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gwbpy-0.1.0a1/gwbpy.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy

gwbpy-0.1.0a1/gwbpy.egg-info/top_level.txt

@@ -0,0 +1 @@
+gwbpy

gwbpy-0.1.0a1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gwbpy"
+version = "0.1.0a1"
+description = "Gravitational-wave visualizations for Blender (alpha)"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["numpy"]
+authors = [{name = "Ellis Eisenberg"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Astronomy",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+[tool.setuptools.packages.find]
+include = ["gwbpy*"]
+
+[tool.setuptools.package-data]
+gwbpy = ["scripts/*.sh", "workers/*.py"]

gwbpy-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+