`castor_etc.telescope`

Telescope Utilities

The castor_etc.telescope package provides methods and classes to simulate and characterize telescope parameters.

Module Contents

Classes

Telescope

Telescope class containing the parameters of the imaging system.

Functions

`secant_method`	Finds the root of a function f using the secant method.
`bisection_method`	Finds the root of a function f using the bisection method.

Data

`_ds9heat`
`_ds9heat_cmap`

API

castor_etc.telescope._ds9heat = None

castor_etc.telescope._ds9heat_cmap = 'LinearSegmentedColormap(...)'

castor_etc.telescope.secant_method(f, x0, x1, tol=1e-06, max_iter=100): Finds the root of a function f using the secant method.

Parameters

f :: function that accepts 1 scalar parameter and returns 1 scalar Function for which to find the root.

x0 :: scalar The first initial guess for the root.

x1 :: scalar The second initial guess for the root.

tol :: scalar Absolute tolerance (i.e., accuracy) for the root.

max_iter :: int Maximum number of iterations.

Returns

result :: scalar The root of the function.

castor_etc.telescope.bisection_method(f, x0, x1, tol=1e-06, max_iter=100): Finds the root of a function f using the bisection method.

Parameters

f :: function that accepts 1 scalar parameter and returns 1 scalar Function for which to find the root.

x0 :: scalar The upper bound for the root. Note that f(x0) and f(x1) must have opposite signs.

x1 :: scalar The lower bound for the root. Note that f(x0) and f(x1) must have opposite signs.

tol :: scalar Absolute tolerance (i.e., accuracy) for the root.

max_iter :: int Maximum number of iterations.

Returns

result :: scalar The root of the function.

class castor_etc.telescope.Telescope(passbands=params.PASSBANDS, passband_limits=params.PASSBAND_LIMITS, passband_response_filepaths=params.PASSBAND_FILEPATHS, passband_response_fileunits=params.PASSBAND_FILEUNITS, passband_resolution=params.PASSBAND_RESOLUTION, passband_pivots=None, phot_zpts=None, phot_zpts_kwargs={'ab_mags': {'uv': [25.5, 23.5], 'u': [25.5, 23.5], 'g': [25.5, 23.5]}, 'method': 'secant', 'tol': 0.0002, 'max_iter': 100}, psf_filepaths=params.PSF_FILEPATHS, psf_supersample_factor=params.PSF_SUPERSAMPLE_FACTOR, fwhm=params.FWHM, px_scale=params.PX_SCALE, transit_fov=params.TRANSIT_FOV, ifov_dimen=params.IFOV_DIMEN, transit_ccd_dim=params.TRANSIT_CCD_DIMENSIONS, mp=params.MP, mirror_diameter=params.MIRROR_DIAMETER, dark_current=params.DARK_CURRENT, bias=params.BIAS, read_noise=params.READ_NOISE, gain=params.GAIN, redleak_thresholds=params.REDLEAK_THRESHOLDS, extinction_coeffs=params.EXTINCTION_COEFFS, show_warnings=True)

Telescope class containing the parameters of the imaging system.

Initialization

Create a Telescope instance.

Parameters

passbands :: list of str The telescope filter (i.e., passband) names. CASTOR passbands are “uv”, “u”, and “g”, but other passband names are allowed.

passband_limits :: dict of 2-element astropy.Quantity arrays Dictionary containing the lower and upper wavelength limits for each passband. Each element should be an astropy.Quantity array of length 2 (e.g., {"uv": [0.150, 0.300] * u.um, "u": [0.300, 0.400] * u.um, "g": [0.400, 0.550] * u.um]}).

