NuRadioReco.modules.analogToDigitalConverter module

NuRadioReco.modules.analogToDigitalConverter.perfect_comparator(trace, adc_n_bits, adc_voltage_range, output='voltage', mode_func=<ufunc 'floor'>)

Simulates a perfect comparator flash ADC that compares the voltage to the voltage for the least significative bit and takes the floor or the ceiling of their ratio as a digitised value of the trace.

Parameters:

trace: array of floats

Trace containing the voltage to be digitised

adc_n_bits: int

Number of bits of the ADC

adc_voltage_range: (float, float)

Is a tuple (Vmin, Vmax) defining the “full scale” voltage range where V_max corresponds to the maximum number of counts given by the ADC 2**adc_n_bits - 1 and V_min to the ADC count 0.

output: {‘voltage’, ‘counts’}, default ‘voltage’

Options:

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

• ‘counts’ to store the ADC output in ADC counts

mode_func: callable

Either np.floor or np.ceil to choose the mode of the comparator

Returns:

digital_trace: array of floats

Digitised voltage trace in volts or ADC counts

Notes

There is often some ambiguity in the definition of the “Least Significant Bit” (i.e., resolution) for an ADC. People either define it as lsb = V / 2^n or lsb = V / (2^n - 1). As you can see we are adopting the latter. The ambiguity comes from an amibguity of what the symbol V in the prev. equations acutally is. The following link provides an explanation [1]. In short: If you divide by 2^n, V refers to a reference voltage which can never be reached. If you divide by 2^n - 1 V refers to the “full scale” voltage which can be reached. How your ADC works will be defined in its datasheet.

[1]: https://masteringelectronicsdesign.com/an-adc-and-dac-least-significant-bit-lsb/

NuRadioReco.modules.analogToDigitalConverter.perfect_floor_comparator(*args, **kwargs)

Perfect comparator ADC that takes the floor value of the comparison. See perfect_comparator

NuRadioReco.modules.analogToDigitalConverter.perfect_ceiling_comparator(*args, **kwargs)

Perfect comparator ADC that takes the floor value of the comparison. See perfect_comparator.

NuRadioReco.modules.analogToDigitalConverter.apply_saturation(adc_counts_trace, adc_n_bits)

Takes a digitised trace in ADC counts and clips the parts of the trace with values higher than 2**adc_n_bits - 1 or lower than 0.

Parameters:

adc_counts_trace: array of floats

Voltage in ADC counts, unclipped

adc_n_bits: int

Number of bits of the ADC

Returns

——-

saturated_trace: array of floats

The clipped or saturated voltage trace

class NuRadioReco.modules.analogToDigitalConverter.analogToDigitalConverter(log_level=0)

Bases: object

This class simulates an analog to digital converter. The steps followed by this module to achieve the conversion are:

1. The following properties of the channel are read. They must be in the

   detector configuration file:

   • “adc_nbits”, the number of bits of the ADC

   • “adc_reference_voltage”, the reference voltage in volts, that is, the

     maximum voltage the ADC can convert without saturating

   • “adc_sampling_frequency”, the sampling frequency in GHz

2. A random clock offset (jitter) can be added, as it would happen in

   a real experiment. Choose random_clock_offset = True to do so. A time delay can also be fixed if the field “adc_time_delay” is specified in ns. The channel trace is interpolated to get the trace values at the clock times displaced from the channel times. This is fine as long as the input channel traces have been simulated with a sampling rate greater than the ADC sampling rate, which should be the case. Upsampling is also possible, and recommended for phased array simulations.

   Important

   Upsampling after digitisation is performed by the FPGA, which means that the digitised trace is no longer discretised after being upsampled. The FPGA uses fixed point arithmetic, which in practice can be approximated as floats for our simulation purposes.

3. A type of ADC converter is chosen, which transforms the trace in ADC

   counts (discrete values). The available types are listed in the list _adc_types, which are (see functions with the same names for documentation):

   • ‘perfect_floor_comparator’

   • ‘perfect_ceiling_comparator’

