Memory expectations¶
Tengri’s forward model is light on memory. The heavy hitters are JIT compilation graphs and inference-backend internals. This page lists the peak RSS you should expect for common cases, the two recurring out-of-memory patterns and how to avoid them, and a watchdog you can run on machines with less than 32 GB when batch-authoring notebooks.
What to expect¶
Workload |
Steady-state RSS |
Peak RSS during compile |
|---|---|---|
Smooth D = 7 photometric fit (NUTS) |
~100 MB |
3–6 GB |
Smooth D = 7 photometric fit (MAP / Laplace / Pathfinder) |
~100 MB |
~1 GB |
Stochastic D ≈ 137 SFH (geoVI) |
~1.5 GB |
5–6 GB |
Spectroscopy (1000-pix optical, NUTS) |
~300 MB |
4–8 GB |
Joint photo + spec (NUTS) |
~500 MB |
6–10 GB |
NUTS warmup with dense_mass_matrix=True peaks 3–6× higher than steady state due to vmap(vmap(...)) tracing. D ≥ 8 with dense_basis can hit 20+ GB. Multi-fit notebooks need dense_mass_matrix=False. See Multiple NUTS fits.
These numbers are CPU on Apple M-series; GPU peaks are typically lower because XLA can fuse more aggressively, but VRAM ceilings are tighter.
Pattern: multiple NUTS fits per process¶
Symptom: First fit OK, second compiles slowly, third OOMs.
Cause: Each NUTS warmup compiles vmap(vmap(...)) of the full predict
graph (~4 GB per fit). The JIT cache amortizes next calls but not
traces. Different Observation or n_warmup invalidates the key,
re-paying compile cost.
Fixes (in order):
One NUTS fit per notebook. Use MAP for cheap “before” fits.
Share state: same model, same observation type, only data changes. JIT cache survives.
Drop dense mass:
forward.fit(..., method="mcmc_nuts", dense_mass_matrix=False). Cuts compile ~3× (costs ~2× autocorrelation; run more samples).Use HMC:
forward.fit(..., method="mcmc_hmc"). Smaller JIT graph, no binary-tree expansion.
Pattern: background compile + macOS jetsam¶
The inference engine pre-compiles every backend when a fit is set up, so the first user-facing call is fast. On models with heavy template blocks, that background compile alone can reach several GB. On macOS, this is enough to trip the jetsam memory killer before the first call runs.
Fix: Disable background compile before import tengri:
import os
os.environ.setdefault("TENGRI_NO_BACKGROUND_COMPILE", "1")
import tengri
All spine notebooks do this; copy the pattern for OOM-prone configurations.
JAX persistent compile cache¶
JAX recompiles XLA on every cold start. Tengri auto-enables a persistent
cache at ~/.cache/tengri_jax_cache to avoid re-compiling.
If the directory is empty after a notebook run:
Check writability.
Check
TENGRI_JAX_CACHE_DIRif set.Compiles faster than
min_compile_time_secsare skipped by design.
After upgrading JAX:
import tengri
tengri.clear_cache()
See Compilation: caching and diagnostics for details.
A safety-net watchdog¶
If you batch-author notebooks or run several sessions in parallel,
running a watchdog daemon in the background is cheap insurance. Two
ship in scripts/:
scripts/python_oom_guard.shsends SIGKILL to any single python process whose RSS exceedsLIMIT_GB(default 10). It catches one runaway JIT compile or fit.scripts/python_total_oom_guard.shwatches the machine-wide total RSS of all python processes and sheds the most memory-hungry ones first. It catches what the per-process guard cannot: many individually-modest workers (pytest-xdist, parallel sessions, orphaned kernels) that together sum past physical RAM.
Four triggers are on by default, because every one of them has a blind spot the others cover:
Trigger |
Fires when |
Catches |
|---|---|---|
sum-RSS |
python RSS sums past |
a resident-memory runaway. Weakest (see below). |
avail hard |
available memory < |
the box is out of memory outright |
avail + swap |
available < |
swap thrash, where available memory never falls far because the kernel is keeping it up by paging |
swap growth |
swap grows > |
the ramp before any level is alarming, immune to whatever the baseline is |
Do not rely on sum-RSS. RSS counts only resident pages, so every page the kernel swaps out stops being counted: the number shrinks as the machine thrashes harder. Measured 2026-08-10, three minutes apart either side of a manual rescue on the same box:
01:19:50 total=12.88GB n=34 avail=18% swap=43.23GB <- emergency
01:22:24 total=23.83GB n=10 avail=44% swap= 8.40GB <- after the rescue
Thirty-four processes summed to 12.9 GB; ten summed to 23.8 GB. A 32 GB limit was unreachable in exactly the condition it existed to catch. Detect with the system-level triggers; sum-RSS is a backstop, and RSS is still the right thing to rank victims by.
SWAP_MAX_GB used to default to 0 (disabled), and that is why the guard sat quiet through the 2026-08-10 incident. The reasoning for disabling it was wrong: it claimed macOS never shrinks the swap file. Across that incident swap went 8.47 → 43.23 → 8.47 GB, reclaiming 35 GB within minutes of the pressure clearing. The “chronic 20+ GB baseline” recorded earlier was not a baseline. It was the opening hours of the same thrash.
The real trap is a swap threshold set near the working baseline
(~8.5 GB here), which fires forever. Keeping it well above baseline, and
requiring available memory to be low at the same time, is what makes it
both sensitive and quiet. tests/unit/scripts/test_python_total_oom_guard.py
pins both directions: the incident must trip, and flat high swap on an
otherwise healthy box must not.
Install it as a LaunchAgent rather than backgrounding it by hand:
scripts/install_oom_guard_agent.sh # start at login, restart if it dies
scripts/install_oom_guard_agent.sh --uninstall
A nohup ... & daemon does not survive logout or reboot and nothing restarts it if it dies. Because its /tmp log is periodically reaped, there is no evidence it was ever gone. On 2026-08-09, a machine reached ~120 GB of summed python RSS with the guard installed but dead for weeks. The agent logs to ~/Library/Logs/tengri-oomguard.log, outside /tmp, so that evidence survives.
Two behaviors worth knowing before you tune it:
MIN_KILL_MBis a preference, not a veto. If the shed target cannot be met without going below it, the guard goes below it. A single-pass guard with a 512 MB floor facing 200 workers of 300 MB selects nobody and logs a warning while the machine dies.Pressure trips are gated on
PRESSURE_MIN_PYTHON_GB(default 8): the guard only sheds if python actually holds that much. Swap pressure is often chronic and not always python’s fault, and killing 2 GB of python cannot fix a 20 GB shortfall caused by something else. The gate also makes shedding self-limiting.
DRY_RUN=1 previews the kill plan without signaling anything, and both daemons honor EXCLUDE_RE. Set limits so your heaviest legitimate fit stays under them. NUTS on a model with template dust emission can briefly cross 10 GB during compile.
When to file a bug¶
A single fit peaking far above the table at the top of this page is a regression. File it with the model config and the observed peak RSS.
See docs/dev/notebook_orchestration_oom.md for technical root causes and subagent-zombie patterns.