Noise Routines¶

Routines for simulating coronagraph model noise terms are listed below. These functions are used within the coronagraph.CoronagraphNoise and coronagraph.count_rates() functions, but are provided here for independent use.

The most important functions are the individual photon count rate terms due to different photon sources. This including photons from the planet cplan(), from zodiacal light czodi() and exo-zodiacal light cezodi(), from coronagraph speckles cspeck(), from dark current cdark() and read noise cread(), from thermal emission from the telescope mirror ctherm(), and from clock-induced charge ccic().

Optional ground-based telescope noise modeling includes extra terms for the emission from Earth’s atmosphere incident on the telescope, ctherm_earth() (also see get_sky_flux()), and an additional throughput term due to atmospheric extinction set_atmos_throughput().

Finally, there are some extra convenience functions: Calculate the fraction of Airy power contained in square or circular aperture using f_airy(); Construct a wavelength grid by specifying either a spectral resolving power or a fixed wavelength bandwidth using construct_lam(); Calculate the Lambertian Phase Function of a planet from the phase angle using lambertPhaseFunction(); Calculate the Planck blackbody radiance given temperature and wavelength using planck().

coronagraph.noise_routines.Fstar(lam, Teff, Rs, d, AU=False)¶

Stellar flux function

Parameters:	lam (float or array-like) – Wavelength [um] Teff (float) – Stellar effective temperature [K] Rs – Stellar radius [solar radii] d – Distance to star [pc] AU (bool, optional) – Flag that indicates d is in AU
Returns:	Fstar – Stellar flux [W/m**2/um]
Return type:	float or array-like

coronagraph.noise_routines.Fplan(A, Phi, Fstar, Rp, d, AU=False)¶

Planetary flux function

Parameters:	A (float or array-like) – Planetary geometric albedo Phi (float) – Planetary phase function Fstar (float or array-like) – Stellar flux [W/m*2/um] Rp (float) – Planetary radius [Earth radii] d (float) – Distance to star [pc] AU (bool, optional*) – Flag that indicates d is in AU
Returns:	Fplan – Planetary flux [W/m**2/um]
Return type:	float or array-like

coronagraph.noise_routines.FpFs(A, Phi, Rp, r)¶

Planet-star flux ratio (Equation 11 from Robinson et al. 2016).

\(\frac{{F}_{p,\lambda }}{{F}_{{\rm{s}},\lambda }}=A{\rm{\Phi }}(\alpha ){\left(\displaystyle \frac{{R}_{{\rm{p}}}}{r}\right)}^{2}\)

Parameters:	A (float or array-like) – Planetary geometric albedo Phi (float) – Planetary phase function Rp (float) – Planetary radius [Earth radii] r (float) – Planetary orbital semi-major axis [AU]
Returns:	FpFs – Planet-star flux ratio
Return type:	float or array-like

coronagraph.noise_routines.cstar(q, fpa, T, lam, dlam, Fstar, D)¶

Stellar photon count rate (not used with coronagraph)

Parameters:	q (float or array-like) – Quantum efficiency fpa (float) – Fraction of planetary light that falls within photometric aperture T (float) – Telescope and system throughput lam (float or array-like) – Wavelength [um] dlam (float or array-like) – Spectral element width [um] Fplan (float or array-like) – Planetary flux [W/m*2/um] D (float*) – Telescope diameter [m]
Returns:	cs – Stellar photon count rate [1/s]
Return type:	float or array-like

coronagraph.noise_routines.cplan(q, fpa, T, lam, dlam, Fplan, D)¶

Exoplanetary photon count rate (Equation 12 from Robinson et al. 2016)

\({c}_{{\rm{p}}}=\pi {{qf}}_{\mathrm{pa}}{ \mathcal T }\displaystyle \frac{\lambda }{{hc}}{F}_{{\rm{p}},\lambda }(d)\Delta \lambda {\left(\displaystyle \frac{D}{2}\right)}^{2}\)

Parameters:	q (float or array-like) – Quantum efficiency fpa (float) – Fraction of planetary light that falls within photometric aperture T (float) – Telescope and system throughput lam (float or array-like) – Wavelength [um] dlam (float or array-like) – Spectral element width [um] Fplan (float or array-like) – Planetary flux [W/m*2/um] D (float*) – Telescope diameter [m]
Returns:	cplan – Exoplanetary photon count rate [1/s]
Return type:	float or array-like

coronagraph.noise_routines.czodi(q, X, T, lam, dlam, D, Mzv, SUN=False, CIRC=False)¶

