Parameter Reference

⚙️ Parameter Reference

⚠️ Schema sync notice — v0.6.8: The runtime parser in src/core/cli_parser.cpp currently accepts these top-level YAML sections: grid, time, ccz4, io, initial_data, black_holes, amr. The older conceptual schema keys (simulation, domain, dissipation, time_integration, boundary, diagnostics) are not parsed at runtime. Until the compatibility layer lands, use the YAML files under benchmarks/ as the canonical runnable examples. See docs/SOURCE_OF_TRUTH.md.

GRANITE v0.6.8 | ← Known Fixed Bugs | Physics Formulations →

Complete reference for every parameter in params.yaml. Each parameter includes type, default value, physical units, valid range, and warnings where applicable.
This is the single most important page for avoiding simulation failures.

---

Table of Contents

1. How to Use This Reference
2. Canonical params.yaml Template
3. simulation — Run Identity & Output
4. domain — Grid Geometry
5. amr — Adaptive Mesh Refinement
6. initial_data — Black Hole Configuration
7. ccz4 — Spacetime Evolution Parameters
8. dissipation — Kreiss-Oliger Dissipation
9. time_integration — CFL and Timestep
10. boundary — Outer Boundary Conditions
11. diagnostics — Output and Monitoring
12. io — Input/Output
13. Dangerous Parameter Combinations
14. Preset Configurations

---

1. How to Use This Reference

Each parameter entry follows this format:

Parameter Name
  Type:     [float | int | bool | string | list]
  Default:  value
  Units:    physical units or "dimensionless"
  Range:    [min, max] or enumeration
  ⚠️ Warning: critical notes (appear only when parameter has failure modes)
  Description: what the parameter does

Units convention: GRANITE uses geometrized units G = c = 1 throughout.
All lengths and times are in units of M (total ADM mass). For M = 1 (standard):

• 1 M (solar-mass BH) ≈ 4.93 μs ≈ 1.48 km
• 1 M (10⁸ M☉ SMBH) ≈ 493 s ≈ 1.48 × 10¹³ cm

---

2. Canonical params.yaml Template

# GRANITE v0.6.8 — Canonical Parameter File
# See: docs/DEVELOPER_GUIDE.md §18 for full description
# See: wiki/Parameter-Reference for complete reference

simulation:
  name:              "B2_eq_production"
  output_dir:        "./output/B2_eq"
  total_time:        500.0
  checkpoint_every:  5000

domain:
  size:  48.0
  nx:    64
  ny:    64
  nz:    64

amr:
  levels: 4
  refinement:
    criteria:
      - variable:   chi
        threshold:  0.15
      - variable:   alpha
        threshold:  0.3

initial_data:
  type: two_punctures
  bh1:
    mass:      0.5
    position:  [5.0, 0.0, 0.0]
    momentum:  [0.0, 0.0840, 0.0]
    spin:      [0.0, 0.0, 0.0]
  bh2:
    mass:      0.5
    position:  [-5.0, 0.0, 0.0]
    momentum:  [0.0, -0.0840, 0.0]
    spin:      [0.0, 0.0, 0.0]

ccz4:
  kappa1:  0.02
  kappa2:  0.0
  eta:     2.0

dissipation:
  ko_sigma:  0.1

time_integration:
  cfl:  0.25

boundary:
  type:  sommerfeld

diagnostics:
  output_every:  100
  gw_extraction:
    enabled:  true
    radii:    [50, 100, 150, 200, 300, 500]
  ah_finder:
    enabled:  true
    every:    10

io:
  output_every:      100
  checkpoint_every:  5000
  format:            hdf5

---

3. simulation — Run Identity & Output

simulation.name

Type:     string
Default:  "granite_run"
Units:    N/A
Range:    any valid filename string (no spaces recommended)
Description:
  Human-readable identifier for this run. Used as prefix for log files
  and checkpoint filenames. Appears in the sim_tracker.py dashboard header.
  Example: "B2_eq_64cubed_t500M"

simulation.output_dir

