NuRadioReco.modules.phasedarray.beamformedPowerIntegrationTrigger module

class NuRadioReco.modules.phasedarray.beamformedPowerIntegrationTrigger.BeamformedPowerIntegrationTrigger(log_level=0)[source]

Bases: PhasedArrayBase

Calculates the trigger for a phased array with primary beam locations using a power integrated envelope. This module allows access to lower level options used during trigger calculations that allow for realistic models of firmware, such as upsampling with FIR filters and integer math specifics like rounding and saturation.

See https://arxiv.org/pdf/1809.04573.pdf

Methods

`calculate_time_delays`(station, det, ...[, ...])	Calculates the delays needed for phasing the array.
`check_vertical_string`(station, det, ...)	Checks if the triggering antennas lie in a straight vertical line Throws error if not.
`get_channel_trace_start_time`(station, ...)	Finds the start time of the desired traces.
`get_traces`(station, det[, ...])	Get the traces from the station object
`phase_signals`(traces, beam_rolls[, ...])	Phase signals together given the rolls
`phased_trigger`(station, det[, threshold, ...])	simulates phased array trigger for each event
`power_sum`(coh_sum, window, step[, ...])	Calculate power summed over a length defined by 'window', overlapping at intervals defined by 'step'
`run`(evt, station, det[, Vrms, threshold, ...])	simulates phased array trigger for each event

begin
hilbert_envelope

run(evt, station, det, Vrms=None, threshold=0.06, triggered_channels=None, trigger_name='simple_phased_threshold', phasing_angles=array([-9.59931089e-01, -7.14608352e-01, -5.13801244e-01, -3.33826648e-01, -1.64572284e-01, 1.11022302e-16, 1.64572284e-01, 3.33826648e-01, 5.13801244e-01, 7.14608352e-01, 9.59931089e-01]), set_not_triggered=False, ref_index=1.75, trigger_adc=False, clock_offset=0, adc_output='voltage', trigger_filter=None, upsampling_factor=1, window=32, averaging_divisor=None, step=16, apply_digitization=True, upsampling_method='fft', coeff_gain=128, filter_taps=45, saturation_bits=8, return_n_triggers=False, **kwargs)[source]

simulates phased array trigger for each event

Several channels are phased by delaying their signals by an amount given by a pointing angle. Several pointing angles are possible in order to cover the sky. The array triggered_channels controls the channels that are phased, according to the angles phasing_angles.

Parameters:

evt: Event object

Description of the current event

station: Station object

Description of the current station

det: Detector object

Description of the current detector

Vrms: float

RMS of the noise on a channel, used to automatically create the digitizer reference voltage. If set to None, tries to use reference voltage as defined int the detector description file.

threshold: float

threshold above (or below) a trigger is issued, absolute amplitude

triggered_channels: array of ints

channels ids of the channels that form the primary phasing array if None, all channels are taken

trigger_name: string

name for the trigger

phasing_angles: array of float

pointing angles for the primary beam

set_not_triggered: bool (default False)

if True not trigger simulation will be performed and this trigger will be set to not_triggered

ref_index: float (default 1.75)

refractive index for beam forming

trigger_adc: bool, (default True)

If True, uses the ADC settings from the trigger. It must be specified in the detector file. See analogToDigitalConverter module for information

clock_offset: float (default 0)

Overall clock offset, for adc clock jitter reasons

adc_output: string (default ‘voltage’)

‘voltage’ to store the ADC output as discretised voltage trace
‘counts’ to store the ADC output in ADC counts

trigger_filter: array floats (default None)

Freq. domain of the response to be applied to post-ADC traces Must be length for “MC freq”

upsampling_factor: integer (default 1)

Upsampling factor. The trace will be a upsampled to a sampling frequency int_factor times higher than the original one after conversion to digital

window: int (default 32)

Power integration window for averaging Units of ADC time ticks

averaging_divisor: int (default 32)