Zodiacal light count rate (Equation 15 from Robinson et al. 2016)

\({c}_{{\rm{z}}}=\pi q{ \mathcal T }{\rm{\Omega }}\Delta \lambda \displaystyle \frac{\lambda }{{hc}}{\left(\displaystyle \frac{D}{2}\right)}^{2}\displaystyle \frac{{F}_{\odot ,\lambda }(1\;{\rm{AU}})}{{F}_{\odot ,V}(1\;{\rm{AU}})}\;{F}_{0,V}{10}^{-{M}_{{\rm{z}},V}/2.5}\)

Parameters:	q (float or array-like) – Quantum efficiency X (float) – Size of photometric aperture (lambda/D) T (float) – Telescope and system throughput lam (float or array-like) – Wavelength [um] dlam (float or array-like) – Spectral element width [um] D (float) – Telescope diameter [m] MzV (float) – Zodiacal light surface brightness [mag/arcsec2] SUN** (bool, optional) – Set to use solar spectrum (Not Implemented) CIRC (bool, optional) – Set to use a circular aperture
Returns:	czodi – Zodiacal light photon count rate [1/s]
Return type:	float or array-like

coronagraph.noise_routines.cezodi(q, X, T, lam, dlam, D, r, Fstar, Nez, Mezv, SUN=False, CIRC=False)¶

Exozodiacal light count rate (Equation 18 from Robinson et al. 2016)

\({c}_{\mathrm{ez}} = \pi q{ \mathcal T }{X}^{2}\displaystyle \frac{{\lambda }^{4}}{4{hc}{ \mathcal R }}{\left(\displaystyle \frac{1{\rm{AU}}}{r}\right)}^{2}\displaystyle \frac{{F}_{{\rm{s}},\lambda }(1\;{\rm{AU}})}{{F}_{{\rm{s}},V}(1\;{\rm{AU}})}\\ \times \displaystyle \frac{{F}_{{\rm{s}},V}(1\;{\rm{AU}})}{{F}_{\odot ,V}(1\;{\rm{AU}})}{N}_{\mathrm{ez}}{F}_{0,V}{10}^{-{M}_{\mathrm{ez},V}/2.5}\)

Parameters:	q (float or array-like) – Quantum efficiency X (float) – Size of photometric aperture (lambda/D) T (float) – System throughput lam (float or array-like) – Wavelength [um] dlam (float or array-like) – Spectral element width [um] D (float) – Telescope diameter [m] r (float) – Planetary orbital semi-major axis [AU] Fstar (array-like) – Host star spectrum at 1 au (W/m2/um) Nez** (float) – Number of exozodis in exoplanetary disk MezV (float) – Exozodiacal light surface brightness [mag/arcsec2] SUN** (bool, optional) – Set to use solar spectrum (Not Implemented) CIRC (bool, optional) – Set to use a circular aperture
Returns:	cezodi – Exozodiacal light photon count rate [1/s]
Return type:	float or array-like

coronagraph.noise_routines.cspeck(q, T, C, lam, dlam, Fstar, D)¶

Speckle count rate (Equation 19 from Robinson et al. 2016)

\({c}_{\mathrm{sp}} = \pi q{ \mathcal T }C\Delta \lambda {F}_{{\rm{s}},\lambda }(d)\displaystyle \frac{\lambda }{{hc}}{\left(\displaystyle \frac{D}{2}\right)}^{2}\)

Parameters:	q (float or array-like) – Quantum efficiency T (float) – System throughput C (float, optional) – Coronagraph design contrast lam (float or array-like) – Wavelength [um] dlam (float or array-like) – Spectral element width [um] D (float) – Telescope diameter [m] Fstar (float or array-like) – Host star spectrum at distance of planet (TOA) [W/m**2/um]
Returns:	cspeck – Speckle photon count rate [1/s]
Return type:	float or array-like

coronagraph.noise_routines.cdark(De, X, lam, D, theta, DNhpix, IMAGE=False, CIRC=False)¶

Dark current photon count rate

Parameters:	De (float, optional) – Dark current [counts/s] X (float, optional) – Width of photometric aperture ( * lambda / diam) lam (float or array-like) – Wavelength [um] D (float) – Telescope diameter [m] theta – Angular size of lenslet or pixel [arcsec2] DNHpix** (float, optional) – Number of horizontal/spatial pixels for dispersed spectrum IMAGE (bool, optional) – Set to indicate imaging mode (not IFS) CIRC (bool, optional) – Set to use a circular aperture
Returns:	Dark current photon count rate (s**-1)
Return type:	cdark

