Coronagraph (YIP) Guide#

During the LUVOIR and HabEx studies a standard “handshake” between coronagraph designers and yield modelers was created called a “Yield Input Package” or YIP (see the definition here). pyEDITH uses YIPs to represent coronagraphs and compute the necessary performance metrics.

Modeling the coronagraph#

A coronagraphic exposure time calculation needs various quantities to represent the coronagraph, primarily:

How much planet light reaches the detector
How big a photometric aperture to integrate it over
How much stellar leakage contaminates that aperture
How much extended-source emission (zodi, exozodi) gets through. All four of those quantities are calculated from the same underlying FITS files that compose a YIP.

To avoid repeated code pyEDITH uses yippy to read YIPs and calculate coronagraph performance metrics. pyEDITH’s CoronagraphYIP is a thin wrapper that calls yippy for the quantities below and exposes them in the form pyEDITH’s noise budget expects.

Finding a YIP#

yippy currently ships a minimal two-entry catalog of YIPs hosted as assets on a tagged GitHub release of the yippy repo. Long-term YIP hosting will be provided by ExEP, and once that catalog comes online the discovery API will route through it. For now, browse the local catalog with yippy.list_yips(), or view the rendered table on the yippy datasets page. To pull a specific YIP, pass its catalog name to fetch_yip, which downloads the archive on first call and serves it from a local cache on subsequent calls.

from yippy import list_yips, fetch_yip

list_yips()                  # all available names (currently two)
list_yips(telescope="eac1")  # narrow by telescope, coronagraph, or sampling
yip_path = fetch_yip("eac1_aavc_2d")

For in-development YIPs that are not in the catalog, drop the YIP folder somewhere on disk and point the YIP_CORO_DIR environment variable at it. pyEDITH will pick it up when a coronagraph_type value matches the folder name (see Where the YIP comes from below).

Coronagraph quantities in the ETC#

These yippy outputs feed directly into pyEDITH’s exposure time calculation. Each link below points to the relevant documentation page for definitions and examples.

Photometric aperture throughput (yippy_obj.throughput_map()): fraction of planet light captured in the photometric aperture at each separation, set by psf_trunc_ratio (default 0.3 captures the off-axis PSF down to 30% of its peak). See Core Throughput.
Photometric aperture solid angle, \(\Omega\) (yippy_obj.core_area_map()): size of the aperture, in \((\lambda/D)^2\). Also set by psf_trunc_ratio, and used to convert background surface brightness (zodi, exozodi) into a count rate. See Spatial Metrics and Backgrounds.
Stellar intensity at the planet location, \(I_*\) (yippy_obj.core_mean_intensity_map(stellar_diam) for the fast radially-averaged form, or yippy_obj.stellar_intens(stellar_diam) for the full 2D map): residual starlight leaking through the coronagraph, which sets the stellar speckle background. See Stellar Leakage and Contrast.
Sky transmission map (yippy_obj.sky_trans()): throughput for extended emission as a function of position, multiplied into zodi and exozodi count rates so they pick up the coronagraph mask geometry.
Separation grid (yippy_obj.separation_map()): radial separation in \(\lambda/D\) at every pixel, used to evaluate the maps above at the planet’s position.
YIP header geometry (yippy_obj.header): pixel scale, image size, and occulter center. Used to map between pixel space and \(\lambda/D\) for the rest of the pipeline.

CoronagraphYIP exposes these as numpy arrays on the configured observatory, and from that point on the exposure time calculator does not need to know that yippy exists.

Recommended pattern: load once, pass everywhere#

The single biggest performance win is to construct a yippy.Coronagraph once and reuse it for every pyEDITH call. Re-loading a YIP from FITS for every target costs ~250 ms per call. Reusing a pre-loaded Coronagraph is ~21 ms per call (a ~12x speedup), and the exposure time is identical.

from yippy import Coronagraph, fetch_yip
from pyEDITH.components.coronagraphs import CoronagraphYIP

# Fetch the YIP (downloaded from the yippy GitHub release on first
# call, cached after).
# See https://yippy.readthedocs.io/en/latest/datasets.html for catalog.
yip_path = fetch_yip("eac1_aavc_2d")

# Build the yippy.Coronagraph once.
coro = Coronagraph(yip_path, psf_trunc_ratio=0.3)

# Pass it into pyEDITH for every target.
for target_params in catalog:
    coronagraph = CoronagraphYIP(yippy_coro=coro)
    # ... run pyEDITH using `coronagraph` ...

To switch psf_trunc_ratio mid-sweep without reloading from disk:

coro.set_psf_trunc_ratio(0.5)

Performance-curve results are cached to yippy_cache/performance/ and reused on subsequent calls with the same ratio. The trade-offs across different ratios are covered in Aperture Methods Comparison.

Other ways to initialize#

CoronagraphYIP can also be initialized with a path to a YIP directory, which is convenient for one-shot calls but reloads the YIP from FITS each time.

# Catalog name -- yippy downloads + caches the YIP for you.
coronagraph = CoronagraphYIP(path=fetch_yip("eac1_aavc_2d"))

# A folder on disk (e.g. an in-development YIP not in the catalog).
coronagraph = CoronagraphYIP(path="/path/to/yip")

For loops, prefer the pre-constructed Coronagraph pattern shown above.

Where the YIP comes from#

When you build an Observatory with create_observatory, the coronagraph_type field controls how the YIP is loaded. pyEDITH resolves it in this priority order:

Pre-constructed yippy.Coronagraph object. If you have already built a Coronagraph and want to reuse it across many targets, pass the object directly. See Recommended pattern above for why this is preferred.
Direct path on disk. A coronagraph_type value that resolves to an existing directory is loaded as a YIP.
YIP_CORO_DIR lookup. A bare name is joined with the YIP_CORO_DIR environment variable and checked next. Use this for in-development YIPs that are not in the yippy catalog.
Remote fetch via yippy. As a last resort, the name is passed to yippy.fetch_yip, which downloads the YIP from the yippy repo’s GitHub release assets and caches it locally. Browse names with yippy.list_yips() or the yippy datasets page.

Coronagraph (YIP) Guide

Contents