Skip to content

PSF

Effective-PSF and extended-PSF construction helpers.

robust_combine(stack, *, weight=None, method='clipped_mean', combine_kappa=3.0, combine_max_iter=5) builtin

Robustly combine an aligned (N, h, w) stack along the stamp axis with sign-agnostic outlier rejection.

A pure cross-N reducer: the caller passes an already-aligned native stack plus the complete per-pixel weight. Used for the extended-PSF native wing stack.

Parameters:

Name Type Description Default
stack ndarray

(N, h, w) caller-aligned native stamp stack, dtype float32 or float64. Determines the dtype channel; weight must match. Non-finite samples are excluded.

 required
weight ndarray

(N, h, w) complete per-pixel weight (valid * 1/sigma^2 * ..., formed by the caller). None is equal weight. A sample with non-finite or non-positive weight is excluded. Default None.

 None
method (clipped_mean, median)

clipped_mean is a symmetric sigma-clipped inverse-variance weighted mean; median is the unweighted median of the inclusion-gated samples. Default "clipped_mean".

 "clipped_mean"
combine_kappa float

clipped_mean clip threshold in robust sigmas. Must be > 0. Ignored for median. Default 3.0.

 3.0
combine_max_iter int

clipped_mean clip-iteration cap. Must be > 0. Ignored for median. Default 5.

 5

Returns:

Type Description
RobustCombined

Three (h, w) planes. A pixel with no surviving sample carries combined = NaN, weight = 0, count = 0 -- a per-pixel sentinel, not an error.

Raises:

Type Description
ValueError

If weight is given with a shape different from stack, if method is invalid, if method == "clipped_mean" with combine_kappa <= 0 or combine_max_iter == 0, or if an array has an unsupported dtype.

RobustCombined

Result of robust_combine: three (h, w) planes. A pixel with no surviving sample carries combined = NaN, weight = 0, count = 0 (passed through unchanged, never raised).

combined property

The combined value per pixel, shape (h, w), dtype float64. NaN for a no-survivor pixel.

count property

The number of surviving samples per pixel, shape (h, w), dtype uint32. 0 for a no-survivor pixel.

weight property

The effective combined weight per pixel (sum of surviving weights; equals count when weight was None), shape (h, w), dtype float64. 0 for a no-survivor pixel.

solve_flux_background(epsf, oversample, data, delta, *, weight=None) builtin

Solve the per-star (flux, background) at a fixed delta by an exact 2x2 weighted linear least squares (no iteration).

Parameters:

Name Type Description Default
epsf ndarray

(os*s, os*s) oversampled effective PSF model, dtype float64 (the model is always f64).

 required
oversample int

The oversample factor os; forced odd. s is recovered from epsf / os.

 required
data ndarray

(N, s, s) per-stamp detector data, dtype float32 or float64. Determines the dtype channel; weight must match.

 required
delta ndarray

(N, 2) fixed per-stamp sub-pixel offset, dtype float64.

 required
weight ndarray

(N, s, s) complete per-pixel weight, same dtype as data. None is equal weight. Default None.

 None

Returns:

Type Description
FluxBackground

(N,) flux / background / ok. An unsolved star carries NaN flux/background and ok = False -- a per-star sentinel, not an error.

Raises:

Type Description
ValueError

If epsf is not square, oversample is not odd, the epsf side is not a multiple of oversample, the derived s is even, the batch dimensions disagree, weight shape does not equal data, or an array has an unsupported dtype.

FluxBackground

Result of solve_flux_background: the per-star (flux, background) at the supplied fixed delta. An unsolved star carries flux = NaN, background = NaN, ok = False (passed through unchanged, never raised).

background property

(N,) per-star scalar background, dtype float64. NaN where ok = False.

flux property

(N,) per-star flux, dtype float64. NaN where ok = False.

ok property

(N,) per-star solvability, dtype bool. False means too few valid pixels or a singular 2x2 normal matrix.

build_epsf(data, delta_init, oversample, *, weight=None, psi_init=None, max_iter=50, tol=0.0001, step=1.0, residual_reweight='none', reweight_c=4.0, nuisance_max_iter=3, nuisance_tol=0.0001) builtin

Solve the core oversampled effective PSF from a caller-assembled stamp stack by projected-Landweber super-resolution, jointly refining the per-star nuisance table.

Parameters:

Name Type Description Default
data ndarray

(N, s, s) caller-assembled stamp stack (from build_stamp, scheme C), dtype float32 or float64. Determines the dtype channel; weight must match.

 required
delta_init ndarray

