redback.simulate_transients.SimulateHighEnergyTransient

class redback.simulate_transients.SimulateHighEnergyTransient(model, parameters, energy_edges, time_range, effective_area=100, background_rate=0.1, time_resolution=0.001, seed=42)

Bases: object

Simulate gamma-ray observations with photon counting statistics

This class generates realistic gamma-ray observations including: - Time-tagged events (TTE): Individual photon arrival times and energies - Binned photon counts: Count rates in time bins and energy channels - Energy-dependent detector response (effective area) - Background modeling (constant or time-varying) - Proper Poisson statistics for photon counting

Useful for: - GRB prompt emission (Fermi/GBM, Swift/BAT) - Magnetar bursts and flares - Pulsar timing - X-ray/gamma-ray afterglows - Fast transients requiring high time resolution

Parameters:

• model (str or callable) – Redback model name or callable function that returns flux density in mJy

• parameters (dict) – Dictionary of model parameters

• energy_edges (array-like) – Energy bin edges in keV (e.g., [10, 50, 100, 300, 1000])

• time_range (tuple) – (t_start, t_end) in seconds relative to trigger time

• effective_area (float, dict, or callable, optional) – Detector effective area in cm^2. Can be: - Float: Constant effective area for all energies - Dict: {energy_keV: area_cm2} mapping - Callable: function(energy_keV) -> area_cm2 Default: 100 cm^2 (typical for Fermi/GBM)

• background_rate (float, dict, or callable, optional) – Background count rate in counts/s/keV. Can be: - Float: Constant background for all energies - Dict: {energy_keV: rate} mapping - Callable: function(energy_keV) -> rate Default: 0.1 counts/s/keV

• time_resolution (float, optional) – Time resolution in seconds for sampling (default: 0.001 s = 1 ms)

• seed (int, optional) – Random seed for reproducibility

Examples

Basic GRB simulation:

>>> energy_edges = [10, 50, 100, 300, 1000]  # keV
>>> sim = SimulateHighEnergyTransient(
...     model='grb_afterglow',
...     parameters={'luminosity': 1e52, 'theta_core': 0.1, ...},
...     energy_edges=energy_edges,
...     time_range=(-1, 100),  # -1s to 100s
...     effective_area=120,  # cm^2
...     background_rate=0.1  # counts/s/keV
... )
>>> events = sim.generate_time_tagged_events()
>>> binned = sim.generate_binned_counts(time_bins=np.logspace(-1, 2, 50))

__init__(model, parameters, energy_edges, time_range, effective_area=100, background_rate=0.1, time_resolution=0.001, seed=42)

__call__(**kwargs)

Call self as a function.

Methods

__init__(model, parameters, energy_edges, ...)
generate_binned_counts(time_bins[, ...])	Generate binned photon counts
generate_time_tagged_events([max_events])	Generate time-tagged photon events (arrival times and energies)
save_binned_counts([filename])	Save binned counts to CSV
save_time_tagged_events([filename])	Save time-tagged events to CSV

generate_binned_counts(time_bins, energy_integrated=False)

Generate binned photon counts

Parameters:

• time_bins (array-like) – Time bin edges in seconds

• energy_integrated (bool, optional) – If True, return energy-integrated counts (single light curve) If False, return counts per energy channel (default)

Returns:

binned_data – DataFrame with columns: - ‘time_start’: Bin start time - ‘time_end’: Bin end time - ‘time_center’: Bin center time - ‘dt’: Bin width - ‘counts’: Total counts in bin - ‘counts_error’: Poisson error (sqrt(counts)) - ‘count_rate’: Count rate (counts/s) - ‘count_rate_error’: Count rate error - ‘energy_channel’: Energy channel index (if energy_integrated=False)

Return type:

pandas.DataFrame

generate_time_tagged_events(max_events=1000000)

Generate time-tagged photon events (arrival times and energies)

Uses thinning algorithm (Lewis & Shedler 1979) for non-homogeneous Poisson process to sample photon arrival times from the model light curve.

Parameters:

max_events (int, optional) – Maximum number of events to generate (safety limit)

Returns:

events – DataFrame with columns: - ‘time’: Photon arrival time (seconds) - ‘energy’: Photon energy (keV) - ‘energy_channel’: Energy channel index (0 to n_energy_bins-1) - ‘is_background’: Boolean indicating if event is from background

Return type:

pandas.DataFrame

save_binned_counts(filename='gamma_ray_binned')

Save binned counts to CSV

Parameters:

filename (str) – Base filename (without .csv extension)

save_time_tagged_events(filename='gamma_ray_events')

Save time-tagged events to CSV

Parameters:

filename (str) – Base filename (without .csv extension)