lezargus.simulator.spectre module

Contents

lezargus.simulator.spectre module#

Simulation code to simulate a SPECTRE observation.

This code simulates a SPECTRE observation, from the target on the sky, all the way to the detector. We use other smaller simulators to simulate common things (like the object itself or the atmosphere) and the specifics of their implementations can be found there. Implementation specifics to the SPECTRE instrument itself are found here.

By self-imposed convention, the attributes are generally named as at_[stage] where the result is the simulated result right after simulating whichever stage is named.

For ease, we package the smaller simulators within this single simulator class.

class lezargus.simulator.spectre.SpectreSimulator(target: hint.TargetSimulator, telescope: hint.IrtfTelescopeSimulator, channel: str, exposure_time: float, coadds: int, atmosphere: hint.AtmosphereSimulator | None = None)[source]#

Bases: object

Main SPECTRE simulator class.

By self-imposed convention, the attributes are generally named as at_[stage] where the result is the simulated result right after simulating whichever stage is named.

__init__(target: hint.TargetSimulator, telescope: hint.IrtfTelescopeSimulator, channel: str, exposure_time: float, coadds: int, atmosphere: hint.AtmosphereSimulator | None = None) None[source]#

Initialize the SPECTRE simulator.

Parameters:
  • target (TargetSimulator) – The target simulator representing the object for simulated observing.

  • telescope (IrtfTelescopeSimulator) – The telescope that the instrument is on. As the SPECTRE instrument is on the IRTF, we expect it to be an IRTF object.

  • channel (str) – The name of the channel (of the three) which we are simulating.

  • exposure_time (float) – The exposure time of the observation integration, in seconds.

  • coadds (int) – The number of co-adds of the provided exposure time for the observation.

  • atmosphere (AtmosphereSimulator, default = None) – The intervening atmosphere simulation object. If None, we skip applying an atmosphere; use this if the target object already has the correct atmosphere applied.

Return type:

None

_convert_to_photon(container: hint.LezargusContainerArithmetic) hint.LezargusContainerArithmetic[source]#

Convert Lezargus spectral flux density to photon flux density.

The core implementation can be found in py:mod:lezargus.simulator.target._convert_to_photon.

Parameters:

container (LezargusContainerArithmetic) – The container we are converting, or more accurately, a subclass of the container.

Returns:

photon_container – The converted container as a photon flux instead of an energy flux. However, please note that the units may change in unexpected ways.

Return type:

LezargusContainerArithmetic

property at_cosmic_rays: hint.LezargusImage#

State of simulation after accounting for cosmic ray hits.

Parameters:

None

Returns:

current_state – The state of the simulation after adding cosmic ray hits.

Return type:

LezargusImage

property at_detector_bias: hint.LezargusImage#

State of simulation after adding in the detector bias level.

Parameters:

None

Returns:

current_state – The state of the simulation after adding in the detector bias level.

Return type:

LezargusImage

property at_detector_dark_current: hint.LezargusImage#

State of simulation after adding in the detector dark current.

Parameters:

None

Returns:

current_state – The state of the simulation after adding in the detector dark current

Return type:

LezargusImage

property at_detector_flat_field: hint.LezargusImage#

State of simulation after accounting the detector flat field.

Parameters:

None

Returns:

current_state – The state of the simulation after acconting for detector flat field variations.

Return type:

LezargusImage

property at_detector_gain: hint.LezargusImage#

State of simulation after accounting the detector gain.

Parameters:

None

Returns:

current_state – The state of the simulation after acconting for the detetor gain factor.

Return type:

LezargusImage

property at_detector_hot_dead_pixels: hint.LezargusImage#

State of simulation after the detector hot and dead pixels.

Parameters:

None

Returns:

current_state – The state of the simulation after applying hot and dead pixels.

Return type:

LezargusImage

property at_detector_linearity: hint.LezargusImage#

State of simulation after the detector linearity functions.

This function is mostly applying an approximation of the effect, see the documentation for more information.

Parameters:

None

Returns:

current_state – The state of the simulation after acounting for the detector linearity functions.

Return type:

LezargusImage

property at_detector_quantum_efficiency: tuple[hint.LezargusCube, ...]#

State of simulation after the detector quantum efficiency.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the detector quantum efficiency.

Return type:

LezargusCube

property at_detector_read_noise: hint.LezargusImage#

State of simulation after the detector read noise.

Parameters:

None

Returns:

current_state – The state of the simulation after acounting for the detector read noise.

Return type:

LezargusImage

property at_dichroic: tuple[hint.LezargusCube, ...]#

State of simulation after the channel dichroic transmission.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the channel dichroic transmission.

Return type:

LezargusCube

property at_fits_file: hint.LezargusImage#

State of simulation near the read out of the FITS file.

Parameters:

None

Returns:

current_state – The state of the simulation ready to read out to a FITS file.

Return type:

LezargusImage

property at_fold_mirror: tuple[hint.LezargusCube, ...]#

State of simulation after the channel fold mirror transmission.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the channel fold mirror transmission.

Return type:

LezargusCube

property at_foreoptics: hint.LezargusCube#

State of simulation after fore-optics.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the fore-optics.

Return type:

LezargusCube

property at_ifu_diffraction: tuple[hint.LezargusCube, ...]#

State of simulation after the IFU image slicer diffraction.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the IFU image slicer diffraction.

Return type:

LezargusCube

property at_ifu_image_slicer: tuple[hint.LezargusCube, ...]#

State of simulation after the IFU image slicer.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the IFU image slicer.

Return type:

LezargusCube

property at_ifu_pupil_mirror_transmission: tuple[hint.LezargusCube, ...]#

State of simulation after the IFU pupil mirror transmission.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the IFU pupil mirror transmission.

Return type:

LezargusCube

property at_ifu_transmission: hint.LezargusCube#

State of simulation after the transmission of the IFU.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the IFU transmission.

Return type:

LezargusCube

property at_observed: hint.LezargusCube#

Exposing the target’s at_observed instance.

See py:meth:lezargus.simulator.target.TargetSimulator.at_observed().

Parameters:

None

Return type:

None

property at_photon_poisson_noise: hint.LezargusImage#

State of simulation after accounting for photon poisson noise.

Parameters:

None

Returns:

current_state – The state of the simulation after adding photon noise.

Return type:

LezargusImage

property at_primary_emission: hint.LezargusCube#

State of simulation after primary mirror emission.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the primary mirror emission.

Return type:

LezargusCube

property at_primary_reflectivity: hint.LezargusCube#

State of simulation after primary mirror reflectivity.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the primary mirror reflectivity.

Return type:

LezargusCube

property at_prisms_transmission: tuple[hint.LezargusCube, ...]#

State of simulation after the channel prisms transmission.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the prisms transmission.

Return type:

LezargusCube

property at_radiance: hint.LezargusCube#

Exposing the target’s at_radiance instance.

See py:meth:lezargus.simulator.target.TargetSimulator.at_radiance().

Parameters:

None

Return type:

None

property at_readout: hint.LezargusImage#

The state of the simulation at readout, fully simulated.

This is mostly a convience function, but it is also done as a final caching level if needed.

Parameters:

None

Returns:

current_state – The state of the finished simulation.

Return type:

LezargusImage

property at_refraction: hint.LezargusCube#

Exposing the target’s at_refraction instance.

See py:meth:lezargus.simulator.target.TargetSimulator.at_refraction().

Parameters:

None

Return type:

None

property at_relay_mirrors: tuple[hint.LezargusCube, ...]#

State of simulation after the channel relay mirrors transmission.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the channel relay mirrors transmission.

Return type:

LezargusCube

property at_scattered_light: hint.LezargusImage#

State of simulation after modeling scattered light.

Parameters:

None

Returns:

current_state – The state of the simulation after adding scattered light interfearence.

Return type:

LezargusImage

property at_secondary_emission: hint.LezargusCube#

State of simulation after secondary mirror emission.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the secondary mirror emission.

Return type:

LezargusCube

property at_secondary_reflectivity: hint.LezargusCube#

State of simulation after secondary mirror reflectivity.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the secondary mirror reflectivity.

Return type:

LezargusCube

property at_seeing: hint.LezargusCube#

Exposing the target’s at_seeing instance.

See py:meth:lezargus.simulator.target.TargetSimulator.at_seeing().

Parameters:

None

Return type:

None

property at_spectral_dispersion: hint.LezargusImage#

State of simulation after modeling spectral dispersion on detector.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of spectral dispersion onto the detector.

Return type:

LezargusImage

property at_target: hint.LezargusCube#

Exposing the target’s at_target instance.

See py:meth:lezargus.simulator.target.TargetSimulator.at_target().

Parameters:

None

Return type:

None

property at_target_photon: hint.LezargusCube#

Exposing the target’s at_target_photon instance.

See py:meth:lezargus.simulator.target.TargetSimulator.at_target_photon().

Parameters:

None

Return type:

None

property at_target_spectrum: hint.LezargusCube | None#

Exposing the target’s at_target_spectrum instance.

See py:meth:lezargus.simulator.target.TargetSimulator.at_target_spectrum().

Parameters:

None

Return type:

None

property at_telescope: hint.LezargusCube#

State of simulation after telescope area integration.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the area of the telescope.

Return type:

LezargusCube

property at_transmission: hint.LezargusCube#

Exposing the target’s at_transmission instance.

See py:meth:lezargus.simulator.target.TargetSimulator.at_transmission().

Parameters:

None

Return type:

None

property at_window_emission: hint.LezargusCube#

State of simulation after entrance window emission.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the entrance window emission.

Return type:

LezargusCube

property at_window_ghost: hint.LezargusCube#

State of simulation after the entrance window ghost.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the entrance window ghost.

Return type:

LezargusCube

property at_window_transmission: hint.LezargusCube#

State of simulation after entrance window transmission.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of the secondary mirror emission.

Return type:

LezargusCube

atmosphere: hint.AtmosphereSimulator#

The atmosphere simulation. This is the working copy.

channel: hint.Literal['visible', 'nearir', 'midir']#

