feat: first-class latent variable API in PyAutoGalaxy

[Jammy2211]

Summary

PyAutoGalaxy now has a first-class latent variable API. Users no longer need to subclass AnalysisImaging and hand-write LATENT_KEYS + compute_latent_variables to get derived quantities into latent.csv. A new autogalaxy/imaging/model/latent.py module owns the registry of named latent computations, autogalaxy/config/latent.yaml lets users toggle individual latents on/off without editing Python, and AnalysisImaging overrides PyAutoFit's stubbed hook to dispatch through the registry.

Day-1 catalogue is one concrete latent — total_galaxy_0_flux_mujy (total integrated flux of the first galaxy in the fit, magzero-converted to microjanskies). It defaults OFF in autogalaxy/config/latent.yaml because it requires magzero to be passed via AnalysisImaging(..., magzero=<value>); existing fits that don't pass magzero would otherwise crash once compute_latent_samples ran. Users opt in by editing the yaml AND passing magzero.

This is the dependency root of the broader latent_refactor epic; PyAutoLens (next sub-prompt) will add the lensing-specific latents (magnification, effective Einstein radius, lensed source flux) on top of this infrastructure.

Closes #439.

API Changes

New public module autogalaxy.imaging.model.latent with helpers (ab_mag_via_flux_from, flux_mujy_via_ab_mag_from), the LATENT_FUNCTIONS registry, the latent_keys_enabled() reader, and one registered latent (total_galaxy_0_flux_mujy, disabled by default). AnalysisImaging gains a LATENT_KEYS @property and a compute_latent_variables(parameters, model) method — both new public surface. New config file autogalaxy/config/latent.yaml. Note: autoconf lowercases yaml keys, so the latent name uses lowercase mujy (not muJy) — this leaks through to the latent.csv column header.

See full details below.

Test Plan

• pytest test_autogalaxy/imaging/model/test_latent.py -x -v — 9/9 pass
• pytest test_autogalaxy/ — 917/917 pass (no regression)
• Default-off check: existing AnalysisImaging fits without magzero continue to produce empty LATENT_KEYS, so compute_latent_variables returns an empty tuple — no crash.
• End-to-end opt-in smoke (follow-up): enable the latent in a workspace config/latent.yaml, pass magzero via Analysis kwargs, run an autogalaxy_workspace modeling script, inspect output/.../latent/latent_summary.json.

Full API Changes (for automation & release notes)

Added

• autogalaxy.imaging.model.latent — new module
• autogalaxy.imaging.model.latent.ab_mag_via_flux_from(flux, magzero, xp=np) — flux → AB magnitude
• autogalaxy.imaging.model.latent.flux_mujy_via_ab_mag_from(ab_mag, xp=np) — AB magnitude → flux in microjanskies
• autogalaxy.imaging.model.latent.total_galaxy_0_flux_mujy(fit, magzero, xp=np) — concrete latent; returns NaN when galaxy 0 has no light profile; raises ValueError if magzero is None
• autogalaxy.imaging.model.latent.LATENT_FUNCTIONS: Dict[str, Callable] — flat registry of name → function
• autogalaxy.imaging.model.latent.latent_keys_enabled(yaml_config=None) -> List[str] — reads conf.instance["latent"] (or an explicit dict for tests); returns enabled keys filtered to those present in LATENT_FUNCTIONS
• autogalaxy.AnalysisImaging.LATENT_KEYS — new @property overriding the inherited class-level []; reads from config at call time
• autogalaxy.AnalysisImaging.compute_latent_variables(parameters, model) — overrides PyAutoFit's stubbed hook; returns a tuple positionally aligned with LATENT_KEYS
• autogalaxy/config/latent.yaml — new config file with one toggle (total_galaxy_0_flux_mujy: false by default)

Changed Behaviour

• No behaviour change for existing fits with the default config — the only registered latent ships off-by-default, so LATENT_KEYS is [] and compute_latent_variables returns (). The latent pipeline runs but produces no output, matching today's behaviour.
• When the latent is enabled (user-edited yaml), AnalysisImaging instances produce latent.csv / latent_summary.json outputs containing total_galaxy_0_flux_mujy columns, provided the user also passes magzero via AnalysisImaging(..., magzero=<value>). If magzero is absent when the latent is enabled, the computation raises ValueError loudly (no silent NaN).

Migration

None required. Existing code continues to work unchanged. To opt into the new latent: set total_galaxy_0_flux_mujy: true in your workspace's config/latent.yaml and pass magzero when constructing AnalysisImaging.

For the follow-up workspace tutorial: workspaces should mirror autogalaxy/config/latent.yaml into <workspace>/config/latent.yaml so users have a clear opt-in surface.

🤖 Generated with Claude Code