warplab 1.0.0

package/src/core/geodesic.ts

@@ -0,0 +1,223 @@
+// ─── Geodesic Integration in Schwarzschild Spacetime ────────────────────
+// RK4 integrator for null and timelike geodesics.
+// Uses lightweight Vec3 instead of THREE.Vector3.
+
+import { Vec3 } from "./vec3";
+import type { GeodesicOutcome, GeodesicResult } from "./types";
+
+const MAX_STEPS = 5000;
+const MAX_STEPS_MASSIVE = 20000;
+const MAX_DIST = 200;
+
+/**
+ * Compute the timelike effective potential V_eff(r) for massive particles.
+ * V_eff = (1 - rs/r)(1 + L²/r²)
+ */
+export function timelikeVeff(r: number, rs: number, L: number): number {
+  if (r <= rs) return 0;
+  return (1 - rs / r) * (1 + (L * L) / (r * r));
+}
+
+/**
+ * Find the ISCO radius for a given rs.
+ * For Schwarzschild: r_isco = 3 * rs (= 6M since rs = 2M)
+ */
+export function iscoRadius(rs: number): number {
+  return 3 * rs;
+}
+
+/**
+ * Compute the energy of a circular orbit at radius r.
+ */
+export function circularOrbitEnergy(r: number, rs: number, L: number): number {
+  return timelikeVeff(r, rs, L);
+}
+
+/**
+ * Integrate a null geodesic (photon) in Schwarzschild spacetime using RK4.
+ */
+export function integrateGeodesic(
+  startPos: Vec3,
+  startVel: Vec3,
+  rs: number,
+  stepSize = 0.04,
+): GeodesicResult {
+  const points: { x: number; y: number; z: number }[] = [];
+
+  const vel = startVel.clone().normalize();
+  const pos = startPos.clone();
+
+  const Lvec = new Vec3().crossVectors(pos, vel);
+  const L2 = Lvec.lengthSq;
+
+  const rHorizon = rs;
+  const halfRs = 1.5 * rs;
+
+  points.push({ x: pos.x, y: pos.y, z: pos.z });
+
+  let outcome: GeodesicOutcome = "orbiting";
+
+  const tmpPos = new Vec3();
+  const k1v = new Vec3();
+  const k2v = new Vec3();
+  const k3v = new Vec3();
+  const k4v = new Vec3();
+
+  for (let i = 0; i < MAX_STEPS; i++) {
+    const r = pos.length;
+
+    if (r <= rHorizon * 1.01) {
+      outcome = "captured";
+      break;
+    }
+    if (r > MAX_DIST) {
+      outcome = "scattered";
+      break;
+    }
+
+    const accel = (r5: number, p: Vec3, out: Vec3) => {
+      const factor = -halfRs * L2 / r5;
+      out.copy(p).multiplyScalar(factor);
+    };
+
+    const dt = stepSize;
+
+    const r1 = pos.length;
+    const r1_5 = r1 * r1 * r1 * r1 * r1;
+    accel(r1_5, pos, k1v);
+
+    tmpPos.copy(pos).addScaledVector(vel, dt * 0.5);
+    const r2 = tmpPos.length;
+    const r2_5 = r2 * r2 * r2 * r2 * r2;
+    accel(r2_5, tmpPos, k2v);
+
+    tmpPos.copy(pos).addScaledVector(vel, dt * 0.5).addScaledVector(k1v, dt * dt * 0.25);
+    const r3 = tmpPos.length;
+    const r3_5 = r3 * r3 * r3 * r3 * r3;
+    accel(r3_5, tmpPos, k3v);
+
+    tmpPos.copy(pos).addScaledVector(vel, dt).addScaledVector(k2v, dt * dt * 0.5);
+    const r4 = tmpPos.length;
+    const r4_5 = r4 * r4 * r4 * r4 * r4;
+    accel(r4_5, tmpPos, k4v);
+
+    pos.addScaledVector(vel, dt);
+
+    vel.addScaledVector(k1v, dt / 6);
+    vel.addScaledVector(k2v, dt / 3);
+    vel.addScaledVector(k3v, dt / 3);
+    vel.addScaledVector(k4v, dt / 6);
+
+    points.push({ x: pos.x, y: pos.y, z: pos.z });
+  }
+
+  return { points, outcome, L: Math.sqrt(L2), particleType: "photon" };
+}
+
+/**
+ * Integrate a timelike (massive particle) geodesic in Schwarzschild spacetime.
+ */
+export function integrateTimelikeGeodesic(
+  startPos: Vec3,
+  startVel: Vec3,
+  rs: number,
+  energy: number,
+  stepSize = 0.03,
+): GeodesicResult {
+  const points: { x: number; y: number; z: number }[] = [];
+
+  const pos = startPos.clone();
+  const r0 = pos.length;
+
+  const velDir = startVel.clone().normalize();
+  const Lvec = new Vec3().crossVectors(pos, velDir);
+  const L = Lvec.length;
+  const L2 = L * L;
+
+  const veff0 = timelikeVeff(r0, rs, L);
+  const drdt2 = energy - veff0;
+
+  const vTangential = L / r0;
+  const vRadial = Math.sqrt(Math.max(0, drdt2));
+
+  const rHat = pos.clone().normalize();
+  const tangentDir = new Vec3().crossVectors(Lvec.clone().normalize(), rHat);
+
+  const radialSign = velDir.dot(rHat) < 0 ? -1 : 1;
+
+  const vel = tangentDir.multiplyScalar(vTangential)
+    .addScaledVector(rHat, radialSign * vRadial);
+
+  const rHorizon = rs;
+  const halfRs = 0.5 * rs;
+  const threeHalfRs = 1.5 * rs;
+
+  points.push({ x: pos.x, y: pos.y, z: pos.z });
+
+  let outcome: GeodesicOutcome = "orbiting";
+  let prevR = r0;
+  let radialTurns = 0;
+  let increasing = vel.dot(pos.clone().normalize()) > 0;
+
+  const tmpPos = new Vec3();
+  const k1v = new Vec3();
+  const k2v = new Vec3();
+  const k3v = new Vec3();
+  const k4v = new Vec3();
+
+  const accel = (p: Vec3, out: Vec3) => {
+    const r = p.length;
+    const r3 = r * r * r;
+    const r5 = r3 * r * r;
+    const factor = -halfRs / r3 - threeHalfRs * L2 / r5;
+    out.copy(p).multiplyScalar(factor);
+  };
+
+  for (let i = 0; i < MAX_STEPS_MASSIVE; i++) {
+    const r = pos.length;
+
+    if (r <= rHorizon * 1.01) {
+      outcome = "captured";
+      break;
+    }
+    if (r > MAX_DIST) {
+      outcome = "scattered";
+      break;
+    }
+
+    const nowIncreasing = r > prevR;
+    if (i > 5 && nowIncreasing !== increasing) {
+      radialTurns++;
+      increasing = nowIncreasing;
+      if (radialTurns >= 6) {
+        outcome = "bound";
+        break;
+      }
+    }
+    prevR = r;
+
+    const dt = stepSize;
+
+    accel(pos, k1v);
+
+    tmpPos.copy(pos).addScaledVector(vel, dt * 0.5);
+    accel(tmpPos, k2v);
+
+    tmpPos.copy(pos).addScaledVector(vel, dt * 0.5).addScaledVector(k1v, dt * dt * 0.25);
+    accel(tmpPos, k3v);
+
+    tmpPos.copy(pos).addScaledVector(vel, dt).addScaledVector(k2v, dt * dt * 0.5);
+    accel(tmpPos, k4v);
+
+    pos.addScaledVector(vel, dt);
+
+    vel.addScaledVector(k1v, dt / 6);
+    vel.addScaledVector(k2v, dt / 3);
+    vel.addScaledVector(k3v, dt / 3);
+    vel.addScaledVector(k4v, dt / 6);
+
+    points.push({ x: pos.x, y: pos.y, z: pos.z });
+  }
+
+  return { points, outcome, L, particleType: "particle" };
+}