passband_response_filepaths :: dict of str The absolute paths to the files containing the passband response curves. The files should be in ASCII format with the first column containing the wavelengths in passband_response_fileunits and the second column containing the passband response; the columns should be separated by a space. Lines starting with a hash (#) will be ignored. Note that the passband response values should account for quantum efficiency.

passband_response_fileunits :: dict of astropy.Quantity lengths The units of the wavelength columns in the passband response files.

passband_resolution :: astropy.Quantity length The desired linear interpolation resolution of the passband response curves.

passband_pivots :: dict of astropy.Quantity wavelengths or None The pivot wavelengths for each passband. If None, calculate the passband pivots based on the given passband limits and passband response files. Note that the passband pivots are calculating using the equal-energy (EE) convention, which should be correct for the AB magnitude system.

phot_zpts :: dict of int/float or None The photometric zero-points for each passband. If None, automatically calculate the photometric zero-points from the given passband response files (also see phot_zpts_kwargs). The photometric zero-point of a passband is defined as the AB magnitude which produces 1 electron/s in the passband.

phot_zpts_kwargs :: dict of kwargs The keyword arguments for finding the photometric zero-points via calc_phot_zpts(). Namely: ‘ab_mags’, ‘method’, ‘tol’, and ‘max_iter’. Following is a description of each parameter: - ab_mags :: dict of 2-element list of floats If method is “secant”, these are the two initial guesses for the photometric zero-point of each passband. If method is “bisection”, these are the lower and upper bounds for the photometric zero-points. Note that for the latter, the lower bound must produce < 1 electron/s and the upper bound must produce > 1 electron/s. - method :: “secant” or “bisection” The method to use for calculating the photometric zero-points. The secant method has faster convergence and does not depend on knowing upper/lower bounds for the photometric zero-point, but is not guaranteed to converge and you must provide two initial guesses for the zero-point. The bisection method has slower convergence and requires guessing the upper/lower limits for the zero-point, but is guaranteed to converge (given suitable upper/lower bounds) and does not require two good initial guesses. - tol :: float The desired accuracy of the photometric zero-points. - max_iter :: int The maximum number of iterations to use for finding each photometric zero point.

psf_filepaths :: dict of str The absolute paths to the FITS files containing the point spread functions (PSFs) for each of the telescope’s passbands. The FITS files should be 2D images at the same resolution as the telescope’s detectors (also see the px_scale parameter below). The value of a particular pixel should represent the flux contained within that pixel relative to the total flux. For example, a pixel value of 0.1 means that 10% of the flux from the source is contained within that pixel. The extent of the PSF images should be sufficiently large as to contain roughly 100% of the flux from a point source (i.e., pixel values should sum to 1). The default files are averaged 2D PSFs that are, strictly speaking, only valid for the center field of view.

psf_supersample_factor :: int The PSF oversampling factor, meaning each square pixel in the PSF file has a side length of px_scale / psf_supersample_factor (e.g., 0.1 arcsec / 20 = 0.005 arcsec).

fwhm :: astropy.Quantity angle The angular full-width at half-maximum of the telescope’s PSF (e.g., 0.15 arcsec).

px_scale :: astropy.Quantity angle The linear angle subtended by each square pixel in the detector (e.g., 0.1 arcsec). This will be used to calculate the solid angle subtended by each square pixel in the detector (e.g., 0.01 arcsec).

transit_fov :: astropy.Quantity angle Full width FoV in degree

ifov_dimen :: 2-element astropy.Quantity angle array The angular dimensions of the telescope’s instantaneous field of view (IFOV). This will be used to calculate the area covered by the telescope’s IFOV. Note that this must be an astropy.Quantity array (e.g., [0.44, 0.56] * u.deg), not a list of astropy.Quantity objects (not, e.g., [0.44 * u.deg, 0.56 * u.deg]). Not currently used for any calculations (other than calculating area of IFOV).

mp :: int or float The telescope detector’s number of megapixels (million pixels). Not currently used for any calculations.

transit_ccd_dim :: 2-element int list Dimensions of the CCD used for plotting gaia source and converts their ra,dec coordinates to (x,y) positions on the CCD

mirror_diameter :: astropy.Quantity length The diameter of the telescope’s primary circular mirror (e.g., 100 cm). This will be used to calculate the area of the primary mirror.

dark_current :: int or float The dark current of the telescope’s detector in electron/s/pixel. For example, at CASTOR’s operating temperature of 180 K, the dark current is ~1e-4 electron/s/pixel.

bias :: int or float The bias of the telescope’s detector in units of electron (e.g., 100 electrons). Not currently used for any calculations.

read_noise :: int or float The telescope detector’s read noise in units of electron/pixel (e.g., 2 electrons/pixel at high gain).

gain :: int or float The gain setting of the telescope’s detector in units of electron/ADU (e.g., 2.0 electrons/ADU). Not currently used for any calculations.

redleak_thresholds :: dict of astropy.Quantity wavelengths The redleak thresholds for each passband (e.g., {"uv": 3880 * u.AA, "u": 4730 * u.AA, "g": 5660 * u.AA}). Flux longward of the threshold is considered red leak.

extinction_coeffs :: dict of int/float The extinction coefficients (i.e., R := A/E(B-V)) for each passband.

show_warnings :: bool If True, print a warning when passband_limits, passband_response_filepaths, passband_response_fileunits, passband_pivots (if not None), phot_zpts (if not None), or redleak_thresholds contain keys that are not in passbands.

Attributes

passbands :: list of str The telescope filter (i.e., passband) names.

passband_limits :: dict of 2-element astropy.Quantity arrays Dictionary containing the lower and upper wavelength limits for each passband.

passband_resolution :: astropy.Quantity length The desired linear interpolation resolution of the passband response curves.

passband_pivots :: dict of astropy.Quantity wavelengths Dictionary containing the pivot wavelength of each passband.

phot_zpts :: dict of int/float Dictionary containing the photometric zero-point of each passband. The photometric zero-point of a passband is defined as the AB magnitude which produces 1 electron/s in the passband.

psfs :: dict of 2D numpy.ndarray The point spread functions (PSFs) for each of the telescope’s passbands. The value of a particular pixel (i.e., entry in the 2D array) represents the flux contained within that pixel relative to the total flux. For example, a pixel value of 0.1 means that 10% of the flux from the source is contained within that pixel.

psf_supersample_factor :: int The PSF oversampling factor, meaning each square pixel in the PSF file has a side length of px_scale / psf_supersample_factor (e.g., 0.1 arcsec / 20 = 0.005 arcsec).

passband_curves :: dict of dicts ! This has since been deprecated and is not used anymore ! ! See full_passband_curves instead ! Dictionary containing the passband response curves for each passband interpolated to the given passband_resolution, only spanning the wavelength range of each passband. The dictionary keys are the passband names and each key is a dictionary containing the passband wavelengths (key: “wavelength”, value: astropy.Quantity array) and the passband response (key: “response”, value: array of floats). An example structure is: python passband_curves = { "uv": { "wavelength": <`astropy.Quantity` array>, "response": <array of floats>, }, "u": { "wavelength": <`astropy.Quantity` array>, "response": <array of floats>, }, "g": { "wavelength": <`astropy.Quantity` array>, "response": <array of floats>, }, }

full_passband_curves :: dict of dicts Like passband_curves, except each passband contains the whole passband response curve (wavelengths and passband response from passband_response_filepaths) and interpolated to the given passband_resolution. Note that, to minimize NaNs at the edges of the passband response curves caused by floating point errors in the interpolation evaluation, the minimum and maximum wavelength of these full passband curves is 0.5 passband_resolution unit more/less than the min/max wavelength from the passband definition files, respectively. For example, if a passband file contains wavelengths between [1000, 11000] A and the desired interpolation resolution is 10 A, the minimum and maximum wavelengths in this full_passband_curves entry will be 1005 A and 10995 A, respectively.

fwhm :: astropy.Quantity angle The angular full-width at half-maximum of the telescope’s PSF.

px_scale :: astropy.Quantity angle The linear angle subtended by each square pixel in the detector.

px_area :: astropy.Quantity angle The solid angle (i.e., angular area) subtended by each square pixel in the detector.

transit_fov :: astropy.Quantity angle Full width FoV in degree.

ifov_dimen :: 2-element astropy.Quantity angle array The angular dimensions of the telescope’s instantaneous field of view. Not currently used for any calculations.

ifov_area :: astropy.Quantity angle The angular area covered by the telescope’s instantaneous field of view. Not currently used for any calculations.

mp :: int or float The telescope detector’s number of megapixels. Not currently used for any calculations.

transit_ccd_dim :: 2-element int list Dimensions of the CCD used for plotting gaia source and converts their ra,dec coordinates to (x,y) positions on the CCD

mirror_diameter :: astropy.Quantity length The diameter of the telescope’s primary circular mirror.

mirror_area :: astropy.Quantity length The area of the telescope’s primary circular mirror.

dark_current :: int or float The telescope detector’s dark current in electron/s/pixel.

bias :: int or float The telescope detector’s bias in units of electron. Not currently used for any calculations.

read_noise :: int or float The telescope detector’s read noise in electron/pixel.

gain :: int or float The telescope detector’s gain in units of electron/ADU. Not currently used for any calculations.

redleak_thresholds :: dict of astropy.Quantity wavelengths Dictionary containing the redleak threshold of each passband. Flux longward of the threshold is considered red leak.

extinction_coeffs :: dict of int/float The extinction coefficients (i.e., R := A/E(B-V)) for each passband.

Returns

Telescope instance

copy(): Convenience method for creating a deep copy of the Telescope object.

Parameters

None

Returns

Telescope_copy :: Telescope object The deep copy of the Telescope object.

show_psf(passband, norm=None, plot=True): Visualize the point spread function (PSF) of a given passband. The visualization assumes (0, 0) is at the center of the image (this assumption does not affect calculations, and is purely for visualization purposes). Non-finite values will be shown as black pixels in the plot.

Parameters

passband :: str The passband corresponding to the PSF.

norm :: matplotlib.colors.Normalize object or None The normalization to use for the PSF plot. If None, use the default (linear) scaling.

plot :: bool If True, plot the PSF and return None. If False, return the figure, axis, image, and colorbar instance associated with the plot.

Returns

If plot is True: None

If plot is False: fig, ax :: matplotlib.figure.Figure and matplotlib.axes.Axes objects The figure and axis instance associated with the plot.

img :: matplotlib.image.AxesImage object The image instance returned by ax.imshow.

cbar :: matplotlib.colorbar.Colorbar object The colorbar instance associated with the plot.

static calc_pivot_wavelength(wavelengths, response, response_func='EE'): Calculate the pivot wavelength of a passband using Eq. (A11) from Tokunaga & Vacca (2005) https://ui.adsabs.harvard.edu/abs/2005PASP..117..421T/abstract. This function uses Simpson’s rule to approximate the integration.

Parameters

wavelengths :: array of floats The wavelengths in the passband

response :: array of floats The passband response at each wavelength. This response should include the quantum efficiency of the detector.

reponse_func :: “EE” or “QE” The convention used for the response function. “EE” denotes an the equal energy response function while “QE” denotes the quantum efficiency response function. The AB magnitude system should use the “EE” convention.

Returns

pivot_wavelength :: float The pivot wavelength of the passband (in the same units as the input wavelengths).

static load_passbands(filepaths, limits, file_units, resolution=1 << u.nm, interp_kind='linear')

Load the passband response curves.

Parameters

filepaths :: dict of str The absolute paths to the files containing the passband response curves. The files should be in ASCII format with the first column containing the wavelengths in file_unit and the second column containing the passband response; the columns should be separated by a space. Lines starting with a hash (#) will be ignored. Note that the passband response values should account for quantum efficiency.

limits :: dict of 2-element astropy.Quantity length arrays or None Dictionary containing key-value pairs of the filter and the wavelength where the value is an astropy.Quantity array containing the lower and upper wavelength limits for that passband (inclusive). For example: {"uv": [150, 300] * u.nm, "u": [300, 400] * u.nm, "g": [400, 550] * u.nm}. If None, the limits will be the minimum and maximum wavelength in the files (note that, if resolution is not None, the minimum/maximum wavelength will be slightly greater/smaller than the actual minimum/maximum wavelength in the file to mitigate floating point errors).

file_units :: dict of astropy.Quantity lengths The units of the wavelength data in the passband response curve files.

resolution :: astropy.Quantity or None The linear interpolation resolution of the passband curves; always recommended to set to not None. If None, use the native resolution of the passband files. There are two scenarios that can occur if the response curve file does not have data at the requested wavelength (i.e., limits go beyond the wavelengths provided in the file): 1. if resolution is not None, the response curve value will be assigned NaN 2. if resolution is None, the response curve will simply omit these wavelengths from the final DataFrame.

interp_kind :: str The type of interpolation to use when resolution is not None. See scipy.interpolate.interp1d for options.

Returns

curves :: dict of dicts Dictionary containing the passband response curves. Each response curve is a dictionary containing the wavelengths in an astropy.Quantity array (same units as file_units) and the response in a float array.

Examples

print(passbands)                     # view all data for all passbands
print(passbands["uv"])               # view all data for the UV-passband
print(passbands["u"]["wavelength"])  # view the u-band wavelengths
print(passbands["g"]["response"])    # view the g-band response

static calc_phot_zpts(passband_curves, ab_mags, mirror_area, method='secant', tol=0.001, max_iter=100): Calculate the photometric zero-points (AB magnitudes) for a passband. The photometric zero-point is defined to be the AB magnitude which produces 1 electron/s in a passband.

Parameters

passband_curves :: dict of dicts Dictionary of the wavelengths and response curves for each passband. The keys should be the passband name (e.g., ‘uv’, ‘u’, ‘g’) and the value should be a dictionary. These second dictionaries should each contain the keys ‘wavelength’ and ‘response’; the first is an astropy.Quantity array of the wavelengths at which the passband response is defined and the second is a float array of the passband response. The passband response should convert photons to electrons.

ab_mags :: dict of 2-element list of floats If method is “secant”, these are the two initial guesses for the photometric zero-point of each passband. If method is “bisection”, these are the lower and upper bounds for the photometric zero-points. Note that for the latter, the lower bound must produce < 1 electron/s and the upper bound must produce > 1 electron/s.

mirror_area :: scalar The area of the Telescope’s primary mirror in square cm.

method :: “secant” or “bisection” The method to use for calculating the photometric zero-points. The secant method has faster convergence and does not depend on knowing upper/lower bounds for the photometric zero-point, but is not guaranteed to converge and you must provide two initial guesses for the zero-point. The bisection method has slower convergence and requires guessing the upper/lower limits for the zero-point, but is guaranteed to converge (given suitable upper/lower bounds) and does not require two good initial guesses.

tol :: float The absolute tolerance (i.e., desired accuracy) of the photometric zero points.

max_iter :: int The maximum number of iterations to use for finding each photometric zero point.

Returns

zpts :: dict of astropy.Quantity length arrays The photometric zero-points for each passband.

castor_etc.telescope

Telescope Utilities

Module Contents

Classes

Functions

Data

API

Parameters

Returns

Parameters

Returns

Parameters

Attributes

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Examples

Parameters

Returns

`castor_etc.telescope`