coronagraph.noise_routines.cread(Re, X, lam, D, theta, DNhpix, Dtmax, IMAGE=False, CIRC=False)¶

Read noise count rate (assuming detector has a maximum exposure time)

Parameters:	Re (float or array-like) – Read noise counts per pixel X (float, optional) – Width of photometric aperture ( * lambda / diam) lam (float or array-like) – Wavelength [um] D (float) – Telescope diameter [m] theta – Angular size of lenslet or pixel [arcsec2] Dtmax** (float, optional) – Detector maximum exposure time [hours] IMAGE (bool, optional) – Set to indicate imaging mode (not IFS) CIRC (bool, optional) – Set to use a circular aperture
Returns:	cread – Read noise photon count rate (s**-1)
Return type:	float or array-like

coronagraph.noise_routines.ccic(Rc, cscene, X, lam, D, theta, DNhpix, Dtmax, IMAGE=False, CIRC=False)¶

Clock induced charge count rate

Parameters:	Rc (float or array-like) – Clock induced charge counts/pixel/photon cscene (float or array-like) – Photon count rate of brightest pixel in the scene [counts/s] X (float, optional) – Width of photometric aperture ( * lambda / diam) lam (float or array-like) – Wavelength [um] D (float) – Telescope diameter [m] theta – Angular size of lenslet or pixel [arcsec2] Dtmax** (float, optional) – Detector maximum exposure time [hours] IMAGE (bool, optional) – Set to indicate imaging mode (not IFS) CIRC (bool, optional) – Set to use a circular aperture
Returns:	Clock induced charge count rate [1/s]
Return type:	ccic

coronagraph.noise_routines.f_airy(X, CIRC=False)¶

Fraction of Airy power contained in square or circular aperture

Parameters:	X (float, optional) – Width of photometric aperture ( * lambda / diam) CIRC (bool, optional) – Set to use a circular aperture
Returns:	f_airy – Fraction of planetary light that falls within photometric aperture X*lambda/D
Return type:	float

coronagraph.noise_routines.ctherm(q, X, T, lam, dlam, D, Tsys, emis, CIRC=False)¶

Telescope thermal count rate

Parameters:	q (float or array-like) – Quantum efficiency X (float, optional) – Width of photometric aperture ( * lambda / diam) T (float) – System throughput lam (float or array-like) – Wavelength [um] dlam (float or array-like) – Spectral element width [um] D (float) – Telescope diameter [m] Tsys (float) – Telescope mirror temperature [K] emis (float) – Effective emissivity for the observing system (of order unity) CIRC (bool, optional) – Set to use a circular aperture
Returns:	ctherm – Telescope thermal photon count rate [1/s]
Return type:	float or array-like

coronagraph.noise_routines.ctherm_earth(q, X, T, lam, dlam, D, Itherm, CIRC=False)¶

Earth atmosphere thermal count rate

Parameters:	q (float or array-like) – Quantum efficiency X (float, optional) – Width of photometric aperture ( * lambda / diam) T (float) – System throughput lam (float or array-like) – Wavelength [um] dlam (float or array-like) – Spectral element width [um] D (float) – Telescope diameter [m] Itherm (float or array-like) – Earth thermal intensity [W/m2/um/sr] CIRC** (bool, optional) – Set to use a circular aperture
Returns:	cthe – Earth atmosphere thermal photon count rate [1/s]
Return type:	float or array-like

coronagraph.noise_routines.lambertPhaseFunction(alpha)¶

Calculate the Lambertian Phase Function from the phase angle,

\({{\rm{\Phi }}}_{{\rm{L}}}(\alpha )=\displaystyle \frac{\mathrm{sin}\alpha +(\pi -\alpha )\mathrm{cos}\alpha }{\pi }\)

Parameters:	alpha (float) – Planet phase angle [deg]
Returns:	Phi – Lambertian phase function
Return type:	float

coronagraph.noise_routines.construct_lam(lammin, lammax, Res=None, dlam=None)¶

Construct a wavelength grid by specifying either a resolving power (Res) or a bandwidth (dlam)

Parameters:

lammin (float) – Minimum wavelength [microns]
lammax (float) – Maximum wavelength [microns]
Res (float, optional) – Resolving power (lambda / delta-lambda)
dlam (float, optional) – Spectral element width for evenly spaced grid [microns]

Returns:

lam (float or array-like) – Wavelength [um]
dlam (float or array-like) – Spectral element width [um]