package/src/core/index.ts

@@ -0,0 +1,53 @@
+// ─── WarpLab Core ───────────────────────────────────────────────────────
+// Pure computation library for gravitational wave physics.
+// No browser dependencies — works in Node.js, Deno, and browser.
+
+export type {
+  GWEvent,
+  WaveformData,
+  QNMMode,
+  CharacteristicStrain,
+  BinaryParams,
+  GeodesicOutcome,
+  ParticleType,
+  GeodesicResult,
+} from "./types";
+
+export { Vec3 } from "./vec3";
+
+export { fetchEventCatalog, classifyEvent } from "./catalog";
+
+export { generateWaveform, generateCustomWaveform } from "./waveform";
+
+export {
+  computeQNMModes,
+  estimateFinalSpin,
+  estimateFinalMass,
+} from "./qnm";
+
+export {
+  computeCharacteristicStrain,
+  computeOptimalSNR,
+  getALIGOCharacteristicStrain,
+  interpolateALIGO_ASD,
+} from "./noise-curve";
+
+export {
+  integrateGeodesic,
+  integrateTimelikeGeodesic,
+  timelikeVeff,
+  iscoRadius,
+  circularOrbitEnergy,
+} from "./geodesic";
+
+export type { EMCounterpart, MultiMessengerData } from "./multi-messenger";
+export { getMultiMessengerData } from "./multi-messenger";
+
+export {
+  generateParametersJSON,
+  generateParametersCSV,
+  generateWaveformCSV,
+  generateBibTeX,
+  generateNotebook,
+  generateREADME,
+} from "./export";

