coronagraphoto.simulation#

Functions for running full simulations and processing sources.

Public API conventions:

<source>_rate(source, optical_path, *, ...) returns the noiseless per-pixel photo-electron rate on the detector for one source.
<source>_readout(source, optical_path, prng_key, *, ...) returns a noisy detector readout (photon Poisson + QE binomial) for one source.
system_rate(scene, optical_path, *, ...) sums every per-source rate map for a scene (the differentiable forward model).
system_readout(scene, optical_path, prng_key, *, ...) sums every per-source Poisson-realised readout for a scene.

All observation parameters (start_time_jd, exposure_time_s, wavelength_nm, bin_width_nm, telescope_pa_deg, ecliptic_lat_deg, solar_lon_deg) are kwarg-only. The convention keeps signatures discoverable when more parameters land later (IFS, multi-roll observations).

Functions#

`pre_coro_bin_processing`(flux, bin_center_nm, ...)	Process a bin through the pre-coro elements of the optical path.
`_resample_to_detector`(image_rate_coro, bin_center_nm, ...)	Resample a coronagraph-plane image onto the detector pixel grid.
`post_coro_bin_processing`(image_rate_coro, ...)	Process a bin through the post-coro elements of the optical path.
`star_rate`(star, optical_path, *, start_time_jd, ...)	Generate the star count rate on the detector.
`star_readout`(star, optical_path, prng_key, *, ...)	Process a star through the provided optical path.
`planet_rate`(planet, optical_path, *, start_time_jd, ...)	Generate the per-batch planet count rate on the detector.
`planet_readout`(planet, optical_path, prng_key, *, ...)	Process a per-batch Planet through the optical path.
`_convolve_quadrants`(flux, psf_datacube)	Convolve flux with a quarter-symmetric PSF datacube via fold-and-sum.
`disk_rate`(disk, optical_path, *, start_time_jd, ...)	Generate the disk count rate on the detector.
`disk_readout`(disk, optical_path, prng_key, *, ...)	Process a disk through the provided optical path.
`zodi_rate`(zodi, optical_path, *, start_time_jd, ...)	Generate the zodi count rate on the detector.
`zodi_readout`(zodi, optical_path, prng_key, *, ...)	Process a zodi source through the provided optical path.
`system_rate`(scene, optical_path, *, start_time_jd, ...)	Sum of deterministic per-source count rates for a `Scene`.
`system_readout`(scene, optical_path, prng_key, *, ...)	Simulate a full `Scene` through the optical path.

Module Contents#

coronagraphoto.simulation.pre_coro_bin_processing(flux, bin_center_nm, bin_width_nm, optical_path)[source]#: Process a bin through the pre-coro elements of the optical path.

coronagraphoto.simulation._resample_to_detector(image_rate_coro, bin_center_nm, optical_path)[source]#

Resample a coronagraph-plane image onto the detector pixel grid.

Pipeline geometry, not detector hardware: needs the coronagraph’s plate scale (lambda/D / px), the detector’s plate scale (arcsec/px), the wavelength, and the primary diameter to convert lambda/D to arcsec.

coronagraphoto.simulation.post_coro_bin_processing(image_rate_coro, bin_center_nm, optical_path)[source]#: Process a bin through the post-coro elements of the optical path.

coronagraphoto.simulation.star_rate(star, optical_path, *, start_time_jd, wavelength_nm, bin_width_nm)[source]#: Generate the star count rate on the detector.

coronagraphoto.simulation.star_readout(star, optical_path, prng_key, *, start_time_jd, exposure_time_s, wavelength_nm, bin_width_nm)[source]#: Process a star through the provided optical path.

coronagraphoto.simulation.planet_rate(planet, optical_path, *, start_time_jd, wavelength_nm, bin_width_nm, telescope_pa_deg, star, trig_solver)[source]#

Generate the per-batch planet count rate on the detector.

