lezargus.simulation.spectre module#
Simulation code for simulating SPECTRE observations.
For more information on the simulation of SPECTRE observations, see the documentation file: [[TODO]].
- class lezargus.simulation.spectre.SimulatorSpectre[source]#
Bases:
object
Simulate a SPECTRE observation.
We group all of the functions needed to simulate a SPECTRE observation into this class. It it easier to group all of data and needed functions this way.
By default, all attributes are public to allow for maximum transparency. By convention, please treat the attributes as read-only. Consult the documentation for changing them. By default, they are None, this allows us to track the process of the simulation.
- astrophysical_object_spectra#
The “perfect” spectra of the astrophysical object who’s observation is being modeled.
- Type:
- astrophysical_object_cube#
The cube form of the perfect astrophysical object who’s observation is being modeled.
- Type:
- astrophysical_object_cube_atm_trn#
The astrophysical object after applying the atmospheric transmission.
- Type:
- astrophysical_object_cube_atm_rad#
The astrophysical object after applying the atmospheric radiance or emission after transmission.
- Type:
- astrophysical_object_cube_atm_see#
The astrophysical object after applying the atmospheric seeing convolution; after transmission and radiance.
- Type:
- astrophysical_object_cube_atm_ref#
The astrophysical object after applying the atmospheric refraction, after transmission, radiance, and seeing. This is actually just a read-only alias for
astronomical_object_cube
.- Type:
- astronomical_object_cube#
The astronomical object, obtained from applying atmospheric conditions to the astrophysical object. Noted as “astronomical” as it is considered “as-observed” from the Earth ground.
- Type:
- __init__() None [source]#
Instantiate the SPECTRE simulation class.
- Parameters:
None –
- Return type:
None
- _prepare_spectra_convolve(spectra: LezargusSpectra, input_resolution: float | None = None, input_resolving: float | None = None, simulation_resolution: float | None = None, simulation_resolving: float | None = None, reference_wavelength: float | None = None, **kwargs: object) LezargusSpectra [source]#
Convolve the input spectra to make its resolution match.
Spectra comes in many resolutions. If the resolution of an input spectra is too high for the simulation, its application can give erroneous results. Here, we use a Gaussian kernel to convolve the spectral data to better match the resolution of the input and the simulation.
We leverage
kernel_1d_gaussian_resolution()
to make the kernel.- Parameters:
spectra (LezargusSpectra) – The transmission spectra which we will be preparing.
input_resolution (float, default = None) – The spectral resolution of the input spectra. Must be in the same units as the spectra.
input_resolving (float, default = None) – The spectral resolving power of the input spectra, relative to the wavelength reference_wavelength.
simulation_resolution (float, default = None) – The spectral resolution of the simulation spectra. Must be in the same units as the simulation spectra.
simulation_resolving (float, default = None) – The spectral resolving power of the simulation spectra, relative to the wavelength reference_wavelength.
reference_wavelength (float, default = None) – The reference wavelength for any needed conversion.
**kwargs (dict) – Keyword argument catcher.
- Returns:
convolved_spectra – The spectra, after convolution based on the input parameters.
- Return type:
- apply_atmospheric_radiance(radiance_spectra: LezargusSpectra) LezargusCube [source]#
Apply atmospheric radiance spectra to the object.
The astrophysical object cube with transmission is required to use this function, see
apply_atmospheric_transmission()
. The results are stored in this class internally asastrophysical_object_cube_atm_rad
.Moreover, consider using
prepare_spectra()
to properly match the resolving power or resolution of the simulation spectra and the radiance spectra.- Parameters:
radiance_spectra (LezargusSpectra) – The atmospheric radiance spectra. The wavelength unit of this spectra should be meters.
- Returns:
cube – The cube of the object after atmospheric radiance has been added.
- Return type:
- apply_atmospheric_refraction(zenith_angle: float, reference_wavelength: float, parallactic_angle: float) Self [source]#
Apply atmospheric refraction effects to the object.
We apply the effects of atmospheric refraction as described in
relative_atmospheric_refraction_function()
. The used atmospheric conditions are specified by the configurations in the configuration file.Note that NaNs are introduced into the cube because of the edge of translations.
- Parameters:
zenith_angle (float) – The zenith angle of the observation, in radians.
reference_wavelength (float) – The reference wavelength where the relative atmospheric refraction is zero; must be in the same units as the cube’s wavelength, typically meters.
parallactic_angle (float) – The parallactic angle of the observation, used to derive the translation vector.
- Returns:
cube – The resulting cube after the effects of atmospheric refraction.
- Return type:
- apply_atmospheric_seeing(seeing_kernel: ndarray) LezargusCube [source]#
Apply atmospheric seeing effects to the object.
This functions simulates atmospheric seeing effects using a convolution kernel. The kernel should emulate the seeing function and should be provided.
The astrophysical object cube with radiance is required to use this function, see
apply_atmospheric_radiance()
.- Parameters:
seeing_kernel (ndarray) – The seeing kernel which is used to convolve against the data cube.
- Returns:
cube – The results of the seeing convolution.
- Return type:
- apply_atmospheric_transmission(transmission_spectra: LezargusSpectra) LezargusCube [source]#
Apply the atmospheric transmission to the object.
The astrophysical object cube is required to use this function, see
create_astrophysical_object_cube()
orcustom_astrophysical_object_cube()
to create it. The results are stored in this class internally asastrophysical_object_cube_atm_trn
.Moreover, consider using
prepare_spectra()
to properly match the resolving power or resolution of the simulation spectra and the transmission spectra.- Parameters:
transmission_spectra (LezargusSpectra) – The atmospheric transmission spectra. The wavelength unit of this spectra should be meters.
- Returns:
cube – The cube of the object after atmospheric transmission has been applied.
- Return type:
- property astrophysical_object_cube_atm_ref: LezargusCube#
Read-only alias for
astronomical_object_cube
.- Parameters:
None –
- Returns:
cube – The
astronomical_object_cube
object as an alias.- Return type:
- create_astrophysical_object_spectra(temperature: float, magnitude: float, filter_spectra: LezargusSpectra, filter_zero_point: float) LezargusSpectra [source]#
Create the astrophysical object from first principles.
This function creates and stores the astrophysical object spectra modeled as a blackbody of a specific temperature. If a custom spectra is to be provided, please see
custom_astrophysical_object_spectra()
. The data is stored in this class internally asastrophysical_object_spectra
.- Parameters:
temperature (float) – The temperature of the black body spectra.
magnitude (float) – The magnitude of the object in the photometric filter system provided.
filter_spectra (LezargusSpectra) – The filter transmission profile, packaged as a LezargusSpectra. It does not need to have any header data. We assume a Vega-based photometric system.
filter_zero_point (float) – The zero point value of the filter.
- Returns:
spectra – The astrophysical object spectra; it is returned as a courtesy as the result is stored in this class.
- Return type:
- custom_astrophysical_object_cube(custom_cube: LezargusCube) LezargusCube [source]#
Use a provided cube for a custom astrophysical cube.
This function is used to provide a custom cube class to use to define the astrophysical object field. If it should be derived instead from a point-source spectra, then please use
generate_astrophysical_object_cube()
instead. The results are stored in this class internally asastrophysical_object_cube
.Note that the wavelength axis of the custom cube is used to define the wavelength scaling of the astrophysical object. We do not add any unknown information.
- Parameters:
custom_cube (LezargusSpectra) – The custom provided spectral cube object to use for the custom astrophysical object field.
- Returns:
cube – The astrophysical object cube; it is returned as a courtesy as the result is stored in this class. This is the same as the input spectra and the return is for consistency.
- Return type:
- custom_astrophysical_object_spectra(custom_spectra: LezargusSpectra) LezargusSpectra [source]#
Use a provided spectra for a custom astrophysical object.
This function is used to provide a custom spectra class to use to define the astrophysical object. If it should be derived instead from much simpler first principles, then please use
create_astrophysical_object_spectra()
instead. The data is stored in this class internally asastrophysical_object_spectra
.The object spectra should be a point source object. If you have a custom cube that you want to use, see
custom_astrophysical_object_cube()
instead.Note that the wavelength axis of the custom spectra is used to define the wavelength scaling of the astrophysical object. We do not add any unknown information.
- Parameters:
custom_spectra (LezargusSpectra) – The custom provided spectral object to use for the custom astrophysical object.
- Returns:
spectra – The astrophysical object spectra; it is returned as a courtesy as the result is stored in this class. This is the same as the input spectra and the return is for consistency.
- Return type:
- generate_astrophysical_object_cube() LezargusCube [source]#
Use the stored astrophysical spectra to generate a field cube.
This function takes the stored astrophysical object spectra and develops a mock field-of-view field of the object represented with a cube. A custom cube may be provided instead with
custom_astrophysical_object_cube()
. The data is stored in this class internally asastrophysical_object_cube
.The astrophysical object spectra is required to use this function, see
create_astrophysical_object_spectra()
orcustom_astrophysical_object_spectra()
to create it.- Parameters:
None –
- Returns:
cube – The astrophysical object cube; it is returned as a courtesy as the result is stored in this class.
- Return type:
- prepare_atmospheric_seeing_kernel(seeing: float) ndarray [source]#
Create an atmospheric seeing kernel based on the seeing.
We create an atmospheric seeing kernel provided some seeing value. This function exists to assist in the transition between different more accurate point spread functions or speckle profile as future kernels are implemented.
Currently, the best implemented model we have a simple Gaussian kernel.
- Parameters:
seeing (float) – The atmospheric seeing, in radians.
- Returns:
seeing_kernel – The atmospheric seeing kernel.
- Return type:
ndarray
- prepare_spectra(spectra: LezargusSpectra, *args: object, skip_convolve: bool = False, **kwargs: object) LezargusSpectra [source]#
Prepare the provided spectra for future steps.
Any provided spectra (transmission curves, emission curves, etc) must be properly prepared before its application to the simulation data. We do the following steps in order (if not otherwise skipped):
Convolve: We match the spectral resolution (or resolving power) to the simulation’s. We leverage
_prepare_convolve_atmospheric_transmission()
.
Please see the linked functions in each of the steps for the parameters required for each step of the preparation, if it is not to be skipped. Without the required inputs, the preparation will likely fail; failure will likely be noisy (logged or raised).
- Parameters:
spectra (LezargusSpectra) – The input spectra which we will be preparing.
skip_convolve (bool, default = False) – If True, we skip the resolution convolution step. The backend function will not be called.
*args (Any) – The positional arguments. We forbid any positional arguments for informing the backend functions because of its ambiguity.
**kwargs (Any) – The keyword arguments which will be fed into the backend functions.
- Returns:
finished_spectra – The finished prepared spectra after all of the steps have been done.
- Return type: