Instrument

class specsim.instrument.Instrument(name, wavelength, fiberloss_method, fiber_acceptance_dict, fast_fiber_acceptance, fiberloss_num_wlen, fiberloss_num_pixels, blur_function, offset_function, cameras, primary_mirror_diameter, obscuration_diameter, support_width, fiber_diameter, field_radius, radial_scale, azimuthal_scale)

Bases: object

Model the instrument response of a fiber spectrograph.

A spectrograph can have multiple cameras with different wavelength coverages. Objects representing each camera are contained in a list accessible from our cameras attribute, which will be in order of increasing effective wavelength.

No instrument attributes can be changed after an instrument has been created. Create a github issue if you would like to change this.

Parameters:

namestr

Descriptive name of this instrument.

wavelengthastropy.units.Quantity

Array of wavelength bin centers where the instrument response is calculated, with units.

fiberloss_methodstr

Must be “table” or “galsim” or “fastsim”. Specifies how fiber acceptance fractions will be loaded or calculated.

fiber_acceptance_dictdict or None

Dictionary of fiber acceptance fractions tabulated for different source models, with keys corresponding to source model names. Ignored when fiberloss_method is “galsim”.

fast_fiber_acceptancedesimodel.fastfiberacceptance.FastFiberAcceptance or None

Initialized instance to use when fiberloss_method is “fastsim”. Ignored for other values of fiberloss_method.

fiberloss_num_wlenint

Number of wavelengths where the fiberloss fraction should be tabulated for interpolation. Ignored when fiberloss_method is not “galsim”.

fiberloss_num_pixelsint

Number of pixels used to subdivide the fiber diameter for numerical convolution and integration calculations. Ignored when fiberloss_method is not “galsim”.

blur_functioncallable

Function of field angle and wavelength that returns the corresponding RMS blur in length units (e.g., microns).

offset_functioncallable

Function of focal-plane position (x,y) in angular units and wavelength that returns the corresponding radial centroid offset in length units (e.g., microns).

cameraslist

List of specsim.camera.Camera instances representing the camera(s) of this instrument.

primary_mirror_diameterastropy.units.Quantity

Diameter of the primary mirror, with units.

obscuration_diameterastropy.units.Quantity

Diameter of a central obscuration of the primary mirror, with units.

support_widthastropy.units.Quantity

Width of the obscuring supports, with units.

fiber_diameterastropy.units.Quantity

Physical diameter of the simulated fibers, with units of length. Converted to an on-sky diameter using the plate scale.

field_radiusastropy.units.Quantity

Maximum radius of the field of view in length units measured at the focal plane. Converted to an angular field of view using the plate scale.

radial_scalecallable

Callable function that returns the plate scale in the radial (meridional) direction (with appropriate units) as a function of focal-plane distance (with length units) from the boresight.

azimuthal_scalecallable

Callable function that returns the plate scale in the azimuthal (sagittal) direction (with appropriate units) as a function of focal-plane distance (with length units) from the boresight.

Attributes Summary

fiberloss_method

The current method used to calculate fiber acceptance fractions.

Methods Summary

field_angle_to_radius(angle)	Convert focal plane radius to an angle relative to the boresight.
field_radius_to_angle(radius)	Convert focal plane radius to an angle relative to the boresight.
get_blur_rms(wavelength, angle)	Get the instrument PSF blur at the specified field angle.
get_centroid_offset(angle_x, angle_y, wavelength)	Get the instrument centroid offset at the specified field angles.
get_focal_plane_optics(focal_x, focal_y, ...)	Calculate the optical parameters at a set of focal-plane positions.
plot([flux, exposure_time, cmap])	Plot a summary of this instrument's model.
plot_field_distortion()	Plot focal plane distortions over the field of view.

Attributes Documentation

fiberloss_method

The current method used to calculate fiber acceptance fractions.

Methods Documentation

field_angle_to_radius(angle)

Convert focal plane radius to an angle relative to the boresight.

The mapping \(r(\theta)\) is calculated by numerically inverting the function \(\theta(r)\).

