coronalyze.core.modeling
========================

.. py:module:: coronalyze.core.modeling

.. autoapi-nested-parse::

   Forward modeling tools for injecting synthetic sources.

   Provides utilities for fake planet injection and simple disk generation
   for throughput estimation and contrast curve calculations.



Functions
---------

.. autoapisummary::

   coronalyze.core.modeling.inject_planet
   coronalyze.core.modeling.make_simple_disk
   coronalyze.core.modeling.subtract_star
   coronalyze.core.modeling.subtract_disk


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

.. py:function:: inject_planet(image, psf_template, flux, pos, order = 3)

   Inject a fake planet into an image using cubic spline shifts.

   The PSF template is shifted from the image center to the target position
   with sub-pixel precision, scaled by the flux, and added to the image.

   Args:
       image: 2D image to inject into, shape (ny, nx).
       psf_template: 2D PSF template centered at image center, same shape as image.
       flux: Flux scaling factor for the injected planet.
       pos: Target position (y, x) in pixels.
       order: Interpolation order for sub-pixel shifting (default: 3 = cubic).

   Returns:
       Image with injected planet, same shape as input.


.. py:function:: make_simple_disk(shape, radius, inclination_deg, width, flux = 1.0, pa_deg = 0.0)

   Generate a simple, optically thin Gaussian ring/disk.

   Analytically projects the disk to avoid interpolation artifacts.
   Flux is normalized so the total integrated flux equals the specified value.

   Args:
       shape: Output image shape (ny, nx).
       radius: Ring radius in pixels.
       inclination_deg: Disk inclination (0 = face-on, 90 = edge-on).
       width: Gaussian width (sigma) of the ring in pixels.
       flux: Total integrated flux of the disk. Default 1.0.
       pa_deg: Position angle of major axis, measured East of North (degrees).

   Returns:
       2D disk image with total flux normalized to the specified value.


.. py:function:: subtract_star(science, star_model, scale = 1.0)

   Subtract stellar PSF model from observation.

   This is the fundamental operation for "perfect" RDI when you have
   a noiseless stellar PSF expectation (e.g., from coronagraphoto).

   Args:
       science: Observed image (electrons).
       star_model: Noiseless stellar PSF expectation (electrons).
       scale: Multiplicative scaling factor for the model before subtraction.
           Use values != 1.0 when the reference brightness differs from
           the science image (e.g., different exposure times or stellar flux).

   Returns:
       Residual image containing noise + planet signal.

   Example::

       residual = subtract_star(observation, star_expectation)
       # With scaling for brightness mismatch:
       residual = subtract_star(observation, star_expectation, scale=0.95)


.. py:function:: subtract_disk(residual, disk_model, scale = 1.0)

   Subtract disk model from residual image.

   Disk subtraction is typically a separate modeling task from stellar
   speckle subtraction. Call this after subtract_star when analyzing
   systems with circumstellar disks.

   Args:
       residual: Image after stellar subtraction (from subtract_star).
       disk_model: Disk model expectation (electrons).
       scale: Multiplicative scaling factor for the disk model.
           Adjust when disk model brightness doesn't match observation.

   Returns:
       Residual image with disk contribution removed.

   Example::

       # Two-step subtraction
       residual = subtract_star(observation, star_model)
       residual = subtract_disk(residual, disk_model)