Model configuration reference

This is the definitive guide to the nested-dict grammar for building a SEDModel. The guide covers universal grammar semantics, per-domain configuration, round-trip serialization, and common patterns.

I. Universal grammar semantics

The nested-dict grammar used by SEDModel.build accepts one dict per physics group, each declaring what physics variant to use, which parameters are free, and per-parameter overrides.

Three kinds of keys

Every group dict contains three kinds of keys:

1. Structural keys: select the model variant or configure the group’s behavior. The key 'type' is universal; some groups have additional structural keys (e.g., 'law' for dust, 'norm' for AGN). Structural keys are non-parameter settings.

# 'type' selects the SFH model, 'age_kernel' configures integration
sfh={'type': 'dpl', 'age_kernel': 'cic'}

2. The wildcard keys 'all_params' and 'other_params': exact synonyms that set the free/fixed status for every parameter in the group not explicitly overridden. Each accepts FREE (defer to the registry’s default prior) or Fixed(DEFAULT) (pin at the registry default value). Never a concrete Fixed(v), since one literal value cannot apply across every parameter in the group, and never an arbitrary Distribution. Giving both spellings in the same dict raises. The retired '*' synonym raises ValueError naming both accepted spellings.

Pick the spelling that reads best for the shape of the dict. Use 'all_params' when the wildcard is the group’s only directive. Use 'other_params' written last, after explicit per-parameter entries, where it reads as “the others.” The to_groups() method and the builder factories always emit following this convention:

# Sole directive: 'all_params' reads best
dust_attenuation={'type': 'two_component', 'law': 'calzetti', 'all_params': Fixed(DEFAULT)}

# Mixed: explicit overrides first, 'other_params' last
dust_attenuation={'type': 'two_component', 'law': 'calzetti', 'tau_bc': 0.5, 'other_params': Fixed(DEFAULT)}
# NOT (legal, but not the taught style): {..., 'all_params': Fixed(DEFAULT), 'tau_bc': 0.5}

3. Parameter keys: bare parameter names or full prefixed names that override the wildcard or default. Short names are auto-prefixed by the group context.

# All three mean the same: set tau_bc to 0.5
dust_attenuation={'type': 'two_component', 'tau_bc': 0.5}
dust_attenuation={'type': 'two_component', 'dust_tau_bc': 0.5}  # full prefixed name
dust_attenuation={'type': 'two_component', 'tau_bc': 0.5}       # short name (preferred)

Free vs fixed: one-minute table

Every parameter is either free (sampled during inference) or fixed (pinned at a single value), and either uses the registry default or a value/prior you provide:

registry default

your choice

free

FREE (sampled with the registry’s default prior)

any Distribution, e.g. Uniform(1, 3)

fixed

Fixed(DEFAULT) (pinned at the registry’s default value)

Fixed(0.3) (pinned at your value)

FREE means “free to vary using the registry’s default prior.” Fixed(DEFAULT) means “pinned at the registry’s default value.” The 'all_params' wildcard applies one disposition to all parameters in the group. After explicit per-parameter entries, spell the remainder 'other_params':

sfh={'type': 'dpl', 'all_params': FREE}                               # everything free
sfh={'type': 'dpl', 'beta': Uniform(1, 3), 'other_params': Fixed(DEFAULT)}  # beta free, rest pinned
dust_attenuation={'type': 'two_component', 'law': 'calzetti', 'tau_bc': 0.4, 'other_params': Fixed(DEFAULT)}  # tau_bc overridden, rest at defaults

Prefixing and name resolution

Inside each group, parameter names are auto-prefixed with the group’s canonical prefix:

  • sfh group: 'alpha' → sfh_dpl_alpha (with the type inserted)

  • dust_attenuation group: 'tau_bc' → dust_tau_bc

  • neb group: 'logz' → neb_logz_cue (varies by type)

Use the short form (unprefixed) whenever possible for readability. The full prefixed name works too, but the parser will resolve it back to the short form in the round-trip model.spec.to_groups().

Nesting and composition

Optional physics blocks (dust_attenuation, neb, agn, etc.) support nesting via sub-dicts. Each sub-block has its own 'type', 'all_params', and parameters:

agn = {
    'type': 'composable',
    'disc': {'type': 'multicolor'},
    'torus': {'type': 'skirtor', 'all_params': FREE},
    'nlr': {'type': 'cue', 'logz': -0.3},
}

Sub-blocks inherit the same grammar rules as top-level groups.

Activation and optional physics

Optional physics blocks (those NOT in the core set) are OFF by default:

  • Core groups with defaults: sfh, met, dust_attenuation, dust_emission, redshift

  • Optional groups: neb, shock, agn, igm, radio, xray, foreground

To activate an optional group, provide its dict with a 'type':

# IGM is OFF (not provided)
model = SEDModel.build(ssp_data=ssp, observation=obs, sfh={...}, redshift=Fixed(0.1))

# IGM is ON (type given)
model = SEDModel.build(ssp_data=ssp, observation=obs, sfh={...}, igm={'type': 'inoue'}, redshift=Fixed(0.1))

# Explicit OFF (same as omitting it)
model = SEDModel.build(ssp_data=ssp, observation=obs, sfh={...}, igm={'type': 'none'}, redshift=Fixed(0.1))

An optional group with no 'type' but with other keys raises ParameterError with the required syntax.

Wildcard rules and no-op detection