Operates on a single skyscapes.scene.Planet (which internally batches K planets sharing the same atmosphere class). The Python loop over a heterogeneous System.planets tuple lives in system_readout(); this function stays inside the per-Planet-type JIT cache boundary (see brain/Planet Loop Architecture.md).

coronagraphoto.simulation.planet_readout(planet, optical_path, prng_key, *, start_time_jd, exposure_time_s, wavelength_nm, bin_width_nm, telescope_pa_deg, star, trig_solver)[source]#: Process a per-batch Planet through the optical path.

coronagraphoto.simulation._convolve_quadrants(flux, psf_datacube)[source]#

Convolve flux with a quarter-symmetric PSF datacube via fold-and-sum.

Handles padding dynamically to ensure all quadrants match the shape of the first quadrant (which defines the PSF datacube shape).

coronagraphoto.simulation.disk_rate(disk, optical_path, *, start_time_jd, wavelength_nm, bin_width_nm, telescope_pa_deg, star, incl_deg, pa_deg)[source]#

Generate the disk count rate on the detector.

Disks return CONTRAST (dimensionless flux ratio relative to the host star); we multiply by star.spec_flux_density here to convert to photon flux density per pixel before resampling and PSF convolution.

incl_deg / pa_deg are the disk’s intrinsic orientation in the sky frame; telescope_pa_deg is the telescope’s roll. The disk is rendered at its intrinsic geometry, then resample_flux rotates the rendered image by -telescope_pa_deg into the detector frame.

Raises:

ValueError: if optical_path.coronagraph.psf_datacube is: None.

coronagraphoto.simulation.disk_readout(disk, optical_path, prng_key, *, start_time_jd, exposure_time_s, wavelength_nm, bin_width_nm, telescope_pa_deg, star, incl_deg, pa_deg)[source]#

Process a disk through the provided optical path.

incl_deg / pa_deg are the disk’s intrinsic sky-frame orientation; system_readout pulls them from scene.system.midplane_inc_deg / midplane_pa_deg so every disk component in the System renders at the same midplane.

coronagraphoto.simulation.zodi_rate(zodi, optical_path, *, start_time_jd, wavelength_nm, bin_width_nm, ecliptic_lat_deg, solar_lon_deg)[source]#

Generate the zodi count rate on the detector.

Treats zodi as a spatially uniform surface-brightness source. The coronagraph’s sky transmission map sets the per-pixel attenuation; no PSF convolution is needed (a flat field convolved with any normalised PSF returns itself).

Parameters:: zodi (skyscapes.background.Zodi)

coronagraphoto.simulation.zodi_readout(zodi, optical_path, prng_key, *, start_time_jd, exposure_time_s, wavelength_nm, bin_width_nm, ecliptic_lat_deg, solar_lon_deg)[source]#

Process a zodi source through the provided optical path.

Parameters:: zodi (skyscapes.background.Zodi)

coronagraphoto.simulation.system_rate(scene, optical_path, *, start_time_jd, wavelength_nm, bin_width_nm, telescope_pa_deg, ecliptic_lat_deg, solar_lon_deg)[source]#

Sum of deterministic per-source count rates for a Scene.

The differentiable companion to system_readout(). Returns the total rate map (electrons/s/pixel, no Poisson noise, no QE multiply) summing star, every planet, the optional disk, and the optional zodi. Use this for likelihood evaluation, retrievals, or any inference loop that needs gradients through the full forward model.

coronagraphoto.simulation.system_readout(scene, optical_path, prng_key, *, start_time_jd, exposure_time_s, wavelength_nm, bin_width_nm, telescope_pa_deg, ecliptic_lat_deg, solar_lon_deg)[source]#

Simulate a full Scene through the optical path.

Sums per-source detector readouts. Each source consumes its own independent PRNG subkey (see jax.random best practices).

The Python loop over scene.system.planets is intentionally unjitted – it orchestrates JIT-cached per-Planet-type kernels (see brain/Planet Loop Architecture.md). The expensive math is inside each planet_readout call, not the loop.