Kilonova

Kilonova#

class Kilonova(model='bulla23', **kwargs)[source]#

Bases: VirtualTarget

Kilonova point source target.

The kilonova spectrum is computed from POSSIS radiative transfer models (Bulla 2019, 2023) for a given viewing angle, see get_kilonova_flux.

Parameters:

model (str, optional) – The kilonova model, passed to get_scene as source="kilonova-{model}": "bulla23" (POSSIS grid of Bulla 2023) [default] or "bulla19" (Bulla 2019).
**kwargs –
Goes to get_scene. Main point source parameters are:
- redshift: redshift of the kilonova (default 0.2).
- phase: days since merger (default 1.4).
- theta: viewing angle in degrees (default 0, i.e. pole-on).
- magabs: peak absolute magnitude in band (default -15.8).
- magobs: peak observed magnitude in band (overrides magabs).
- band: bandpass of the normalisation (default "sdssr").
- position: position in the IFU in spaxels (default [1, 0.5]).
instrument sets the instrument configuration.

See also

slicersim.lazuli.LazuliKilonova: The Lazuli flavour of this target.

Methods

`change_detector`	Change the detector read-out configuration.
`change_properties`	Change any mutable parameter of the simulation.
`change_spectrograph`	Change the spectrograph configuration.
`from_scene`	Load the instance from a scene configuration.
`from_simulation`	Load the instance from an already-built simulation.
`get_band_snr`	Get the signal-to-noise ratio over a wavelength range.
`get_cube`	Get the simulated cube in the current configuration.
`get_data_volume`	Get the data volume of the observation.
`get_detector_image`	Not implemented for the generic VirtualTarget class.
`get_exposure_time`	Get the exposure time of the current configuration.
`get_properties`	Get parameter values of the target's simulation.
`get_readout_config`	Get the current MACC mode and number of ramps.
`get_spectrum`	Get the simulated spectrum of the point source.
`get_variance_contribution`	Get the contribution of each noise source to the variance.
`setup_to_snr`	Find the detector read-out configuration reaching a target SNR.
`to_image`	Project the simulated cube onto a detector image.

Attributes

`pointsource_properties`	Names of the mutable parameters of the point source (list of str).
`simulation`	The `Simulation` wrapped by the target.

change_detector(nmd=None, max_group=None, nramps=None)#

Change the detector read-out configuration.

Parameters set to None are left unchanged.

Parameters:

nmd (tuple of int, optional) – MACC mode (n_groups, n_frames_per_group, n_drops). Default is None.
max_group (int, optional) – Maximum number of groups in a single ramp. Default is None.
nramps (int, optional) – Number of ramps. Default is None.

Returns:

None

change_properties(**kwargs)#

Change any mutable parameter of the simulation.

Shortcut to update.

Parameters:: **kwargs – The parameters to change, as name=value (e.g. redshift=0.5 or pointsource__phase=-2).
Returns:: None

change_spectrograph(spatial_shape=None, spatial_scale=None)#

Change the spectrograph configuration.

Parameters:

spatial_shape (tuple of int, optional) – Spaxel grid shape (e.g. (40, 40)). If None, it is left unchanged. Default is None.
spatial_scale (float or list of float, optional) – Spaxel size in arcsec. If a float, spaxels are square; if a list, (x, y). If None, it is left unchanged. Default is None.

Returns:

None

classmethod from_scene(scene=None, instrument=None, **kwargs)#

Load the instance from a scene configuration.

Parameters:

scene (dict or str, optional) –

Scene configuration (see get_scene), in the format:

scene = {"scene": {"pointsource": {},  # PSF
                   "background": {},   # spatially flat
                   "host": {}}}        # structured background

or the name of a scene configuration file. Default is None.

instrument (str or dict, optional) – Configuration of the instrument, if any. If None, the class _INSTRUMENT is used when defined. Default is None.
**kwargs – Goes to get_config, overriding the scene and instrument configuration.

Returns:

VirtualTarget – An instance of the class.

classmethod from_simulation(simulation)#

Load the instance from an already-built simulation.

Parameters:: simulation (slicersim.simulation.Simulation) – The simulation the target wraps.
Returns:: VirtualTarget – An instance of the class.

See also

from_scene: Build the simulation from a scene configuration.

get_band_snr(lbda_range, frame='obs', per_resolution=True, statistic=<function nanmean>, **kwargs)#

Get the signal-to-noise ratio over a wavelength range.

Parameters:

lbda_range (tuple of float or list of tuple) – Wavelength range (min, max) in Angstrom (or a list of them).
frame (str, optional) – Reference frame of lbda_range: "rest" or "obs". Default is "obs".
per_resolution (bool, optional) – If True, return the SNR per spectral resolution element, otherwise per wavelength bin. Default is True.
statistic (callable, optional) – Function used to summarise the signal and variance over lbda_range. Default is numpy.nanmean.
**kwargs – Goes to get_band_snr (e.g. switch_off).

Returns:

float or numpy.ndarray – The SNR, one per wavelength range if a list is given. If any detector pixel saturates, numpy.inf is returned.

get_cube()#

Get the simulated cube in the current configuration.

Returns:

cube (numpy.ndarray) – Data cube in ADU, of shape (nlbda, ny, nx).
varcube (numpy.ndarray) – Variance cube in ADU^2, same shape.

See also

get_cube: The underlying method.

get_data_volume(units='GB', per_ramp=False)#

Get the data volume of the observation.

Parameters:

units (str, optional) – Unit of the returned volume (any astropy data unit, e.g. "MB" or "GB"). Default is "GB".
per_ramp (bool, optional) – If True, return the volume of a single ramp instead of the total volume over all ramps. Default is False.

