feat: over/under-prediction policies for point-source pairing likelihoods

[Jammy2211]

Summary

Deliberate over/under-prediction handling for the point-source image-plane likelihoods (issue #585; PyAutoMind feature/cluster/10_solver_over_under_prediction.md). The audit on the issue found the model-fit default silently ignored extra model images and the Hungarian scheme actively rewarded under-predicting models (its own docstring carried an all-caps do-not-use warning about it).

API Changes

FitPositionsImagePairRepeat gains an unmatched_model_policy class attribute — "magnification_filter" (new default: extra model images with |μ| < magnification_threshold=0.1 are exempt per the demagnified-central observational convention, brighter extras add distance-to-nearest-observed penalty residuals), "penalize", "ignore" (the historical behaviour, now explicit) — plus a no_image_residual finite floor when the solver returns no images and an n_unmatched_model_positions diagnostic. FitPositionsImagePair (Hungarian) now penalizes unmatched observed positions instead of dropping them. Behaviour change: fits where the max-likelihood model over-predicts bright images or under-predicts will report (correctly) worse likelihoods than before; equal-count well-matched fits are numerically unchanged (regression-tested).
See full details below.

Test Plan

• 5 new regression tests: exact penalty values, policy switching via subclass, demagnified-central exemption (IsothermalSph), no-image finite floors (both schemes), Hungarian anti-reward with exact residuals.
• Full PyAutoLens suite: 358 pass.
• Workspace guide runs end-to-end demonstrating all three cases (companion PR).

Validation checklist (--auto run — in-session directives)

• Effective level: supervised (header: supervised, cap: feature → supervised); "continue --auto"; design defaults batched on feat: point-source over/under-prediction handling in pairing likelihoods + cluster guide #585 (override there if wanted); Heart-ack carried in-session
• Parallel-claim note: weak-small-datasets holds PyAutoLens (autolens/weak/ files) — disjoint from autolens/point/; re-verified at ship
• Human: is magnification_filter the right default (vs ignore preserving old numbers)?
• Human: merge, amend, or reject — then log the outcome

Full API Changes

Added

• FitPositionsImagePairRepeat.unmatched_model_policy (class attr, default "magnification_filter"), .magnification_threshold (0.1), .no_image_residual (1e4), .unmatched_model_mask, .unmatched_model_penalty_map, .n_unmatched_model_positions.
• FitPositionsImagePair.no_image_residual (1e4).

Changed Behaviour

• FitPositionsImagePairRepeat.chi_squared — adds the unmatched-model penalty term under non-ignore policies; unchanged when every model image is matched.
• FitPositionsImagePairRepeat.residual_map — vectorized; returns the no_image_residual floor when the solver yields no finite images (previously crashed/NaN'd).
• FitPositionsImagePair.residual_map — unmatched observed positions contribute distance-to-nearest-model residuals in data order (previously dropped, rewarding under-prediction); NaN model rows filtered; no-image floor.

Migration

• To reproduce pre-change likelihood values exactly: subclass with unmatched_model_policy = "ignore" and pass via AnalysisPoint(fit_positions_cls=...).

🤖 Generated with Claude Code