Simulate Module¶

The classes and methods in gbm.simulate are for simulating spectra and event data.

PHA Simulation¶

Simulate count spectra by folding a photon model through a detector response. Also simulates background from a background model.

PhaSimulator¶

class gbm.simulate.PhaSimulator(rsp, function, params, exposure, bkgd, bkgd_distrib)[source]¶

Bases: object

Simulate PHA data given a modeled background spectrum, detector response, source spectrum, and exposure.

Parameters

rsp (RSP) – A detector response object
function (Function) – A photon model function
params (iterable) – The parameters for the function
exposure (float) – The source exposure
bkgd (BackgroundSpectrum) – A modeled background spectrum
bkgd_distrib (str) – The distribution from which the background is simulated; either ‘Poisson’ or ‘Gaussian’

set_background(bkgd, bkgd_distrib)[source]¶

Set/change the background model.

Parameters

bkgd (BackgroundSpectrum) – A modeled background spectrum
bkgd_distrib (str) – The distribution from which the background is simulated; either ‘Poisson’ or ‘Gaussian’

set_rsp(rsp)[source]¶

Set/change the detector response.

Parameters: rsp (RSP) – A detector response object

set_source(function, params, exposure)[source]¶

Set/change the source spectrum.

Parameters

function (Function) – A photon model function
params (iterable) – The parameters for the function
exposure (float) – The source exposure

simulate_background(num_sims)[source]¶

Generate simulations of the modeled background spectrum

Parameters: num_sims (int) – Number of simulations
Returns: list of BackgroundSpectrum – The deviates of the background spectrum

simulate_source(num_sims)[source]¶

Generate simulations of the source spectrum

Parameters: num_sims (int) – Number of simulations
Returns: list of EnergyBins – The deviates of the source spectrum

simulate_sum(num_sims)[source]¶

Generate simulations of the background + source spectrum.

Parameters: num_sims (int) – Number of simulations
Returns: list of EnergyBins – The deviates of the total background + source spectrum

to_bak(num_sims, tstart=None, tstop=None, **kwargs)[source]¶

Produce BAK objects from simulations

Parameters

num_sims (int) – Number of simulations
tstart (float, optional) – The start time. If not set, then is zero.
tstop (float, optional) – Then end time. If not set, then is the exposure.
**kwargs – Options passed to BAK

Returns

list of BAK – The simulated BAK objects

to_pha(num_sims, tstart=None, tstop=None, **kwargs)[source]¶

Produce PHA objects of the background + source from simulations

Parameters

num_sims (int) – Number of simulations
tstart (float, optional) – The start time. If not set, then is zero.
tstop (float, optional) – Then end time. If not set, then is the exposure.
**kwargs – Options passed to PHA

Returns

list of PHA – The simulated PHA objects

to_phaii(num_sims, bin_width=None, **kwargs)[source]¶

Produce a PHAII object by concatenating the simulations.

Parameters

num_sims (int) – Number of simulations
bin_widths (float, optional) – The width of each time bin. Must be >= the exposure. If not set, the is the exposure.
**kwargs – Options passed to PHAII

Returns

PHAII – The simulated PHAII object

TTE Simulation¶

Simulate event data generated from a spectral and temporal source model, as well as event data from a spectral and temporal background model.

TteSourceSimulator¶

class gbm.simulate.TteSourceSimulator(rsp, spec_func, spec_params, time_func, time_params, sample_period=0.001, deadtime=2e-06)[source]¶

Bases: object

Simulate TTE or EventList data for a source spectrum given a detector response, spectral model and time profile model. The spectral shape is fixed throughout the time profile of the signal, but the amplitude of the spectrum is time-dependent, set by the time profile function.

Parameters

rsp (RSP) – A detector response object
spec_func (Function) – A photon model function
spec_params (iterable) – The parameters for the function
time_func (<function>) – A time profile function
time_params (iterable) – Parameters for the time profile function
sample_period (float, optional) – The sampling period of the simulator in seconds. Default is 0.001. The simulator will produce arrival times consistent with a spectrum over a finite time slice. This time slice should be short enough to approximate a non-homogeneous Poisson process, but long enough to allow for a tractable computation time.
deadtime (float, optional) – The dead time in seconds for each recorded count during which another count cannot be recorded. Default is 2e-6 s.

set_response(rsp)[source]¶

Set/change the detector response.

Parameters: rsp (RSP) – A detector response object

set_spectrum(spec_func, spec_params)[source]¶

Set/change the spectrum.

Parameters

spec_func (Function) – A photon model function
spec_params (iterable) – The parameters for the function

set_time_profile(time_func, time_params)[source]¶

Set/change the time profile.

Parameters

time_func (<function>) – A time profile function
time_params (iterable) – Parameters for the time profile function

simulate(tstart, tstop)[source]¶

Generate an EventList containing the individual counts from the simulation

Parameters

tstart (float) – The start time of the simulation
tstop (float) – The stop time of the simulation

Returns

EventList – The simulated EventList