Type:     string
Default:  "./output"
Units:    N/A
Range:    any valid directory path
Description:
  Directory where all HDF5 checkpoints, diagnostic logs, and GW data
  files are written. Created automatically if it does not exist.
  Relative paths are resolved from the working directory at launch time.
  For HPC runs, use an absolute path on the parallel filesystem (Lustre, GPFS).

simulation.total_time

Type:     float
Default:  100.0
Units:    M (code units, G = c = 1)
Range:    (0.0, ∞)
Description:
  Total simulated time. The engine stops when t ≥ total_time.
  
  Recommended values by benchmark:
    single_puncture:  500.0 M  (64³) / 120.0 M  (128³)
    gauge_wave:       100.0 M
    B2_eq:            500.0 M  (inspiral validation)
    B5_star:          varies by physical scenario

simulation.checkpoint_every

Type:     int
Default:  5000
Units:    steps
Range:    [1, ∞)
Description:
  Write a full HDF5 checkpoint every N time steps.
  Checkpoints capture complete CCZ4 + GRMHD state for all AMR levels.
  
  ⚠️ Warning: loadCheckpoint() is NOT implemented in v0.6.8.
  Checkpoints are written but cannot be used for restart.
  Reduce checkpoint_every if disk space is a concern.

---

4. domain — Grid Geometry

domain.size

Type:     float
Default:  48.0
Units:    M
Range:    [32.0, ∞)
⚠️ WARNING — MINIMUM 48M FOR STABLE LONG RUNS:
  Gauge waves travel at speed √2 ≈ 1.414 M/M in 1+log slicing.
  A gauge wave from the puncture at r=0 reaches the boundary at:
    t_reflection = domain_size / √2
  
  For domain_size = 16M: t_reflection ≈ 11.3M  ← crashes at t ≈ 6M
  For domain_size = 32M: t_reflection ≈ 22.6M  ← crashes at t ≈ 18M  
  For domain_size = 48M: t_reflection ≈ 33.9M  ← stable for t = 500M ✓
  For domain_size = 200M: t_reflection ≈ 141M  ← use for BBH (B2_eq)
  
  This is the single most common cause of simulation crashes.
  Never set domain_size < 48M for single-puncture runs,
  and never set domain_size < 200M for BBH runs at t > 100M.
Description:
  Half-width of the cubic simulation domain in each dimension.
  Full domain: [-size, +size]³. Total domain width: 2 × size.
  dx (base level) = 2 × size / nx

domain.nx / domain.ny / domain.nz

Type:     int
Default:  64
Units:    cells
Range:    [16, 512] (practical desktop range: 32–128)
Description:
  Number of base-level grid cells in each dimension.
  dx = 2 × domain.size / nx  (similarly for y, z)
  
  Standard configurations:
    64³:   dx = 1.5M (domain=48M) or dx = 6.25M (domain=200M)
    96³:   dx = 1.0M (domain=48M) or dx = 4.17M (domain=200M)
    128³:  dx = 0.75M (domain=48M)
  
  Note: ny and nz default to nx if not specified. Always use equal
  dimensions for isotropic resolution (required for rotating BH systems).

---

5. amr — Adaptive Mesh Refinement

amr.levels

Type:     int
Default:  4
Units:    dimensionless
Range:    [1, 12]
Description:
  Maximum number of AMR refinement levels.
  Level 0 = base grid (dx = base dx)
  Level 1 = 2× finer (dx/2)
  Level ℓ = 2^ℓ× finer (dx/2^ℓ)
  
  dx at finest level = dx_base / 2^(levels-1)
  
  For 64³ base, 4 levels, domain=48M:
    L0: dx = 1.50 M
    L1: dx = 0.75 M
    L2: dx = 0.375 M
    L3 (finest): dx = 0.1875 M
  
  ⚠️ Warning: Dynamic regridding is partially implemented in v0.6.8.
  Block count is fixed at initialization. Setting levels > 4 with current
  code will create the initial blocks but not refine further at runtime.
  
  Production targets:
    Desktop development:    4–6 levels
    Cluster production:     8–10 levels
    B5_star flagship:       12 levels

amr.refinement.criteria

