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