Important

Since this module already performs a downsampling, there is no need to use the channelResampler in those channels that possess an ADC. The chosen method for resampling is interpolation, since filtering only the spectrum below half the sampling frequency would eliminate the higher Nyquist zones.

Note that after this module the traces are still expressed in voltage units, only the possible values are discretised.

If the ADC is used for triggering and the user does not want to modify the trace, the function get_digital_trace can be used. If there are two different ADCs for the same channel, one for triggering and another one for storing, one can define a trigger ADC adding “trigger_” to every relevant ADC field in the detector configuration, and use them setting trigger_adc to True in get_digital_trace.

Methods

get_digital_trace(station, det, channel[, ...])	Returns the digital trace for a channel, without setting it.
run(evt, station, det[, clock_offset, ...])	Runs the analogToDigitalConverter and transforms the traces from all the channels of an input station to digital voltage values.

end

get_digital_trace(station, det, channel, Vrms=None, trigger_adc=False, clock_offset=0.0, adc_type='perfect_floor_comparator', return_sampling_frequency=False, adc_output='voltage', trigger_filter=None, adc_baseline_voltage=0)

Returns the digital trace for a channel, without setting it. This allows the creation of a digital trace that can be used for triggering purposes without removing the original information on the channel.

Parameters:

station: framework.station.Station object

det: detector.detector.Detector object

channel: framework.channel.Channel object

Vrms: float

If supplied, overrides adc_reference_voltage as supplied in the detector description file

trigger_adc: bool

If True, the relevant ADC parameters in the config file are the ones that start with ‘trigger_’

random_clock_offset: bool

If True, a random clock offset between -1 and 1 clock cycles is added

adc_type: string

The type of ADC used. The following are available:

• perfect_floor_comparator

• perfect_ceiling_comparator

See functions with the same name on this module for documentation

return_sampling_frequency: bool

If True, returns the trace and the ADC sampling frequency

adc_output: string

Options:

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

• ‘counts’ to store the ADC output in ADC counts

trigger_filter: array of floats

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

adc_baseline_voltage: float (default: 0 V)

The baseline voltage to be added to the trace before digitisation.

Returns:

digital_trace: array of floats

Digitised voltage trace

adc_sampling_frequency: float

ADC sampling frequency for the channel

run(evt, station, det, clock_offset=0.0, adc_type='perfect_floor_comparator', adc_output='voltage', trigger_filter=None, adc_baseline_voltage=0)

Runs the analogToDigitalConverter and transforms the traces from all the channels of an input station to digital voltage values.

Parameters:

evt: framework.event.Event object

station: framework.station.Station object

det: detector.detector.Detector object

clock_offset: float

adc_type: string

The type of ADC used. The following are available:

• ‘perfect_floor_comparator’

See functions with the same name on this module for documentation

adc_output: string

Options:

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

• ‘counts’ to store the ADC output in ADC counts

trigger_filter: array of floats

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

adc_baseline_voltage: float (default: 0 V)

The baseline voltage to be added to the trace before digitisation.

end()

NuRadioReco.modules.analogToDigitalConverter.downsampling_linear_interpolation(trace, sampling_rate, new_sampling_rate)

Downsamples a trace using linear interpolation.

Parameters:

trace: array of floats

The trace to be downsampled

sampling_rate: float

The sampling rate of the input trace

new_sampling_rate: float

The sampling rate of the output trace

Returns:

times_downsampled: array of floats

The times of the downsampled trace (without start time)

downsampled_trace: array of floats

The downsampled trace

NuRadioReco.modules.analogToDigitalConverter.apply_filter(channel, filter)

Applies a filter to a trace in the frequency domain.

Parameters:

channel: `NuRadioReco.framework.channel.Channel` object

The (channel) trace to be filtered

filter: array of floats

The filter to be applied