repeat_Grid

class zdm.repeat_grid.repeat_Grid(survey, state, zDMgrid, zvals, dmvals, smear_mask, wdist, prev_grid=None, opdir=None, Exact=True, MC=False, verbose=False)

Bases: Grid

This class is designed to take a p(z,DM) grid and calculate the effects of repeating FRBs.

It is an “add-on” to an existing grid class, i.e. it is passed an existing grid, and performs calculations from there.

Repetition parameters are contained within the grid object itself. Optionally, these can be sepcified as additional arguments at compilation.

Currently, only Poisson repeaters are enabled. This will change. Well, maybe…

Methods Summary

GenNReps(Rthresh, Nreps)	Samples N random FRB rates R above Rthresh
MCsample(Rthresh, Rmult[, doplots, tag])	Samples FRBs from Rthresh upwards
calcRmult([beam_b, time_days])	beam_b: value of sensitivity time: time spent on this pointing
calc_Rthresh([Exact, MC, Pthresh, doplots, old])	For FRBs on a zdm grid, calculate the repeater rates below which we can reasonably treat the distribution as continuous
calc_constant([verbose])	Calculates the constant of the repeating FRB function:
calc_exact_repeater_probability(Nreps, DM[, ...])	Calculates exact expected number of Nreps bursts from a repeater population We have this repeater at z-value z, DM value DM
calc_expected_repeat_bursts(expected_singles)	Calculates the expected total number of bursts from repeaters.
calc_expected_repeaters(expected_singles, ...)	Calculates the expected number of FRBs observed as repeaters.
calc_p_no_bursts(Tobs[, N1thresh, N3thresh])	calculates the chance that no bursts are observed in a given volume This is an integral over the repeater and luminosity distributions
calc_p_no_repeaters(Npointings)	Calculates the probability per volume that there are no progenitors there By default, does this for a single pointing AND all pointings combined Not currently used, might be in the future.
calc_singles_exactly()	Calculates exact expected number of single bursts from a repeater population
calc_stochastic_distance(p)	Calculates the distance out to which the chance of there being any progenitors becomes p, beyond which the chance is higher
calc_zeroes_exactly(singles)	Calculates the probability of observing zero bursts exactly
do_2D_plot(array, savename[, log, clabel, ...])	does a standard imshow
do_z_plot(array, savename[, log, label, ratio])	does a standard 1d plot projected onto the z axis
get_rep_prob_at_point(iz, idm, effGamma, ...)	Calculates the probability of getting a repeater at grid point
perform_exact_calculations([slow])	Performs exact calculations of:
sim_repeaters(Rthresh, beam_b, Solid[, ...])	Simulates once-off and repeat bursts for a given value of b (sensitivity) Rthresh: threshold in ergs on a z-DM grid beam_b: value of beam for this calculation solid: solid angle corresponding to beam value b MC: if True, performs MC evaluation.
slow_exact_calculation(exact_singles, ...[, ...])	Calculates exact expected number of single bursts from a repeater population
update(vparams[, ALL, prev_grid])	Routine to update based upon new Rmin,Rmax,gamma parameters.

Methods Documentation

GenNReps(Rthresh, Nreps)

Samples N random FRB rates R above Rthresh

CDF [integral Rstar to Rmax] = (R**Rgamma - Rthresh**gamma) / (Rmax**Rgamma - Rthresh**gamma)

MCsample(Rthresh, Rmult, doplots=False, tag=None)

Samples FRBs from Rthresh upwards

Rmult scales a repeater rate to an expected Nevents rate

Rthresh alrady has the Tfield baked into it. Rmult also has the Tfield baked into it.

volume_grid should be in units of Mpc^3, accounting for solid angle and dV/dz/dOmega

tag: only used if plotting

calcRmult(beam_b=1, time_days=1)

beam_b: value of sensitivity time: time spent on this pointing

We also need to account for the rate scaling if it exists.

calc_Rthresh(Exact=True, MC=False, Pthresh=0.01, doplots=False, old=[False, False, False])

For FRBs on a zdm grid, calculate the repeater rates below which we can reasonably treat the distribution as continuous

Steps:

• Calculate the apparent repetition threshold to ignore repetition

• Calculate rate scaling between energy at which repeat rates are defined, and energy threshold

Exact: if True, performs an “exact” analytic calculation of

the singles and repeater rates.

MC (bool or int): if bool and True, perform a single MC evaluation

if bool and False, use the analytic method if int >0: performs MC Monte Carlo evaluations

Pthresh: only if MC is true

threshold above which to allow progenitors to produce multilke bursts

Old defines which parameters (Rmin, Rmax, gamma) are being redone

calc_constant(verbose=False)

Calculates the constant of the repeating FRB function:

dPhi(R)/dR = Cr * (R/R0)^power between Rmin and Rmax. Here R0 is the unit of R, taken to be 1/day

The constant C is the constant burst rate at energy E0 per unit volume By definition, int_{R=Rmin}^{R=Rmax} R dPhi(R)/dR dR = C Hence, C=Cr * (power+2)^-1 (R_max^(power+2)-R_min^(power+2)) and thus Cr = C * (power+2)/(R_max^(power+2)-R_min^(power+2))

We also need to account for frequency dependence. The default frequency for FRB properties is 1.3 GHz. Under the rate approximation, the rate per repeater changes with frequency Under the spectral index approximation, FRBs become brighter/dimmer. This MUST therefore factor into calculations!

NOTE: if updating, in theory all steps before Rc = … could be held in memory

calc_exact_repeater_probability(Nreps, DM, z=None, verbose=False)

Calculates exact expected number of Nreps bursts from a repeater population We have this repeater at z-value z, DM value DM

INPUTS:

Nreps (int): Number of observed repetitions (>=2) DM (float): Extragalactic dispersion measure of the FRB z (float): Redshift of the FRB verbose (bool): if verbose output is required

Returns:

relative probability of observing an FRB with

Nreps given a repeater has been observed

Return type:

rel_prob (float)

MATH:

The singles probability is: int constant * R exp(-R) * R^(Rgamma)

where the factor “R exp(-R)” is Poisson(1) We now replace this with Poisson(N) = R^N exp(-R)/R!

The definition of gamma function is R^x-1 exp(-R) for gamma(x)

hence here x is gamma+N+1

This simply means we calculate a new gamma function at the relevant point

limits set by Rmin and Rmax (determind after multiplying intrinsic by Rmult) This is Gamma(Rgamma+N+1,Rmin) - Gamma(Rgamma+N+1,Rmax)

calc_expected_repeat_bursts(expected_singles)

Calculates the expected total number of bursts from repeaters.

This is simply calculated as <all bursts> - <single bursts>

calc_expected_repeaters(expected_singles, expected_zeros)

Calculates the expected number of FRBs observed as repeaters. The total expected number of observed repeaters is the total number of actual repeaters, minus those that are observed once, minus those observed not at all

calc_p_no_bursts(Tobs, N1thresh=0.1, N3thresh=10.0)

calculates the chance that no bursts are observed in a given volume This is an integral over the repeater and luminosity distributions

The chance of having no bursts is:

Outer integral over distribution of repeaters: int_Rmin ^ Rmax C_r R^gamma dV [] dR Inner integral

p(no bursts) = int (rate) p(no repeaters) + p(no bursts | repeaters) dR

The following gives the fraction of the total luminosity function visible

at any given distance. It has already been integrated over beamshape and width self.fractions

# breaks the calculation into many steps. These are:

# High repetition regime: chance of detecting an FRB given a repeater is 100% # Calculate pure chance of any FRB existing

# calculates the fraction of the luminosity function visible at any given distance calc_effective_rate()

calc_p_no_repeaters(Npointings)

Calculates the probability per volume that there are no progenitors there By default, does this for a single pointing AND all pointings combined Not currently used, might be in the future. Useful!

calc_singles_exactly()

Calculates exact expected number of single bursts from a repeater population

Probability is: int constant * R exp(-R) * R^(Rgamma) definition of gamma function is R^x-1 exp(-R) for gamma(x) # hence here x is gamma+2 limits set by Rmin and Rmax (determind after multiplying intrinsic by Rmult)

This is Gamma(Rgamma+2,Rmin) - Gamma(Rgamma+2,Rmax)

calc_stochastic_distance(p)

Calculates the distance out to which the chance of there being any progenitors becomes p, beyond which the chance is higher

calc_zeroes_exactly(singles)

Calculates the probability of observing zero bursts exactly

probability is: constant * exp(-R) * R^(Rgamma) definition of gamma function is R^x-1 exp(-R) for gamma(x) # hence here x is gamma+1 limits set by Rmin and Rmax (determind after multiplying intrinsic by Rmult)

This is Gamma(Rgamma+1,Rmin) - Gamma(Rgamma+1,Rmax)

do_2D_plot(array, savename, log=True, clabel='', lrange=4, zmax=1)

does a standard imshow

do_z_plot(array, savename, log=True, label='', ratio=False)

does a standard 1d plot projected onto the z axis

if ratio is True: divide all plots by the last one

get_rep_prob_at_point(iz, idm, effGamma, factorial)

Calculates the probability of getting a repeater at grid point

iz,idm with given number of repeates.

Key normalisation factors are missing and are added later

iz (int): index of redshift idm (int): index of dispersion measure eff_gamma (float): effective value of gamma for the integral factorial (floart): pre-computer factorial factor

perform_exact_calculations(slow=False)

Performs exact calculations of:

• <single bursts>

• <no bursts>

• < progenitors with N>2 bursts>

• < number of N>2 bursts>

sim_repeaters(Rthresh, beam_b, Solid, doplots=False, Exact=True, MC=False, Rmult=None)

Simulates once-off and repeat bursts for a given value of b (sensitivity) Rthresh: threshold in ergs on a z-DM grid beam_b: value of beam for this calculation solid: solid angle corresponding to beam value b MC: if True, performs MC evaluation. Skips if False doplots: plots a bunch of stuff if True

slow_exact_calculation(exact_singles, exact_zeroes, exact_rep_bursts, exact_reps, plot=True, zonly=True)

Calculates exact expected number of single bursts from a repeater population

Probability is: int constant * R exp(-R) * R^(Rgamma) definition of gamma function is R^x-1 exp(-R) for gamma(x) # hence here x is gamma+2 limits set by Rmin and Rmax (determind after multiplying intrinsic by Rmult)

This is Gamma(Rgamma+2,Rmin) - Gamma(Rgamma+2,Rmax)

update(vparams: dict, ALL=False, prev_grid=None)

Routine to update based upon new Rmin,Rmax,gamma parameters.

Inputs:

vparams (dict): dict containing the parameters

to be updated and their values

prev_grid (Grid, optional):

If provided, it is assumed this grid has been updated on items that need not be repeated for the current grid. i.e. Speed up!

ALL (bool, optional): If True, update the full grid

__init__(survey, state, zDMgrid, zvals, dmvals, smear_mask, wdist, prev_grid=None, opdir=None, Exact=True, MC=False, verbose=False)

Initialises repeater class :param Same as ‘grid.py’:

update(vparams: dict, ALL=False, prev_grid=None)

Routine to update based upon new Rmin,Rmax,gamma parameters.

Inputs:

vparams (dict): dict containing the parameters

to be updated and their values

prev_grid (Grid, optional):

If provided, it is assumed this grid has been updated on items that need not be repeated for the current grid. i.e. Speed up!

ALL (bool, optional): If True, update the full grid

calc_constant(verbose=False)

Calculates the constant of the repeating FRB function:

dPhi(R)/dR = Cr * (R/R0)^power between Rmin and Rmax. Here R0 is the unit of R, taken to be 1/day

The constant C is the constant burst rate at energy E0 per unit volume By definition, int_{R=Rmin}^{R=Rmax} R dPhi(R)/dR dR = C Hence, C=Cr * (power+2)^-1 (R_max^(power+2)-R_min^(power+2)) and thus Cr = C * (power+2)/(R_max^(power+2)-R_min^(power+2))

We also need to account for frequency dependence. The default frequency for FRB properties is 1.3 GHz. Under the rate approximation, the rate per repeater changes with frequency Under the spectral index approximation, FRBs become brighter/dimmer. This MUST therefore factor into calculations!

NOTE: if updating, in theory all steps before Rc = … could be held in memory

calc_Rthresh(Exact=True, MC=False, Pthresh=0.01, doplots=False, old=[False, False, False])

For FRBs on a zdm grid, calculate the repeater rates below which we can reasonably treat the distribution as continuous

Steps:

• Calculate the apparent repetition threshold to ignore repetition

• Calculate rate scaling between energy at which repeat rates are defined, and energy threshold

Exact: if True, performs an “exact” analytic calculation of

the singles and repeater rates.

MC (bool or int): if bool and True, perform a single MC evaluation

if bool and False, use the analytic method if int >0: performs MC Monte Carlo evaluations

Pthresh: only if MC is true

threshold above which to allow progenitors to produce multilke bursts

Old defines which parameters (Rmin, Rmax, gamma) are being redone

perform_exact_calculations(slow=False)

Performs exact calculations of:

• <single bursts>

• <no bursts>

• < progenitors with N>2 bursts>

• < number of N>2 bursts>

calc_expected_repeaters(expected_singles, expected_zeros)

Calculates the expected number of FRBs observed as repeaters. The total expected number of observed repeaters is the total number of actual repeaters, minus those that are observed once, minus those observed not at all

calc_expected_repeat_bursts(expected_singles)

Calculates the expected total number of bursts from repeaters.

This is simply calculated as <all bursts> - <single bursts>

calc_singles_exactly()

Calculates exact expected number of single bursts from a repeater population

Probability is: int constant * R exp(-R) * R^(Rgamma) definition of gamma function is R^x-1 exp(-R) for gamma(x) # hence here x is gamma+2 limits set by Rmin and Rmax (determind after multiplying intrinsic by Rmult)

This is Gamma(Rgamma+2,Rmin) - Gamma(Rgamma+2,Rmax)

calc_zeroes_exactly(singles)

Calculates the probability of observing zero bursts exactly