package/src/core/multi-messenger.ts

@@ -0,0 +1,77 @@
+// ─── Multi-Messenger Data ───────────────────────────────────────────────
+// EM counterpart metadata for GW events with electromagnetic counterparts.
+
+export interface EMCounterpart {
+  name: string;
+  type: "GRB" | "optical" | "X-ray" | "radio" | "kilonova";
+  delaySeconds: number;
+  observatory: string;
+  description: string;
+}
+
+export interface MultiMessengerData {
+  eventName: string;
+  emCounterpart: string;
+  emCounterparts: EMCounterpart[];
+  hostGalaxy: string;
+  hostGalaxyDistanceMpc: number;
+  h0Measurement: string;
+  ejectaMass: string;
+  grbDelay: string;
+}
+
+const MM_DATA: Record<string, MultiMessengerData> = {
+  GW170817: {
+    eventName: "GW170817",
+    emCounterpart: "GRB 170817A / AT 2017gfo (kilonova)",
+    emCounterparts: [
+      {
+        name: "GRB 170817A",
+        type: "GRB",
+        delaySeconds: 1.7,
+        observatory: "Fermi GBM / INTEGRAL SPI-ACS",
+        description:
+          "A short gamma-ray burst detected just 1.7 seconds after the gravitational wave signal, confirming the long-theorized link between neutron star mergers and short GRBs.",
+      },
+      {
+        name: "AT 2017gfo",
+        type: "kilonova",
+        delaySeconds: 11 * 3600,
+        observatory: "Swope Telescope (Las Campanas)",
+        description:
+          "The first kilonova observed with a known gravitational-wave source. Its rapid reddening revealed freshly synthesized heavy elements forged by the r-process.",
+      },
+      {
+        name: "CXO J130948.0\u2013233120",
+        type: "X-ray",
+        delaySeconds: 9 * 86400,
+        observatory: "Chandra X-ray Observatory",
+        description:
+          "X-ray emission appeared days after the merger, produced by the interaction of the relativistic jet with the surrounding interstellar medium.",
+      },
+      {
+        name: "VLA J130948.0\u2013233120",
+        type: "radio",
+        delaySeconds: 16 * 86400,
+        observatory: "Karl G. Jansky VLA",
+        description:
+          "Radio afterglow from the expanding cocoon of material around the jet, confirming the merger launched a structured relativistic outflow.",
+      },
+    ],
+    hostGalaxy: "NGC 4993, 40 Mpc",
+    hostGalaxyDistanceMpc: 40,
+    h0Measurement: "70 +12/\u22128 km/s/Mpc",
+    ejectaMass: "~0.05 M\u2609",
+    grbDelay: "1.7 s",
+  },
+};
+
+/**
+ * Look up multi-messenger data for a given event common name.
+ * Returns null if no EM counterpart data exists.
+ */
+export function getMultiMessengerData(
+  commonName: string,
+): MultiMessengerData | null {
+  return MM_DATA[commonName] ?? null;
+}

