coronalyze.pipelines.yield_pipeline
===================================

.. py:module:: coronalyze.pipelines.yield_pipeline

.. autoapi-nested-parse::

   Yield simulation pipelines for fast SNR calculation.

   Provides high-level workflows for yield estimation:

   - calculate_yield_snr: End-to-end subtraction + SNR calculation
   - klip_subtract: PCA/KLIP PSF subtraction

   For subtraction primitives, see coronalyze.core.modeling:
   - subtract_star, subtract_disk

   All functions are JIT-compiled and differentiable.



Functions
---------

.. autoapisummary::

   coronalyze.pipelines.yield_pipeline.klip_subtract
   coronalyze.pipelines.yield_pipeline.calculate_yield_snr


Module Contents
---------------

.. py:function:: klip_subtract(science, reference_cube, n_modes = 5)

   KLIP/PCA PSF subtraction.

   Uses PCA to build a stellar PSF model from a reference cube
   (e.g., images at different roll angles) and subtracts it.

   This is the most physically realistic stellar subtraction mode
   but also the slowest.

   Args:
       science: Science observation (electrons).
       reference_cube: Reference library of shape (n_frames, ny, nx).
           Typically star-only images at different roll angles.
       n_modes: Number of PCA modes to use for subtraction.

   Returns:
       Residual image after KLIP subtraction.

   Example::

       # ADI with KLIP
       residual = klip_subtract(science, roll_cube, n_modes=10)
       # If you also need disk subtraction, do it after:
       residual = subtract_disk(residual, disk_model)


.. py:function:: calculate_yield_snr(science, planet_positions, fwhm, star_model = None, disk_model = None, reference_cube = None, n_modes = 5, method = 'star', star_scale = 1.0, disk_scale = 1.0, exclusion_buffer = 0.5, validity_map = None)

   End-to-end yield SNR calculation.

   Convenience function that performs subtraction and SNR calculation
   in one call. Selects the appropriate subtraction method based on
   the `method` argument.

   Args:
       science: Observed image (electrons).
       planet_positions: Planet positions as (N, 2) array of (y, x) coords.
       fwhm: PSF FWHM in pixels.
       star_model: Noiseless star expectation (required for 'star' method).
       disk_model: Optional noiseless disk expectation.
       reference_cube: Reference library for KLIP (required for 'klip'/'rdi').
       n_modes: Number of PCA modes (for klip method only).
       method: Subtraction method - "star", "rdi", or "klip".
       star_scale: Scaling factor for star model (default 1.0).
       disk_scale: Scaling factor for disk model (default 1.0).
       exclusion_buffer: Gap between test and reference apertures in units
           of angular step (default 0.5). Prevents PSF wing leakage.
       validity_map: Optional 2D mask (1=valid, 0=invalid) to exclude
           known companions, bad pixels, or edge regions.

   Returns:
       SNR values for each planet position.

   Example::

       # Fast yield calculation with static PSF
       snrs = calculate_yield_snr(
           science_image,
           planet_positions,
           fwhm=4.5,
           star_model=star_expectation,
           disk_model=disk_expectation,
           method="star"
       )