Type:     list of {variable, threshold} pairs
Default:  chi threshold=0.15, alpha threshold=0.3
Units:    depends on variable (dimensionless for chi and alpha)
Description:
  Refinement tagging criteria. A cell is marked for refinement when
  the specified variable falls below (chi, alpha) or exceeds the threshold.
  
  Supported variables:
    chi:    Refine where conformal factor χ < threshold (near punctures)
    alpha:  Refine where lapse α < threshold (near collapsing regions)
    rho:    Refine where rest-mass density ρ > threshold (dense matter)
    ham:    Refine where ‖H‖ > threshold (large constraint violation)
  
  Recommended single-puncture: chi threshold=0.15
  Recommended BBH (B2_eq):     chi threshold=0.15, alpha threshold=0.3
  Recommended BNS:             chi threshold=0.15, rho threshold=1e-4

---

6. initial_data — Black Hole Configuration

initial_data.type

Type:     string (enum)
Default:  "brill_lindquist"
Range:    "brill_lindquist" | "two_punctures" | "bowen_york" | "tov"
Description:
  Selects the initial data generator.
  
  "brill_lindquist": BL conformal factor sum. N BHs at rest.
    Compatible boundary conditions: COPY ONLY (not Sommerfeld)
    Use for: single puncture stability tests
    
  "two_punctures": Spectral BBH initial data. Includes BY extrinsic curvature.
    Compatible boundary conditions: Sommerfeld (recommended) or copy
    Use for: binary BH simulations requiring inspiral
    
  "bowen_york": Bowen-York extrinsic curvature on BL background.
    Compatible boundary conditions: Sommerfeld or copy
    
  "tov": Tolman-Oppenheimer-Volkoff neutron star.
    Requires: tabulated nuclear EOS

initial_data.bh1 / initial_data.bh2 (for BBH)

mass

Type:     float
Default:  0.5 (for equal-mass BBH with M_total = 1)
Units:    M_total (code units; M_total = m1 + m2 = 1 by convention)
Range:    (0.0, 1.0)  [for BBH; sum must equal 1.0]
Description:
  ADM mass of this black hole in units of the total system mass.
  For equal-mass BBH: m1 = m2 = 0.5
  For mass ratio q = 4: m1 = 0.8, m2 = 0.2

position

Type:     list[float, float, float]
Default:  [5.0, 0.0, 0.0] for bh1, [-5.0, 0.0, 0.0] for bh2
Units:    M
Range:    coordinates within the domain
Description:
  Initial coordinate position of the puncture.
  Separation d = |pos_bh1 - pos_bh2|.
  Standard: d = 10M with positions at [±5, 0, 0]
  
  ⚠️ Warning: Do not place a puncture at the exact grid center [0,0,0].
  The MICRO_OFFSET in main.cpp shifts the domain by 1.36e-6 M to avoid
  r=0 division-by-zero, but placing the puncture at the origin in YAML
  is still fine — the offset handles this automatically.

momentum

Type:     list[float, float, float]
Default:  [0.0, 0.0, 0.0]
Units:    M (in code units: dimensionless momentum p / M_total)
Range:    any 3-vector
⚠️ CRITICAL WARNING — QUASI-CIRCULAR ORBIT REQUIRES NONZERO TANGENTIAL MOMENTUM:
  Momentum = [0, 0, 0] produces a HEAD-ON COLLISION, not an inspiral.
  If your B2_eq run shows no inspiral or merger, check this parameter first.
  
  Quasi-circular tangential momentum for equal-mass d=10M BBH (PN estimate):
    p_t ≈ ±0.0840 M
    bh1: momentum: [0.0,  0.0840, 0.0]
    bh2: momentum: [0.0, -0.0840, 0.0]
  
  These values are from post-Newtonian approximations (Pfeiffer et al. 2007).
  More accurate values can be computed from eccentricity-reduced PN formulas.
  
  For separation d:  p_t ≈ (M/4) × (M/d)^{1/2} × (1 + corrections)

spin

Type:     list[float, float, float]
Default:  [0.0, 0.0, 0.0]
Units:    dimensionless (a = J/M² ∈ [-1, 1])
Range:    |spin| ≤ 0.998 (Kerr bound)
Description:
  Dimensionless spin vector S^i / M² for this BH.
  [0, 0, 0]: non-spinning (Schwarzschild)
  [0, 0, 0.7]: spin aligned with z-axis (Kerr a=0.7)
  
  Note: Spin in Bowen-York initial data generates a small amount of
  spurious junk radiation (Hannam et al. 2007). For production runs,
  use iterative eccentricity removal methods.