package/src/core/noise-curve.ts

@@ -0,0 +1,162 @@
+// ─── FFT, Characteristic Strain & SNR Computation ───────────────────────
+// Radix-2 Cooley-Tukey FFT, characteristic strain computation, and
+// aLIGO design sensitivity. Pure computation — no Canvas/DOM.
+
+import type { WaveformData, CharacteristicStrain } from "./types";
+
+// ─── FFT ──────────────────────────────────────────────────────────────
+
+/** In-place radix-2 Cooley-Tukey FFT. Arrays must have length = power of 2. */
+function fftInPlace(re: Float64Array, im: Float64Array): void {
+  const N = re.length;
+  for (let i = 1, j = 0; i < N; i++) {
+    let bit = N >> 1;
+    while (j & bit) {
+      j ^= bit;
+      bit >>= 1;
+    }
+    j ^= bit;
+    if (i < j) {
+      [re[i], re[j]] = [re[j], re[i]];
+      [im[i], im[j]] = [im[j], im[i]];
+    }
+  }
+  for (let len = 2; len <= N; len *= 2) {
+    const halfLen = len / 2;
+    const angle = (-2 * Math.PI) / len;
+    const wRe = Math.cos(angle);
+    const wIm = Math.sin(angle);
+    for (let i = 0; i < N; i += len) {
+      let curRe = 1;
+      let curIm = 0;
+      for (let j = 0; j < halfLen; j++) {
+        const a = i + j;
+        const b = a + halfLen;
+        const tRe = curRe * re[b] - curIm * im[b];
+        const tIm = curRe * im[b] + curIm * re[b];
+        re[b] = re[a] - tRe;
+        im[b] = im[a] - tIm;
+        re[a] += tRe;
+        im[a] += tIm;
+        const nextRe = curRe * wRe - curIm * wIm;
+        curIm = curRe * wIm + curIm * wRe;
+        curRe = nextRe;
+      }
+    }
+  }
+}
+
+/** Next power of 2 >= n */
+function nextPow2(n: number): number {
+  let p = 1;
+  while (p < n) p *= 2;
+  return p;
+}
+
+// ─── Characteristic strain from waveform ──────────────────────────────
+
+/**
+ * Compute characteristic strain h_c(f) from a time-domain waveform.
+ * Zero-pads to at least 2048 samples (next power of 2).
+ */
+export function computeCharacteristicStrain(waveform: WaveformData): CharacteristicStrain {
+  const minN = 2048;
+  const N = nextPow2(Math.max(waveform.hPlus.length, minN));
+  const dt = 1 / waveform.sampleRate;
+
+  const re = new Float64Array(N);
+  const im = new Float64Array(N);
+  for (let i = 0; i < waveform.hPlus.length; i++) {
+    re[i] = waveform.hPlus[i];
+  }
+
+  fftInPlace(re, im);
+
+  const halfN = N / 2;
+  const df = 1 / (N * dt);
+  const frequencies = new Float64Array(halfN);
+  const hc = new Float64Array(halfN);
+
+  for (let k = 0; k < halfN; k++) {
+    const f = k * df;
+    frequencies[k] = f;
+    const mag = Math.sqrt(re[k] * re[k] + im[k] * im[k]) * dt;
+    hc[k] = 2 * f * mag;
+  }
+
+  return { frequencies, hc };
+}
+
+// ─── aLIGO design sensitivity ─────────────────────────────────────────
+
+const ALIGO_DATA: [number, number][] = [
+  [10, 1e-20], [11, 6.5e-21], [12, 4.2e-21], [13, 2.9e-21],
+  [14, 2.1e-21], [15, 1.6e-21], [16, 1.3e-21], [17, 1.1e-21],
+  [18, 9.0e-22], [19, 7.8e-22], [20, 6.8e-22], [22, 5.3e-22],
+  [24, 4.3e-22], [26, 3.6e-22], [28, 3.1e-22], [30, 2.7e-22],
+  [33, 2.3e-22], [36, 2.0e-22], [40, 1.7e-22], [45, 1.4e-22],
+  [50, 1.2e-22], [55, 1.05e-22], [60, 9.5e-23], [65, 8.7e-23],
+  [70, 8.0e-23], [75, 7.5e-23], [80, 7.0e-23], [85, 6.6e-23],
+  [90, 6.3e-23], [95, 6.0e-23], [100, 5.7e-23], [110, 5.2e-23],
+  [120, 4.8e-23], [130, 4.5e-23], [140, 4.2e-23], [150, 4.0e-23],
+  [160, 3.9e-23], [170, 3.8e-23], [180, 3.7e-23], [190, 3.6e-23],
+  [200, 3.6e-23], [220, 3.6e-23], [240, 3.7e-23], [260, 3.8e-23],
+  [280, 4.0e-23], [300, 4.2e-23], [320, 4.5e-23], [340, 4.8e-23],
+  [360, 5.2e-23], [380, 5.6e-23], [400, 6.0e-23], [430, 6.8e-23],
+  [460, 7.7e-23], [500, 9.0e-23], [550, 1.1e-22], [600, 1.3e-22],
+  [650, 1.5e-22], [700, 1.8e-22], [750, 2.1e-22], [800, 2.5e-22],
+  [850, 2.9e-22], [900, 3.4e-22], [950, 4.0e-22], [1000, 4.6e-22],
+  [1100, 6.2e-22], [1200, 8.2e-22], [1300, 1.1e-21], [1400, 1.4e-21],
+  [1500, 1.8e-21], [1600, 2.3e-21], [1700, 3.0e-21], [1800, 3.8e-21],
+  [1900, 4.8e-21], [2000, 6.0e-21], [2200, 9.5e-21], [2400, 1.5e-20],
+  [2600, 2.3e-20], [2800, 3.5e-20], [3000, 5.5e-20], [3500, 1.5e-19],
+  [4000, 4.5e-19], [4500, 1.3e-18], [5000, 4.0e-18],
+];
+
+/**
+ * Get the aLIGO design sensitivity as characteristic strain h_c = √(f · S_n(f)).
+ */
+export function getALIGOCharacteristicStrain(): { frequencies: number[]; hc: number[] } {
+  const frequencies: number[] = [];
+  const hc: number[] = [];
+  for (const [f, asd] of ALIGO_DATA) {
+    frequencies.push(f);
+    hc.push(Math.sqrt(f) * asd);
+  }
+  return { frequencies, hc };
+}
+
+/** Log-log interpolate aLIGO ASD at an arbitrary frequency. */
+export function interpolateALIGO_ASD(f: number): number {
+  if (f <= ALIGO_DATA[0][0]) return ALIGO_DATA[0][1];
+  if (f >= ALIGO_DATA[ALIGO_DATA.length - 1][0]) return ALIGO_DATA[ALIGO_DATA.length - 1][1];
+  for (let i = 0; i < ALIGO_DATA.length - 1; i++) {
+    const [f0, a0] = ALIGO_DATA[i];
+    const [f1, a1] = ALIGO_DATA[i + 1];
+    if (f >= f0 && f <= f1) {
+      const t = Math.log(f / f0) / Math.log(f1 / f0);
+      return Math.exp(Math.log(a0) + t * Math.log(a1 / a0));
+    }
+  }
+  return ALIGO_DATA[ALIGO_DATA.length - 1][1];
+}
+
+/**
+ * Compute optimal matched-filter SNR.
+ * rho^2 = integral( (h_c(f))^2 / (h_n(f))^2 ) d(ln f)
+ */
+export function computeOptimalSNR(strain: CharacteristicStrain): number {
+  const fMin = 10;
+  const fMax = 5000;
+  let rhoSq = 0;
+  for (let k = 1; k < strain.frequencies.length - 1; k++) {
+    const f = strain.frequencies[k];
+    if (f < fMin || f > fMax || strain.hc[k] <= 0) continue;
+    const asd = interpolateALIGO_ASD(f);
+    const hn = Math.sqrt(f) * asd;
+    const ratio = strain.hc[k] / hn;
+    const df = strain.frequencies[k + 1] - strain.frequencies[k];
+    rhoSq += ratio * ratio * (df / f);
+  }
+  return Math.sqrt(rhoSq);
+}

