feat: point-source over/under-prediction handling in pairing likelihoods + cluster guide

[Jammy2211]

Overview

Completes PyAutoMind feature/cluster/10_solver_over_under_prediction.md. The cluster/point-source image-plane likelihood needs deliberate behaviour when the model predicts more or fewer images than observed. Autonomy: supervised --auto (continuation of "do the next task --auto" / "continue --auto"); design decisions below proceed on the recommended defaults — override here if wanted.

Audit (deliverable 1 — complete)

Scheme	Under-prediction (n_model < n_obs)	Over-prediction (n_model > n_obs)
FitPositionsImagePair (Hungarian)	Rewarded — linear_sum_assignment pairs min(n,m); unmatched observed rows silently dropped, so χ² falls as images vanish. The source carries an all-caps warning to this effect (pair.py:19-22).	Extra model images unpaired; no penalty.
FitPositionsImagePairRepeat (model-fit default)	Soft penalty — every observed image pairs to its nearest surviving model image (pair_repeat.py residual = per-observed min distance). n_model = 0 / all-NaN edge worth a regression test.	Silent — extra model images are never selected by any observed image; a model spraying spurious images pays nothing.
FitPositionsImagePairAll (mixture)	Principled — each observed marginalizes over all model images (log-sum-exp); a missing image ⇒ low probability everywhere.	The 1/n_permutations = n_model^n_obs normalization is an Occam factor penalizing extra images, but weakly and undocumented; demagnified centrals still enter the mixture.

LensTool comparison (from its C source + published practice): unmatched observed images incur an explicit large χ² penalty; predicted-but-unobserved images are conventionally tolerated when demagnified ("below detection limit") and otherwise count against the model.

Design (deliverable 2 — recommended defaults, implementation proceeding)

1. FitPositionsImagePairRepeat gains an explicit over-prediction policy via an unmatched_model_policy constructor arg: "ignore" (today's behaviour, stated not silent), "penalize" (each model image not the nearest neighbour of any observed image adds its distance-to-nearest-observed as a residual — the symmetric Repeat term), "magnification_filter" (drop model images with |μ| below magnification_threshold before pairing — the LensTool "below detection limit" convention — then penalize remaining extras). Default: "magnification_filter" with the solver's existing magnification_threshold.
2. Under-prediction hard floor: when n_model < n_obs (after any filter), each observed image beyond the model's multiplicity adds a configurable large residual (default: distance to nearest model image — already Repeat's behaviour — plus a documented count in the fit's info); n_model == 0 returns -inf-safe large χ² rather than NaN (regression-tested).
3. FitPositionsImagePair (Hungarian): fix by adding the unmatched-observed penalty term (per unmatched observed row, residual = distance to nearest model image), replacing the warning; stays non-default.
4. FitPositionsImagePairAll: document the Occam normalization; no behaviour change.
5. Solver robustness: regression test + guide section showing a too-coarse solver grid masquerading as under-prediction (n_model vs grid resolution on the standard cluster model), anchored on the fresh profiling numbers (autolens_profiling#58: solve 0.32 s/call @ 200×200/0.7″).
6. Workspace guide autolens_workspace/scripts/guides/point_source_pairing.py: the three schemes, both mismatch directions, policy choice, solver settings at cluster scale, source-plane vs image-plane trade-offs, the precision-floor interaction (likelihood_sanity finding) — the reference the Lenstool example README links to.

Affected Repositories

• PyAutoLens (primary; parallel to the active weak-small-datasets claim — autolens/point/ disjoint from autolens/weak/)
• autolens_workspace (guide; parallel to weak-likelihood-function — scripts/guides/ disjoint from scripts/weak/)

Branch: feature/point-pairing-policies · Worktree: ~/Code/PyAutoLabs-wt/point-pairing-policies/

Original Prompt

Click to expand

$(cat PyAutoMind/feature/cluster/10_solver_over_under_prediction.md)

[Jammy2211]

Shipped to PR-open (library-first merge order): #586 → PyAutoLabs/autolens_workspace#248 (both pending-release ✓).

Implemented per the design on this issue: FitPositionsImagePairRepeat gains unmatched_model_policy (default magnification_filter — demagnified-central convention with |μ|<0.1 exemption; penalize/ignore alternatives via the class-attribute pattern), a finite no_image_residual floor, and the n_unmatched_model_positions diagnostic; the Hungarian FitPositionsImagePair no longer rewards under-prediction (its all-caps warning is retired). Guide at scripts/guides/point_source_pairing.py with runnable cases and the 'search source-plane, validate image-plane' workflow.

Gate record: 5 new regressions (exact values incl. the IsothermalSph demagnified-central exemption) + full suite 358 pass · guide end-to-end (case χ²: exempt central 0.0 / bright extra 15.21 / missing image 16.0) · navigator catalogue regenerated · review CLEAN (the 160 deletions = replaced docstrings + vectorized loops, test-covered) · parallel-claim disjointness vs the weak tasks re-verified · Heart-ack carried in-session.

One decision to confirm at merge (batched, default proceeded): magnification_filter as the default changes likelihood values for over/under-predicting models (correctly worse); ignore reproduces historical numbers via subclass. Merge stays with you.

[Jammy2211]

PRs #586 + autolens_workspace#248 merged — over/under-prediction policies live (magnification_filter default stands unless amended). Closing.