---

7. ccz4 — Spacetime Evolution Parameters

ccz4.kappa1

Type:     float
Default:  0.02
Units:    1/M
Range:    [0.01, 0.05] (Alic et al. 2012 recommended range: [0.01, 0.04])
Description:
  CCZ4 constraint damping coefficient κ₁.
  Controls the exponential damping rate of constraint violations.
  
  In the CCZ4 evolution equations, the Θ equation contains:
    ∂_t Θ ∋ -κ₁(2 + κ₂)αΘ
  and the K equation contains:
    ∂_t K ∋ -κ₁(1 + κ₂)αΘ
  
  These terms drive Θ → 0 and hence H → 0 exponentially.
  
  ⚠️ Warning: kappa1 = 0.1 (10× larger than default) over-damps constraint
  violations near the puncture and slightly accelerates gauge collapse.
  The safe standard value is 0.02 per Alic et al. (2012).
  Values above 0.05 are not recommended.

ccz4.kappa2

Type:     float
Default:  0.0
Units:    dimensionless
Range:    [0.0, 1.0]
Description:
  CCZ4 constraint damping coefficient κ₂.
  κ₂ = 0: standard CCZ4 (Alic et al. 2012)
  κ₂ ≠ 0: Z4c variant (Hilditch et al. 2013)
  
  The production default is κ₂ = 0.0 (standard CCZ4).
  Do not change without understanding the Z4c variant consequences.

ccz4.eta

Type:     float
Default:  2.0
Units:    1/M
Range:    [0.5, 4.0]
Description:
  Gamma-driver shift damping parameter η.
  Appears in the moving-puncture shift evolution:
    ∂_t B^i = ∂_t Γ̃^i - η B^i
  
  Controls how quickly the shift adjusts to track the puncture.
  Large η: rapid shift adjustment (may overshoot)
  Small η: slow shift adjustment (puncture may drift from grid center)
  
  η = 2.0 is the standard production value (Campanelli et al. 2006).
  
  ⚠️ Warning: η = 4.0 was tested and confirmed to deepen lapse collapse
  and cause instability to arrive earlier. Do not exceed η = 2.0 without
  testing on the specific configuration.
  
  For SMBH mergers with M = 10⁸ M☉, η should be scaled as η = 1/M_ADM
  (Campanelli 2006 prescription), i.e., η = 1.0 for M_total = 1.

---

8. dissipation — Kreiss-Oliger Dissipation

dissipation.ko_sigma

Type:     float
Default:  0.1
Units:    dimensionless
Range:    [0.0, 0.15]

⚠️ CRITICAL WARNING — DO NOT SET ABOVE 0.1:
  Values of ko_sigma > 0.1 have been confirmed to OVER-DISSIPATE
  the trumpet gauge profile, destroying the physical near-puncture
  solution without producing NaN events.
  
  Symptoms of over-dissipation:
    - Lapse collapses but never recovers to trumpet value
    - ‖H‖₂ appears to decay but the gauge is unphysical
    - Secondary gauge collapse without NaN events
  
  CONFIRMED FAILURE MODE: ko_sigma = 0.35 (from early B2_eq config)
  destroys the trumpet geometry completely. This is documented in
  CHANGELOG.md Phase 7 and DEVELOPER_GUIDE.md §20 as a known failure.
  
  SAFE VALUE: 0.1 (validated in DEV_LOG5: single puncture stable to t=120M,
  BBH B2_eq stable to t=500M with ‖H‖₂ decaying by factor ×61).
  
  The 6th-order KO dissipation operator is:
    (∂_t u)_KO = -σ × (Δx)^(2p-1) × D^(2p)_+ u   [p=3]