Power integral divisor for averaging (division by 2^n much easier in firmware) Units of ADC time ticks

step: int (default 16)

Time step in power integral. If equal to window, there is no time overlap in between neighboring integration windows. Units of ADC time ticks

apply_digitization: bool (default True)

Perform the quantization of the ADC. If set to true, should also set options trigger_adc, adc_output, clock_offset

upsampling_method: str (default ‘fft’)

Choose between FFT, FIR, or Linear Interpolaion based upsampling methods

coeff_gain: int (default 1)

If using the FIR upsampling, this will convert the floating point output of the scipy filter to a fixed point value by multiplying by this factor and rounding to an int.

filter_taps: int (default 45)

If using FIR upsampling these are the number of filter coefficients

saturation_bits: int (default 8)

If using counts, determines how large the coherently summed waveforms will saturate

return_n_triggers: bool (default False)

To better estimate simulated thresholds one should count the total triggers in the entire trace for each beam. If true, this return the total trigger number.

Returns:

is_triggered: bool: True if the triggering condition is met
n_triggers: int (Optional): Count of the total number of triggers in all beamformed traces

begin(debug=False, pre_trigger_time=100)

calculate_time_delays(station, det, triggered_channels, phasing_angles=None, ref_index=1.75, sampling_frequency=None)

Calculates the delays needed for phasing the array.

Parameters:

station: Station object: Description of the current station
det: Detector object: Description of the current detector
triggered_channels: array of ints: channels ids of the channels that form the primary phasing array if None, all channels are taken
phasing_angles: array of float: pointing angles for the primary beam
ref_index: float: refractive index for beam forming
sampling_frequency: float: Rate of the ADC used

Returns:

beam_rolls: array of dicts of keys=antenna and content=delay

check_vertical_string(station, det, triggered_channels)

Checks if the triggering antennas lie in a straight vertical line Throws error if not.

Parameters:

station: Station object: Description of the current station
det: Detector object: Description of the current detector
triggered_channels: array of ints: channels ids of the channels that form the primary phasing array if None, all channels are taken

get_channel_trace_start_time(station, triggered_channels)

Finds the start time of the desired traces. Throws an error if all the channels dont have the same start time.

Parameters:

station: Station object: Description of the current station
triggered_channels: array of ints: channels ids of the channels that form the primary phasing array if None, all channels are taken

Returns:

channel_trace_start_time: float: Channel start time

get_traces(station, det, triggered_channels=None, apply_digitization=False, adc_kwargs={}, upsampling_kwargs={})

Get the traces from the station object

Parameters:

station: Station object: Description of the current station
det: Detector object: Description of the current detector
triggered_channels: array of ints (default: None): channels ids of the channels that form the primary phasing array if None, all channels are taken
apply_digitization: bool: If True, the traces are digitized
adc_kwargs: dict: Keyword arguments for the ADC
upsampling_kwargs: dict: Keyword arguments for the upsampling function

Returns:

traces: 2D array of floats: Signals from the antennas to be phased together.
sampling_frequency: float: Sampling frequency of the traces

hilbert_envelope(coh_sum, adc_output='voltage', ideal_transformer=False, hilbert_n_taps=31, hilbert_coeff_gain=1)

phase_signals(traces, beam_rolls, adc_output='voltage', saturation_bits=None)

Phase signals together given the rolls

Parameters:

traces: 2D array of floats: Signals from the antennas to be phased together.
beam_rolls: 2D array of floats: The amount to shift each signal before phasing the traces together

Returns:

phased_traces: array of arrays

