yippy.performance

yippy.performance#

Coronagraph performance metric computation.

This module provides standalone functions for computing coronagraph performance curves: throughput, raw contrast, core area, occulter transmission, and core mean intensity. Each metric has its own compute function for clarity, plus a compute_all_performance_curves orchestrator.

All functions operate on a Coronagraph instance passed as the first argument, keeping the Coronagraph class itself slim while preserving backward-compatible delegation methods on it.

Classes#

OffAxisPosition

Data for a single off-axis PSF position along the performance axis.

Functions#

_iter_xaxis_positions(coro)

Yield OffAxisPosition for each valid x-offset (y ~= 0).

_collect_and_sort(separations, values)

Convert lists to sorted arrays by separation.

_point_source_in_image(pos)

Return True if the nominal point-source pixel lies inside the PSF image.

_oversample_psf(psf, pixel_scale_arcsec, oversample)

Oversample a PSF using flux-conserving resampling.

_threshold_mask(psf_os, trunc_ratio)

Create boolean mask of pixels exceeding trunc_ratio * peak.

_compute_iwa_owa(coro, sep, throughput)

Compute IWA and OWA from throughput curve, storing on coro.

compute_radial_average(image, pixel_scale_value[, ...])

Compute radial average of a 2D image.

plot_performance_curve(x, y, title, xlabel, ylabel[, ...])

Plot a single performance curve.

compute_throughput_curve(coro[, aperture_radius_lod, ...])

Compute coronagraph throughput vs separation.

compute_raw_contrast_curve(coro[, stellar_diam, ...])

Compute raw contrast curve vs separation.

compute_core_area_curve(coro[, aperture_radius_lod, ...])

Compute core area vs separation.

compute_truncation_throughput_curve(coro[, ...])

Compute throughput using a PSF-truncation-ratio aperture.

compute_truncation_core_area_curve(coro[, ...])

Compute core area using a PSF-truncation-ratio aperture.

compute_occ_trans_curve(coro)

Compute occulter (sky) transmission curve.

compute_core_mean_intensity_curve(coro[, ...])

Compute core mean intensity curves for different stellar diameters.

_build_perf_interps(coro, sep, throughput, ...)

Assign throughput, contrast, and core area spline interpolators to coro.

compute_all_performance_curves(coro[, ...])

Compute (or load) all coronagraph performance curves.

Module Contents#

class yippy.performance.OffAxisPosition[source]#

Data for a single off-axis PSF position along the performance axis.

separation: float#
psf: numpy.ndarray#
px: int#
py: int#
yippy.performance._iter_xaxis_positions(coro)[source]#

Yield OffAxisPosition for each valid x-offset (y ~= 0).

Iterates over each valid x-offset position along the performance-curve axis. All native YIP offsets are included, even those where the nominal point-source location lies outside the image, because the truncation-ratio throughput remains meaningful as long as the translated PSF retains significant in-image power.

Parameters:

coro (yippy.coronagraph.Coronagraph)

yippy.performance._collect_and_sort(separations, values)[source]#

Convert lists to sorted arrays by separation.

Parameters:
Return type:

tuple[numpy.ndarray, numpy.ndarray]

yippy.performance._point_source_in_image(pos)[source]#

Return True if the nominal point-source pixel lies inside the PSF image.

Parameters:

pos (OffAxisPosition)

Return type:

bool

yippy.performance._oversample_psf(psf, pixel_scale_arcsec, oversample)[source]#

Oversample a PSF using flux-conserving resampling.

Uses resample_flux from hwoutils which converts to surface brightness before interpolation and back to integrated flux after, guaranteeing per-pixel flux accuracy.

Args:

psf: 2D PSF image. pixel_scale_arcsec: Pixel scale of the input PSF (lam/D per pixel). oversample: Oversampling factor.

Returns:

Oversampled PSF with flux conserved and negative values clamped.

Parameters:
Return type:

numpy.ndarray

yippy.performance._threshold_mask(psf_os, trunc_ratio)[source]#

Create boolean mask of pixels exceeding trunc_ratio * peak.

Falls back to peak-only mask if no pixels exceed the threshold.

Parameters:
Return type:

numpy.ndarray

yippy.performance._compute_iwa_owa(coro, sep, throughput)[source]#

Compute IWA and OWA from throughput curve, storing on coro.

Parameters:
Return type:

None

yippy.performance.compute_radial_average(image, pixel_scale_value, center=None, nbins=None)[source]#

Compute radial average of a 2D image.

Thin wrapper around hwoutils.radial.radial_profile() for backward compatibility.

Args:

image: 2D numpy array. pixel_scale_value: Pixel scale in lambda/D per pixel (float). center: (cy, cx) pixel coordinates of centre. Defaults to

image centre.

nbins: Number of radial bins. Defaults to floor(max_dim / 2).

Returns:

(separations_lod, radial_profile) - 1-D arrays.

Parameters:
Return type:

tuple[numpy.ndarray, numpy.ndarray]

yippy.performance.plot_performance_curve(x, y, title, xlabel, ylabel, marker='o-', log_scale=False, ms=4)[source]#

Plot a single performance curve.

yippy.performance.compute_throughput_curve(coro, aperture_radius_lod=0.7, oversample=2)[source]#

