FAQ

❓ Frequently Asked Questions

GRANITE v0.6.8 | ← Documentation Index & Master Reference | Gravitational Wave Extraction →

---

Science Questions

Q: Why CCZ4 and not BSSN?

A: BSSN (Baumgarte-Shapiro-Shibata-Nakamura) evolves the constraint variables algebraically — violations can only grow. CCZ4 (Alic et al. 2012) promotes the Z4 algebraic constraint Z_μ = 0 to a dynamical field with active damping terms:

∂_t Θ ∋ −κ₁(2+κ₂)αΘ

This exponentially damps constraint violations with time constant τ ≈ 1/(κ₁α). For κ₁=0.02 and α≈1, constraint violations decay on a timescale ~50M. This is essential for long-duration (500M+) simulations where small violations would otherwise accumulate.

Q: Why not use Einstein Toolkit?

A: Einstein Toolkit is excellent for binary mergers and is the community standard. GRANITE's goal is different: a single, unified codebase capable of N>2 body simulations with simultaneous GRMHD, M1 radiation, and neutrino leakage. Einstein Toolkit's modular thorn system creates architectural barriers that make this coupling difficult. GRANITE is architected from scratch for this specific goal.

Q: What resolution do I need for a realistic inspiral?

A: The GW phase accuracy requires resolving the orbital dynamics. For SXS-catalog quality (phase error < 0.01 rad over 10 orbits):

• Finest dx < 0.05M near the puncture
• This requires ~6 AMR levels at 64³ base
• At 128³ base with 4 levels, dx_finest ≈ 0.094M — marginal for phase accuracy, good for stability tests
• Production validation runs need 256³+ with 6+ levels

Q: What does ‖H‖₂ reduction by ×61 mean physically?

A: The Hamiltonian constraint ‖H‖₂ measures how accurately the evolved spacetime satisfies Einstein's equations. Starting at ~8×10⁻⁴ and decaying to ~1.3×10⁻⁵ over 500M means the simulation is becoming more accurately consistent with the Einstein equations as it evolves. This monotonic decay is proof of:

1. CCZ4 constraint damping working correctly (Θ → 0)
2. No accumulation of numerical error
3. Physical consistency of the moving-puncture solution

Q: My BBH runs to t=500M but I don't see any merger — is this a bug?

A: Most likely not a bug — check the tangential momentum:

• momentum: [0, 0, 0] → head-on collision, no inspiral
• momentum: [0, 0.0840, 0] → quasi-circular orbit for d=10M

Secondly, at 64³ base resolution with d=10M separation, the orbital period is T_orb ≈ 2π × (d/2)^(3/2) / √M_total ≈ 220M. You may not see merger within 500M depending on the eccentricity. Check the BH separation time series to confirm orbital motion.

---

Engineering Questions

Q: What does ko_sigma do and why is 0.1 the safe value?

A: Kreiss-Oliger dissipation suppresses high-frequency numerical noise (modes near the Nyquist frequency) that would otherwise accumulate and destabilize the simulation. The formula is:

(∂_t u)_KO = -σ × (Δx)^5 × D^6 u

σ = 0.1 damps Nyquist modes without affecting the physically important trumpet gauge profile. σ > 0.1 (e.g., 0.35) over-dissipates — it damps the steep gradient that forms the trumpet geometry, destroying the physical near-puncture solution. The failure is silent (no NaN events), making it particularly dangerous.

Q: Why can't I use Sommerfeld BCs with Brill-Lindquist data?

A: Sommerfeld BCs assume the outgoing field has a 1/r profile. BL initial data has ψ = 1 + Σ(m/2r) — not a 1/r outgoing wave. The BC formula introduces metric gradient artifacts from step 1 that accumulate into the Ricci tensor. Measured in Phase 6: Sommerfeld+BL → ‖H‖₂ 8× worse than copy BCs. Always use copy BCs with BL data.

Q: Why do I need domain_size ≥ 48M for single-puncture runs?

A: Gauge waves in 1+log slicing propagate at speed √2 ≈ 1.41 M/M. A wave emitted from the puncture at t=0 reaches the outer boundary at t = domain_size/√2. At that moment, any BC (Sommerfeld or copy) generates a spurious reflection that causes ‖H‖₂ to jump to NaN in one output window. For domain_size=48M: t_reflection ≈ 33.9M — safe for t=500M runs.

Q: Why is the M1 radiation module built but not active?

A: The M1 modules are implemented and pass all unit tests. Wiring them into the RK3 loop requires careful coupling with the GRMHD source terms at each stage, and requires the checkpoint-restart system to work (so long radiation runs can be paused and resumed). Both of these are v0.7 blockers. Using M1 before checkpoint-restart is implemented would make any radiation run uninterruptible.

Q: Why must I run from a Linux-native path in WSL?

A: WSL2 uses a 9P filesystem bridge for /mnt/c/ (Windows filesystem) that has ~10× higher I/O latency than the native Linux filesystem. For simulations writing HDF5 checkpoints every 5000 steps, this causes serious I/O bottlenecks. Additionally, MPI process creation from Windows-mounted paths can fail intermittently. Always work from ~/Granite/ or /home/username/Granite/, not /mnt/c/.

---

HPC Questions

Q: What hardware do I need to run B5_star?

A: ~2 TB RAM minimum, ~5×10⁶ CPU-hours or ~5×10⁵ GPU-hours. This is firmly Tier-0 supercomputer territory (NERSC, ARCHER2, Jülich, BSC). Current v0.6.8 development runs are at 128³ on a desktop (16 GB RAM). GPU porting (v0.7) and cluster validation (v0.8) must be completed first.

Q: How do I cite GRANITE?

A:

@software{granite2026,
  author    = {LiranOG},
  title     = {{GRANITE}: General-Relativistic Adaptive N-body Integrated
               Tool for Extreme Astrophysics},
  year      = {2026},
  version   = {v0.6.8},
  url       = {https://github.com/LiranOG/Granite-NR},
  note      = {CCZ4 + GRMHD + AMR engine for multi-body black hole merger simulations}
}

Also cite the upstream physics papers — full list in docs/SCIENCE.md §8.

---