'all_params': FREE on a group whose parameters default to Fixed(DEFAULT) is valid and cascades. However, when a wildcard cannot actually free anything, 'all_params': FREE raises ParameterError instead of silently building a model with that physics pinned (#2187). Two shapes both raise:

The group declares no parameters at all under the selected configuration (e.g. radio with every sub-model disabled):

model = SEDModel.build(
    ssp_data=ssp, observation=obs,
    radio={'sf': {'type': 'none'}, 'agn': {'type': 'none'}, 'all_params': FREE},
    redshift=Fixed(0.1),
)
# Raises ParameterError:
# "'all_params'/'other_params': FREE in group 'radio' covers no parameters --
#  this group declares none to free under the selected configuration.
#  FREE resolves each parameter's registry default; with nothing declared
#  here there is nothing for it to resolve, so the fit would silently not
#  vary anything in this group.
#  Remove the wildcard, or pass explicit priors for the parameters you meant
#  to vary (e.g. radio={'param_name': Uniform(lo, hi)} for whichever
#  parameter your chosen configuration actually declares)."

The group declares parameters, but every one of them is Fixed-only (no declared free_prior), so the wildcard would free zero of them. The guard raises for this shape, and the message names the parameters it would have freed. The met table type is refused at build (#2425), so the shape is not reproduced here.

# The remedy depends on the parameter -- it is not always "add a prior".
# met_alpha_fe acts only on an SSP grid with an [alpha/Fe] axis (a 4-D `_afe`
# grid). On a 3-D grid it has no effect, and the build refuses it (see below).
# For this parameter, drop the wildcard rather than free it on a grid you have
# not confirmed carries the axis.
model = SEDModel.build(ssp_data=ssp, observation=obs, sfh={'type': 'dpl'}, met={'type': 'delta'}, redshift=Fixed(0.1))

# CORRECT (general case): an explicit prior on a parameter you genuinely
# mean to vary -- gas-phase metallicity, live in every photoionized
# nebular backend:
model = SEDModel.build(
    ssp_data=ssp, observation=obs,
    neb={'type': 'cue', 'logZ_gas': Uniform(-1.0, 0.3)},
    redshift=Fixed(0.1),
)

A partial free (where some parameters have a declared range and some do not) warns with WildcardPartialFreeWarning rather than raising, naming which ones stay pinned. See the docstring of _check_wildcard_freed_something for the full four-outcome table.

The same refusal applies to an explicitly named per-parameter FREE, not just the wildcard. Naming one specific parameter as FREE must free it or refuse, never silently leave it pinned. met_alpha_fe is the worked refusal example: its declaration has no free_prior, so naming it FREE raises rather than quietly building a model with it pinned. Run on a 3-D grid, the message is:

model = SEDModel.build(
    ssp_data=ssp, sfh={'type': 'dpl'},
    met={'type': 'delta', 'alpha_fe': FREE}, redshift=Fixed(0.1),
)
# Raises ParameterError:
# "'alpha_fe': FREE cannot be honored -- 'met_alpha_fe' has no declared
#  free prior (its registry default is Fixed(0.0)). Pass an explicit prior
#  instead, e.g. alpha_fe: Uniform(lo, hi)."

An explicit prior does not help on a 3-D grid. A grid with no [alpha/Fe] axis has one metallicity node per total Z and no alpha-enhanced templates, so met_alpha_fe would not change the SED, and the build refuses any non-zero value, free or fixed. Run on the same 3-D grid, Uniform(-0.2, 0.4) raises:

model = SEDModel.build(
    ssp_data=ssp, sfh={'type': 'dpl'},
    met={'type': 'delta', 'alpha_fe': Uniform(-0.2, 0.4)}, redshift=Fixed(0.1),
)
# Raises ParameterError:
# "met_alpha_fe is free, but the SSP grid 'fsps_prsc_miles_chabrier' has no
#  [alpha/Fe] axis (it is a 3-D grid). Its metallicity nodes are total Z and
#  carry no alpha-enhanced templates, so met_alpha_fe would not change the SED.
#  Use an alpha-enhanced 4-D grid (a name containing '_afe'; see
#  tengri.list_remote_ssps()), or remove met_alpha_fe, or hold it at Fixed(0.0)."

To vary [alpha/Fe], pass an alpha-enhanced 4-D grid (a name containing _afe, listed by tengri.list_remote_ssps()) as ssp_data, then give met_alpha_fe an explicit prior. The prior is checked against the grid’s [alpha/Fe] nodes: one with no overlap is refused, and one that extends past them is kept with a GridSupportWarning, since the lookup clips at the edge nodes. On such a grid the FREE refusal above also names the node range, e.g. For this grid: alpha_fe: Uniform(-0.2, 0.6). Fixed(0.0), the declared default, builds on any grid and is what every build uses unless a prior is given.

redshift is the worked example of the opposite outcome: a parameter with a declared default free prior. It declares free_prior=Uniform(0.0, 20.0), an interval chosen to span and exceed every shipped recipe’s redshift prior (photoz Uniform(0.01, 6.0), high_z Uniform(3.5, 10.0), stochastic/JWST Uniform(0.01, 12.0)), so redshift=FREE frees it over that range rather than raising:

model = SEDModel.build(ssp_data=ssp, observation=obs, sfh={...}, redshift=FREE)
# Builds. model.spec.get_distribution('redshift') == Uniform(0.0, 20.0)

# Narrow it with an explicit prior for a survey-specific photo-z fit
model = SEDModel.build(ssp_data=ssp, observation=obs, sfh={...}, redshift=Uniform(0.01, 6.0))

An emission-line fit with a free redshift is a local optimization. Aliased redshifts, where a line is matched to a different transition at another redshift, are real minima, and the optimizer settles in whichever basin it starts from. Do not rely on a free-redshift line fit to find the right solution unaided. Either fix the redshift when it is known, or seed the fit near the true value: pass init_from= a Posterior whose redshift sits at a photometric or catalog estimate, for example a photometric-only fit, so the emission-line fit starts in the correct basin.

Error handling and suggestions

Unknown structural keys trigger a ParameterError with the list of valid keys and suggestions via difflib:

dust_attenuation={'type': 'two_component', 'law': 'calzetti', 'tau_bc_': 0.5}
# Raises: "Unknown key 'tau_bc_' in dust_attenuation. Did you mean: tau_bc?"

An AGN sub-block refuses a key that its selected type does not read, so the key is never accepted and then dropped; the message names the types that do read it.

CIGALE spellings

The refusal for a key that CIGALE’s AGN modules use, but tengri spells differently, names the tengri key to use:

CIGALE key

tengri key

disk_type

agn={'disc': {'type': ...}}: 0 is 'skirtor', 1 is 'schartmann2005', 2 is 'adaf_lopez2024'

delta

on agn.disc, agn_cigale_disk_delta for disc types 'skirtor' and 'schartmann2005', and agn_cigale_adaf_delta for 'adaf_lopez2024' (the ADAF blend weight)

lambda_fracAGN

agn={'ir_frac_window': (lambda_min_um, lambda_max_um)} (or the string '5/20') together with agn_ir_frac; (0, 0) is the total-dust case

fracAGN

agn_ir_frac

The torus parameter agn_delta is a different quantity, and no composable torus block reads it.


II. Per-domain configuration

Each physics block follows the universal grammar. This section lists the structural keys and one minimal working example for each.

Parameter reference

This page documents the configurable structure of the model grammar. For per-component parameter details (defaults, units, descriptions), see :doc:components or call tengri.describe(component_name).

Structural keys by domain

agb_dust

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'other_params' —

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

agn

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'atten' — AGN attenuation sub-block.

  • 'axis_grids' —

  • 'blr' — Broad-line region sub-block.

  • 'disc' — AGN accretion disk sub-block.

  • 'feii' — Iron emission sub-block.

  • 'ir_frac_window' —

  • 'lines' — Deprecated: expands to (nlr, blr).

  • 'nlr' — Narrow-line region sub-block.

  • 'norm' — Cross-component normalization: ‘cigale_joint’ (default) or ‘independent’.

  • 'other_params' —

  • 'polar_law' —

  • 'torus' — AGN infrared torus sub-block.

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

dust_attenuation

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'Rv_bc' — Birth-cloud RV override (two_component).

  • 'Rv_diff' — Diffuse RV override (two_component).

  • 'Rv_neb' — Nebular RV override (two_component).

  • 'age_mixture' —

  • 'agn_screen' —

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'bump_strength_bc' — Birth-cloud bump strength override (two_component).

  • 'bump_strength_diff' — Diffuse bump strength override (two_component).

  • 'bump_strength_neb' — Nebular bump strength override (two_component).

  • 'delta_bc' — Birth-cloud delta override (two_component).

  • 'delta_diff' — Diffuse delta override (two_component).

  • 'delta_neb' — Nebular delta override (two_component).

  • 'dust_curve' — WG00 attenuation curve selector.

  • 'geometry' — WG00 geometry (‘slab’, ‘sphere’, etc.).

  • 'law' — Dust law (e.g., ‘calzetti’, ‘ccm89’). Required for single_component.

  • 'law_bc' — Birth-cloud dust law. Required with law_diff on two_component.

  • 'law_diff' — Diffuse dust law. Required with law_bc on two_component.

  • 'law_neb' — Nebular dust law (reddens birth-cloud continuum only).

  • 'lyc_escape_geometry' —

  • 'lyc_in_energy_balance' — Include ionizing luminosity in dust energy-balance integral.

  • 'lyc_reprocessed_by' — Which stars’ non-escaping ionizing photons are reprocessed: ‘young’ (birth clouds, default) or ‘all’ (FSPS/CIGALE style). Two-component only.

  • 'lyman_cutoff' — Zero attenuation below 912 Å (Lyman limit). Two-component only.

  • 'nebular_screen' —

  • 'other_params' —

  • 'parameterization' —

  • 'screens' —

  • 'shock_screen' —

  • 'slope_bc' — Birth-cloud law parameter override (two_component).

  • 'slope_diff' — Diffuse law parameter override (two_component).

  • 'slope_neb' — Nebular law parameter override (two_component).

  • 'structure' — WG00 structure (‘clumpy’, ‘homogeneous’, etc.).

  • 't_birth_yr' — Birth-cloud dispersal age [yr] (default 1e7; pcigale separation_age). Two-component only.

  • 'transition_width_dex' — Dispersal width [dex] of every age edge; 0 (default) is the hard step. Two-component and age_binned.

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

dust_emission

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'cmb' —

  • 'diffuse_screen' —

  • 'eta_balance' — Energy-balance coupling parameter or prior.

  • 'f_cnm' — Cold neutral medium fraction.

  • 'log_L_ir' —

  • 'other_params' —

  • 'spinning_dust' — Include small spinning dust grains.

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

foreground

  • 'ebmv_mw' — Milky Way E(B-V) reddening (mag).

  • 'law' — Dust law (e.g., ‘calzetti’, ‘ccm89’). Required for single_component.

  • 'rv' — Dust RV parameter for foreground reddening.

igm

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'dla' — Damped Lyman alpha sub-block. Omit or provide {‘type’: …}.

  • 'other_params' —

  • 'patchy' — Picket-fence vs smooth IGM (bool).

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

met

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'alpha_fe_evolving' —

  • 'met_bin_edges_log_yr' —

  • 'other_params' —

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

neb

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'full_catalog' — Line catalog scope (bool).

  • 'other_params' —

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

radio

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'agn' — AGN radio sub-block.

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'other_params' —

  • 'sf' — Star-formation radio sub-block.

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

sfh

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'age_kernel' — Integration method: ‘cic’ (default, cloud-in-cell) or ‘dsps’ (histogram).

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'bin_edges_gyr' — Non-parametric bin edges (Gyr). Only for type=’histogram’.

  • 'coordinates' —

  • 'field_centering' — Field draw centering. Only for type=’field’.

  • 'other_params' —

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

shock

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'abundance' — Abundance mode: ‘solar’, ‘lmc’, etc.

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'component' —

  • 'norm' — Cross-component normalization: ‘cigale_joint’ (default) or ‘independent’.

  • 'other_params' —

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

xray

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'all_params' — Wildcard: set all parameters to FREE or FIXED. Only user-facing wildcard (not ‘*’).

  • 'other_params' —

  • 'type' — Physics variant (e.g., ‘dpl’, ‘calzetti’, ‘cue’). Required.

Round-trip serialization

A model’s configuration can be inspected and edited via serialization:

.. code-block:: python

model = SEDModel.build(...)
config = model.spec.to_groups()  # dict with all groups and parameters
model.spec.summary()             # print with provenance tags

For per-parameter documentation, see the component reference or:

.. code-block:: python

import tengri
tengri.describe("cue")     # nebular backend "Cue"
tengri.describe("calzetti")  # dust law "Calzetti 2000"

Generated per-domain parameter references are shown above. For per-type parameter defaults, units, and descriptions, see Components Reference.

Star-formation history: sfh

Structural keys:

  • 'type': SFH model ('dpl', 'delayed_tau', 'lognorm', 'field', etc.). Menu: tengri.list_sfh_models().

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

  • 'age_kernel': 'cic' (default, cloud-in-cell) or 'dsps', which names the same integration (#2683).

  • 'bin_edges_gyr': Non-parametric bin edges (Gyr). Only for type='histogram' or similar.

  • 'field_centering': Field draw centering (‘none’ or ‘mean’). Only for type='field'.

  • 'type': ['delayed', 'recent'] and ['delayed', 'recent_ssfr'] build a current star-formation episode of constant rate over the last timescale_myr on top of the smooth delayed history, with log_sfr (or the specific rate log_ssfr) as the episode parameter; recent_ssfr is refused at build if its priors reach the sSFR pole. See docs/model_reference/sfh.md.

  • 'coordinates': For type='continuity', 'ratios' (default) samples the Student-t log-SFR ratios, and 'young_fraction' samples the stick-breaking mass fractions from the youngest bin instead. The fractions give the photometrically pinned young mass its own axis, because the ratio coordinates make the posterior a curved ridge when that mass is well constrained. The Student-t ratio prior is carried to the fractions as an exact pullback, so both choices describe the same posterior. The young-fraction form needs all six fractions free and fits on the Fitter paths that evaluate the standardized prior; the evidence and hierarchical paths refuse it with a ConfigError.

Minimal example:

sfh={'type': 'dpl', 'all_params': FREE, 'beta': Uniform(1, 3), 'age_kernel': 'cic'}

Gotchas:

  • 'age_kernel': 'dsps' gives the same weights as 'cic' (identical to round-off, #2683). DSPS’s own histogram assigns each parcel wholly to one SSP node, which mis-places structure narrower than the node spacing (a 30 Myr burst at z = 2.5: 14-19 % in the FUV) and cannot see an onset or step edge between table rows (a zero psb_flex tflex gradient); first-order sharing of the exact integrand is the exact answer, so the zeroth-order definition is not offered. It is not a speed knob.

  • A field SFH accepts both names (#2684): the draw is the linear interpolation of its own lookback nodes, integrated with the nodes as knots. Without an explicit age_kernel a field SFH uses 'cic'.

  • Default age_kernel is 'cic' for every SFH type.

Metallicity: met

Structural keys:

  • 'type': Metallicity model ('table' for per-age SSP indexing, 'ramp' for a linear Z(t) history, etc.). Menu: tengri.list_metallicity_modes().

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

  • 'met_bin_edges_log_yr': Lookback-time bin edges [log₁₀ yr] for metallicity-history modes ('bins' or 'bins_continuity'). Default spans 1 Myr to 13.8 Gyr. Accepts an array of strictly increasing edge values (at least 2 edges). Mirroring sfh={'bin_edges_gyr': [...]} for non-parametric star formation histories.

  • 'alpha_fe_evolving': True replaces the single alpha_fe by a linear ramp in lookback time between alpha_fe_young (today) and alpha_fe_old (the oldest stars). Needs an SSP grid with an [α/Fe] axis; alpha_fe and alpha_fe_evolving cannot be given together. Both ends are fixed at 0.0 unless given explicit priors, which follow the same rule as alpha_fe. Default False.

Minimal example:

met={'type': 'table'}  # all_params defaults to Fixed(DEFAULT)
met={'type': 'ramp', 'logzsol_0': Fixed(-0.3), 'logzsol_1': Free}  # two-knot ramp
met={'type': 'bins', 'all_params': Fixed(DEFAULT), 'met_bin_edges_log_yr': [6.0, 8.0, 9.5]}  # custom ladder
met={'alpha_fe_evolving': True, 'alpha_fe_old': Uniform(0.0, 0.6), 'alpha_fe_young': Fixed(0.0)}  # [α/Fe] ramp, 4-D grid

Gotchas:

  • Metallicity is separate from star formation. met= selects SSP templates; neb={'logZ_gas': ...} drives nebular emission independently.

  • Default met_logzsol = 0.0 (solar). The SSP grid uses absolute log10(Z) internally, with a Zsun offset (Asplund 2009).

  • A tabulated (per-SSP-age) met= beside a non-tabulated sfh warns but does not raise.

AGB circumstellar dust shell: agb_dust

Structural keys:

  • 'type': AGB dust-shell model: 'fsps_shell' (the only supported type). Omitting the group, or agb_dust={'type': 'none'}, leaves the SSP grid untouched.

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

Minimal example:

agb_dust={'type': 'fsps_shell'}  # weight fixed at 1.0 (bit-identical to omitting the group)
agb_dust={'type': 'fsps_shell', 'weight': Uniform(0, 3)}  # free
agb_dust={'type': 'fsps_shell', 'weight': Fixed(2.0)}  # fixed at a non-default strength

Gotchas:

  • 'weight' is the short-form override for agb_dust_weight, the dimensionless scale on FSPS’s Villaume, Conroy & Johnson (2015) circumstellar AGB dust-shell reprocessing. Default Fixed(1.0) (the grid as shipped, FSPS’s own agb_dust default). Free prior Uniform(0, 3).

  • MIST-isochrone SSP libraries only (fsps_mist_*): FSPS’s add_agb_dust_model routine is MIST-only. Any other grid raises at build time, naming the supported grids.

  • The ratio was computed with FSPS 0.4.7 using MIST isochrones, the MILES spectral library and a Chabrier IMF, and is reused for the c3k_a grids and the Kroupa and Salpeter IMFs. The IMF dependence was measured only at solar metallicity (ages 0.3, 1, 3 Gyr; weights 0 and 3): at most 0.004 (Kroupa) and 0.019 (Salpeter) in the ratio. The spectral-library dependence could not be measured.

  • The ratio is stored on a ladder of weights and interpolated linearly between them: between stored weights it matches direct FSPS to better than 2% over 2-30 um (0.4-1.6% per interval, measured at solar metallicity for 0.3, 1 and 3 Gyr). Below w = 1/1024 the error reaches 4% (3.6% over 2-30 um), because the ratio is nearly discontinuous at w = 0 (FSPS switches the shell off); a weight near 0 carries a few-percent error. A free weight reaches the exact spectrum, the photometry and compute_log_nion; the nebular Q_H tables built once at model construction read the unweighted cube (measured effect below 1e-4 dex up to 10 Myr, at most 0.107 dex in single 45-100 Myr cells where Q_H is negligible).

  • The gradient with respect to the weight is the slope of the bracketing segment, so it has a kink at every stored weight (1/1024, 1/128, 1/8, 7/32, 5/16, 7/16, 9/16, 13/16, 1, 5/4, 13/8, 2, 3). For a 1 Gyr population the 10 um ratio peaks close to w = 1, so its slope changes sign around it.

  • The ratio spans 0.055 (far-infrared, w = 0) to 236 (old, metal-poor populations at 1200-1500 A) and is not clamped. It is exactly 1 outside 284 A to 3.4e7 A; the lower edge comes from a few 45-100 Myr low-metallicity populations at the 1e-4 threshold, not from shell absorption.

  • A fixed weight is baked into the SSP tensor at SEDModel.build time, so the exact path and every precompute table (WavePrecomp, SpectrumPrecomp, FeaturePrecomp) stay bit-exact.

  • A free weight cannot be baked (its value is only known per sample). Exact photometry, spectra and the ionizing rate apply it live. Everything built once from the SSP cube refuses, naming the exact path: WavePrecomp, SpectrumPrecomp, the FeaturePrecomp window table for baked-in lines, and approx=True on predict_spectral_indices / measure_line_fluxes. The FeaturePrecomp Cue grid reads the live ionizing rate and works. approx='auto' resolves to the exact path for single, catalog and population fits.

Dust attenuation: dust_attenuation

Structural keys:

  • 'type': Architecture: 'single_component' (one dust screen) or 'two_component' (birth-cloud + diffuse). Default varies by law.

  • 'parameterization': Screen-depth parameterization of a 'two_component' block: 'tau_bc_diff' (default; declares 'tau_bc' and 'tau_diff') or 'tauv_mu' (declares 'tau_v' and 'mu'). Charlot & Fall (2000) written as a total V-band depth and the fraction in the diffuse ISM: tau_BC = (1 - mu) tau_V, tau_ISM = mu tau_V. The two forms are the same model, bit-identical at equivalent values.

    • 'tau_v' (under 'tauv_mu'): total V-band optical depth of the two screens (dust_tau_v). Default Fixed(1.0); free prior Uniform(0, 4).

    • 'mu' (under 'tauv_mu'): fraction of the V-band depth in the diffuse ISM (dust_mu), in [0, 1]. Default Fixed(0.3); free prior Uniform(0, 1).

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

  • 'law': Attenuation law: 'calzetti', 'ccm89', 'mw_rv31', 'kext00', etc. Menu: tengri.list_dust_laws().

    • On 'single_component': one law for the entire dust.

    • On 'two_component': 'law' applies to both screens. Override per-screen with 'law_bc' and 'law_diff'.

    • On 'wg00' (Willis & Graves 2000 screen): use structural keys like 'dust_curve', 'geometry', 'structure' instead of a law name.

  • 'law_bc': Birth-cloud attenuation law (two-component only). Required with 'law_diff' when not using shared 'law'.

  • 'law_diff': Diffuse dust attenuation law (two-component only). Required with 'law_bc' when not using shared 'law'.

    • 'chevallard13' (Chevallard et al. 2013, optical-depth-dependent curve) is accepted as 'law_diff' only. Its slope flattens as the diffuse depth grows, and it is fitted over 0.1 to 2.5 μm, with the index held at its edge values outside that range.

  • 'law_neb': Nebular dust law (the curve for the nebular channel; which screen that channel passes through is 'nebular_screen'). Under 'nebular_screen': 'own' it is the law of the own screen.

  • 'nebular_screen': Which dust screen the nebular continuum, the line catalog and the fast-nebular fallback pass through. On 'two_component': 'birth_cloud' (default: the young-star screen, birth cloud + diffuse, mixed by where the ionizing photons come from), 'diffuse' (the old-star screen), 'none' ('off' is a synonym), or 'own': one dedicated screen T_neb(λ) = exp(−tau_neb · k_neb(λ)), with k_neb the 'law_neb' curve (default 'law_bc', normalized to k(5500 Å) = 1) and tau_neb the declared parameter dust_tau_neb (Fixed at 1 unless set or freed; Uniform(0, 4) when freed). 'own' is the TOTAL nebular attenuation: no cascade through the diffuse screen, no young/old mixture, no dust_f_obscuration floor; the absorbed nebular energy joins the dust budget as for the other choices. On 'age_binned': 'birth_cloud' (default, the ionizing-weighted interval mixture) or 'own' (law_neb defaults to the first screen’s law, with that screen’s shape parameters; an explicit law_neb declares its own <shape>_neb parameters). 'tau_neb' (and, on 'age_binned', 'law_neb' and the <shape>_neb keys) is refused with any choice but 'own', naming nebular_screen='own'. 'single_component' accepts only 'none'. Cross-code: CIGALE’s E(B−V)_lines = f_att⁻¹ · E(B−V)_stars is this screen with tau_neb = f_att⁻¹ · tau_stars; Prospector/FSPS (dust1 + dust2 on the lines) and BAGPIPES (η · A_V on the birth cloud) have no separate nebular depth, which is what the default reproduces.

  • 'shock_screen': Which screen the shock SED passes through; same values; default 'diffuse' (AGN-outflow shocks sit outside the birth clouds).

  • 'agn_screen': Screen choice for AGN continuum attenuation: 'birth_cloud', 'diffuse', or 'none' (default). Two-component only. Incompatible with agn_norm='cigale_joint' (both read the dust budget); use agn_norm='independent' or 'conserving' instead.

  • 'dust_curve': WG00 dust curve selector (only for type='wg00').

  • 'geometry': WG00 geometry (‘slab’, ‘sphere’, etc.) (only for type='wg00').

  • 'structure': WG00 structure (‘clumpy’, ‘homogeneous’, etc.) (only for type='wg00').

  • 'slope_bc', 'slope_diff', 'slope_neb': Per-screen law-parameter overrides (two-component only). Accepted only when that screen’s law reads a slope.

  • 'bump_strength_bc', 'bump_strength_diff', 'bump_strength_neb': Per-screen bump-strength overrides (two-component only). Accepted only when that screen’s law reads a bump strength.

  • 'Rv_bc', 'Rv_diff', 'Rv_neb': Per-screen RV overrides (two-component only). Accepted only when that screen’s law reads R_V.

  • 'delta_bc', 'delta_diff', 'delta_neb': Per-screen delta overrides (two-component only). Accepted only when that screen’s law reads a slope modification.

  • 'lyman_cutoff': Zero attenuation below 912 Å (Lyman limit). Two-component only.

  • 't_birth_yr': Birth-cloud lifetime [yr] (type='two_component' only; default 1e7). Stars younger than this sit behind the birth-cloud screen, stars older behind the diffuse screen alone. The split is exact: each SSP age node’s share of mass formed younger than t_birth_yr is taken through the SFH kernel, so a node straddling the boundary is partly young and the result does not depend on where the SSP nodes fall. The default is a hard step, as in pcigale (separation_age) and FSPS (dust_tesc).

  • 'transition_width_dex': Dispersal width [dex] of every age edge (two_component, age_binned). The default 0 is the hard step; a positive value replaces it with a logistic dispersal of that width in log10(age).

  • 'lyc_reprocessed_by': Which stellar population’s ionizing photons are absorbed by neb_fesc: 'young' (birth-cloud only; the default for every nebular backend except Cue) or 'all' (FSPS/CIGALE style; the default when neb is 'cue' and counts every age). Two-component only. Cue counts the ionizing photons of every stellar age (neb 'lyc_max_age_yr'), so the stellar SED must give up the LyC of every age too; with 'young' the older ages’ LyC would stay in the SED and be re-emitted by Cue as well. With a finite neb 'lyc_max_age_yr' the default is 'young'. 'young' with Cue counting ages above t_birth_yr is an error (ConfigError): use 'all' with every age counted, or set lyc_max_age_yr <= t_birth_yr. 'all' with a finite lyc_max_age_yr is also an error: it would remove the LyC of the ages Cue does not count from the SED and re-emit none of it. The one exception is the former 100 Myr cut (lyc_max_age_yr=1e8) with 'young': it is accepted with a one-time warning, because ages between t_birth_yr and 100 Myr then keep their LyC in the SED while Cue re-emits it (a small energy gap, 10-100 Myr stars only). model.spec.summary() prints the resolved value as [default: 'all' for cue], [default: 'young' for cue with a finite lyc_max_age_yr] or [user].

  • 'lyc_in_energy_balance': Include ionizing luminosity in the dust energy-balance integral (FSPS/Prospector parity). Default false. (See also 'diffuse_screen' under dust_emission below: an analogous opt-in single-pass toggle, applied to the escaping re-emitted IR through this group’s diffuse screen rather than to the absorbed budget.)

  • 'screens': type='age_binned' only (#2528). A list of {'law': <law name>, 'window_log_yr': (lo, hi)} dicts, one per screen; lo/hi are log10(age/yr) edges, either or both None for unbounded. N independent screens generalize the birth-cloud/diffuse pair to any N; windows need not partition the age axis. Optical depths add over every screen whose window contains a star’s age: nested windows (each (None, hi_i) with increasing hi_i, the last unbounded) cascade as the birth cloud and diffuse medium do in 'two_component', and tau_i is the depth screen i adds; windows that tile the age axis give each age a single screen, and tau_i is the total depth of that age bin. Per-screen parameters are indexed from the screen count: 'tau_0', 'tau_1', … (full name dust_tau_i), plus one '<lawparam>_i' for every shape parameter that screen’s own law declares (e.g. 'slope_0', 'Rv_2'), defaulting to that law’s own published value. screens = [{'law': law_bc, 'window_log_yr': (None, log10(t_birth))}, {'law': law_diff, 'window_log_yr': (None, None)}] reproduces 'two_component' bit-identically. Not supported under approx=WavePrecomp()/SpectrumPrecomp() (raises at construction; a fit’s approx="auto" resolves to the exact path instead). Nebular continuum and the line catalog are attenuated only by screens whose window is unbounded below (the t -> 0 limit, the same convention 'two_component' applies to lines); a finite lower edge must sit at least five transition widths above the loaded SSP grid’s youngest node or the build raises ConfigError, naming the screen, the edge, the grid’s youngest node, and the two fixes.

  • 'age_mixture': How the two-component mixture of young and old transmissions is evaluated; the model is the same either way. 'grouped' (default) takes the sum in this order, T_young·L_young + T_old·L_old with L_young = Σ_a y(a)·L(a) and L_old = Σ_a (1 − y(a))·L(a) formed by the stellar component: two attenuated spectra instead of n_age, equal to floating-point reassociation (soft boundary and Lyman-continuum branch included), with much less memory under vmap(value_and_grad). 'per_node' attenuates every SSP age node, Σ_a L(a)·[y(a)·T_young + (1 − y(a))·T_old], and stays selectable. Two-component only. Static: the two choices compile separately.

  • 'lyc_escape_geometry': Whether the escaping fraction (neb_fesc) bypasses the birth-cloud screen through a geometric hole, instead of only skipping nebular reprocessing. 'screened' (default): the escaping fraction never touches the dust screen, only the nebular budget — unchanged from every model built without this key. 'birth_cloud_holes': a covering fraction neb_fesc of the young population’s light bypasses the birth-cloud screen but still crosses the diffuse ISM (FSPS frac_obrun-style: an OB star outside its birth cloud still sees the general dust). 'clear': that same fraction sees no dust at all (Synthesizer fesc-style: a fully clear sightline). Applies at every wavelength, not only below the Lyman limit — a hole in a birth cloud is geometric, not wavelength-selective. Two-component only (an attenuator needs a birth-cloud screen distinct from the diffuse screen for a hole to be in); incompatible with 'lyc_reprocessed_by': 'all' (both would reduce the young population’s escaping light from the same neb_fesc, double-counting it).

Each of the 12 per-screen keys above ('slope_bc', 'bump_strength_bc', 'Rv_bc', 'delta_bc', and their '_diff'/'_neb' siblings) takes either a plain number (as before) or Fixed(...)/a prior distribution (#2428). A plain number is a build-time config override, baked into the compiled model exactly as it always was. Fixed(...)/Uniform(...)/ etc. instead declares a real, free-able parameter named dust_<stem>_<screen> (e.g. dust_slope_bc, dust_Rv_neb). It appears in spec.free_params when given a prior, and a Fixed(v) per-screen declaration predicts bit-identically to the plain number v. These names are explicit-only: an all_params: FREE wildcard never frees them (name one explicitly to fit it), and the flat Parameters(dust_law_overrides={...}) surface still accepts only plain numbers in that dict. Passing a prior there raises ParameterError naming the dust_<stem>_<screen> spelling as the remedy. Naming only one half of a _bc/_diff pair (e.g. slope_bc without slope_diff) raises. Give both explicitly, or use a group-level wildcard ('all_params': FREE/Fixed(DEFAULT)) to free or pin them together, following the same rule the plain-number spelling of these keys already enforces.

Minimal example:

# Single component
dust_attenuation={'type': 'single_component', 'law': 'calzetti', 'tau': 0.5, 'other_params': Fixed(DEFAULT)}

# Two component (one law)
dust_attenuation={'type': 'two_component', 'law': 'calzetti', 'tau_bc': 0.4, 'tau_diff': 0.2, 'other_params': Fixed(DEFAULT)}

# Two component (per-screen laws)
dust_attenuation={'type': 'two_component', 'law_bc': 'ccm89', 'law_diff': 'calzetti', 'tau_bc': 0.4, 'tau_diff': 0.2}

# Total V-band depth and diffuse fraction (Charlot & Fall 2000), chevallard13 as the diffuse-ISM law
dust_attenuation={'type': 'two_component', 'parameterization': 'tauv_mu', 'law_bc': 'power_law', 'law_diff': 'chevallard13', 'tau_v': FREE, 'mu': Fixed(0.4), 'other_params': Fixed(DEFAULT)}

# WG00 screen with structural selectors
dust_attenuation={'type': 'wg00', 'dust_curve': 'mw_rv31', 'geometry': 'slab', 'structure': 'clumpy'}

# Age-binned, nested windows (#2528): a cascade; young stars see all three screens,
# and each tau_i is the depth that screen adds
dust_attenuation={
    'type': 'age_binned',
    'screens': [
        {'law': 'calzetti', 'window_log_yr': (None, 7.0)},
        {'law': 'power_law', 'window_log_yr': (None, 8.5)},
        {'law': 'cardelli', 'window_log_yr': (None, None)},
    ],
    'tau_0': 0.5, 'tau_1': 0.3, 'tau_2': 0.2, 'other_params': Fixed(DEFAULT),
}

# Age-binned, tiling windows: each age sees one screen; each tau_i is that bin's total depth
dust_attenuation={
    'type': 'age_binned',
    'screens': [
        {'law': 'calzetti', 'window_log_yr': (None, 7.0)},
        {'law': 'power_law', 'window_log_yr': (7.0, 8.5)},
        {'law': 'cardelli', 'window_log_yr': (8.5, None)},
    ],
    'tau_0': 1.0, 'tau_1': 0.5, 'tau_2': 0.2, 'other_params': Fixed(DEFAULT),
}

Gotchas:

  • Dust attenuation and dust emission are two separate peer groups, not nested. The retired dust={'attenuation': {...}, 'emission': {...}} form raises.

  • Each emission source passes through the screen its selector names ('nebular_screen', 'shock_screen', 'agn_screen'); the absorbed nebular and shock power joins the dust energy balance under those screens.

  • Two-component law-pairing rule: if you name one of 'law_bc'/'law_diff', you must name both (or use a shared 'law' for both).

  • A native depth key ('tau_bc', 'tau_diff') under 'parameterization': 'tauv_mu' raises, and so does 'tau_v' or 'mu' without 'tauv_mu'; name one description per block.

  • 'parameterization' on a 'single_component' block raises, because it is a two-component setting.

  • 'chevallard13' given as 'law', 'law_bc' or 'law_neb' raises, because it is legal only as 'law_diff'.

  • Parameters like 'slope', 'bump_strength', 'Rv', 'delta' are set per-screen on two-component ('slope_bc', 'slope_diff', etc.). On single-component, just 'slope': the per-screen spellings raise there, because a single screen has no second screen to name and the value would never reach a curve.

  • A shape key must be one the selected law reads. Each law declares exactly the parameters it uses, so 'slope' under 'noll09' raises and names 'delta', the parameter that law does read; 'Rv' under 'calzetti' raises, because that curve is fitted at R_V = 4.05; 'slope' under 'vw07_bc' / 'vw07_diff' raises, because those are the Charlot & Fall birth-cloud and diffuse slopes, not knobs (use 'power_law' for a free slope). The same rule applies per screen: with 'law_bc': 'power_law', 'law_diff': 'noll09', 'slope_bc' is accepted and 'slope_diff' is not. A lone 'slope_bc' is then complete, because there is no partner to give.

  • The 'neb' channel ('law_neb', 'slope_neb', etc.) reddens only the nebular birth-cloud continuum, not the young stars. Used when nebular emission is routed through a different dust screen. 'law_neb' defaults to 'law_bc', and a '*_neb' override is checked against whichever of the two is in force.

Dust emission: dust_emission

Structural keys:

  • 'type': Emission model: 'dale2014', 'draine2016', etc. Menu: tengri.list_dust_emission_models().

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

  • 'spinning_dust': Include small spinning dust grains (default: auto from type).

  • 'f_cnm': Cold neutral medium fraction (parametrization-dependent).

  • 'eta_balance': Energy-balance coupling: Fixed(1.0) (default, strict balance where L_IR = eta * L_absorbed). FREE selects the default free prior, Gaussian(1.0, 0.2) truncated at 0. Pass an explicit Uniform(...) or any other prior to override it. The all_params wildcard reaches it on every emission engine, since it scales the budget every template normalizes to, so it remains live regardless of the selected engine (#2286).

  • 'log_L_ir': Total dust IR budget override, log10(L_IR/L_sun). Declaring it (with Fixed(...) or any prior) replaces the energy-balance budget outright. Leaving it undeclared keeps energy balance. Because it renders eta_balance inert, declaring both (with eta_balance free or fixed not equal to 1) raises at build. Radio’s FIRRC amplitudes follow this budget, so it is not a dust-only knob. Never reached by the all_params wildcard. An explicit FREE on it is refused; declare a real prior instead.

  • 'diffuse_screen': Opt-in single-pass attenuation of the re-emitted IR dust emission by the diffuse dust screen’s transmission T(λ) (the dust_diff_transmission derived key, published by every dust_attenuation type). The escaping SED is sed_dust_ir * T: the IR energy absorbed on the way out is REMOVED, not re-emitted or iterated back into the budget (unlike FSPS, which iterates the IR to convergence; CIGALE never attenuates its re-emitted IR at all — this is a deliberate single pass). log_L_ir_emergent reports the escaping (post-screen) IR luminosity; L_ir/L_absorbed (and radio’s FIRRC amplitudes, which read L_ir) keep the pre-screen absorbed budget unchanged. For single-screen attenuators (dust_attenuation={'type': 'single_component', ...}) and for type='wg00', “diffuse” means the single screen — there is no separate birth-cloud/diffuse split to choose between. Default false (off, bit-identical to a build without this key). Requires an active, non-'none' dust_attenuation and a real dust_emission type; raises a clear ValueError at parse time otherwise.

  • 'cmb': Opt-in CMB heating and contrast of a tabulated emission model (da Cunha et al. 2013, Eqs. 12 and 18). True applies the contrast factor 1 - B_nu(T_CMB(z))/B_nu(T_d(z)) to every tabulated type (schreiber2016, schreiber2018, draine_li2007, draine_li2014, dale2014, themis, astrodust, dh02_ce01, bosa) and, for the single-temperature schreiber2016 / schreiber2018 libraries, also heats the dust temperature (Eq. 12) and scales the luminosity by the heated-to-intrinsic temperature ratio to the power 4 + beta, beta = 1.8. The radiation-field libraries get the contrast only, at a dust temperature read off the template (an approximation, see the dust reference). Default false (off, bit-identical to a build without the key). Reads the model’s redshift. Raises a ValueError for modified_blackbody, graybody and casey2012, which always apply both effects, and without a dust_emission type.

Minimal example:

dust_emission={'type': 'dale2014', 'eta_balance': Fixed(1.0), 'other_params': Fixed(DEFAULT)}

Gotchas:

  • Energy balance: eta_balance defaults to Fixed(1.0), which enforces L_IR = L_absorbed. FREE resolves to Gaussian(1.0, 0.2) truncated at 0. Setting it free or to a constant ≠ 1 decouples IR and absorption.

  • Missing dust_emission (or {'type': 'none'}) is valid and common for UV-only work.

  • 'diffuse_screen' under dust_attenuation={'type': 'wg00', ...}: the vendored WG00 attenuation tables (data/wg00_attenuation_grid.h5) are tabulated only 1000–30001 Å (0.1–3 μm). Past that domain T = 1 by construction, so under wg00 the switch has no effect in the far-IR where dust re-emission actually peaks — this is a limitation of the vendored table’s wavelength coverage, not a defect in the diffuse-screen feature itself.

Nebular emission: neb

Structural keys:

  • 'type': Backend: 'cue' (Cue, default), 'cloudy' (CLOUDY, slower, higher fidelity), 'cb19' (Charlot & Bruzual 2019), 'gutkin16' (Gutkin+2016 NEOGAL H II line tables), 'mappings' or 'mappings_agn' (MAPPINGS V stellar and AGN; both backends are registered as experimental; both refuse loudly pending data rehabilitation (#2082): stellar grid is 51.2% NaN, AGN backend lacks protocol surface), or 'none' (off). Menu: tengri.list_nebular_backends().

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

  • 'full_catalog': cue only: bool, default True (#2239). Publishes the full ~138-line Cue-trained catalog. Set to False to narrow to the legacy 128-line CLOUDY/FSPS-matched subset, kept for cross-code comparisons. No-op on other backends.

  • 'nitrogen': cue only: 'absolute' (default) or a relation name ('nicholls17') (#2693). Selects the meaning of gas_logno; see the nebular notes below. Raises on other backends.

  • 'balmer_series_n_max': cue only: 50 (default), an integer from 10 to 50, or None. Appends the hydrogen Balmer lines H11 to Hn_max above Cue’s last native line (H10) to the full catalog, each at its Case-B emissivity ratio to H-beta (Storey & Hummer 1995) at 10^4 K and 10^2 cm^-3. None (or 10) publishes Cue’s own lines only. The ratios are fixed at that temperature and density and change by up to 6.7% for H24 and below, and 27% at H50, over 5000-20000 K and 10^2-10^3 cm^-3; each added line carries that change in its model sigma. The legacy 128-line subset (full_catalog: False) is never extended. Raises on other backends.

  • 'lyc_max_age_yr': cue only: 'all' (default) or the oldest stellar age [yr] whose ionizing photons Cue counts. By default Q_H and the ionizing-spectrum shape come from every age bin of the SSP, so a quiescent galaxy has the Hα luminosity its old (post-AGB) Lyman continuum implies. 1e8 gives the former 100 Myr cut: Q_H, the shape and the nebular lines and continuum are bit-identical to it, and with a finite value dust_attenuation['lyc_reprocessed_by'] defaults to 'young', so the stellar SED below 912 Å keeps the LyC of the ages Cue does not count, as before. 'all' together with a finite value raises (see lyc_reprocessed_by). With a birth-cloud dust type (two_component, age_binned) the supported pairings are: lyc_max_age_yr='all' with lyc_reprocessed_by='all' (the default); lyc_max_age_yr <= t_birth_yr with 'young'; and t_birth_yr < lyc_max_age_yr <= 1e8 with 'young' (one warning about the 10-100 Myr gap). A finite value above 1e8 has no supported pairing and raises, because energy is created under 'young' (LyC of ages between t_birth_yr and the cutoff stays in the SED while Cue re-emits it) and lost under 'all' (LyC of ages beyond the cutoff is removed and never re-emitted). single_component and wg00 have no young/old split, so this pairing check does not apply to them. Raises on other backends.

  • 'publish_line_fraction': cue only: bool, default False. Publishes derived['nebular_line_frac'], the line share of the nebular SED, lines / (continuum + lines), with sed_nebular and every observable unchanged. Required by Spectroscopy(nebular_lines=False), which removes Cue’s lines from the spectrum only, so the photometry keeps them while the caller fits the spectrum’s lines with its own free amplitudes. Raises with DIG active.

  • 'grid': Path to the backend’s own HDF5 grid file. Accepted only for 'cloudy', 'cb19', 'gutkin16', 'mappings', and 'mappings_agn'; None (the default) resolves each backend’s own packaged grid (#2220).

  • 'mup': gutkin16 only: upper stellar mass cutoff [M⊙], 100 (default) or 300, the two m_up slices of the table. Other values raise.

  • 'continuum': gutkin16 only: 'analytic' (default; free-free plus two-photon continuum) or 'none'. Other values raise.

  • 'model': MAPPINGS V stellar model ('mappings' type only): 'sb99' (Starburst99) or 'bpass' (BPASS v2.2).

  • 'density': MAPPINGS V density structure ('mappings'/'mappings_agn'): 'cpr' (isobaric, recommended) or 'cdn' (isochoric).

  • 'ionizing_source_warning': MAPPINGS V ionizing-source warning control ('mappings'/'mappings_agn'): 'raise', 'warn', or 'suppress'.

Minimal example:

neb={'type': 'cue', 'logZ_gas': -0.3, 'other_params': Fixed(DEFAULT)}
neb={'type': 'cloudy', 'grid': {'logz': [-2, -1, 0], 'logU': [-3, -2, -1]}}

Gutkin+2016 backend ('gutkin16'). It implements the Cloudy c13.03 H II-region grids of Gutkin, Charlot & Bruzual (2016) from the public NEOGAL tables, over the same line set that BEAGLE interpolates. The packaged grid data/gutkin16_grid.h5 is used unless 'grid' is given.

Key

Default

Free prior (FREE resolves to)

Table extent

'logU' (neb_logU)

Fixed(-3.0)

Uniform(-4.0, -1.0)

log10 U_S, −4.0 to −1.0 (7 nodes)

'logZ_gas' (neb_logZ_gas)

Fixed(-0.3)

Uniform(-2.15, 0.45)

log10(Z/Z⊙), −2.15 to +0.45 (14 metallicities)

'log_nH' (neb_log_nH)

Fixed(2.0)

Uniform(2.0, 3.0)

log10(n_H / cm⁻³), 2 to 3 (100 and 1000 cm⁻³)

'xi_d' (neb_xi_d)

Fixed(0.3)

Uniform(0.1, 0.5)

dust-to-metal ratio, 0.1, 0.3, 0.5 (3 nodes)

'co_ratio' (neb_co_ratio)

Fixed(1.0)

Uniform(0.1, 1.4)

(C/O)/(C/O)⊙, 0.1 to 1.4 (9 nodes)

FREE adopts the table extent. An explicit prior or a fixed value outside the table is refused at build, with the range to narrow to. In the grammar neb_logZ_gas is log10(Z/Z⊙) with Z⊙ = 0.0142. The table axis is absolute log10 Z, from Z = 0.0001 to 0.04 at 14 metallicities, and the nebular component adds log10 Z⊙ before the backend reads the value. neb_co_ratio is linear (C/O)/(C/O)⊙, not the log10 C/O of 'cb19'.

model = SEDModel.build(
    ssp_data=ssp, observation=obs, sfh={...}, redshift=Fixed(0.1),
    neb={'type': 'gutkin16', 'mup': 300, 'logU': Uniform(-4.0, -1.0), 'other_params': Fixed(DEFAULT)},
)

Gotchas:

  • Nebular metallicity ('neb_logZ_gas' or short 'logZ_gas' in the neb dict) is independent from stellar metallicity ('met=').

  • Default neb_logZ_gas = -0.3 (solar). It is not automatically inherited from the stellar metallicity, even if tabulated.

  • Nebular emission is additive to stellar continuum; it composites with dust and shock when both are present.

  • Cue’s response to neb_logU depends on the ionizing spectrum it is fed. neb_logU reaches the network unchanged as Cue’s gas_logu (the inner-face U at R = 10^19 cm, trained over log U -4 to -1, Li et al. 2025, arXiv:2405.04598, Table 1; values outside that range are passed unclipped). Cue is not a fixed-spectrum CLOUDY grid: its 7 ionizing-shape inputs are derived from the SSP, and the fitted shape sets how far O++ can grow with U. At Cue’s own default (hard) young-starburst shape, [O III]/H-beta rises from 3.4 to 6.1 between log U = -3 and -1.5. For the soft shape fitted to a delayed-tau population (tau = 300 Myr, age 100 Myr, FSPS MIST+MILES, Z = 0.02), [O III]/H-beta saturates at 0.60, 0.67, 0.65 for log U = -3, -2, -1.5; the saturated level depends on the population’s age weights. A flat [O III]/H-beta against neb_logU therefore reflects the ionizing shape, not a wiring error, and a difference from a CLOUDY grid computed at a fixed spectrum is a difference of model and spectrum. Use ionspec_* overrides to probe other shapes.

  • Cue counts ionizing photons from every stellar age. For a population whose star formation ended long ago the nebular emission is then set by the old-star Lyman continuum (post-AGB and extreme horizontal-branch stars; Binette et al. 1994, A&A 292, 13), at about the case-B Hα per ionizing photon (L(Hα) = 1.37e-12 erg x Q_H, Osterbrock & Ferland 2006). Hα equivalent widths of order 1 Å follow. The photon rate of these ages depends on the SSP library: the FSPS/MIST grids carry about 3e40-1e41 photons/s/Msun at ages above 1 Gyr, the FSPS/Padova grid essentially none. For a star-forming history the change from the 100 Myr cut is below 0.5%. Because the stellar SED gives up the LyC of every age under the Cue default dust_attenuation['lyc_reprocessed_by']='all', the energy closes: measured on a grid with 5e40 photons/s/Msun above 1 Gyr, the nebular light is 94% (tau 0.3 Gyr at 10 Gyr) to 97% (tau 1 Gyr at 10 Gyr) of the LyC energy removed, the rest not being re-emitted within the SED grid. With a finite cutoff the default is 'young', which leaves the LyC of the ages beyond the cut in the stellar SED. Cue’s forbidden-line ratios for old (post-AGB) ionizing shapes are not validated against CLOUDY. neb={'type': 'cue', 'lyc_max_age_yr': 1e8} restores the cut. The cloudy, cb19 and mappings backends keep their own age range, set by the ages their grids cover.

  • 'gutkin16': an explicit prior on neb_logU or neb_log_nH wider than the table (−4 to −1, 2 to 3) is refused at build, with the range to narrow to. Use FREE to take the table extent, or a prior inside it as in the example above.

  • 'gutkin16': at Z = 0.040 the public table’s m_up = 300 rows are identical to its m_up = 100 rows. The table is used as published.

  • 'gutkin16': With approx=FeaturePrecomp() and a free neb_logU, the fast nebular table reproduces the exact gutkin16 line fluxes to 8e-4 per band at the default 16 nodes and to 5e-5 with FeaturePrecomp(n_grid={'neb_logU': 32}); the exact path interpolates the table’s seven logU nodes with PCHIP and the fast table re-samples it.

  • Cue’s gas_logno is its absolute [N/O] input by default; neb={'type': 'cue', 'nitrogen': 'nicholls17'} makes it the offset from the Nicholls+2017 N/O–O/H relation at neb_logZ_gas, the convention of neb_dno in the grid backends (which embody their own, unrecorded, relation; the two agree at the N/[O II] level, Cue/grid 0.78-0.99 over neb_logZ_gas -1 to 0). The [N/O] Cue is actually fed is the log_no property in both modes (#2693).

Shock emission: shock

Structural keys:

  • 'type': Shock backend: 'mappings' (MAPPINGS V, default) or 'none' (off).

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

  • 'norm': Normalization: 'frac' (scales the galaxy Hα), 'lhalpha' (absolute Hα luminosity, decoupled from SFR), or 'component' (explicit component label).

  • 'abundance': Abundance mode: 'solar', 'lmc', etc.

  • 'component': Component label for compartmentalization (advanced).

Minimal example:

shock={'type': 'mappings', 'norm': 'frac', 'frac': Uniform(0, 1)}
shock={'type': 'mappings', 'norm': 'lhalpha', 'lhalpha': 10**42}  # erg/s

Gotchas:

  • 'all_params': FREE on shock raises if no free-parameter models are configured. Use explicit priors instead.

  • Shock and nebular emission compose (both can be on). The shock norms apply independently.

  • Default shock_abundance = 'solar'. No abundance parameter by default.

IGM absorption: igm

Structural keys:

  • 'type': IGM model: 'inoue' (Inoue+2014, default), 'madau' (Madau+1995), 'meiksin06' (Meiksin 2006), 'none' (off).

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

  • 'patchy': Picket-fence vs smooth IGM: bool, model-dependent default.

  • 'dla': Damped Lyman alpha: omit for no DLA, or provide {'type': ...} for DLA models (e.g., {'type': 'dla_lookback'} to evolve DLA properties with redshift).

Minimal example:

igm={'type': 'inoue'}  # Smooth IGM
igm={'type': 'inoue', 'patchy': True}  # Picket-fence
igm={'type': 'inoue', 'dla': {'type': 'dla_lookback'}}  # With evolving DLA

Gotchas:

  • IGM is applied only to observed-frame wavelengths (after redshifting). It affects photometry and spectroscopy, not rest-frame predictions.

  • IGM models are applied to observer-frame wavelengths, so redshift must be specified for IGM to have an effect.

  • 'patchy' has minimal effect on Inoue (mostly Rayleigh scattering); larger on Madau.

Radio emission: radio

Structural keys:

  • 'type': Radio model: 'sfonly' (star-formation only, default), 'agn' (AGN only), 'sf_agn' (both), 'none' (off).

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

  • 'sf': Star-formation radio sub-block: {'type': ..., 'nu_ref': ..., 'freefree': bool, 'ir_window': 'total' | 'tir' | 'fir'} to customize. For bell2003, 'nu_ref' sets where the q calibration anchors the synchrotron: '1.4GHz' (default, Bell 2003), '21cm' (1.42758 GHz, CIGALE’s convention) or a frequency in Hz; 'freefree' (True/False) overrides whether the radio block carries the Murphy et al. (2011) free-free term. 'ir_window' selects the infrared band of the dust-emission SED that L_IR is integrated over for the q relations: 'tir' is 8-1000 um (Bell 2003; Delvecchio et al. 2021; McCheyne et al. 2022), 'fir' is 42.5-122.5 um (Helou et al. 1985, nominal IRAS band) and 'total' is the dust power as published (CIGALE’s convention). Unset, each model takes its own paper’s window: 'tir' for bell2003, bell2003_split, delvecchio2021 and mccheyne2022. See the radio model reference.

  • 'agn': AGN radio sub-block: {'type': ...} to customize.

Minimal example:

radio={'type': 'sfonly'}
radio={'type': 'sf_agn', 'sf': {'type': 'condon'}, 'agn': {'type': 'nandra'}}

Gotchas:

  • Radio parameters are fixed by default. 'all_params': FREE raises unless a model with free params is configured.

  • Use explicit priors on individual parameters, e.g., radio={'q10': Uniform(-0.5, 0.5)}.

  • Radio is composable: both SF and AGN can emit at once.

X-ray emission: xray

Structural keys:

  • 'type': X-ray model: 'simple' / 'yang20' (Yang+2020 corona, Fragos+2013 XRBs), 'lopez24' (Lopez+2024 corona), 'none' (off).

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

Minimal example:

xray={'type': 'yang20', 'all_params': Fixed(DEFAULT)}
xray={'type': 'simple', 'log_nh': Fixed(21.0)}  # Hydrogen column density, log10(cm^-2)

Gotchas:

  • X-ray emission scales with star-formation rate and optionally AGN accretion rate.

  • Default calibrations assume specific normalization conventions; consult paper for details.

  • X-ray can be free or fixed like any component.

AGN: agn

Structural keys:

  • 'type': AGN mode: 'composable' (six independent emitters), 'legacy' (single monolithic AGN), or 'none' (off).

  • 'all_params': Wildcard: sets every parameter in the group to FREE or Fixed(DEFAULT). Exact synonym: 'other_params' (reads best written last, after explicit per-param entries). Not '*' (retired).

  • 'norm': Across-component normalization: 'cigale_joint' (default, CIGALE-style energy conservation across disc/torus/polar) or 'independent' (each component on its own scale).

  • 'polar_law': Extinction curve of the polar dust: 'smc' (default, Pei 1992), 'calzetti', 'gaskell' or 'bongiorno' (CIGALE’s extinction_law = 0: the Bongiorno et al. 2012 power law above 100 nm with the Weingartner & Draine 2001 SMC-bar shape below it). Also accepted inside 'atten'.

  • 'axis_grids': User-supplied node grids for the composable AGN band table (WavePrecomp): a dict mapping each free agn_* parameter name to a 1-D increasing array, which must span that parameter’s prior. A grid that does not cover the prior is refused at build with a ValueError, and parameters without a grid use the default nodes. The build also measures the table at its cell centers and uses the exact per-call path instead when it is off by more than 1e-3.

  • 'ir_frac_window': CIGALE’s lambda_fracAGN window for agn_ir_frac, (lambda_min_um, lambda_max_um) or the string '5/20'. (0, 0) (default) makes agn_ir_frac the fraction of the total dust luminosity; a window makes it the fraction of the light in [lambda_min, lambda_max]; equal non-zero edges are monochromatic. Needs the composable AGN and an active agn_ir_frac.

  • 'disc': AGN accretion disk sub-block (with 'type', 'all_params', parameters).

  • 'torus': Infrared-obscured torus sub-block (with 'type', 'all_params', parameters).

  • 'nlr': Narrow-line region sub-block (with 'type', 'all_params', parameters).

  • 'blr': Broad-line region sub-block (with 'type', 'all_params', parameters).

  • 'feii': Iron emission sub-block (with 'type', 'all_params', parameters).

  • 'atten': AGN-specific attenuation sub-block (with 'type', 'all_params', parameters, and 'law' for dust law selection).

  • 'lines': Deprecated: expands to 'nlr' + 'blr'.

Minimal example:

agn={
    'type': 'composable',
    'disc': {'type': 'multicolor', 'all_params': Fixed(DEFAULT)},
    'torus': {'type': 'skirtor', 'all_params': FREE},
    'nlr': {'type': 'cue', 'all_params': Fixed(DEFAULT)},
    'norm': 'cigale_joint',
}

# Or a monolithic model (one self-contained block, no sub-blocks):
agn={'type': 'skirtor_stalevski', 'all_params': Fixed(DEFAULT)}

Gotchas:

  • On 'composable', all six sub-blocks are optional. Omitting one deactivates it (e.g., no 'disc' means no direct accretion disk emission).

  • Each sub-block follows the same grammar (type, all_params, parameters) as a top-level group.

  • 'norm': 'cigale_joint' ties disc/torus/polar normalization to a single AGN-power reference; 'norm': 'independent' lets each float freely.

  • AGN sub-block names ('disc', 'torus', etc.) are single, not plural. 'discs' raises.

Foreground extinction: foreground

Structural keys:

  • 'ebmv_mw': Milky Way E(B-V) reddening (mag). Typically 0.01–0.2.

  • 'law': 'cardelli' (Cardelli, Clayton & Mathis 1989, default) or 'fitzpatrick99' (Fitzpatrick 1999). Multiply a Schlegel et al. (1998) map E(B-V) by 0.86 (Schlafly & Finkbeiner 2011) before using it with 'fitzpatrick99'; the code applies the E(B-V) it is given.

  • 'rv': Total-to-selective extinction ratio R_V (default 3.1).

Minimal example:

foreground={'ebmv_mw': 0.05, 'law': 'fitzpatrick99'}

Gotchas:

  • Foreground reddening is applied in addition to any dust attenuation in the model.

  • The screen is applied once on the observed-frame projection path, so the spectrum and the photometry are reddened by the same transmission.

  • On the batched spectroscopic path the law and R_V come from the template and E(B-V) is per galaxy: give each GalaxySpectrum its ebmv_mw (a template with a nonzero foreground E(B-V) refuses galaxies without one).

  • No free parameters by default (use Fixed() if you need to pin values precisely).

Redshift: redshift

Structural keys: None (redshift is a scalar or Distribution, not a dict).

The redshift can be specified as:

  • Fixed(z): Known redshift (e.g., Fixed(0.05)).

  • Uniform(z_min, z_max): Photo-z prior (e.g., Uniform(0.0, 2.0)).

  • Any Distribution (e.g., Normal(...)).

  • A bare scalar: redshift=0.05 auto-converts to Fixed(0.05).

Minimal examples:

redshift=Fixed(0.05)                  # Known redshift
redshift=Uniform(0.0, 1.0)            # Photo-z fit
redshift=0.05                         # Auto-converts to Fixed(0.05)

Gotchas:

  • Redshift is REQUIRED. Omitting it raises ParameterError listing the three allowed forms.

  • A free redshift (Uniform or Distribution) is expensive with precompute (approx=WavePrecomp(...)). See the performance guide for details.

  • IGM models apply only to observed-frame wavelengths, so redshift must be known for IGM to work.


Spectroscopic calibration: Spectroscopy options

These options configure the analytic calibration marginal (calibration_marginalize=True), not the SED build grammar. They are fields of Spectroscopy.

  • calibration_segments: the pixel count of each camera segment (for example wave_obs_segment_sizes) or one integer id per pixel, 0 .. n_seg - 1. The calibration multiplier then carries one free scale per segment, M = s_seg + sum_j a_j T_j. Default None: the multiplier is 1 + sum_j a_j T_j, bit-identical to a model without the option.

  • cal_prior: "gaussian" (default) puts N(0, sigma^2) on the tilt and N(1, sigma^2) on each segment scale; "scale_free" puts a flat prior on the coefficients in data-flux units, so the marginal does not depend on the model’s flux scale.

  • cal_scale_prior: (log10_center, sigma_dex), a log-normal prior on the mean multiplier q over a window. It adds one sampled parameter, cal_log_q = ln q. A Gaussian in q itself at 0.3 dex puts 7 % of its mass at q < 0 and is much stronger on the high side, which is why the log-normal is the form.

  • cal_scale_window: (lo, hi) [Angstrom] inside the grid over which q is averaged. Default: every fitted pixel of the segment that contains the r band’s effective wavelength (6231 Angstrom). Needs cal_scale_prior.

On the batched path GalaxySpectrum(segment_ids=..., cal_scale_prior=...) gives each galaxy its own layout and prior.

III. Round-trip: configuration serialization

A model’s resolved configuration can be inspected and edited via serialization.

Inspect the model config

config = recipes.star_forming_photometry()
model = SEDModel.build(ssp_data=ssp, observation=obs, **config)

# Get the resolved config as a nested dict
config = model.spec.to_groups()
# config is a plain dict ready for re-parse or export

# Print a formatted summary with provenance
model.spec.summary()  # Tags show [user], [default], [all_params FREE], [resolved to cloudy grid: lo..hi], etc.

# Access the raw spec (lower-level; rarely needed)
model.spec  # the Parameters object

Export to YAML / JSON

Round-trip serialization (planned for #75) will support:

# Export to YAML
model.to_yaml("config.yaml")
model.to_json("config.json")

# Load from file
model = SEDModel.from_yaml("config.yaml", ssp_data=ssp, observation=obs)
model = SEDModel.from_dict(config_dict, ssp_data=ssp, observation=obs)

For now, use:

import yaml
config = model.spec.to_groups()
with open("config.yaml", "w") as f:
    yaml.dump(config, f)

Round-trip semantics

to_groups() never expands a wildcard into individual per-parameter priors. A mixed group (explicit overrides plus a wildcard) round-trips with the overrides first and the wildcard collapsed to 'other_params' last. This follows the same convention the grammar teaches for hand-written dicts:

# Input
model = SEDModel.build(ssp_data=ssp, observation=obs, sfh={'type': 'dpl', 'all_params': FREE, 'beta': Uniform(1, 3)}, met={'type': 'delta'}, redshift=Fixed(0.1))

# Output of model.spec.to_groups()
{
    'sfh': {
        'type': 'dpl',
        'beta': Uniform(1.0, 3.0),  # user override, kept explicit
        'other_params': FREE,       # everything else in the group, collapsed
    },
    # ... other groups ...
}

A sole-directive wildcard (no explicit per-parameter overrides) round-trips unchanged:

model = SEDModel.build(ssp_data=ssp, observation=obs, sfh={'type': 'dpl', 'all_params': FREE}, met={'type': 'delta'}, redshift=Fixed(0.1))
model.spec.to_groups()['sfh']
# {'type': 'dpl', 'all_params': FREE}

Unknown keys in a saved config file are detected on re-parse and raise with suggestions.


IV. Common patterns

Recipe + tweak

Start with a recipe, then modify:

from tengri import recipes, Uniform

config = recipes.star_forming_photometry()
config['dust_attenuation']['tau_bc'] = 0.6  # override default
config['neb']['logZ_gas'] = Uniform(-0.5, 0.0)  # photo-Z on gas metallicity

model = SEDModel.build(ssp_data=ssp, observation=obs, **config)

Variant swap

Exchange one sub-component:

config = recipes.agn_panchromatic()
config['agn']['disc'] = {'type': 'multicolor'}  # swap the disk model
model = SEDModel.build(ssp_data=ssp, observation=obs, **config)

Wildcard + explicit override

Free everything except a few things:

model = SEDModel.build(
    ssp_data=ssp, observation=obs,
    sfh={'type': 'dpl', 'beta': Fixed(2.0), 'other_params': FREE},  # beta pinned, the rest free
    dust_attenuation={'type': 'two_component', 'law': 'calzetti', 'tau_bc': Uniform(0, 1), 'other_params': Fixed(DEFAULT)},  # only tau_bc free
    redshift=Fixed(0.1),
)

Composable AGN with mixed freedom

agn = {
    'type': 'composable',
    'disc': {'type': 'multicolor', 'all_params': Fixed(DEFAULT)},
    'torus': {'type': 'skirtor', 'all_params': FREE},
    'nlr': {'type': 'analytic', 'all_params': Fixed(DEFAULT)},  # fixed at registry defaults
    'blr': {'type': 'analytic'},  # uses defaults
    # feii and atten omitted (OFF)
}
model = SEDModel.build(ssp_data=ssp, observation=obs, agn=agn, redshift=Fixed(0.1))

V. Error messages tour

The grammar is designed to fail loudly with actionable guidance.

Missing required setting

model = SEDModel.build(ssp_data=ssp, observation=obs, sfh={'type': 'dpl'})
# ParameterError: redshift is required. Specify one of:
#   - redshift=Fixed(z) for a known redshift
#   - redshift=Uniform(lo, hi) for a photo-z fit
#   - redshift=<any Distribution> for other priors

Missing structural key (when required)

model = SEDModel.build(ssp_data=ssp, observation=obs, dust_attenuation={'type': 'two_component', 'all_params': Fixed(DEFAULT)}, redshift=Fixed(0.1))
# ParameterError: dust_attenuation type 'two_component' requires 'law' or ('law_bc' and 'law_diff').
# See tengri.list_dust_laws() for options.

Mismatched law pair

dust_attenuation={'type': 'two_component', 'law_bc': 'calzetti'}
# ParameterError: On dust_attenuation type 'two_component', 'law_bc' requires 'law_diff'.
# Specify both, or use 'law' for both screens.

Unknown key with suggestion

sfh={'type': 'dpl', 'beta_': Uniform(1, 3)}
# ParameterError: Unknown key 'beta_' in sfh group.
# Did you mean: beta?

Retired spelling

stellar={'type': 'chabrier'}
# ValueError: The 'stellar' kwarg is retired. Use 'met=' instead to select metallicity mode.
# met={'type': 'table'} for the same behavior.

Retired wildcard

sfh={'type': 'dpl', '*': FREE}
# ValueError: The wildcard key '*' has been retired; the wildcard is spelled
# 'all_params' (or its synonym 'other_params'). Write {'all_params': FREE}
# instead of {'*': FREE}.

No-op wildcard

model = SEDModel.build(ssp_data=ssp, observation=obs, radio={'type': 'sfonly', 'all_params': FREE}, redshift=Fixed(0.1))
# ValueError: radio legacy type form is retired. radio={'type': 'sfonly'} → use the
# composable form: radio={'sf': {'type': 'bell2003'}, 'agn': {'type': 'powerlaw'}}

IGM without redshift

The model will build, but IGM has no effect:

model = SEDModel.build(ssp_data=ssp, observation=obs, sfh={'type': 'dpl'}, igm={'type': 'inoue'}, redshift=Uniform(0, 1))
# ✓ Builds. IGM model is loaded but applied only when redshift is known (during prediction).

See also