(N, 2) per-stamp delta initial value (from build_stamp; in-basin), dtype float64.

 required
oversample int

The oversample factor os; forced odd. s is recovered from the data stamp dimension.

 required
weight ndarray

(N, s, s) complete per-pixel base weight, same dtype as data. None is unit weight. The residual reweight multiplies an internal copy; this array is never mutated. Default None.

 None
psi_init ndarray

(os*s, os*s) warm-start psi, dtype float64. None triggers the internal seed. Default None.

 None
max_iter int

Outer SR iteration cap. Must be > 0. Default 50.

 50
tol float

‖Δpsi‖_rel < tol convergence threshold. Finite, > 0. Default 1e-4.

 0.0001
step float

Landweber relaxation (operator-norm adaptive, so 1.0 is a safe full step regardless of flux scale). Finite, > 0. Default 1.0.

 1.0
residual_reweight (none, huber, tukey)

Per-pixel residual M-estimator down-weighting. Symmetric / sign-agnostic. Default "none".

 "none"
reweight_c float

The Huber / Tukey transition in robust sigmas. Must be finite and > 0 for "huber" / "tukey". Ignored for "none". Default 4.0.

 4.0
nuisance_max_iter int

Per-round refine_nuisance inner-iteration cap. Must be > 0; 1 = one block-coordinate step. Default 3.

 3
nuisance_tol float

Per-round refine_nuisance ‖Δdelta‖ threshold. Finite, > 0. Default 1e-4.

 0.0001

Returns:

Type Description
BuildEpsf

The unit-volume-gauged epsf, the per-star flux / background / delta / ok, and the global iterations / converged. A star that cannot be solved carries the sentinel and ok = False -- a per-star sentinel, not an error.

Raises:

Type Description
ValueError

If oversample is not odd, the recovered s is even, the batch dimensions disagree, weight / psi_init shapes are wrong, any scalar parameter is invalid, residual_reweight is invalid, or an array has an unsupported dtype.

BuildEpsf

Result of build_epsf: the solved oversampled effective PSF plus the refined per-star table and the global fixed-point flags. A star that could not be solved carries the nuisance sentinel and ok = False (passed through unchanged, never raised).

background property

(N,) refined per-star scalar background, dtype float64. NaN where ok = False.

converged property

Global convergence: ‖Δpsi‖_rel < tol was reached strictly before max_iter (distinct from any per-star flag).

delta property

(N, 2) refined per-star centroid (delta_row, delta_col), dtype float64.

epsf property

(os*s, os*s) solved oversampled effective PSF, unit-volume gauged (sum(epsf) / os^2 = 1), dtype float64.

flux property

(N,) refined per-star flux, dtype float64. NaN where ok = False.

iterations property

Number of outer SR iterations actually run.

ok property

(N,) per-star usability, dtype bool. A False star did not enter the psi accumulate.

stitch_psf(core, oversample, wing, *, wing_confidence=None, match_radius=8.0, feather_width=4.0, ee_aperture_radius=15.0) builtin

Stitch a Phase-6 oversampled core and a native wing into a hybrid encircled-energy-normalized extended PSF. The core is not re-solved.

Parameters:

Name Type Description Default
core ndarray

(os*s, os*s) Phase-6 oversampled ePSF (unit-volume gauged), dtype float64 (the model is always f64).

 required
oversample int

The oversample factor os; forced odd. The core native edge s is recovered from core / os.

 required
wing ndarray

(H, W) native large-support robust wing, centered, H / W odd, dtype float64.

 required
wing_confidence ndarray

(H, W) per-pixel confidence (the robust_combine weight / count), dtype float64. Only weights the seam scalar match; not stored. None is uniform. Default None.

 None
match_radius float

Native-pixel core<->wing crossover (the feather ring center). Finite, > 0. Default 8.0.

 8.0
feather_width float

Native-pixel raised-cosine feather full width. Finite, > 0. Default 4.0.

 4.0
ee_aperture_radius float

Native-pixel circular aperture the result is encircled-energy normalized to (integral within == 1). Finite, > 0. Default 15.0.

 15.0

Returns:

Type Description
ExtendedPsf

The hybrid / multi-resolution extended PSF. A degenerate all-sentinel wing yields a pure-core EE-normalized result, not an error.

Raises:

Type Description
ValueError

If core is not square, oversample is not odd, the core side is not a multiple of oversample, the derived s is even, wing does not have odd dimensions, wing_confidence shape does not equal wing, the stitch params are infeasible, or an array has an unsupported dtype.