to_tte(tstart, tstop, trigtime=None, **kwargs)[source]¶

Generate an TTE object containing the individual counts from the simulation

Parameters

tstart (float) – The start time of the simulation
tstop (float) – The stop time of the simulation
trigtime (float, optional) – The trigger time. Default is 0.
**kwargs – Options to pass to TTE

Returns

TTE – The simulated TTE object

TteBackgroundSimulator¶

class gbm.simulate.TteBackgroundSimulator(bkgd_spectrum, distrib, time_func, time_params, sample_period=0.001, deadtime=2e-06)[source]¶

Bases: object

Simulate TTE or EventList data given a modeled background spectrum and time profile model. The spectrum is fixed throughout the time profile of the background, but the amplitude of the background is time-dependent, set by the time profile function.

Parameters

bkgd_spectrum (BackgroundSpectrum) – A modeled background spectrum
distrib (str) – The distribution from which the background is simulated; either ‘Poisson’ or ‘Gaussian’
time_func (<function>) – A time profile function
time_params (iterable) – Parameters for the time profile function
sample_period (float, optional) – The sampling period of the simulator in seconds. Default is 0.001. The simulator will produce arrival times consistent with a spectrum over a finite time slice. This time slice should be short enough to approximate a non-homogeneous Poisson process, but long enough to allow for a tractable computation time.
deadtime (float, optional) – The dead time in seconds for each recorded count during which another count cannot be recorded. Default is 2e-6 s.

set_background(bkgd_spectrum, distrib)[source]¶

Set/change the spectrum.

Parameters

bkgd_spectrum (BackgroundSpectrum) – A modeled background spectrum
distrib (str) – The distribution from which the background is simulated; either ‘Poisson’ or ‘Gaussian’

simulate(tstart, tstop)[source]¶

Generate an EventList containing the individual counts from the background simulation

Parameters

tstart (float) – The start time of the simulation
tstop (float) – The stop time of the simulation

Returns

EventList – The simulated EventList

to_tte(tstart, tstop, trigtime=None, **kwargs)[source]¶

Generate an TTE object containing the individual counts from the background simulation

Parameters

tstart (float) – The start time of the simulation
tstop (float) – The stop time of the simulation
trigtime (float, optional) – The trigger time. Default is 0.
**kwargs – Options to pass to TTE

Returns

TTE – The simulated TTE object

Simulation Generators¶

A variety of specialized random generators

PoissonBackgroundGenerator¶

class gbm.simulate.generators.PoissonBackgroundGenerator(bkgd)[source]¶

Bases: gbm.simulate.generators.SimGenerator

Simulation generator for Poisson Background. Once initialized, a single deviate or many deviates can be generated:

gen = PoissonBackgroundGenerator(bkgd)

# generate a single deviate
next(gen)

# generate 10 deviates
[next(gen) for i in range(10)]

Parameters: bkgd (BackgroundSpectrum) – A modeled background spectrum
Yields: BackgroundSpectrum – A Poisson random deviate of the initialized spectrum

GaussianBackgroundGenerator¶

class gbm.simulate.generators.GaussianBackgroundGenerator(bkgd)[source]¶

Bases: gbm.simulate.generators.SimGenerator

Simulation generator for Gaussian Background. Once initialized, a single deviate or many deviates can be generated:

gen = GaussianBackgroundGenerator(bkgd)

# generate a single deviate
next(gen)

# generate 10 deviates
[next(gen) for i in range(10)]

Parameters: bkgd (BackgroundSpectrum) – A modeled background spectrum
Yields: BackgroundSpectrum – A Gaussian random deviate of the initialized spectrum

SourceSpectrumGenerator¶

class gbm.simulate.generators.SourceSpectrumGenerator(rsp, function, params, exposure)[source]¶

Bases: gbm.simulate.generators.SimGenerator

Simulation generator for a Poisson source spectrum. Once initialized, a single deviate or many deviates can be generated:

gen = SourceSpectrumGenerator(rsp, function params, exposure)

# generate a single deviate
next(gen)

# generate 10 deviates
[next(gen) for i in range(10)]

Parameters

rsp (RSP) – A detector response object
function (Function) – A photon model function
params (iterable) – The parameters for the function
exposure (float) – The source exposure

Yields

EnergyBins – A Poisson random deviate of the initialized source spectrum

VariablePoissonBackground¶

class gbm.simulate.generators.VariablePoissonBackground(bkgd)[source]¶

Bases: gbm.simulate.generators.PoissonBackgroundGenerator

Simulation generator for a variable Poisson Background. This non-homogeneous approximation allows the amplitude of the spectrum to be adjusted, thereby scaling the simulated counts. Once initialized, a single deviate or many deviates can be generated:

gen = VariablePoissonBackground(bkgd)

# generate a single deviate
next(gen)

# generate 10 deviates
[next(gen) for i in range(10)]

# change the amplitude to half of the initialized amplitude
gen.amp = 0.5