Compute coronagraph throughput vs separation.

Throughput is the fraction of the total flux (planet PSF normalised to 1) that lands inside a photometric aperture at each off-axis position.

Args:

coro: Coronagraph instance. aperture_radius_lod: Aperture radius in lam/D. oversample: Oversampling factor.

Returns:

(separations, throughputs) - sorted 1-D arrays.

Parameters:
Return type:

tuple[numpy.ndarray, numpy.ndarray]

yippy.performance.compute_raw_contrast_curve(coro, stellar_diam=0.0 * lod, aperture_radius_lod=0.7, oversample=2)[source]#

Compute raw contrast curve vs separation.

Contrast is the ratio of stellar flux to planet flux within the same photometric aperture at each off-axis position.

Args:

coro: Coronagraph instance. stellar_diam: Stellar angular diameter for the on-axis PSF. aperture_radius_lod: Aperture radius in lam/D. oversample: Oversampling factor.

Returns:

(separations, contrasts) - sorted 1-D arrays.

Parameters:
Return type:

tuple[numpy.ndarray, numpy.ndarray]

yippy.performance.compute_core_area_curve(coro, aperture_radius_lod=0.7, fit_gaussian=False, use_phot_aperture_as_min=False, oversample=2)[source]#

Compute core area vs separation.

The core area represents the effective area of the PSF core. If fit_gaussian is True a 2-D Gaussian is fitted to each PSF; otherwise a fixed circular aperture is used.

Args:

coro: Coronagraph instance. aperture_radius_lod: Aperture radius in lam/D. fit_gaussian: Whether to fit a 2-D Gaussian. use_phot_aperture_as_min: Use aperture area as a floor when fitting. oversample: Oversampling factor.

Returns:

(separations, core_areas) - sorted 1-D arrays, area in (lam/D)**2.

Parameters:
Return type:

tuple[numpy.ndarray, numpy.ndarray]

yippy.performance.compute_truncation_throughput_curve(coro, psf_trunc_ratio=0.5, oversample=None)[source]#

Compute throughput using a PSF-truncation-ratio aperture.

Instead of a fixed circular aperture, selects all pixels where the oversampled PSF exceeds psf_trunc_ratio * peak. Throughput is the sum of those pixels (after flux-conserving resampling). This matches the photap_frac calculation in AYO’s load_coronagraph.pro.

Args:

coro: Coronagraph instance. psf_trunc_ratio: Fraction of the PSF peak used as threshold

(e.g. 0.5 keeps all pixels > 50% of the peak).

oversample: Oversampling factor. None uses AYO’s rule:

ceil(pixscale / 0.05).

Returns:

(separations, throughputs) - sorted 1-D arrays.

Parameters:
Return type:

tuple[numpy.ndarray, numpy.ndarray]

yippy.performance.compute_truncation_core_area_curve(coro, psf_trunc_ratio=0.5, oversample=None)[source]#

Compute core area using a PSF-truncation-ratio aperture.

The core area is the solid angle (in (lam/D)**2) of all oversampled pixels that exceed psf_trunc_ratio * peak. This matches AYO’s omega_lod calculation.

Args:

coro: Coronagraph instance. psf_trunc_ratio: Fraction of PSF peak used as threshold. oversample: Oversampling factor. None uses AYO’s rule.

Returns:

(separations, core_areas) - sorted 1-D arrays, area in (lam/D)^2.

Parameters:
Return type:

tuple[numpy.ndarray, numpy.ndarray]

yippy.performance.compute_occ_trans_curve(coro)[source]#

Compute occulter (sky) transmission curve.

This is the radial profile of the sky transmission mask.

Args:

coro: Coronagraph instance.

Returns:

(separations_lod, occ_trans) - 1-D arrays.

Parameters:

coro (yippy.coronagraph.Coronagraph)

Return type:

tuple[numpy.ndarray, numpy.ndarray]

yippy.performance.compute_core_mean_intensity_curve(coro, stellar_diam_values=None)[source]#

Compute core mean intensity curves for different stellar diameters.

Args:

coro: Coronagraph instance. stellar_diam_values:

List of stellar diameters. None -> use all available.

Returns:

(separations_lod, intensities_dict) where intensities_dict maps each stellar diameter to its radial intensity profile.

Parameters:

coro (yippy.coronagraph.Coronagraph)

Return type:

tuple[numpy.ndarray, dict]

yippy.performance._build_perf_interps(coro, sep, throughput, raw_contrast, sep_ca, core_area, interp_order)[source]#

Assign throughput, contrast, and core area spline interpolators to coro.

yippy.performance.compute_all_performance_curves(coro, aperture_radius_lod=0.7, stellar_diam=None, fit_gaussian_for_core_area=False, use_phot_aperture_as_min=False, oversample=2, save_to_fits=True, performance_file='coro_perf.fits', load_from_file=None, cache_dir=None, plot=False, psf_trunc_ratio=None, interp_order=1)[source]#

Compute (or load) all coronagraph performance curves.

Stores interpolators on coro. This is the main entrypoint called during Coronagraph.__init__. It delegates to the individual compute_* helpers above, builds spline interpolators, and computes IWA / OWA.

Returns a dict of all curve data for convenience.

Parameters:
Return type:

dict