Description:
  Kreiss-Oliger dissipation coefficient σ. Controls amplitude of
  numerical high-frequency damping added to all 22 CCZ4 right-hand sides.
  
  σ = 0.0: No dissipation (not recommended for production — allows
           high-frequency modes to alias and destabilize)
  σ = 0.1: Safe production default — damps aliased modes without
           affecting the physical trumpet geometry
  σ > 0.1: Over-dissipates — physically destroys the moving-puncture solution

---

9. time_integration — CFL and Timestep

time_integration.cfl

Type:     float
Default:  0.25
Units:    dimensionless (Courant number)
Range:    (0.0, 0.5]

⚠️ WARNING — CFL AT FINEST AMR LEVEL MUST BE ≤ 0.5:
  The effective CFL at AMR level ℓ = cfl × (dt_base) / (dx_finest)
  = cfl × 2^(levels-1)
  
  For cfl=0.25 with 4 AMR levels:
    CFL_finest = 0.25 × 2^3 = 2.0  ← EXCEEDS 0.5!
    (Stable only because lapse suppression α≈0 reduces effective dt)
  
  For production with lapse collapse compensation, cfl=0.25 is safe.
  For gauge_wave or other runs without lapse collapse, use cfl=0.1.

Description:
  Global CFL safety factor. Timestep:
    dt = cfl × min(dx) / max_signal_speed
  
  For the Gamma-driver gauge, max signal speed ≈ √2 (gauge waves).
  
  Standard values:
    0.25: Production default (BBH, single puncture with lapse collapse)
    0.1:  Conservative (gauge wave tests, high-resolution runs)
    0.08: Very conservative (was tested in Phase 6; made crash WORSE — see CHANGELOG)
  
  The adaptive CFL guardian in main.cpp monitors the advection CFL
  (|β|·dt/dx) and automatically reduces dt by 20% if CFL > 0.95.

---

10. boundary — Outer Boundary Conditions

boundary.type

Type:     string (enum)
Default:  "sommerfeld"
Range:    "sommerfeld" | "copy"

⚠️ CRITICAL WARNING — COMPATIBILITY WITH INITIAL DATA:
  "sommerfeld" with Brill-Lindquist initial data = CONFIRMED FAILURE
  This was tested in Phase 6 and produced ‖H‖₂ 8× WORSE than copy BC.
  
  Root cause: BL data does not match a spherical 1/r outgoing wave.
  The Sommerfeld ghost formula f_ghost = f∞ + (f_int - f∞)·r_int/r_ghost
  assumes an outgoing 1/r profile, which BL data violates from t=0.
  The resulting metric gradient artifacts feed into the Ricci tensor
  and accumulate constraint violation over the first ~90 steps.
  
  COMPATIBILITY MATRIX:
  ┌─────────────────────────┬────────────────┬─────────────┐
  │ Initial Data            │ Sommerfeld BC  │ Copy BC     │
  ├─────────────────────────┼────────────────┼─────────────┤
  │ Brill-Lindquist (SP)    │ ❌ FORBIDDEN   │ ✅ USE THIS │
  │ Two-Punctures / BY      │ ✅ Recommended │ ✅ Also OK  │
  │ TOV (neutron star)      │ ❌ NOT tested  │ ✅ Use this │
  └─────────────────────────┴────────────────┴─────────────┘

Description:
  Outer boundary condition applied to ghost cells at the domain boundary.
  
  "sommerfeld": Radiative 1/r falloff condition
    f_ghost = f∞ + (f_int - f∞) · r_int / r_ghost
    Asymptotic values: χ→1, α→1, γ̃_{xx/yy/zz}→1, all others→0
    Gauge wave characteristic speed: √2 (hardcoded)
    Applied: every SSP-RK3 substep, after ghost zone sync
    
  "copy": Zeroth-order outflow (Neumann ∂_n f = 0)
    f_ghost = f_interior
    Required for Brill-Lindquist initial data
    Produces ‖H‖₂ ≤ 0.3 for single-puncture runs to t=6.25M
    Becomes inadequate when gauge wave reaches boundary (domain-size issue)

---

11. diagnostics — Output and Monitoring

diagnostics.output_every