probability is: constant * exp(-R) * R^(Rgamma) definition of gamma function is R^x-1 exp(-R) for gamma(x) # hence here x is gamma+1 limits set by Rmin and Rmax (determind after multiplying intrinsic by Rmult)

This is Gamma(Rgamma+1,Rmin) - Gamma(Rgamma+1,Rmax)

calc_exact_repeater_probability(Nreps, DM, z=None, verbose=False)

Calculates exact expected number of Nreps bursts from a repeater population We have this repeater at z-value z, DM value DM

INPUTS:

Nreps (int): Number of observed repetitions (>=2) DM (float): Extragalactic dispersion measure of the FRB z (float): Redshift of the FRB verbose (bool): if verbose output is required

Returns:

relative probability of observing an FRB with

Nreps given a repeater has been observed

Return type:

rel_prob (float)

MATH:

The singles probability is: int constant * R exp(-R) * R^(Rgamma)

where the factor “R exp(-R)” is Poisson(1) We now replace this with Poisson(N) = R^N exp(-R)/R!

The definition of gamma function is R^x-1 exp(-R) for gamma(x)

hence here x is gamma+N+1

This simply means we calculate a new gamma function at the relevant point

limits set by Rmin and Rmax (determind after multiplying intrinsic by Rmult) This is Gamma(Rgamma+N+1,Rmin) - Gamma(Rgamma+N+1,Rmax)

get_rep_prob_at_point(iz, idm, effGamma, factorial)

Calculates the probability of getting a repeater at grid point

iz,idm with given number of repeates.

Key normalisation factors are missing and are added later

iz (int): index of redshift idm (int): index of dispersion measure eff_gamma (float): effective value of gamma for the integral factorial (floart): pre-computer factorial factor

slow_exact_calculation(exact_singles, exact_zeroes, exact_rep_bursts, exact_reps, plot=True, zonly=True)

Calculates exact expected number of single bursts from a repeater population

Probability is: int constant * R exp(-R) * R^(Rgamma) definition of gamma function is R^x-1 exp(-R) for gamma(x) # hence here x is gamma+2 limits set by Rmin and Rmax (determind after multiplying intrinsic by Rmult)

This is Gamma(Rgamma+2,Rmin) - Gamma(Rgamma+2,Rmax)

sim_repeaters(Rthresh, beam_b, Solid, doplots=False, Exact=True, MC=False, Rmult=None)

Simulates once-off and repeat bursts for a given value of b (sensitivity) Rthresh: threshold in ergs on a z-DM grid beam_b: value of beam for this calculation solid: solid angle corresponding to beam value b MC: if True, performs MC evaluation. Skips if False doplots: plots a bunch of stuff if True

calcRmult(beam_b=1, time_days=1)

beam_b: value of sensitivity time: time spent on this pointing

We also need to account for the rate scaling if it exists.

MCsample(Rthresh, Rmult, doplots=False, tag=None)

Samples FRBs from Rthresh upwards

Rmult scales a repeater rate to an expected Nevents rate

Rthresh alrady has the Tfield baked into it. Rmult also has the Tfield baked into it.

volume_grid should be in units of Mpc^3, accounting for solid angle and dV/dz/dOmega

tag: only used if plotting

GenNReps(Rthresh, Nreps)

Samples N random FRB rates R above Rthresh

CDF [integral Rstar to Rmax] = (R**Rgamma - Rthresh**gamma) / (Rmax**Rgamma - Rthresh**gamma)

do_2D_plot(array, savename, log=True, clabel='', lrange=4, zmax=1)

does a standard imshow

do_z_plot(array, savename, log=True, label='', ratio=False)

does a standard 1d plot projected onto the z axis

if ratio is True: divide all plots by the last one

calc_p_no_repeaters(Npointings)

Calculates the probability per volume that there are no progenitors there By default, does this for a single pointing AND all pointings combined Not currently used, might be in the future. Useful!

calc_stochastic_distance(p)

Calculates the distance out to which the chance of there being any progenitors becomes p, beyond which the chance is higher

calc_p_no_bursts(Tobs, N1thresh=0.1, N3thresh=10.0)

calculates the chance that no bursts are observed in a given volume This is an integral over the repeater and luminosity distributions

The chance of having no bursts is:

Outer integral over distribution of repeaters: int_Rmin ^ Rmax C_r R^gamma dV [] dR Inner integral

p(no bursts) = int (rate) p(no repeaters) + p(no bursts | repeaters) dR

The following gives the fraction of the total luminosity function visible

at any given distance. It has already been integrated over beamshape and width self.fractions

# breaks the calculation into many steps. These are:

# High repetition regime: chance of detecting an FRB given a repeater is 100% # Calculate pure chance of any FRB existing

# calculates the fraction of the luminosity function visible at any given distance calc_effective_rate()