yippy.coronagraph

Base coronagraph class.

Classes

Coronagraph

Primary object for simulating a coronagraph.

Module Contents

class yippy.coronagraph.Coronagraph(yip_path, stellar_intens_file='stellar_intens.fits', stellar_diam_file='stellar_intens_diam_list.fits', offax_data_file='offax_psf.fits', offax_offsets_file='offax_psf_offset_list.fits', sky_trans_file='sky_trans.fits', x_symmetric=True, y_symmetric=True, use_quarter_psf_datacube=True, downsample_shape=None, aperture_radius_lod=0.7, contrast_floor=None, use_inscribed_diameter=False, psf_trunc_ratio=None, interp_order=1)

Primary object for simulating a coronagraph.

The Coronagraph object manages the coronagraph response for both on-axis and off-axis sources. It is primarily called with either :ref:pydata:Coronagraph.offax(x,y), to get the off-axis response at a given (x,y) offset from the star, or Coronagraph.stellar(r) to get the coronagraph response at a given stellar angular diameter r.

Parameters:

• yip_path (pathlib.Path)

• stellar_intens_file (str)

• stellar_diam_file (str)

• offax_data_file (str)

• offax_offsets_file (str)

• sky_trans_file (str)

• x_symmetric (bool)

• y_symmetric (bool)

• use_quarter_psf_datacube (bool)

• downsample_shape (tuple[int, int] | None)

• aperture_radius_lod (float)

• contrast_floor (float | None)

• use_inscribed_diameter (bool)

• psf_trunc_ratio (float | None)

• interp_order (int)

yip_path

name

aperture_radius_lod = 0.7

contrast_floor = None

psf_trunc_ratio = None

header

pixel_scale_arcsec = None

frac_obscured = None

use_inscribed_diameter = False

_diameter_ratio = 1.0

stellar_intens

offax

sky_trans

has_psf_datacube = False

use_quarter_psf_datacube = True

psf_shape

npixels

interp_order = 1

create_psf_datacube(batch_size=128)

Load the PSF datacube from a file or generate it if it doesn’t exist.

The PSF datacube is a 4D array of PSFs at each pixel (x psf offset, y psf offset, x, y). Given the computational cost of generating this datacube, it is only generated when needed and saved to a numpy binary file in the yip_path directory.

Args:

batch_size (int):

Number of PSFs to generate in each batch. Default is 128.

_create_psf_datacube_gpu(batch_size=128)

Generate PSF datacube on GPU/TPU, transferring each batch to host.

Uses vmap+jit (offax.create_psfs) instead of shard_map to avoid the CPU multi-device overhead that create_psfs_parallel carries. Each batch is copied to a pre-allocated host buffer immediately after synthesis, then np.save writes the final cube. The on-device accumulation + jnp.concatenate pattern is avoided because it silently corrupts output on some GPUs (Blackwell observed; A100 with broken CUDA12 plugin observed).

Args:

batch_size (int):

Number of PSFs to generate per batch. Default is 128.

__repr__()

String representation of the Coronagraph object.

property _cache_dir: pathlib.Path

Directory for all yippy-computed artifacts.

Return type:

pathlib.Path

property _datacube_cache_path: pathlib.Path

PSF datacube cache file, keyed by quarter/full and active float dtype.

Return type:

pathlib.Path

property _perf_dir: pathlib.Path

Directory for cached performance curve FITS files.

Return type:

pathlib.Path

_perf_filename()

Build a performance cache filename encoding the aperture mode.

Return type:

str

set_psf_trunc_ratio(ratio)

Switch PSF truncation ratio, recomputing only the affected curves.

Throughput and core area curves depend on the truncation ratio. Contrast, occulter transmission, and core mean intensity do not. Results are cached to yippy_cache/performance/ for reuse.

Args:

ratio: PSF truncation ratio (e.g. 0.3).

Parameters:

ratio (float)

Return type:

None

_compute_radial_average(image, center=None, nbins=None)

Compute radial average of a 2D image.

Deprecated since version Use: yippy.performance.compute_radial_average().

_plot_performance_curve(x, y, title, xlabel, ylabel, marker='o-', log_scale=False, ms=4)

Helper method to plot performance curves.

Deprecated since version Use: yippy.performance.plot_performance_curve().

compute_all_performance_curves(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)

Compute all coronagraph performance curves at once.

Delegates to yippy.performance.compute_all_performance_curves().

_compute_performance_metrics(stellar_diam=0.0 * lod, aperture_radius_lod=0.7, fit_gaussian_for_core_area=False, use_phot_aperture_as_min=False, oversample=2, compute_throughput=True, compute_contrast=True, compute_core_area=True)

Compute performance metrics.

Deprecated since version Use: individual functions in yippy.performance.

occulter_transmission_curve(plot=True)

Compute occulter transmission curve.

Delegates to yippy.performance.compute_occ_trans_curve().

core_mean_intensity_curve(stellar_diam_values=None, plot=True)

Compute core mean intensity curves.

Delegates to yippy.performance.compute_core_mean_intensity_curve().

_convert_separation_to_lod(separation)

Convert separation value(s) to lambda/D units (scalar or array).

Args:

separation (float, Quantity, or array-like):

The separation value(s), either as scalar(s) in lambda/D or Quantity.

Returns:

numpy.ndarray: The separation value(s) in lambda/D.

Raises:

ValueError: If the separation has units that are not lambda/D.

_is_scalar_input(sep_values, separation)

Check if the original input was scalar.

throughput(separation)

Return the throughput at the given separation(s).

Args:

separation: Separation(s) in lambda/D (float, Quantity, or array).

