synthesizer.instruments.instrument

A module defining a class for observational instruments.

This module contains the Instrument class, which is used to define observational instruments for use in the Synthesizer package. The Instrument class contains everything needed to define a telescope or spectrograph, including the filters, resolution, wavelength array, depth, depth aperture radius, signal-to-noise ratios, PSFs, fixed noise_maps and correlated-noise source maps.

Instrument objects can define instruments to be used for synthetic:

  • Photometry (with or without noise)

  • Imaging (with or without PSFs and noise)

  • Spectroscopy (with or without noise)

  • Resolved Spectroscopy (with or without PSFs and noise)

Example usage:

# Create an Instrument object instrument = Instrument(

label=”HST”, filters=FilterCollection(…), resolution=0.1 * kpc, noise_maps={…}, noise_source_maps={…}, psfs={…}, )

print(instrument)

Classes

class synthesizer.instruments.instrument.Instrument(label, filters=None, resolution=None, lam=None, depth=None, depth_app_radius=None, snrs=None, psfs=None, noise_maps=None, noise_source_maps=None)[source]

A class containing the properties defining an observational instrument.

This class contains everything needed to define a telescope or spectrograph, including the filters, resolution, wavelength array, depth, depth aperture radius, signal-to-noise ratios, PSFs, fixed noise arrays and correlated-noise source maps.

Instrument objects can define instruments to be used for synthetic:

  • Photometry (with or without noise)

  • Imaging (with or without PSFs and noise)

  • Spectroscopy (with or without noise)

  • Resolved Spectroscopy (with or without PSFs and noise)

label

The label of the Instrument.

Type:

str

filters

The filters of the Instrument.

Type:

FilterCollection

resolution

The resolution of the Instrument.

Type:

unyt_array

lam

The wavelength array of the Instrument.

Type:

unyt_array

depth

The depth of the Instrument.

Type:

unyt_array

depth_app_radius

The depth aperture radius of the Instrument.

Type:

unyt_array

snrs

The signal-to-noise ratios of the Instrument.

Type:

unyt_array

psfs

The PSFs of the Instrument.

Type:

unyt_array

noise_maps

Fixed noise arrays to apply directly.

Type:

unyt_array

noise_source_maps

Source maps used to build correlated-noise models.

Type:

unyt_array

add_filters(filters, psfs=None, noise_maps=None, noise_source_maps=None)[source]

Add filters to the Instrument.

If PSFs, fixed noise arrays, or correlated-noise source maps are provided, an entry for each new filter must be provided in the corresponding dictionary.

Parameters:

  • filters (FilterCollection) – The filters to add to the Instrument.

  • psfs (dict, optional) – The PSFs for the new filters. Default is None.

  • noise_maps (dict, optional) – Fixed noise arrays for the new filters. Default is None.

  • noise_source_maps (dict, optional) – Correlated-noise source maps for the new filters. Default is None.

apply_noise(image, filter_code, correct_periodicity=True, rng_seed=None, aperture_radius=None)[source]

Apply noise to a single image using the instrument’s noise model.

Dispatches automatically to the appropriate noise mode based on what is configured on the instrument:

  • noise_maps present → apply the stored fixed noise array.

  • noise_source_maps dict present → correlated noise modelled from the observed template for filter_code.

  • snrs + depth set → white noise scaled from the instrument’s depth and signal-to-noise ratio.

Parameters:

  • image (Image) – The image to apply noise to.

  • filter_code (str) – The filter code identifying which noise array, source map, or SNR entry to use.

  • correct_periodicity (bool) – Passed to the correlated-noise path: if True a periodicity-dilution correction is applied. Default is True.

  • rng_seed (int, optional) – Seed for the random number generator (correlated noise only).

  • aperture_radius (unyt_quantity, optional) – Aperture radius for the SNR/depth noise path. If None a point-source depth is assumed.

Returns:

A new Image with noise added. noise_arr and weight_map are set on the returned object.

Return type:

Image

Raises:

MissingArgument – If the instrument has no noise configuration.

apply_noises(image_collection, correct_periodicity=True, rng_seed=None, aperture_radius=None)[source]

Apply noise to every image in a collection.

Calls apply_noise() for each filter in the collection. When correlated-noise source maps are used, the expensive correlation- function estimation is cached on the per-filter model so the FFT step runs at most once per filter regardless of how many images share the same instrument.

Parameters:

  • image_collection (ImageCollection) – The collection to apply noise to.

  • correct_periodicity (bool) – Passed to the correlated-noise path. Default is True.

  • rng_seed (int, optional) – Seed for the random number generator (correlated noise only).

  • aperture_radius (unyt_quantity, optional) – Aperture radius for the SNR/depth noise path.

Returns:

A new ImageCollection with noise applied to each image.

Return type:

ImageCollection

property can_do_imaging

Return whether the Instrument do simple imaging.

This flags whether the Instrument do imaging basic imaging without PSFs and noise.

Returns:

Whether the Instrument do simple imaging.

Return type:

bool

property can_do_noisy_imaging

Return whether the Instrument do imaging with noise.

This is a bit more complex than the other flags as it can be true for various different noise definitions.

We ignore the depth aperature radius here since a depth and SNR without it is assumed to be a point source depth.

Returns:

Whether the Instrument do imaging with noise.

Return type:

bool

property can_do_noisy_resolved_spectroscopy

Return whether the Instrument can do noisy resolved spectroscopy.

This is a bit more complex than the other flags as it can be true for various different noise definitions.

We ignore the depth aperature radius here since a depth and SNR without it is assumed to be a point source depth.

Returns:

Whether the Instrument do noisy resolved spectroscopy.

Return type:

bool

property can_do_noisy_spectroscopy

Return whether the Instrument can do spectroscopy with noise.

This is a bit more complex than the other flags as it can be true for various different noise definitions.

We ignore the depth aperature radius here since a depth and SNR without it is assumed to be a point source depth.

Returns:

Whether the Instrument do spectroscopy with noise.

Return type:

bool

property can_do_photometry

Return whether the Instrument do photometry.

Returns:

Whether the Instrument do photometry.

Return type:

bool

property can_do_psf_imaging

Return whether the Instrument do imaging with PSFs.

Returns:

Whether the Instrument do imaging with PSFs.

Return type:

bool

property can_do_psf_spectroscopy

Return whether the Instrument can do smoothed resolved spectroscopy.

Returns:

Whether the Instrument do smoothed resolved spectroscopy.

Return type:

bool

property can_do_resolved_spectroscopy

Return whether the Instrument do resolved spectroscopy.

Returns:

Whether the Instrument do simple resolved spectroscopy.

Return type:

bool

property can_do_spectroscopy

Return whether the Instrument do spectroscopy.

Returns:

Whether the Instrument do spectroscopy.

Return type:

bool

get_correlated_noise_model(filter_code)[source]

Return the correlated-noise model for a given filter.

Parameters:

filter_code (str) – Key into self.correlated_noise_models identifying the model to use.

Returns:

The correlated-noise model associated with filter_code.

Return type:

CorrelatedNoiseModel

Raises:
property noise_source_maps

Return the correlated-noise source maps.

Returns:

The dictionary of per-filter correlated-noise source maps, or None if no correlated-noise templates are configured.

Return type:

dict or None

to_hdf5(group)[source]

Save the Instrument to an HDF5 group.

Parameters:

group (h5py.Group) – The group in which to save the Instrument.