Type:     int
Default:  100
Units:    steps
Range:    [1, ∞)
Description:
  Frequency of telemetry output lines written to stdout (parsed by sim_tracker.py).
  Each output line contains: step, t, α_center, ‖H‖₂, AMR block count, speed, ETA.
  
  ⚠️ Note on α_center: The diagnostic reads α from the AMR level 0 block
  at r ≈ 0.65M (near but not at the puncture). This is NOT the lapse
  at the puncture. Values will show α ≈ 0.97 even in BBH runs where the
  puncture lapse is physically ~0.03. This is a known bug (v0.7 target fix).

diagnostics.gw_extraction

Type:     section
Description:
  Configuration for gravitational wave extraction via Newman-Penrose Ψ₄.

  enabled [bool, default: true]
    Enable/disable GW extraction.
    ⚠️ Note: GW extraction infrastructure exists but Ψ₄ computation
    is not active in all production runs in v0.6.8. Enable this for
    simulations where GW output is needed.

  radii [list[float], default: [50, 100, 150, 200, 300, 500]]
    Extraction radii in units of M.
    Ψ₄ is evaluated on coordinate spheres at each radius.
    Extraction at multiple radii enables extrapolation to null infinity.
    Minimum recommended: 3 radii for convergence testing.
    Maximum: as many as compute budget allows (each adds ~1% overhead).

diagnostics.ah_finder

Type:     section
Description:
  Apparent horizon finder configuration.

  enabled [bool, default: true]
    Enable the AH finder.

  every [int, default: 10]
    Run the AH finder every N diagnostic output steps.
    Set every=1 for continuous monitoring (expensive).
    Set every=10 for standard production runs.
    Set every=100 for long production runs where AH tracking is secondary.

---

12. io — Input/Output

io.output_every

Type:     int
Default:  100
Units:    steps
Description:
  Frequency of full field data output (VTK or HDF5 slices).
  Separate from checkpoint_every (which writes complete restart state).

io.checkpoint_every

Type:     int
Default:  5000
Units:    steps
Description:
  Write a complete HDF5 checkpoint (all CCZ4 + GRMHD variables at all
  AMR levels) every N steps.
  
  Checkpoint file format:
    checkpoint_XXXXXX.h5
    ├── /metadata: {time, step, amr_level_count}
    ├── /level_0: {ccz4_vars[nblocks,22,nx,ny,nz], grmhd_vars[nblocks,9,nx,ny,nz]}
    └── /level_1: ...
  
  ⚠️ Warning: loadCheckpoint() is NOT implemented in v0.6.8.
  Checkpoints are written but cannot be used to resume a simulation.
  This is a Tier-1 blocker tracked for v0.7.

io.format

Type:     string (enum)
Default:  "hdf5"
Range:    "hdf5" | "vtk"
Description:
  Output file format. HDF5 is required for checkpointing and is the
  standard for analysis with granite_analysis Python package.
  VTK output is planned for visualization with VisIt/ParaView (v0.7).

HPC I/O Tuning Parameters

For Lustre/GPFS parallel filesystems:

io:
  hdf5_stripe_count:   16       # Match to number of MPI ranks / storage nodes
  hdf5_stripe_size:    4194304  # 4 MB per stripe (optimal for large arrays)
  collective_io:       true     # MPI-IO collective mode (required for parallel HDF5)

---

13. Dangerous Parameter Combinations

The following combinations are confirmed to produce incorrect results and must never be used:

Parameter A	Value	Parameter B	Value	Consequence	Source
boundary.type	sommerfeld	initial_data.type	brill_lindquist	‖H‖₂ 8× worse than copy BC	CHANGELOG Phase 6
dissipation.ko_sigma	> 0.15	any	any	Trumpet gauge destroyed	DEVELOPER_GUIDE §20
domain.size	< 48M	initial_data.type	brill_lindquist	Crash at t ≈ domain/√2	CHANGELOG Phase 6
domain.size	< 200M	simulation.total_time	> 100M	Gauge reflections contaminate interior	BENCHMARKS.md
initial_data.bh*.momentum	[0,0,0]	simulation.name	BBH inspiral	Head-on collision instead of inspiral	README Known Limitations
ccz4.kappa1	0.1	any	any	Over-damping near puncture	CHANGELOG Phase 6

---

See also: Architecture Overview | Simulation Health & Debugging | Known Fixed Bugs