ExtendedPsf

The hybrid / multi-resolution extended PSF: an oversampled core plus a native wing plus the meta-info linking the two grids.

Sampling contract: recon(r) = f_core(r) * core_sample(r) + wing_sample(r) with the raised-cosine f_core = 1 - f_wing. The stored wing already has f_wing and the scalar match baked in (so it is ~0 in the core region); both planes are encircled-energy normalized.

core property

(os*s, os*s) oversampled core, EE-normalized, dtype float64.

ee_aperture_radius property

The native-pixel encircled-energy aperture radius.

feather_width property

The native-pixel feather full width.

match_radius property

The native-pixel core<->wing crossover radius.

oversample property

The oversample factor os (the meta-info linking the two grids).

wing property

(H, W) native wing: scalar-matched at match_radius, raised-cosine feathered (so ~0 in the core region), and EE-normalized, dtype float64.

build_extended_psf(wing_data, wing_delta, core, oversample, *, wing_weight=None, match_radius=8.0, feather_width=4.0, ee_aperture_radius=15.0, combine='clipped_mean', combine_kappa=3.0, combine_max_iter=5, scale_aperture_radius=6.0, scale_background_annulus=(18.0, 24.0)) builtin

Build the native wing from a bright-star stack (per-stamp robust sky + per-stamp scale + robust combine) and stitch it onto a Phase-6 core.

Parameters:

Name Type Description Default
wing_data ndarray

(M, H, W) caller-aligned bright-star large-support native stamps, dtype float32 or float64. Determines the dtype channel; wing_weight must match.

 required
wing_delta ndarray

(M, 2) bright-star build_stamp delta, dtype float64. Used only for integer re-centering bookkeeping (the sub-pixel part is intentionally not applied -- the wing is sky-dominated).

 required
core ndarray

(os*s, os*s) Phase-6 ePSF, dtype float64 (the core is not re-solved here).

 required
oversample int

The oversample factor os; forced odd.

 required
wing_weight ndarray

(M, H, W) complete per-pixel base weight, same dtype as wing_data. None is unit weight. Default None.

 None
match_radius float

Native-pixel core<->wing crossover. Finite, > 0. Default 8.0.

 8.0
feather_width float

Native-pixel raised-cosine feather full width. Finite, > 0. Default 4.0.

 4.0
ee_aperture_radius float

Native-pixel encircled-energy aperture radius. Finite, > 0. Default 15.0.

 15.0
combine (clipped_mean, median)

The robust_combine method for the cross-M wing stack. Default "clipped_mean".

 "clipped_mean"
combine_kappa float

clipped_mean clip threshold in robust sigmas. Must be > 0. Ignored for median. Default 3.0.

 3.0
combine_max_iter int

clipped_mean clip-iteration cap. Must be > 0. Ignored for median. Default 5.

 5
scale_aperture_radius float

Native-pixel aperture radius for the aperture-photometry fallback scale (used when the core solve is saturated). Finite, > 0. Default 6.0.

 6.0
scale_background_annulus tuple of (float, float)

Native-pixel (r_in, r_out) ring for the per-stamp robust sky. Finite, 0 <= r_in < r_out. Default (18.0, 24.0).

 (18.0, 24.0)

Returns:

Type Description
ExtendedPsfBuilt

The stitched ExtendedPsf plus the per-bright-star table. A star that cannot be calibrated carries star_ok = False -- a per-star sentinel, not an error.

Raises:

Type Description
ValueError

If core is not square, oversample is not odd, the core side is not a multiple of oversample, the derived s is even, wing_data does not have odd spatial dimensions, the batch dimensions disagree, wing_weight shape does not equal wing_data, any param is invalid, combine is invalid, or an array has an unsupported dtype.

ExtendedPsfBuilt

Result of build_extended_psf: the stitched ExtendedPsf plus the per-bright-star table. A star that cannot be calibrated carries star_ok = False and NaN scale/background (passed through unchanged, never raised).

extended property

The stitched hybrid extended PSF (an ExtendedPsf).

star_background property

(M,) per-stamp robust sky actually subtracted, dtype float64. NaN where star_ok = False.

star_flux property

(M,) per-stamp scale actually used (core-solve flux or aperture-photometry fallback), dtype float64. NaN where star_ok = False.

star_ok property

(M,) per-star usability, dtype bool. False means saturated and the aperture fallback was also unusable.

star_scale_from_core property

(M,) scale provenance, dtype bool: True = the core solve_flux_background, False = the aperture-photometry fallback. Meaningless where star_ok = False.