coronagraph.noise_routines.set_quantum_efficiency(lam, qe, NIR=False, qe_nir=0.9, vod=False)¶

Set instrumental quantum efficiency

Parameters:	lam (float or array-like) – Wavelength [um] qe (float) – Detector quantum efficiency NIR (bool, optional) – Use near-IR detector proporties q_nir (float, optional) – NIR quantum efficiency vod (bool, optional) – “Valley of Death” red QE parameterization from Robinson et al. (2016)
Returns:	q – Wavelength-dependent instrumental quantum efficiency
Return type:	numpy.array

coronagraph.noise_routines.set_dark_current(lam, De, lammax, Tdet, NIR=False, De_nir=0.001)¶

Set dark current grid as a function of wavelength

Parameters:	lam (array-like) – Wavelength grid [microns] De (float) – Dark current count rate per pixel (s-1) lammax** (float) – Maximum wavelength Tdet (float) – Detector Temperature [K] NIR (bool, optional) – Use near-IR detector proporties De_nir (float, optional) – NIR minimum dark current count rate per pixel
Returns:	De – Dark current as a function of wavelength
Return type:	numpy.array

coronagraph.noise_routines.set_read_noise(lam, Re, NIR=False, Re_nir=2.0)¶

Set read noise grid as a function of wavelength

Parameters:	lam (array-like) – Wavelength grid [microns] Re (float) – Read noise counts per pixel (s-1) NIR** (bool, optional) – Use near-IR detector proporties Re_nir (float, optional) – NIR read noise counts per pixel
Returns:	Re – Read noise as a function of wavelength
Return type:	numpy.array

coronagraph.noise_routines.set_lenslet(lam, lammin, diam, X, NIR=True, lammin_nir=1.0)¶

Set the angular size of the lenslet

Parameters:	lam (ndarray) – Wavelength grid lammin (float) – Minimum wavelength diam (float) – Telescope Diameter [m] X (float) – Width of photometric aperture (`lambda/diam`) NIR* (bool (optional)) – Use near-IR detector proporties lammin_nir (float (optional)) – Wavelength min to use for NIR lenslet size
Returns:	theta – Angular size of lenslet
Return type:	numpy.array

coronagraph.noise_routines.set_throughput(lam, Tput, diam, sep, IWA, OWA, lammin, FIX_OWA=False, SILENT=False)¶

Set wavelength-dependent telescope throughput such that it is zero inside the IWA and outside the OWA.

Parameters:	lam (ndarray) – Wavelength grid Tput (float) – Throughput diam (float) – Telescope diameter [m] sep (float) – Planet-star separation in radians IWA (float) – Inner working angle OWA (float) – Outer working angle lammin (float) – Minimum wavelength SILENT (bool, optional) – Suppress printing
Returns:	T – Wavelength-dependent throughput
Return type:	numpy.array

coronagraph.noise_routines.set_atmos_throughput(lam, dlam, convolve, plot=False)¶

Use pre-computed Earth atmospheric transmission to set throughput term for radiation through the atmosphere

Parameters:	lam (ndarray) – Wavelength grid dlam (ndarray) – Wavelength bin width grid convolve (func) – Function used to degrade/downbin spectrum
Returns:	Tatmos – Atmospheric throughput as a function of wavelength
Return type:	numpy.array

coronagraph.noise_routines.get_sky_flux()¶

Get the spectral flux density from the sky viewed at a ground-based telescope an an average night. This calculation comes from ESO SKYCALC and includes contributions from molecular emission of lower atmosphere, emission lines of upper atmosphere, and airglow/residual continuum, but neglects scattered moonlight, starlight, and zodi.

Returns:	lam_sky (numpy.array) – Wavelength grid [microns] flux_sky (numpy.array) – Flux from the sky [W/m^2/um]

coronagraph.noise_routines.exptime_element(lam, cp, cn, wantsnr)¶

Calculate the exposure time (in hours) to get a specified signal-to-noise

Parameters:	lam (ndarray) – Wavelength grid cp (ndarray) – Planetary photon count rate [s*-1] cn (ndarray) – Noise photon count rate [s-1] wantsnr* (float) – Signal-to-noise required in each spectral element
Returns:	DtSNR – Exposure time necessary to get specified SNR [hours]
Return type:	ndarray

coronagraph.noise_routines.planck(temp, wav)¶

Planck blackbody function

Parameters:	temp (float or array-like) – Temperature [K] wav (float or array-like) – Wavelength [microns]
Returns:
Return type:	B_lambda [W/m^2/um/sr]