phased_trigger(station, det, threshold=0.06, triggered_channels=None, phasing_angles=array([-9.59931089e-01, -7.14608352e-01, -5.13801244e-01, -3.33826648e-01, -1.64572284e-01, 1.11022302e-16, 1.64572284e-01, 3.33826648e-01, 5.13801244e-01, 7.14608352e-01, 9.59931089e-01]), ref_index=1.75, apply_digitization=False, adc_kwargs={'adc_output': 'voltage'}, upsampling_kwargs={'coeff_gain': 128, 'filter_taps': 31, 'upsampling_factor': 1, 'upsampling_method': 'fft'}, saturation_bits=8, window=32, step=16, averaging_divisor=None, hilbert_transformer_kwargs={'hilbert_coeff_gain': 128, 'hilbert_n_taps': 31, 'ideal_transformer': False}, mode='power_sum')

simulates phased array trigger for each event

Several channels are phased by delaying their signals by an amount given by a pointing angle. Several pointing angles are possible in order to cover the sky. The array triggered_channels controls the channels that are phased, according to the angles phasing_angles.

Parameters:

station: Station object

Description of the current station

det: Detector object

Description of the current detector

threshold: float

threshold above (or below) a trigger is issued, absolute amplitude

triggered_channels: array of ints

channels ids of the channels that form the primary phasing array if None, all channels are taken

phasing_angles: array of float

pointing angles for the primary beam

ref_index: float (default 1.75)

refractive index for beam forming

apply_digitization: bool (default False)

Perform the quantization with the analogToDigitalConverter module.

adc_kwargs: dict

Keyword arguments for the ADC module. Only used if apply_digitization == True. For arguments, see the documentation of the analogToDigitalConverter module.

upsampling_kwargs: dict

For arguments, see the documentation of the digital_upsampling function

saturation_bits: int (default None)

Determines what the coherenty summed waveforms will saturate to if using adc counts

window: int (default 32)

Power integration window for averaging Units of ADC time ticks

step: int (default 16)

Time step in power integral. If equal to window, there is no time overlap in between neighboring integration windows. Units of ADC time ticks

averaging_divisor: int (default 32)

Power integral divisor for averaging (division by 2^n much easier in firmware) Units of ADC time ticks

ideal_transformer: bool (default False)

If true, use scipy.hilbert to compute an exact Hilbert envelope with scipy.hilbert and np.sqrt. Otherwise, a firmware-like FIR-based Hilbert transformer will be used and with an approximation function to a square root to calculate the envelope.

hilbert_n_taps: int (defult 31)

Number of taps used to construct the FIR-based Hilbert transformer

hilbert_coeff_gain: int (default 128)

Rescaling factor to quantize the FIR-based Hilbert transformer

mode: string (default: “power_sum”)

The mode of the trigger. Can be either “power_sum” or “hilbert_env”.

“power_sum”: uses the power_sum method to calculate the trigger

“hilbert_env”: uses the hilbert envelope method to calculate the trigger

Returns:

is_triggered: bool: True if the triggering condition is met
trigger_delays: dictionary: the delays for the primary channels that have caused a trigger. If there is no trigger, it’s an empty dictionary
trigger_time: float: the earliest trigger time with respect to first interaction time.
trigger_times: dictionary: all time bins that fulfil the trigger condition per beam. The key is the beam number. Time with respect to first interaction time.
maximum_amps: list of floats (length equal to that of phasing_angles): the maximum value of all the integration windows for each of the phased waveforms
n_trigs: int: total number of triggers that happened for all beams across the full traces
triggered_beams: list: list of bools for which beams triggered

power_sum(coh_sum, window, step, adc_output='voltage', averaging_divisor=None)

Calculate power summed over a length defined by ‘window’, overlapping at intervals defined by ‘step’

Parameters:

coh_sum: array of floats

Phased signal to be integrated over

window: int

Power integral window Units of ADC time ticks

step: int

Time step in power integral. If equal to window, there is no time overlap in between neighboring integration windows Units of ADC time ticks.

adc_output: string

Options:

‘voltage’ to store the ADC output as discretised voltage trace

‘counts’ to store the ADC output in ADC counts

averaging_divisor: int (default None)

Power integral divisor for averaging. If not specified, the divisor is the same as the summation window.

Returns:

power:: Integrated power in each integration window
num_frames: Number of integration windows calculated