Parameters: bkgd (BackgroundSpectrum) – A modeled background spectrum
Attributes: amp (float) – The amplitude, relative to initialized spectrum. Setting amp=1 gives the initialized amplitude.
Yields: BackgroundSpectrum – A Poisson random deviate of the spectrum

VariableGaussianBackground¶

class gbm.simulate.generators.VariableGaussianBackground(bkgd)[source]¶

Bases: gbm.simulate.generators.GaussianBackgroundGenerator

Simulation generator for a variable Gaussian Background. This non-homogeneous approximation allows the amplitude of the spectrum to be adjusted, thereby scaling the simulated counts. Once initialized, a single deviate or many deviates can be generated:

gen = VariableGaussianBackground(bkgd)

# generate a single deviate
next(gen)

# generate 10 deviates
[next(gen) for i in range(10)]

# change the amplitude to twice of the initialized amplitude
gen.amp = 2.0

Parameters: bkgd (BackgroundSpectrum) – A modeled background spectrum
Attributes: amp (float) – The amplitude, relative to initialized spectrum. Setting amp=1 gives the initialized amplitude.
Yields: BackgroundSpectrum – A Gaussian random deviate of the spectrum

VariableSourceSpectrumGenerator¶

class gbm.simulate.generators.VariableSourceSpectrumGenerator(rsp, function, params, exposure)[source]¶

Bases: gbm.simulate.generators.SourceSpectrumGenerator

Simulation generator for a Poisson source spectrum, efficient for generating deviates when the source spectrum amplitude changes. Once initialized, a single deviate or many deviates can be generated:

gen = AmpFreeSourceSpectrumGenerator(rsp, function params, exposure)

# generate a single deviate
next(gen)

# generate 10 deviates
[next(gen) for i in range(10)]

# change amplitude, and generate a new deviate
gen.amp = 0.01
next(gen)

Parameters

rsp (RSP) – A detector response object
function (Function) – A photon model function
params (iterable) – The parameters for the function
exposure (float) – The source exposure

Attributes

amp (float) – The amplitude. This value can be set.

Yields

EnergyBins – A Poisson random deviate of the initialized source spectrum

EventSpectrumGenerator¶

class gbm.simulate.generators.EventSpectrumGenerator(count_spectrum, dt, min_sep=2e-06)[source]¶

Bases: gbm.simulate.generators.SimGenerator

Simulation generator producing Poisson arrival times for a source spectrum during a finite slice of time. Photon losses from deadtime and detection/electronic processes can be accounted for by setting the min_sep > 0. Once initialized, a single deviate or many deviates can be generated:

gen = EventSpectrumGenerator(spectrum, dt)

# generate a single deviate
next(gen)

# generate 10 deviates
[next(gen) for i in range(10)]

Parameters

count_spectrum (np.array) – An array of counts in each energy channel
dt (float) – The width of the time slice in seconds
min_sep (float, optional) – The minimum possible time separation between events. Default is 2e-6 seconds.

Attributes

spectrum (np.array) – The counts in each channel. This value can be set. The counts array will be converted to integer type.

Yields

(np.array, np.array) – The arrival times and energy channels for each event

Time-Profile Functions¶

These functions are provided to define the time profile of background and sources.

gbm.simulate.profiles.constant(x, amp)[source]¶

A constant background function.

Parameters

x (np.array) – Array of times
amp (float) – The background amplitude

Returns

np.array – The background evaluated at x times

gbm.simulate.profiles.linear(x, c0, c1)[source]¶

A linear background function.

Parameters

x (np.array) – Array of times
c0 (float) – The constant coefficient
c1 (float) – The linear coefficient

Returns

np.array – The background evaluated at x times

gbm.simulate.profiles.norris(x, amp, tstart, t_rise, t_decay)[source]¶

A Norris pulse-shape function:

\(I(t) = A \lambda e^{-\tau_1/t - t/\tau_2} \text{ for } t > 0;\\ \text{ where } \lambda = e^{2\sqrt(\tau_1/\tau_2)};\)

and where

\(A\) is the pulse amplitude
\(\tau_1\) is the rise time
\(\tau_2\) is the decay time

References

Norris, J. P., et al. 2005 ApJ 627 324

Parameters

x (np.array) – Array of times
amp (float) – The amplitude of the pulse
tstart (float) – The start time of the pulse
t_rise (float) – The rise timescal of the pulse
t_decay (flaot) – The decay timescale of the pulse

Returns

np.array – The Norris pulse shape evaluated at x times

gbm.simulate.profiles.quadratic(x, c0, c1, c2)[source]¶

A quadratic background function.

Parameters

x (np.array) – Array of times
c0 (float) – The constant coefficient
c1 (float) – The linear coefficient
c2 (float) – The quadratic coefficient

Returns

np.array – The background evaluated at x times

gbm.simulate.profiles.tophat(x, amp, tstart, tstop)[source]¶

A tophat (rectangular) pulse function.

Parameters

x (np.array) – Array of times
amp (float) – The tophat amplitude
tstart (float) – The start time of the tophat
tstop (float) – The end time of the tophat

Returns

np.array – The tophat evaluated at x times