Discovery and citations

The introspection surface: browse every model, dust law, SFH variant, nebular backend, AGN block, inference method, filter, and recipe that tengri ships; look one up by name; search across all of them; and emit the exact citations a built model uses. All of these are importable directly from tengri (e.g. tengri.describe("skirtor")).

A worked, run-it-yourself tour lives in the discovery notebook; the citation verbs are covered narratively on the Citing tengri page.

Getting oriented

Start here on a fresh install: a one-screen overview, an interactive help panel, and an install/environment health check.

tengri.summary() → None[source]

Print a one-line count of every menu in tengri.

Notes

This is what to run right after import tengri to see what’s available.

tengri.help(topic: str | None = None) → None[source]

Print a curated cheatsheet covering the entry points new users need.

Parameters:

topic (str, optional) – If given, narrow the cheatsheet to one menu. Recognized topics: "agn", "dust", "sfh", "nebular", "components", "inference", "filters", "properties". Without a topic the full cheatsheet is printed.

Notes

Counts are read live from the registries: adding a new model or inference backend updates the cheatsheet immediately, no edit needed.

This shadows builtins.help() only when accessed as tengri.help; the global help() builtin is unaffected.

tengri.doctor() → str[source]

Run an environment health check and return a human-readable report.

Checks:

  • JAX version and backend

  • 64-bit (x64) enabled

  • XLA compilation cache directory

  • tengri version

  • SSP data discoverability

  • Python version

  • Platform

All checks are non-fatal; failures are reported as “WARNING: …” rather than raising.

Returns:

Health check report (also printed).

Return type:

str

tengri.explain(thing) → None[source]

Print the architectural role of a built-in class or model.

For built-in classes this prints the layered-architecture context (where the class fits in the Parameters → SEDModel → Fitter → Posterior pipeline) plus a pointer to the relevant tutorial. For registered names it delegates to tengri.describe().

Parameters:

thing (type or str) – Either a tengri class (tengri.Parameters, tengri.SEDModel, tengri.Fitter, tengri.Posterior, tengri.Observation) or a registered name ("skirtor", "calzetti", "dpl"…).

Examples

>>> tengri.explain(tengri.SEDModel)
>>> tengri.explain("skirtor")
tengri.tutorial(name: str | None = None, *, run: bool = False) → None[source]

Print (and optionally execute) a runnable tutorial recipe.

Parameters:
  • name (str, optional) – Tutorial name. Pass without an argument to list all topics.

  • run (bool) – If True and the tutorial supports live execution, run it after printing the recipe. Tutorials that need an SSP file or external data print a “skipping live execution” note instead.

  • Topics

  • ------

  • s (first_fit Mock galaxy → posterior in 30)

  • (live) (register_a_component Protocol-conforming SEDComponent)

  • (live)

  • model (swap_inference Same)

  • samplers (three)

  • Student-t (custom_likelihood)

  • floor (calibration)

  • Protocol (custom)

  • checking (diagnostics Convergence)

  • ESS

  • divergences

  • galaxies (hierarchical Population fit across many)

tengri.examples() → None[source]

List every runnable example script under examples/.

Prints the script path, one-line description (from its module docstring), and the canonical command to run it. Use this to discover what’s already on disk before writing a new script from scratch.

Print the tengri logo.

Parameters:
  • size ({"default", "small", "stipple", "compact"}) – Which rendering to print. “default” is the 37-line solid-block mark. “small” is the 21-line compact stipple. “stipple” is the 37-line textured variant. “compact” prints plain text (“tengri”) because rendering the logo any smaller would misrepresent the mark.

  • compact (bool or None) – Deprecated alias for size="compact". Kept for backward compatibility.

Notes

Respects the TENGRI_NO_LOGO environment variable: if set to anything truthy, this function writes nothing.

Per-category describe

The universal describe() covers most lookups; these return the richer, category-specific record (and describe_agn_block takes a category because AGN block names are not unique across categories).

tengri.describe_sfh_model(name: str) → _DescribeRecord[source]

Return the descriptor row for one star-formation history model.

tengri.describe_dust_law(name: str) → _DescribeRecord[source]

Return the descriptor row for one dust attenuation law.

tengri.describe_dust_emission_model(name: str) → _DescribeRecord[source]

Return the descriptor row for one dust emission template family.

tengri.describe_nebular_backend(name: str) → _DescribeRecord[source]

Return the descriptor row for one nebular emission backend.

tengri.describe_agn_model(name: str) → _DescribeRecord[source]

Return the descriptor row for one AGN model (citation, status, short doc).

Symmetric with list_agn_models(). Use the generic describe() for a cross-kind lookup.

