Known limitations

Tengri is research code under active development (v0.1.0). The forward model and inference pipeline work and are covered by 2000+ tests, but several capabilities are partial. This page collects the caveats you are most likely to encounter.

Verification status

No physics component has completed full external cross-validation against FSPS, Prospector, or CIGALE. The reproduction notebooks under docs/reproduction/ compare specific components against established codes, but the formal verification protocol (docs/dev/verification-protocol.md) lists every major block as still in progress. Do not treat fitted parameters as publication-grade until your component has been cross-validated.

Approximations

Both precompute paths trade a bounded, quantified error for a large speedup. Each does the same thing: integrate everything that does not depend on a free parameter once at build time, then reduce each likelihood call to a small contraction.

An SSP grid under the GALEX and ugriz bandpasses, one band split into five equal-mass sub-bands, per-age-bin quadrature nodes, the stored tensor, the SFH age weights, and the composite-stellar-population sum.

What approx=WavePrecomp() does to a real SSP grid, and where the star formation history enters. (a) The grid holds one spectrum per age bin; five are drawn, under the GALEX and ugriz bandpasses. SDSS u is followed through the rest of the figure. (b) That band is cut into \(K = 5\) sub-bands of equal filter mass — the five shaded areas are equal, so they run narrow where the filter is most transmissive and wide out in the wings. The partition depends on the filter alone. (c) Every age bin is then integrated separately against that partition, and each gets its own \(K\) nodes \(\lambda^\star_{jk}\) (the tick rows): a node is that age bin’s own flux-weighted centroid within its sub-band, so it moves as the spectrum ages. (d) What is stored is therefore a tensor, not a vector — \(K\) numbers for every age bin, every metallicity and every band, \(\Phi_{ijbk}\). None of it depends on a free parameter, so it is all built once. (e) At fit time the star formation history is integrated onto that same age grid by the cloud-in-cell kernel, giving one mass weight \(w_j\) per age bin. (f) The composite-stellar-population flux is then the double sum \(f_b = \sum_j w_j \sum_k \Phi_{jk} A(\lambda^\star_{jk})\) — over all 93 age bins and their 5 sub-bands, with the dust screen evaluated only at the nodes. No wavelength grid is touched at any point in the likelihood, and for this band the result lands within a few thousandths of a percent of the exact integral. Generated by scripts/render_precompute_schematic.py.

The reason a factorization like this needs care: the photometry integral wants \(\langle F_\nu A \rangle_b\) (the SSP spectrum times the dust screen, averaged over the bandpass). Precomputing the two separately would give \(\langle F_\nu \rangle_b \langle A \rangle_b\), and the difference between them is exactly the in-band covariance \(\mathrm{Cov}_b(F_\nu, A)\). That covariance is the entire error term, and the sub-band quadrature buys it back. Additive emitters (dust IR, AGN, radio, X-ray) need none of this: each is a sum of rank-one terms, so it factors through the filter exactly and carries no quadrature error.

The GALEX FUV bandpass split into five equal-mass sub-bands with one quadrature node each, and the resulting convergence with K.