package/src/core/qnm.ts

@@ -0,0 +1,97 @@
+// ─── Quasi-Normal Mode (QNM) Computation ────────────────────────────
+// Berti fitting coefficients for Kerr QNM frequencies and damping times.
+// Reference: Berti, Cardoso & Starinets, CQG 26, 163001 (2009), Table VIII.
+//
+// ω = f1 + f2 * (1 - a_f)^f3          (frequency in geometric units)
+// τ⁻¹ = q1 + q2 * (1 - a_f)^q3        (inverse quality factor)
+// Physical frequency: f = ω / (2π M_f)  in natural units → converted to Hz
+
+import type { QNMMode } from "./types";
+
+// Berti fitting coefficients: [f1, f2, f3, q1, q2, q3]
+const BERTI_COEFFS: Record<string, [number, number, number, number, number, number]> = {
+  "2,2,0": [1.5251, -1.1568, 0.1292, 0.7000, 1.4187, -0.4990],
+  "2,2,1": [1.3673, -1.0260, 0.1628, 0.3562, 2.3420, -0.2467],
+};
+
+// Physical constants
+const MSUN_KG = 1.989e30;
+const G = 6.674e-11;
+const C = 2.998e8;
+const MSUN_SEC = (G * MSUN_KG) / (C * C * C); // ~4.926e-6 s
+
+/**
+ * Estimate the final spin of the remnant BH using the Hofmann et al. (2016) fit.
+ * Simplified: a_f ≈ √12 η - 3.871 η² + 4.028 η³  (non-spinning limit)
+ */
+export function estimateFinalSpin(m1: number, m2: number, chi1 = 0, chi2 = 0): number {
+  const totalMass = m1 + m2;
+  const eta = (m1 * m2) / (totalMass * totalMass);
+  const chiEff = (m1 * chi1 + m2 * chi2) / totalMass;
+
+  const aFinal = Math.sqrt(12) * eta - 3.871 * eta * eta + 4.028 * eta * eta * eta
+    + chiEff * eta * (2.0 - 1.25 * eta);
+
+  return Math.min(Math.max(aFinal, 0), 0.998);
+}
+
+/**
+ * Estimate the final mass of the remnant BH.
+ * Uses the Healy & Lousto (2017) fit for radiated energy.
+ */
+export function estimateFinalMass(m1: number, m2: number): number {
+  const totalMass = m1 + m2;
+  const eta = (m1 * m2) / (totalMass * totalMass);
+  const erad = 0.0559745 * eta + 0.1469 * eta * eta;
+  return totalMass * (1 - erad);
+}
+
+/**
+ * Compute QNM modes for a binary black hole merger.
+ *
+ * @param m1 - Primary mass in solar masses
+ * @param m2 - Secondary mass in solar masses
+ * @param chi1 - Primary dimensionless spin (default 0)
+ * @param chi2 - Secondary dimensionless spin (default 0)
+ * @param modes - Which (l,m,n) modes to compute (default: fundamental + first overtone)
+ * @returns Array of QNMMode results
+ */
+export function computeQNMModes(
+  m1: number,
+  m2: number,
+  chi1 = 0,
+  chi2 = 0,
+  modes: string[] = ["2,2,0", "2,2,1"],
+): QNMMode[] {
+  const finalMass = estimateFinalMass(m1, m2);
+  const finalSpin = estimateFinalSpin(m1, m2, chi1, chi2);
+
+  const mfSec = finalMass * MSUN_SEC;
+
+  const results: QNMMode[] = [];
+
+  for (const modeKey of modes) {
+    const coeffs = BERTI_COEFFS[modeKey];
+    if (!coeffs) continue;
+
+    const [f1, f2, f3, q1, q2, q3] = coeffs;
+
+    const omegaHat = f1 + f2 * Math.pow(1 - finalSpin, f3);
+    const Q = q1 + q2 * Math.pow(1 - finalSpin, q3);
+
+    const frequency = omegaHat / (2 * Math.PI * mfSec);
+    const dampingTime = Q / (Math.PI * frequency);
+
+    const [l, m, n] = modeKey.split(",").map(Number);
+
+    results.push({
+      l, m, n,
+      frequency,
+      dampingTime,
+      qualityFactor: Q,
+      label: `(${l},${m},${n})`,
+    });
+  }
+
+  return results;
+}