tengri.describe_agn_block(name: str, *, category: str | None = None) → _DescribeRecord | list[_DescribeRecord][source]

Return the descriptor record(s) for one composable AGN block.

Since block names may not be globally unique (e.g., “grahsp” appears in disc, nlr, blr, torus, attenuation categories), this function returns:

  • A single _DescribeRecord if category is specified or the name is unambiguous.

  • A list of _DescribeRecord (one per matching category) if the name is ambiguous and category=None.

Parameters:
  • name (str) – Block name (e.g., "grahsp", "multicolor", "analytic").

  • category (str, optional) – Category to narrow the search: "disc", "nlr", "blr", "feii", "torus", or "attenuation". If None, search all categories.

Returns:

Single record if unambiguous, list of records if ambiguous.

Return type:

_DescribeRecord or list[_DescribeRecord]

Raises:

KeyError – If the name is not found in the specified (or any) category.

tengri.describe_inference_method(name: str) → _DescribeRecord[source]

Return the descriptor row for one inference backend (MAP / VI / NUTS / NSS / …).

Resolves any name the fitter dispatches: every tier, including "broken", which list_inference_methods() hides by default (#1287); and every registered alias.

list and describe answer different questions. list asks “what should I pick?”, so it curates. describe asks “what is this name?”, so it must not: a name the fitter accepts is never “unknown”. Deriving this lookup from the curated listing reported six dispatchable names as unknown (#1560); the five broken backends, plus "vi_nonlinear", a tier="primary" alias named in fit()’s own docstring. A confidently wrong answer is worse than a warning (#1446).

Parameters:

name (str) – A method name or alias, as passed to fit(method=...).

Returns:

Fields: {name, kind, tier, short_doc, requires, status, use}, plus alias_of when name is an alias. Check tier before acting on the result; "broken" backends resolve here but are refused by Fitter.run without allow_unvalidated=True.

Return type:

_DescribeRecord

Raises:

KeyError – If no backend is registered under name.

Examples

>>> import tengri
>>> tengri.describe_inference_method("vi_nonlinear")["alias_of"]
'vi'
tengri.describe_recipe(name: str) → _DescribeRecord[source]

Return the full descriptor block for a single recipe.

Parameters:

name (str) – Recipe name (see list_recipes()).

Returns:

Dict-like with name, docstring, ssp_requirement, returns (the actual nested-dict the recipe builds), and a ready-to-paste use example.

Return type:

_DescribeRecord

Raises:

KeyError – If name is not in tengri.recipes.

tengri.describe_property(name: str) → _DescribeRecord[source]

Return full metadata for one derived property.

Parameters:

name (str) – Property name (e.g., "stellar_mass").

Returns:

Labeled record with name, units, group, component, and description.

Return type:

_DescribeRecord

Raises:

KeyError – If the property name is not registered. Call list_properties() to see all available names.

Examples

>>> tengri.describe_property("stellar_mass")

Custom filter loading

In-memory registration, file-based directory loading, and DSPS integration for user-provided transmission curves.

Curve files may be whitespace- or comma-separated, with or without a header row; # comments are stripped. Wavelengths are Angstrom unless you say otherwise with wave_unit="nm", "um" (or "micron"), or "AA" / "angstrom". The name is case-insensitive, and the curve is converted to Angstrom once, at registration. See Units and conventions for the one spelling used at every raw-array boundary.

State the unit whenever the file is not already in Angstrom. A range wholly below 0.01 Angstrom or above 1e9 Angstrom is refused with ValueError, since it cannot be a bandpass in Angstrom. A curve given in nanometers is a valid array of numbers describing the extreme UV, so it cannot always be detected: registration warns when a curve lies wholly inside the 100-1340 Angstrom gap where the ISM is opaque and no bandpass exists. That backstop cannot see micron input at all, since a 0.3-1.0 Angstrom curve is a real NuSTAR band, and cannot catch a nanometer set running past 1340 nm without also firing on GALEX FUV.

The $TENGRI_FILTER_DIR route has nowhere to record a unit, so files placed there must already be in Angstrom.

Worked end to end, including an ADU-and-zeropoint table taken to a fit, in notebooks/custom_filters_7dt.py.

tengri.register_filter(name: str, wave_aa: ndarray | list, trans: ndarray | list, *, overwrite: bool = False, wave_unit: str | None = None) → None[source]

Register a filter in the in-memory user registry.

Creates an immutable FilterCurve from the given wavelength and transmission arrays. The name becomes available immediately to load_filter() and Photometry.from_names().

Parameters:
  • name (str) – Filter identifier (e.g., "my_custom_band"). Must be unique among all registered names (including built-in aliases, SVO stems, and synthetic bands) unless overwrite=True.

  • wave_aa (array_like, shape (n_wave,)) – Wavelength grid, in wave_unit (Angstrom by default). Must be strictly increasing.

  • trans (array_like, shape (n_wave,)) – Transmission (dimensionless). Normalization is free: only the shape of the curve enters AB synthetic photometry, since a constant scale cancels in the ratio of the two bandpass integrals.

  • overwrite (bool, optional) – If False (default), raise if name already exists in any registry (built-in, SVO, synthetic, or user). If True, silently replace an existing user-registered filter or shadow a built-in name. Default: False.

  • wave_unit (str or None, optional) – Unit of wave_aa: "AA" ("angstrom" is equivalent), "nm", "um" ("micron" is equivalent), a frequency ("Hz", "kHz", "MHz", "GHz") or an energy ("eV", "keV"). Matching is case-insensitive. The array is converted to Angstrom here, once, at the boundary, and reordered so wavelength increases with trans kept aligned. None (default) means no unit was stated, which is read as Angstrom. Pass "AA" explicitly to state Angstrom.

Raises:
  • ValueError – If wave_aa and trans have incompatible shapes.

  • ValueError – If wave_aa is not strictly increasing after sanitization.

  • ValueError – If wave_unit is not an accepted name (the message lists them).

  • ValueError – If the range lies wholly below 0.01 Å or above 3e11 Å once converted to Angstrom. This is refused, not warned, because it is nonsense for Angstrom.

  • KeyError – If name exists in a built-in registry and overwrite=False.

Warns:
  • UserWarning – If the unit was Angstrom or not stated and the range lies wholly in 100-1340 Å, which is most likely nanometers. A stated nm or um unit is never warned, because the unit is no longer in doubt.

  • UserWarning – If no unit was stated and the range lies wholly in 0.1-100 Å, which may be keV. Pass wave_unit="keV" if so.

Notes

Shadowing built-in curves (a name that already exists in FILTER_REGISTRY, SVO display stems, or SYNTHETIC_BAND_REGISTRY) requires explicit overwrite=True to prevent accidental collisions. This is a deliberate gate: the default behavior keeps user registrations from silently hiding critical built-in data.

Immutability: The returned FilterCurve is immutable. The wavelength and transmission are stored as JAX arrays; the registry does not hand out mutable references to internal state.

Examples

>>> import numpy as np
>>> from tengri.observation.filters import register_filter
>>> wave = np.linspace(5000, 7000, 100)
>>> trans = np.exp(-0.5 * ((wave - 6000) / 300) ** 2)
>>> register_filter("my_narrow_band", wave, trans)
>>> from tengri import Photometry
>>> phot = Photometry.from_names(["my_narrow_band"])
tengri.register_filter_from_file(name: str, filepath: str | Path, *, overwrite: bool = False, wave_unit: str | None = None) → None[source]

Register a filter from a two-column text file.

Reads wavelength and transmission columns, sanitizes, and registers in the user registry.

Parameters:
  • name (str) – Filter identifier (e.g., "my_band_from_file").

  • filepath (str or pathlib.Path) – Path to a two-column file of wavelength and transmission. Columns may be whitespace- or comma-separated, with or without a single header row; # comments are stripped.

  • overwrite (bool, optional) – If False (default), raise if name already exists. If True, silently replace an existing user-registered filter or shadow a built-in name. Default: False.

  • wave_unit (str or None, optional) – Unit of the wavelength column: "AA", "nm", "um", a frequency ("Hz", "kHz", "MHz", "GHz") or an energy ("eV", "keV"). None (default) means no unit was stated; see register_filter().

Raises:

Examples

>>> from tengri.observation.filters import register_filter_from_file
>>> register_filter_from_file("my_band", "/path/to/curve.txt")
>>> from tengri import Photometry
>>> phot = Photometry.from_names(["my_band"])

A curve tabulated in nanometers, converted at the boundary:

>>> register_filter_from_file(
...     "m400", "7DT_transmission_23bands/m400.csv", wave_unit="nm"
... )
tengri.unregister_filter(name: str) → None[source]

Remove a user-registered filter from the in-memory registry.

After unregistration, load_filter() falls back to built-in registries (FILTER_REGISTRY, SVO, synthetic bands). Does nothing if the name is not registered (no error).

Parameters:

name (str) – Filter identifier to remove.

Examples

>>> from tengri.observation.filters import unregister_filter
>>> unregister_filter("my_band")
tengri.load_custom_filter(filepath: str) → FilterCurve[source]

Load a custom filter from a two-column text file.

Parameters:

filepath (str) – Path to a text file with columns: wavelength (Angstrom), transmission.

Returns:

Filter with raw transmission values (not normalized). The absolute scale cancels in the photometry integral ∫fλTλdλ / ∫Tλdλ.

Return type:

FilterCurve

Raises:

Notes

Not JAX-compatible (uses file I/O). Useful when filter profiles are not available in SVO or when using synthetic, custom-defined bandpasses. File format is flexible: trailing whitespace and comment lines (starting with #) are ignored.

tengri.load_tophat_filter(wave_center_aa: float, width_aa: float, name: str = '', n_points: int = 50) → FilterCurve[source]

Create a synthetic top-hat filter (e.g. for ALMA continuum bands).

Use this when the photometric measurement does not correspond to a standard bandpass on SVO, for example, an ALMA continuum flux at a given observed frequency.

Parameters:
  • wave_center_aa (float) – Central wavelength [Angstrom].

  • width_aa (float) – Full width of the top-hat [Angstrom].

  • name (str) – Label for this filter (e.g. "alma_band6"). Default: empty string.

  • n_points (int) – Number of wavelength samples. Default: 50.

Returns:

Rectangular transmission curve with uniform transmission = 1.0.

Return type:

FilterCurve

Notes

Useful for continuum photometry measurements (e.g., ALMA, SCUBA-2) that are defined in frequency space rather than bandpass shape.

tengri.load_filter_from_dsps_transmission_curve(dsps_curve: object, name: str | None = None, *, wave_unit: str = 'AA') → FilterCurve[source]

Convert a DSPS transmission curve to a FilterCurve.

Extracts wavelength and transmission from a DSPS TransmissionCurve object and validates that wavelengths are in Angstrom.

Parameters:
  • dsps_curve (object) – A DSPS TransmissionCurve named tuple with wave and transmission attributes. Must have wave in Angstrom.

  • name (str, optional) – Filter name. If None, uses "dsps_filter". Default: None.

  • wave_unit (str, optional) – Unit of dsps_curve.wave [AA | angstrom | nm | um | micron, case-insensitive]. Converted to Angstrom once, here. Default: "AA".

Returns:

Transmission curve with wavelengths in Angstrom.

Return type:

FilterCurve

Raises:
  • AttributeError – If dsps_curve does not have wave and transmission attributes.

  • ValueError – If wavelengths are not strictly increasing after sanitization.

Warns:

UserWarning – If wavelength range looks implausible for Angstrom.

Notes

Unit verification: DSPS TransmissionCurve documents wavelengths as λ/Å. This function validates that assumption and warns if the range looks incorrect. Getting this wrong is a silent, catastrophic error, so verify the conversion against the DSPS source, never assume.

Examples

>>> from dsps.data_loaders import load_transmission_curve
>>> dsps_curve = load_transmission_curve(fn="/path/to/filter.h5")
>>> from tengri.observation.filters import load_filter_from_dsps_transmission_curve
>>> fc = load_filter_from_dsps_transmission_curve(dsps_curve, name="my_dsps_band")
tengri.load_filter_from_dsps_file(filepath: str | Path, name: str | None = None, *, wave_unit: str = 'AA') → FilterCurve[source]

Load a DSPS transmission curve from an HDF5 file.

Opens a DSPS-format filter file and converts it to a FilterCurve. Uses lazy import so DSPS is not a hard requirement unless this function is called.

Parameters:
  • filepath (str or pathlib.Path) – Path to a DSPS filter file (HDF5 format with wave and transmission datasets).

  • name (str, optional) – Filter name. If None, uses the file stem. Default: None.

  • wave_unit (str, optional) – Unit of the file’s wave dataset [AA | angstrom | nm | um | micron, case-insensitive]. Default: "AA".

Returns:

Transmission curve with wavelengths in Angstrom.

Return type:

FilterCurve

Raises:
  • ImportError – If the dsps package is not installed.

  • FileNotFoundError – If filepath does not exist.

  • ValueError – If the file format is invalid or wavelengths are not strictly increasing.

Warns:

UserWarning – If wavelength range looks implausible for Angstrom.

Examples

>>> from tengri.observation.filters import load_filter_from_dsps_file
>>> fc = load_filter_from_dsps_file("/path/to/filter.h5", name="my_band")
tengri.load_alma_band(band: int, name: str | None = None) → FilterCurve[source]

Create a synthetic top-hat filter for an ALMA continuum band.

ALMA is an interferometric array with no entries on the SVO Filter Profile Service. This function constructs a rectangular bandpass spanning the full receiver bandwidth of the requested band, which is appropriate for fitting SED continuum photometry.

Parameters:
  • band (int) – ALMA band number (1–10).

  • name (str, optional) – Label for the filter. Defaults to "alma_band{N}".

Returns:

Top-hat bandpass in observed-frame wavelengths (Angstrom).

Return type:

FilterCurve

Raises:

ValueError – If band is not in 1–10.

Examples

>>> fc = load_alma_band(6)  # 1.23 mm continuum (211–275 GHz)
>>> fc = load_alma_band(7)  # 870 μm continuum (275–373 GHz)

Notes

Band definitions follow the ALMA Cycle 11 receiver specifications. Wavelengths are in the observed frame; the filter should be applied at the observed frequency. For a source at redshift z, Band N probes rest-frame wavelength λ_rest = λ_obs / (1 + z).

Backward compatibility: This function delegates to the synthetic band registry and is kept here for API stability. New code can use load_filter() with "alma_band{N}" directly.

Citations

Component-level citation: a built model, Parameters spec, or Posterior carries the citation for every SSP grid, physics block, and inference backend it uses. Composable AGN models fan out into each of their block slots (disc, torus, NLR, BLR, Fe II, attenuation).

tengri.cite(thing) → Citation | None[source]

Look up a citation, or print every citation a model uses.

Polymorphic on the argument:

  • cite(key: str): look up a single bibliography entry and return the Citation (existing behavior). Raises KeyError if the key isn’t registered.

  • cite(parameters | sed_model | posterior): print the table of every component the object is configured to use plus the paste-ready BibTeX block beneath, then return None. This composes tengri.cite_components() and tengri.print_components_bibtex() into a single call.

Examples

>>> tengri.cite("calzetti2000")  # → Citation
>>> tengri.cite(spec)  # prints table + BibTeX
>>> tengri.cite(model)
>>> tengri.cite(posterior)
tengri.print_citations(obj: Any, *, include_backend: bool = True) → None[source]

Print the human-readable citation report for obj to stdout.

Convenience wrapper around citations_report().

Parameters:
  • obj (Any) – Any object understood by collect_citations().

  • include_backend (bool, optional) – Include inference-backend citations. Default True.

Return type:

None

Notes

JIT-compatible: no; performs I/O.

Examples

>>> import numpy as np, tengri as tg
>>> g = tg.Galaxy.from_arrays(..., preset="starforming")
>>> tg.print_citations(g)
Please cite the following when publishing results that use tengri:
  [1] Cooray et al. (2026, Paper I); SED fitting framework ...
  ...
tengri.cite_components(obj=None) → _RegistryTable[source]

Citations for every physics component a Parameters / SEDModel / Posterior uses.

This is the “live” citation walk: read straight from the registry metadata you (or contributors) populated via the citation= kwarg on @register_agn_model / @register_dust_law / SFH _register / etc.

Goes beyond tengri.collect_citations() (which uses a static BibTeX-key association table): every per-alternative citation is pulled live, so a contributor adding a new model with a fresh citation="Author+Year" immediately appears here.

Parameters:

obj (Parameters or SEDModel or Posterior, optional) – Object whose structural choices to inspect. If None, returns the citations attached to the four core dependencies (tengri, JAX, DSPS) plus an empty per-component slate.

Returns:

One row per component used. Columns: component (where in the SED model), name (the registered alternative chosen), citation (the live string from the registry), kind.

Return type:

_RegistryTable

Examples

>>> spec = tengri.Parameters(
...     mean_sfh_type="dpl", agn_model="skirtor", dust_emission="dl07_tabulated"
... )
>>> tengri.cite_components(spec)
>>>
>>> # Same call works on the SEDModel and Posterior; they expose .spec
>>> tengri.cite_components(model)
>>> tengri.cite_components(posterior)
tengri.print_components_bibtex(obj=None) → None[source]

Print BibTeX entries for every component used by obj.

Walks cite_components() to discover the components, then for each component looks up the formal BibTeX entry in the bundled citation registry (tengri.citations.references.bib). Components with a registered free-form citation= string but no BibTeX entry in the bundled registry are emitted as a % comment line so the user knows to track down the BibTeX themselves.

Output is paste-ready into a paper’s .bib file.

Examples

>>> spec = tengri.Parameters(
...     mean_sfh_type="dpl", agn_model="skirtor", dust_emission="dl07_tabulated"
... )
>>> tengri.print_components_bibtex(spec)
@article{Stalevski_2016, ...}
@article{Carnall_2018, ...}
@article{Draine_2007, ...}
...
tengri.cite_all() → list[Citation][source]

Return every registered citation, sorted by key.