Where the residual error lives. (a) The real GALEX FUV bandpass split into \(K = 5\) sub-bands of equal filter mass — the five shaded regions have equal area under \(T_b w\). Each carries one node \(\lambda^\star\), the template’s own flux-weighted centroid there, so the screen is evaluated at five points and held constant across each sub-band; the shaded gap between the true screen and that step function is the whole of the approximation. Because each node is a first moment, the first moment of the in-band residual vanishes identically — a first-order correction on top of the sub-band rule would add exactly zero. Edges and nodes are drawn from the shipped subband_quadrature partition. Panel (a) is a mild configuration (\(z = 0\), \(\tau_\mathrm{diff} = 0.7\)) where the \(K = 0\) Taylor extrapolation still nearly coincides with the true screen; it diverges as redshift and optical depth grow, which is what the \(K = 0\) points in (b) quantify. (b) Worst-band error against the exact path over \(z \le 1\) and \(\tau \le 2\). Generated by scripts/render_precompute_schematic.py.

  • WavePrecomp accelerates the photometry channel. It precomputes the SSP × filter integrals, with free redshift via interpolation. Each filter is split into n_subbands sub-bands of equal filter mass (default 5), and the multiplicative screens (dust attenuation and IGM transmission) are evaluated at each sub-band’s quadrature node (the template’s own flux-weighted centroid there). Measured against the exact path across GALEX→WISE at z ≤ 1.5 with τ_diff = 0.7 / τ_bc = 1.0, the worst band agrees to ≲0.5%, and the optical/NIR bands to ≲0.01%. Accuracy improves as 1/K²; raise WavePrecomp(n_subbands=8) for the deep rest-UV. Emission that the quadrature cannot reach (nebular lines, AGN, dust IR) is still projected at the filter’s effective wavelength.

  • WavePrecomp(n_subbands=0) restores the old first-order Taylor projection, which extrapolates the screen from each filter’s effective wavelength instead of evaluating it. That linear-in-λ model is accurate for smooth attenuation curves (optical/IR) but biases rest-UV bands where the curve is steep: at z ≈ 2 with τ ≈ 0.5, SDSS u/g run 5–10% high and GALEX FUV greater than 10× high. A build-time UserWarning flags such configurations. It is retained only for reproducing results from earlier versions.

  • SpectrumPrecomp is the default for spectroscopy fits only where it serves the pixels exactly. approx="auto" takes the spectrum LUT for a spectroscopy fit when three things hold: the pixels are point-sampled or no wider than the model grid (no bin integral), sigma_v_kms is Fixed, and no banded resolution matrix is attached. Otherwise the fit stays on the exact path, and a free sigma_v_kms says so once. approx=None always stays exact, and an explicit SpectrumPrecomp() engages the table as before. When the LUT is in use, it applies the same velocity-dispersion and instrument stages as the exact path (σ_v on the model grid, the library-deconvolved instrument kernel on the pixel grid) and agrees with it to better than 1e-3 across the pixels, lines included; with a free sigma_v_kms the table broadens the stellar sum per draw on the full model grid, which costs roughly 15 times the exact path per gradient step and warns once, and a banded resolution matrix falls back to the exact path.

  • SpectrumPrecomp accelerates the spectroscopy channel. It precomputes a per-pixel effective-wavelength continuum LUT. It agrees with the exact path to machine precision with zero dust. With dust, it carries the same error class as WavePrecomp but far milder (pixel-wide versus filter-wide): typically ≲1% on the continuum, growing to ~10–15% only in the deep rest-UV at high optical depth. It applies the exact path’s stages in the same order (stellar velocity dispersion on the model grid, IGM, instrument kernel on the pixels) and matches it to better than 2e-3 at every pixel of the line-rich test fixture at R = 2000 and 5000 and \(\sigma_v\) = 300 km/s; a banded resolution_matrix falls back to the exact path with a warning. Component coverage: stellar, dust IR, radio, X-ray, AGN, and non-baked nebular (Cue/CloudyGrid) are included in the spectrum LUT. Nebular emission is reddened by the young-limit screen, matching the exact path. BakedIn nebular is carried by the stellar LUT.

  • Joint photometry + spectroscopy is supported under precompute. Either precompute opt-in builds both LUT families, and approx="auto" puts the spectrum channel on the spectrum LUT under the same three conditions as a spectroscopy fit; the forward pass projects both channels in one fused, cached JIT kernel. For independent per-channel tuning, pass approx=(WavePrecomp(n_z=200), SpectrumPrecomp()). Velocity dispersion and the instrument LSF are applied by the spectrum LUT; with a free sigma_v_kms the stellar sum is broadened per draw on the full model grid, which costs roughly an order of magnitude more per gradient step, so a joint fit with approx=WavePrecomp() keeps a free-sigma_v_kms spectrum channel on the exact path and says so once. Under approx="auto" the photometry channel takes WavePrecomp and the spectrum channel stays exact when any of the three conditions fails.

Inference backends

Each backend is tagged primary or experimental. Experimental backends carry explicit [POOR MIXING] or [UNSTABLE] flags (e.g. mcmc_ghmc, mcmc_mclmc, pathfinder, native_vi_*). Use primary backends for science. See Choosing an inference method.

Memory

NUTS/VI warmup peaks far above the resident forward model (20+ GB on dense_basis D≈8 with dense_mass_matrix=True). Rules:

  • Run one NUTS/VI fit per Python process.

  • On D ≥ 8, use dense_mass_matrix=False or mcmc_hmc.

  • WavePrecomp keeps photometry fits in the few-GB range.

Full detail: docs/dev/notebook_orchestration_oom.md.