Returns:

float or numpy.ndarray: The throughput value(s).

raw_contrast(separation)

Return the raw contrast at the given separation(s).

Args:

separation: Separation(s) in lambda/D (float, Quantity, or array).

Returns:

float or numpy.ndarray: The raw contrast value(s).

noise_floor_exosims(separation, contrast_floor=1e-10, ppf=30.0)

Return the noise floor in EXOSIMS contrast convention.

Computes max(|raw_contrast|, floor) / ppf. The result is in contrast-normalized units (per-aperture, divided by throughput). EXOSIMS multiplies this by core_thruput to recover C_sr.

See Noise Floor Conventions for details.

Args:

separation: Separation(s) in lambda/D. contrast_floor (float): Minimum contrast value. Default is 1e-10. ppf (float): Post-processing factor. Default is 30.0.

Returns:

float or numpy.ndarray: Noise floor in EXOSIMS convention.

noise_floor_ayo(separation, ppf=30.0)

Return the noise floor in AYO/pyEDITH per-pixel convention.

Computes core_mean_intensity(sep) / ppf. The result is in per-pixel intensity units. AYO and pyEDITH multiply this by omega / pixscale**2 to get the per-aperture noise.

See Noise Floor Conventions for details.

Args:

separation: Separation(s) in lambda/D. ppf (float): Post-processing factor. Default is 30.0.

Returns:

float or numpy.ndarray: Noise floor in AYO/pyEDITH convention.

occulter_transmission(separation)

Return the occulter transmission at the given separation(s).

Args:

separation: Separation(s) in lambda/D.

Returns:

float or numpy.ndarray: The occulter transmission value(s).

core_area(separation)

Return the core area at the given separation(s).

Args:

separation: Separation(s) in lambda/D.

Returns:

float or numpy.ndarray: Core area in (lambda/D)^2.

core_mean_intensity(separation, stellar_diam=0.0 * lod)

Return core mean intensity at the given separation(s).

Interpolates over both separation and stellar angular diameter using a 2D RegularGridInterpolator when multiple diameters are available and a non-default diameter is requested. Uses the faster 1D spline for the default diameter (point source) or when the yield input package contains only one diameter.

Out-of-bounds queries on the 2D grid return NaN.

Args:

separation: Separation(s) in lambda/D. stellar_diam: Stellar angular diameter (Quantity in lod

units, float in lod, or array-like). Default is 0.0*lod (point source).

Returns:

float or numpy.ndarray: Core mean intensity value(s).

separation_map()

Pixel-grid separations from the coronagraph center in lam/D.

Returns:

numpy.ndarray: (npix, npix) array of separations.

core_mean_intensity_map(stellar_diam=0.0 * lod)

Azimuthally averaged stellar intensity projected onto the pixel grid.

Equivalent to computing a radial profile of stellar_intens, fitting a 1D interpolator, and evaluating it at every pixel’s separation. This replaces the rotate-and-average approach with a faster, artifact-free result.

See Azimuthal Averaging of Stellar Intensity for the comparison.

Args:

stellar_diam: Stellar angular diameter. Default 0.0 lam/D.

Returns:

numpy.ndarray: (npix, npix) core mean intensity values.

noise_floor_ayo_map(ppf=30.0, stellar_diam=0.0 * lod)

Noise floor in AYO/pyEDITH per-pixel convention on the pixel grid.

Computes core_mean_intensity_map / ppf.

Args:

ppf (float): Post-processing factor. Default 30.0. stellar_diam: Stellar angular diameter. Default 0.0 lam/D.

Returns:

numpy.ndarray: (npix, npix) noise floor values.

throughput_map(psf_trunc_ratios=None)

Throughput projected from the 1D curve onto the pixel grid.

Args:

psf_trunc_ratios (array-like or None):

If provided, returns a stacked (npix, npix, nratios) array with one slice per truncation ratio. Each ratio triggers a fresh performance computation. If None, uses the current throughput interpolator.

Returns:

numpy.ndarray: (npix, npix) or (npix, npix, nratios) throughput.

core_area_map(psf_trunc_ratios=None)

Core area (omega) projected from the 1D curve onto the pixel grid.

Args:

psf_trunc_ratios (array-like or None):

If provided, returns a stacked (npix, npix, nratios) array. If None, uses the current core_area interpolator.

Returns:

numpy.ndarray: (npix, npix) or (npix, npix, nratios) core area

in (lam/D)^2.

throughput_curve(aperture_radius_lod=0.7, oversample=1, plot=True)

Compute and optionally plot the throughput curve.

Delegates to yippy.performance.compute_throughput_curve().

raw_contrast_curve(stellar_diam=0 * lod, aperture_radius_lod=0.7, oversample=2, plot=True)

Compute and optionally plot the raw contrast curve.

Delegates to yippy.performance.compute_raw_contrast_curve().

core_area_curve(aperture_radius_lod=0.7, fit_gaussian=False, use_phot_aperture_as_min=False, oversample=2, plot=True)

Compute and optionally plot the core area curve.

Delegates to yippy.performance.compute_core_area_curve().

to_exosims(aperture_radius_lod=0.7, fit_gaussian_for_core_area=False, use_phot_aperture_as_min=False, units='LAMBDA/D')

Save performance curves in EXOSIMS format.

Delegates to yippy.export.export_exosims().

dump_ayo_csv(output_path, sep_min=0.125, sep_max=32.0, sep_step=0.25, contrast_floor=1e-10, ppf=30.0)

Export performance curves in AYO-compatible CSV format.

Delegates to yippy.export.export_ayo_csv().