Returns:

float – Data volume in units.

See also

get_data_volume: The underlying method.

get_detector_image(mapper, cubes=None, **kwargs)#

Not implemented for the generic VirtualTarget class.

Parameters:

mapper (slicersim.mapper.SlicerMapper) – Mapper describing where each slice falls on the detector.
cubes (tuple, optional) – Pre-computed cubes to project, to avoid regenerating them. Default is None.
**kwargs – Goes to the subclass implementation.

Raises:

NotImplementedError – Always raised; the projection depends on how the instrument lays its fields out on the detector, so instrument-specific subclasses must override this method. See e.g. VirtualLazuliTarget.

get_exposure_time(snr=None, full=False, **kwargs)#

Get the exposure time of the current configuration.

Parameters:

snr (float, optional) – Currently has no effect on the returned time: setup_to_snr is called with inplace=False, so the configuration used for the exposure time remains the current one. Default is None.
full (bool, optional) – If True, return all timing details; otherwise only the total exposure time. Default is False.
**kwargs – Goes to setup_to_snr. Ignored if snr is None.

Returns:

float or dict – Total exposure time in seconds (all ramps included), or, if full is True, a dict of times in seconds with keys "integration_time", "exposure_time" (one ramp), "tframe", "tgroup" and "total_exptime".

get_properties(which, default=None, as_dict=True)#

Get parameter values of the target’s simulation.

Shortcut to get_parameter.

Parameters:

which (str or list of str) – Name(s) of the parameter(s), e.g. "redshift" or ["nmd", "nramps"].
default (object, optional) – Value returned if a parameter is not found. Default is None.
as_dict (bool, optional) – Only used when which is a single name that is not found: if True, {which: default} is returned instead of default. Default is True.

Returns:

object or dict – The parameter value if which is a str, a dict {name: value} if it is a list.

get_readout_config()#

Get the current MACC mode and number of ramps.

Returns:

dict – Read-out configuration, with keys:

"nmd": (n_groups, n_frames_per_group, n_drops).
"nramps": number of ramps, each ramp following the nmd MACC mode.

get_spectrum(unit='adu', incl_error=True, **kwargs)#

Get the simulated spectrum of the point source.

The spectrum is extracted from the simulation in ADU and converted to unit.

Parameters:

unit (str, optional) –
Unit of the returned flux (and of the variance, squared):
- "adu": total ADU integrated over all ramps.
- "flambda": erg/s/cm^2/A.
- "fphoton": photon/s.
- "rate": ADU/s.
- "framerate": ADU/frame.
Default is "adu".
incl_error (bool, optional) – If True, the returned flux is randomly scattered according to the variance (hence realistic). If False, the noise-free flux is returned. Default is True.
**kwargs – Goes to get_spectrum (e.g. switch_off).

Returns:

lbda (numpy.ndarray) – Wavelengths in Angstrom.
flux (numpy.ndarray) – Flux in unit.
variance (numpy.ndarray) – Variance of the flux, in unit squared.

get_variance_contribution()#

Get the contribution of each noise source to the variance.

Returns:: pandas.DataFrame – One row per wavelength, with columns "lbda" (Angstrom), "flux" and "variance" (ADU, ADU^2), and one column per variance source (see variance_sources, e.g. "dark", "ron", "pointsource", "background", "thermal") giving its contribution to the variance in ADU^2.

setup_to_snr(snr, per_resolution=True, lbda_range=[4000, 6800], frame='rest', statistic=<function nanmean>, inplace=True, **kwarg)#

Find the detector read-out configuration reaching a target SNR.

The MACC mode and number of ramps are varied until the signal-to-noise ratio over lbda_range reaches snr (see fetch_snr).

Parameters:

snr (float) – Target signal-to-noise ratio.
per_resolution (bool, optional) – If True, snr is given per spectral resolution element and is converted into a SNR per wavelength bin, snr / sqrt(dispersion_resolution), before being passed to fetch_snr. If False, snr is per wavelength bin. Default is True.
lbda_range (list of float, optional) – Wavelength range [min, max] in Angstrom over which the SNR is computed. Default is [4000, 6800].
frame (str, optional) – Reference frame of lbda_range: "rest" (rest-frame) or "obs" (observer-frame). Default is "rest".
statistic (callable, optional) – Function used to summarise the SNR over lbda_range. Default is numpy.nanmean.
inplace (bool, optional) – If True, the simulation is updated to the returned configuration. Default is True.
**kwarg – Goes to fetch_snr (e.g. max_group or ndrop). nframe_per_group is set to 8 and cannot be given.

Returns:

config (dict) – Read-out configuration reaching snr, with keys "nmd" and "nramps".
reached_snr (float) – SNR reached with config, per resolution element if per_resolution is True, per wavelength bin otherwise.

to_image(mapper, sliceid, image=None, **kwargs)#

Project the simulated cube onto a detector image.

Parameters:

mapper (slicersim.mapper.SlicerMapper) – Mapper describing where each slice falls on the detector.
sliceid (int or array_like) – Identifier(s) of the slice(s) the cube is projected onto.
image (numpy.ndarray, optional) – Existing detector image this projection is added to. If None, only the contribution of this target is returned. Default is None.
**kwargs – Goes to get_cube. The generic get_cube accepts none; use them with subclasses such as VirtualLazuliTarget.

Returns:

numpy.ndarray – 2D detector image. When image is given, the sum of image and of the projected cube; image itself is left unchanged.

pointsource_properties#: Names of the mutable parameters of the point source (list of str).

simulation#: The Simulation wrapped by the target.

Kilonova

Contents

Kilonova#