lezargus.simulator.target module#

Simulation code to simulate an astrophysical object or target.

This code simulates an astrophysical target, creating the theoretical cube which represents it on sky.

We name this file “target.py” to prematurely avoid name conflicts with the Python built-in “object”.

class lezargus.simulator.target.TargetSimulator(*args: hint.Any, _cube: hint.LezargusCube, **kwargs: hint.Any)[source]#

Bases: object

Simulate an astrophysical target.

This class is a bit of a wrapper, acting as an effective means of generating the simulation of an astrophysical field. However, this class nevertheless acts as a nice point of abstraction for the instruments simulators.

Other property attributes exist but are not documented here as they have their own docstrings. In order to reduce the amount of repeat computing, every important computed property likely has a cache variant which stores the most recently calculated result as a cache and uses it instead of recomputing things. This is generally an internal application.

__init__(*args: hint.Any, _cube: hint.LezargusCube, **kwargs: hint.Any) None[source]#

Create the target simulator.

This class should not be called directly, but the helper class functions should be used instead to create the simulator. Internal options are provided and documented but their use is discouraged.

Parameters:
  • *args (Any) – Arguments we catch. If there are any arguments, we give an error.

  • _cube (hint.LezargusCube) – The main target cube. It should be the same as py:attr:target.

  • **kwargs (Any) – Extra keyword arguments we catch. If there are any, we give an error.

Return type:

None

_cache_observed = None#
_cache_target_photon = None#
static _convert_to_photon(container: hint.LezargusContainerArithmetic) hint.LezargusContainerArithmetic[source]#

Convert Lezargus spectral flux density to photon flux density.

This function is a convenience function to convert the spectral flux density of any container to a photon flux density. Please note that the units may change in unexpected ways because of unit conversions related to the constants and unit decomposition.

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

add_atmosphere(atmosphere: hint.AtmosphereSimulator) None[source]#

Add an atmosphere simulator to simulate the atmospheric effects.

Note, we only allow one atmosphere at a time.

Parameters:

atmosphere (AtmosphereSimulator) – The atmosphere simulator to add to this target simulator to allow it to simulate different effects of the atmosphere.

Return type:

None

property at_observed: hint.LezargusCube#

State of simulation after an “observation”.

This object is basically the preferred alias for referring to the simulation at the point right after atmospheric effects. This is where the a target simulation ends and further simulation is done by specific instrument simulators.

Parameters:

None

Returns:

current_state – The state of the simulation after an “observation”.

Return type:

LezargusCube

property at_radiance: hint.LezargusCube#

State of simulation after atmospheric radiance.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of atmospheric radiance.

Return type:

LezargusCube

property at_refraction: hint.LezargusCube#

State of simulation after atmospheric refraction.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of atmospheric refraction.

Return type:

LezargusCube

property at_seeing: hint.LezargusCube#

State of simulation after atmospheric seeing.

Parameters:

None

Returns:

current_state – The state of the simulation after applying the effects of atmospheric seeing.

Return type:

LezargusCube

property at_target: hint.LezargusCube#

Alias for py:attr:target to match naming convention.

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.

This may be a read-only alias, for for most cases, that is fine.

Parameters:

None

Returns:

target – The energy based flux simulation data cube of the target.

Return type:

LezargusCube

property at_target_photon: hint.LezargusCube#

Target photon flux, calculated from target spectral energy density.

Please note that the units may change in unexpected ways because of unit conversions related to the constants and unit decomposition.

Parameters:

None

Returns:

target_photon – Exactly the same as the target, except the data (flux) is a photon flux and not an energy based flux.

Return type:

LezargusCube

property at_target_spectrum: hint.LezargusCube | None#

Alias for py:attr:target_spectrum to match naming convention.

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.

This may be a read-only alias, for for most cases, that is fine.

Parameters:

None

Return type:

None

property at_transmission: hint.LezargusCube#

State of simulation after atmospheric transmission.

Parameters:

None

Returns:

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

Return type:

LezargusCube

atmosphere = None#

The atmosphere simulator which describes and simulates atmospheric effects. If not provided by py:meth:add_atmosphere, this defaults to None.

Type:

AtmosphereSimulator

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

classmethod from_blackbody(wavelength: hint.NDArray, temperature: float, magnitude: float, photometric_filter: hint.PhotometricABFilter | hint.PhotometricVegaFilter, spatial_grid_shape: tuple, spatial_fov_shape: tuple, spectral_scale: float, **kwargs: hint.Any) hint.Self[source]#

Create a target simulation object from a point source blackbody.

This is a convenience wrapper around the from_spectrum() function. Some required parameters for that function are needed and not otherwise described here. See the documentation for that function to properly use this wrapper.

Parameters:
  • wavelength (ndarray) – The wavelength sampling that we will sample the black body at.

  • temperature (float) – The temperature of the black body spectrum.

  • magnitude (float) – The magnitude of the object in the photometric filter system provided.

  • photometric_filter (PhotometricVegaFilter | PhotometricABFilter) – The photometric filter which we are using to scale the blackbody to match the magnitude provided; which is assumed to be in the correct photometric system.

  • spatial_grid_shape (tuple) – The spatial pixel grid shape. This defines the array shape of the simulation’s spatial component. The pixel and slice scale is calculated from this and the field of view.

  • spatial_fov_shape (tuple) – The defined field of view shape. This defines the on-sky field of view shape of the array, and is in radians. The pixel and slice scale is calculated from this and the field of view.

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

  • **kwargs (Any) – Additional keyword arguments passed to the py:meth:from_spectrum function which does the heavy lifting.

Returns:

target_instance – The target simulator instance derived from the input parameters.

Return type:

TargetSimulator

classmethod from_cube(cube: hint.LezargusCube) hint.Self[source]#

Create a target simulation object from a provided cube.

This function is just a formality. Usually if a cube has already been defined and provided, the cube itself is the data of the simulated target. Nevertheless, we allow for the specification of a target based on a cube to provide this common interface.

Parameters:

cube (LezargusCube) – The target cube which define the object we are simulating.

Returns:

target_instance – The target simulator instance derived from the input parameters.

Return type:

TargetSimulator

classmethod from_spectrum(spectrum: hint.LezargusSpectrum, spatial_grid_shape: tuple, spatial_fov_shape: tuple, location: tuple | str = 'center') hint.Self[source]#

Create a target simulation object from a point source spectrum.

Parameters:
  • spectrum (LezargusSpectrum) – The point source spectrum which we will use as the target to make the target cube of. The spectrum should be an energy-based spectrum.

  • spatial_grid_shape (tuple) – The spatial pixel grid shape. This defines the array shape of the simulation’s spatial component. The pixel and slice scale is calculated from this and the field of view.

  • spatial_fov_shape (tuple) – The defined field of view shape. This defines the on-sky field of view shape of the array, and is in radians The pixel and slice scale is calculated from this and the field of view.

  • location (tuple or str, default = "center") –

    Where the spectra, as a point source, be placed spatially. If a string, we compute the location from the instruction:

    • center : It is placed in the center, or close to it, rounded down, for even valued shapes.

Returns:

target_instance – The target simulator instance derived from the input parameters.

Return type:

TargetSimulator

target = None#

The target, represented as a LezargusCube. The exact properties of the cube are determined from how the simulator was created.

Type:

LezargusCube

target_spectrum = None#

The spectrum of the target. This is only made if the target cube was made by extending a point source, making the cube from a Spectrum; otherwise, this is None.

Type:

LezargusSpectrum

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.

Type:

bool