NuRadioReco.modules.phasedarray.phasedArrayTrigger module

class NuRadioReco.modules.phasedarray.phasedArrayTrigger.PhasedArrayTrigger(log_level=0)

Bases: PhasedArrayBase

Calculates the trigger for a phased array with primary beam locations using a power integrated envelope. This module maintains the legacy interface and performs ideal calculations in upsampling, beamforming, and power averaging.

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
end
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, step=16, apply_digitization=True, return_n_triggers=False)

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, no 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 integral window 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

Returns:

is_triggered: bool

True if the triggering condition is met

end()

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