package/src/core/types.ts

@@ -0,0 +1,86 @@
+// ─── Shared types for WarpLab core computation ─────────────────────────
+// These types are used by both browser and server (MCP/CLI) entry points.
+
+/** GWOSC event catalog entry */
+export interface GWEvent {
+  commonName: string;
+  GPS: number;
+  mass_1_source: number;
+  mass_1_source_lower: number;
+  mass_1_source_upper: number;
+  mass_2_source: number;
+  mass_2_source_lower: number;
+  mass_2_source_upper: number;
+  luminosity_distance: number;
+  luminosity_distance_lower: number;
+  luminosity_distance_upper: number;
+  redshift: number;
+  chi_eff: number;
+  network_matched_filter_snr: number;
+  far: number;
+  catalog_shortName: string;
+  total_mass_source: number;
+  chirp_mass_source: number;
+  chirp_mass_source_lower: number;
+  chirp_mass_source_upper: number;
+  final_mass_source: number;
+  final_mass_source_lower: number;
+  final_mass_source_upper: number;
+  p_astro: number;
+  /** Derived 3D position for the universe map (ra, dec, distance → cartesian) */
+  mapPosition?: { x: number; y: number; z: number };
+}
+
+/** Pre-processed waveform data for an event */
+export interface WaveformData {
+  eventName: string;
+  sampleRate: number;
+  hPlus: number[];
+  hCross: number[];
+  duration: number;
+  peakIndex: number;
+}
+
+/** A single QNM mode result */
+export interface QNMMode {
+  /** Mode indices (l, m, n) */
+  l: number;
+  m: number;
+  n: number;
+  /** Oscillation frequency in Hz */
+  frequency: number;
+  /** Damping time in seconds */
+  dampingTime: number;
+  /** Quality factor Q = π f τ */
+  qualityFactor: number;
+  /** Label string e.g. "(2,2,0)" */
+  label: string;
+}
+
+/** Characteristic strain data from FFT */
+export interface CharacteristicStrain {
+  /** Frequency bins in Hz */
+  frequencies: Float64Array;
+  /** h_c(f) = 2f |h̃(f)| */
+  hc: Float64Array;
+}
+
+/** Parameters for a custom binary merger waveform */
+export interface BinaryParams {
+  m1: number;          // solar masses (1–150)
+  m2: number;          // solar masses (1–150)
+  chi1: number;        // spin (-1 to +1)
+  chi2: number;        // spin (-1 to +1)
+  distance: number;    // Mpc
+  inclination: number; // radians
+}
+
+export type GeodesicOutcome = "captured" | "scattered" | "orbiting" | "bound";
+export type ParticleType = "photon" | "particle";
+
+export interface GeodesicResult {
+  points: { x: number; y: number; z: number }[];
+  outcome: GeodesicOutcome;
+  L: number;
+  particleType: ParticleType;
+}