The specific channel of the three channels of SPECTRE that we are simulating.

clear_cache() None[source]#

Clear the cache of computed result objects.

This function clears the cache of computed results, allowing for updated values to properly be utilized in future calculations and simulations.

Parameters:

None

Return type:

None

coadds: int#

Co-adds are a way to combine multiple exposures into a single file, giving better signal to noise without saturating.

exposure_time: float#

The exposure time of the integration, used near the end for Poisson statistics on the observation.

classmethod from_advanced_parameters(channel: str, wavelength: hint.NDArray, blackbody_temperature: float, magnitude: float, photometric_filter: hint.PhotometricABFilter | hint.PhotometricVegaFilter, exposure_time: float, coadds: int, spatial_shape: tuple, field_of_view: tuple, spectral_scale: float, atmosphere_temperature: float, atmosphere_pressure: float, atmosphere_ppw: float, atmosphere_pwv: float, atmosphere_seeing: float, zenith_angle: float, parallactic_angle: float, reference_wavelength: float, telescope_temperature: float, transmission_generator: hint.AtmosphereSpectrumGenerator | None = None, radiance_generator: hint.AtmosphereSpectrumGenerator | None = None) hint.Self[source]#

Initialize the SPECTRE simulator, only using parameter values.

By default, the initialization of the SPECTRE simulator requires the creation of three different inner simulator classes. This convenience function does that for the user, as long as they provide the environmental parameters for all three.

We assume a blackbody simulated target, an Earth-like atmosphere, and the IRTF telescope. The parameters modify just the specifics. For a more detailed approach, please construct the classes instead.

Parameters:
  • channel (str) – The name of the channel that will be simulated; one of three channels: visible, nearir, and midir.

  • wavelength (ndarray) – The wavelength basis of the simulator; this defines the wavelength axis and are its values.

  • blackbody_temperature (float) – The blackbody temperature of the object that we are simulating, in Kelvin.

  • magnitude (float) – The simulated magnitude of the object. The photometric filter system this magnitude is in must match the inputted photometric filter.

  • photometric_filter (PhotometricABFilter or PhotometricVegaFilter) – The photometric filter (system) that the inputted magnitude is in.

  • exposure_time (float) – The exposure time of the observation integration, in seconds.

  • coadds (int) – The number of co-adds of the provided exposure time for the observation.

  • spatial_shape (tuple) – The spatial shape of the simulation array, the units are in pixels. This parameter should not be confused with the field of view parameter.

  • field_of_view (tuple) – A tuple describing the field of view of the spatial area of the simulation array, the units are in radians. We suggest oversizing this a little more than the traditional 7.2 by 7.2 arcseconds.

  • spectral_scale (float) – The spectral scale of the simulated spectra, as a resolution, in wavelength separation (in meters) per pixel.

  • atmosphere_temperature (float) – The temperature of the intervening atmosphere, in Kelvin.

  • atmosphere_pressure (float) – The pressure of the intervening atmosphere, in Pascal.

  • atmosphere_ppw (float) – The partial pressure of water in the atmosphere, in Pascal.

  • atmosphere_pwv (float) – The precipitable water vapor in the atmosphere, in meters.

  • atmosphere_seeing (float) – The seeing of the atmosphere, given as the FWHM of the seeing disk, often approximated as a Gaussian distribution, at zenith and at the reference wavelength. The units are in radians.

  • zenith_angle (float) – The zenith angle of the simulated object, at the reference wavelength in radians; primarily used to determine airmass.

  • parallactic_angle (float) – The parallactic angle of the simulated object, in radians; primarily used to atmospheric dispersion direction.

  • reference_wavelength (float) – The reference wavelength which defines the seeing and zenith angle parameters. Assumed to be in the same units as the provided wavelength axis.

  • telescope_temperature (float) – The local temperature of the telescope, usually the temperatures of the primary and other mirrors; in Kelvin.

  • transmission_generator (AtmosphereSpectrumGenerator, default = None) – The transmission spectrum generator used to generate the specific transmission spectra. If None, we default to the built-in generators.

  • radiance_generator (AtmosphereSpectrumGenerator, default = None) – The transmission spectrum generator used to generate the specific transmission spectra. If None, we default to the built-in generators.

Returns:

spectre_simulator – The simulator, with the properties provided from the parameters.

Return type:

SpectreSimulator

input_atmosphere: hint.AtmosphereSimulator | None#

The inputted atmosphere simulation. We store this original copy as the actual working copy is being modified in place.

input_target: hint.TargetSimulator#

The inputted target object simulation. We store this original copy as the actual working copy is being modified in place.

input_telescope: hint.IrtfTelescopeSimulator#

The inputted telescope simulation. We store this original copy as the actual working copy is being modified in place.

target: hint.TargetSimulator#

The target object simulation. This is the working copy.

telescope: hint.IrtfTelescopeSimulator#

The telescope simulation. This is the working copy.

use_cache = True#

If True, we cache calculated values so that they do not need to be calculated every time when not needed. If False, caches are never returned and instead everything is always recomputed.