The input values must be within the field of view. Use field_radius_to_angle() for the inverse transform.

Parameters:

angleastropy.units.Quantity

One or more angle values where the radius should be calculated. Values must be between 0 and field_angle.

Returns:

astropy.units.Quantity

Radial coordinate(s) in the focal plane corresponding to the input angle value(s).

Raises:

ValueError

One or more input values are outside the allowed range.

field_radius_to_angle(radius)

Convert focal plane radius to an angle relative to the boresight.

The mapping is derived from the radial (meridional) plate scale function \(dr/d\theta(r)\) via the integral:

\[\theta(r) = \int_0^{r} \frac{dr}{dr/d\theta(r')}\, dr'\]

The input values must be within the field of view. Use field_angle_to_radius() for the inverse transform.

Parameters:

radiusastropy.units.Quantity

One or more radius values where the angle should be calculated. Values must be between 0 and field radius.

Returns:

astropy.units.Quantity

Opening angle(s) relative to the boresight corresponding to the input radius value(s).

Raises:

ValueError

One or more input values are outside the allowed range.

get_blur_rms(wavelength, angle)

Get the instrument PSF blur at the specified field angle.

Parameters:

wavelengthastropy.units.Quantity

Wavelength where the blur should be calculated.

angleastropy.units.Quantity

Angular separation from the field center.

Returns:

astropy.units.Quantity

RMS blur of the instrument at this wavelength and field radius in length units.

get_centroid_offset(angle_x, angle_y, wavelength)

Get the instrument centroid offset at the specified field angles.

This method does not make any assumptions about how the x and y axes are defined, as long as (0, 0) is the field center.

Note that the focal-plane position is input as angles relative to the field center, while the offsets are returned as lengths relative to the nominal fiber center.

Parameters:

angle_xastropy.units.Quantity

Angular separation from the field center along x.

angle_yastropy.units.Quantity

Angular separation from the field center along y.

wavelengthastropy.units.Quantity

Wavelength where the blur should be calculated.

Returns:

tuple

Tuple (dx, dy) of astropy quantities giving the spot centroid offset components at this wavelength and position in the focal plane. Offsets are given in length units, e.g., microns.

get_focal_plane_optics(focal_x, focal_y, wlen_grid)

Calculate the optical parameters at a set of focal-plane positions.

Uses get_centroid_offset(), get_blur_rms(), and field_radius_to_angle() to calculate the optics at each focal plane location.

This method does not make any assumptions about how the x and y axes are defined, as long as (0, 0) is the field center. However radial symmetry is broken by the (dx, dy) offsets calculated by get_centroid_offset().

Note that units are required for the input arrays and included with the returned arrays.

Parameters:

focal_xastropy.units.Quantity

1D array of X coordinates in the focal plane relative to the boresight, with length units.

focal_yastropy.units.Quantity

1D array of Y coordinates in the focal plane relative to the boresight, with length units.

wlen_gridastropy.units.Quantity

1D array of wavelengths where parameters should be tabulated, with length units.

Returns:

tuple

Tuple of arrays scale, blur, offset with shapes (N,2), (N,M) and (N,M,2) where N is the size of the 1D input (x,y) arrays, M is the size of the input wavelength grid, and axes of length 2 correspond to radial and azimuthal axes (not the input x,y!). All output arrays have units.

plot(flux=<Quantity 1.e-17 erg / (Angstrom s cm2)>, exposure_time=<Quantity 1000. s>, cmap='nipy_spectral')

Plot a summary of this instrument’s model.

Requires that the matplotlib package is installed.

Parameters:

fluxastropy.units.Quantity

Constant source flux to use for displaying the instrument response.

exposure_timeastropy.units.Quantity

Exposure time to use for displaying the instrument response.

cmapstr or matplotlib.colors.Colormap

Matplotlib colormap name or instance to use for displaying the instrument response. Colors are selected for each camera according to its central wavelength, so a spectral color map will give reasonably intuitive results.

plot_field_distortion()

Plot focal plane distortions over the field of view.

Requires that the matplotlib package is installed.