Physics caveats

  • The cb19 nebular grid is not shipped. data/cb19_templates.h5 is not in the repository, and scripts/download_cb19_templates.py cannot rebuild it because the 3MdB databases hold no CB_19 reference (see docs/internal/advanced/cb19_grid.md). A build that reads the grid raises FileNotFoundError. Use cloudy or cue until the grid is restored. tengri.list_nebular_backends() still lists cb19 with status production, so do not infer availability from that status.

  • BPASS surviving mass is not metallicity-dependent. No surviving-mass table exists for the BPASS grids (src/tengri/data/ssp_mass_remaining/PROVENANCE.md). A BPASS build refuses the default source. Pass mass_remaining="dsps_fit" to use DSPS’s metallicity-independent fit, which does not track the metallicity dependence of the surviving mass.

  • One filter convention per Photometry. Every band in a Photometry object uses one convention: "bessell" (photon-counting, the default) or "energy" (CIGALE’s energy-type bands such as 2MASS, MIPS, PACS and SPIRE). The two conventions differ by 5 to 40 mmag (about 0.5 to 4 %) depending on band and SED slope. Set the convention to match each detector, and expect that error on bolometer bands if they are measured under the photon-counting convention.

  • AGN torus: agn/torus.py toy models are not for science. Use agn_model="skirtor" (Stalevski et al. 2016).

  • Dust IR emission templates must be loaded from data/; analytic fallbacks are not suitable for science.

  • Dust emission JIT scaling: DL07-family dust-emission models (DL07, DL14, and tabulated variants) build very large JIT graphs when dust_umin is left free in the sampler. The compiled graph can exceed 2 GB, causing slowdowns (~150× slower) in nested sampling backends. Workarounds: (1) fix dust_umin rather than fitting it, or (2) use fixed-redshift models where the precomputation (approx=WavePrecomp()) amortizes the graph across many calls. Technical details are tracked in the repository’s engineering notes (docs/dev/known_bugs.md on GitHub).

  • Nebular backends: Cue and CloudyGrid require bare-stellar SSP grids; BakedIn cannot vary neb_logU / neb_fesc. Four of six tengri.recipes need bare-stellar grids.

  • Metallicity is log10(Z) absolute on the SSP grid; user-facing neb_logZ_gas is log10(Z/Z_sun).

  • Super-solar metallicity above Z = 0.04 in the PARSEC grids is held at Z = 0.04 for young stars. The Z = 0.06 node of every PARSEC-based grid (fsps_prsc_*, ssp_prsc_*) has no stars above about 12 Msun for log10(age/yr) <= 7.15, because the PARSEC massive-star tracks stop at Z = 0.04 (Chen et al. 2015). Used as shipped, it is about 800-2700 times low in ionizing photons (Q_H(Z = 0.06) / Q_H(Z = 0.04) = 3.7e-4, 4.1e-4 and 1.3e-3 at log age 5.5, 6.0 and 6.5) and about 16 times low at 1500 A. The loader therefore refuses that part of the node: for log age <= 7.15 a metallicity above Z = 0.04 gives the Z = 0.04 population, and the Z = 0.06 node returns linearly in log age over the next 0.05 dex (one grid step: weight 0 at 7.15, 1 from 7.20), so there is no step in age. Older populations are unchanged. A model warns at build time when its metallicity weights can reach the Z = 0.06 node, that is when the met_logzsol prior’s upper bound plus 3 sigma of the metallicity scatter’s upper bound exceeds the lower edge of that node’s metallicity bin (log10(Z/Z_sun) = 0.544, Z = 0.0497, on the PARSEC grids; 0.572 with top_z="mist"). Below the edge the node’s weight is exactly zero, so the default Uniform(-2, 0.2) prior with a scatter of 0.1 dex does not warn. To use a MIST [Z/H] = +0.5 node (FSPS’s zlegend value Z = Z_sun 10^[Z/H] = 0.0449 with Z_sun = 0.0142; MILES, same IMF and ages) at young ages instead, load the grid with tengri.load_ssp(name, top_z="mist"); the node is inserted at that metallicity and the model never extrapolates above it at young ages. top_z="raw" keeps the file as shipped (cross-code comparison with FSPS only). MIST grids are complete at their top node and are not affected.

  • top_z="mist" mixes isochrone sets. Between Z = 0.040 (PARSEC) and 0.0449 (MIST) the young part of the metallicity axis switches isochrone physics, not just metallicity. MIST node / PARSEC Z = 0.04 node, measured on fsps_prsc_miles_chabrier at log age 6.0 / 6.5 / 7.0: Q_H 0.909 / 1.72 / 0.434, L_nu(1500 A) 0.908 / 0.773 / 0.783, V band (mean L_nu over 5000-5900 A) 0.775 / 0.749 / 0.911. A gradient in met_logzsol over about 0.45-0.50 at young ages reflects that switch. The default top_z="clip" has no such switch.

Reporting

Found something not listed here? Open an issue at https://github.com/suchethac/tengri/issues.