Event counting

Countrate

class Countrate : public IteratorBase

Measures the average count rate on one or more channels. Specifically, it determines the counts per second on the specified channels starting from the very first tag arriving after the instantiation or last call to clear() of the measurement. The Countrate works correctly even when the USB transfer rate or backend processing capabilities are exceeded.

See all common methods

Public Functions

Countrate(TimeTaggerBase tagger, channel_t[] channels)

Parameters:

• tagger – Time tagger object instance.

• channels – Channels for which the average count rate is measured.

float[] getData()

Returns:

Average count rate in counts per second.

int[] getCountsTotal()

Returns:

The total number of events since the instantiation of this object.

Counter

class Counter : public IteratorBase

Time trace of the count rate on one or more channels. Specifically, this measurement repeatedly counts tags within a time interval binwidth and stores the results in a two-dimensional array of size number of channels by n_values. The incoming data is first accumulated in a not-accessible bin. When the integration time of this bin has passed, the accumulated data is added to the internal buffer, which can be accessed via the getData… methods. Data stored in the internal circular buffer is overwritten when n_values are exceeded. You can prevent this by automatically stopping the measurement in time as follows counter.startFor(duration=binwidth*n_values).

See all common methods

Public Functions

Counter(TimeTaggerBase tagger, channel_t[] channels, timestamp_t binwidth = 1000000000, int n_values = 1)

Parameters:

• tagger – Time tagger object.

• channels – Channels used for counting tags.

• binwidth – Bin width in ps (default: 1e9).

• n_values – Number of bins (default: 1).

int[,] getData(bool rolling = true)

Returns an array of accumulated counter bins for each channel. The optional parameter rolling, controls if the not integrated bins are padded before or after the integrated bins.

When rolling=True, the most recent data is stored in the last bin of the array and every new completed bin shifts all other bins right-to-left. When continuously plotted, this creates an effect of rolling trace plot. For instance, it is useful for continuous monitoring of countrate changes over time.

When rolling=False, the most recent data is stored in the next bin after previous such that the array is filled up left-to-right. When array becomes full and the Counter is still running, the array index will be reset to zero and the array will be filled again overwriting previous values. This operation is sometimes called “sweep plotting”.

Parameters:

rolling – Controls how the counter array is filled (default: True).

Returns:

An array of size number of channels by n_values containing the counts in each fully integrated bin.

timestamp_t[] getIndex()

Returns the relative time of the bins in ps. The first entry of the returned vector is always 0.

Returns:

A vector of size n_values containing the time bins in ps.

float[,] getDataNormalized(bool rolling = true)

Does the same as getData() but returns the count rate in Hz as a float. Not integrated bins and bins in overflow mode are marked as NaN.

Parameters:

rolling – Controls how the counter array is filled (default: True).

Returns:

An array of size number of channels by n_values containing the count rate in Hz as a float in each fully integrated bin.

int[] getDataTotalCounts()

Returns total number of events per channel since the last call to clear(), excluding the currently integrating bin. This method works correctly even when the USB transfer rate or backend processing capabilities are exceeded.

Returns:

Number of events per channel.

CounterData getDataObject(bool remove = false)

Returns CounterData object containing a snapshot of the data accumulated in the Counter at the time this method is called.

Parameters:

remove – Controls if the returned data shall be removed from the internal buffer (default: False).

Returns:

A CounterData object providing access to a snapshot data.

class CounterData

Objects of this class are created and returned by Counter::getDataObject(), and contain a snapshot of the data accumulated by the Counter measurement.

Public Functions

timestamp_t[] getIndex()

Returns the relative time of the bins in ps. The first entry of the returned vector is always 0 for size() > 0.

Returns:

A vector of size size() containing the relative time bins in ps.

int[,] getData()

Returns:

An array of size number of channels by size() containing only fully integrated bins.

float[,] getDataNormalized()

Does the same as getData() but returns the count rate in Hz. Bins in overflow mode are marked as NaN.

Returns:

An array of size number of channels by size() containing the count rate in Hz as a float only for fully integrated bins.

float[,] getFrequency(timestamp_t time_scale = 1000000000000)

Returns the counts normalized to the specified time scale. Bins in overflow mode are marked as NaN.

Parameters:

time_scale – Scales the return value to this time interval. Default is 1 s, so the return value is in Hz. For negative values, the time scale is set to binwidth.

Returns:

An array of size number of channels by size() containing the counts normalized to the specified time scale.

int[] getDataTotalCounts()

Returns the total number of events per channel since the last call to IteratorBase::clear(), excluding the counts of the internal bin where data is currently integrated into. This method works correctly even when the USB transfer rate or backend processing capabilities are exceeded.

Returns:

Number of events per channel.

timestamp_t[] getTime()

This is similar to getIndex() but it returns the absolute timestamps of the bins. For subsequent calls to Counter::getDataObject, these arrays can be concatenated to obtain a full index array.

Returns:

A vector of size size() containing the time corresponding to the return value of getData() in ps.

int[] getOverflowMask()

Array of values for each bin that indicate if an overflow occurred during accumulation of the respective bin.

Returns:

An array of size size() containing overflow mask.

Public Members

int size

Number of returned bins.

int dropped_bins

Number of bins which have been dropped because n_values of the Counter measurement has been exceeded.

bool overflow

Status flag for whether any of the returned bins have been in overflow mode.

GatedCounter

class GatedCounter : public IteratorBase

Counts events on a list of channels within the time indicated by “start” and “stop” signals. The bin edges between which counts are accumulated are determined by one or more hardware triggers. Specifically, the measurement records data into an array of shape number of channels by n_values (initially filled with zeros). It waits for tags on the begin_channel. When a tag is detected on the begin_channel, it starts counting tags on all click_channels. When the next tag is detected on the begin_channel, it stores the current counter values (one per click channel) as the next column in the data array, resets the counter to zero and starts accumulating counts again. If an end_channel is specified, the measurement stores the current counter values and resets the counters when a tag is detected on the end_channel rather than the begin_channel. You can use this, e.g., to accumulate counts within a gate by using rising edges on one channel as the begin_channel and falling edges on the same channel as the end_channel. The accumulation time for each value can be accessed via getBinWidths(). The measurement stops when all entries in the data array are filled.

See all common methods

Public Functions

GatedCounter(TimeTaggerBase tagger, channel_t[] click_channels, channel_t begin_channel, channel_t end_channel = CHANNEL_UNUSED, int n_values = 1000)

Parameters:

• tagger – Time tagger object.

• click_channels – Channels on which clicks are received, gated by begin_channel and end_channel.

• begin_channel – Channel that triggers the beginning of counting and stepping to the next value.

• end_channel – Channel that triggers the end of counting (optional, default: CHANNEL_UNUSED)

• n_values – Number of values stored (data buffer size) (default: 1000)

int[,] getData()

Returns:

Array of size number of channels by n_values containing the acquired counter values.

timestamp_t[] getIndex()

Returns:

Vector of size n_values containing the time in ps of each start click in respect to the very first start click.

timestamp_t[] getBinWidths()

Returns:

Vector of size n_values containing the time differences of ‘start -> (next start or stop)’ for the acquired counter values.

bool ready()

Returns:

True when the entire array is filled.

class CountBetweenMarkers : public IteratorBase

Same as GatedCounter, but for a single click_channel only.

Deprecated:

Since version 2.22. Please use the multi-channel class GatedCounter instead.

Public Functions

CountBetweenMarkers(TimeTaggerBase tagger, channel_t click_channel, channel_t begin_channel, channel_t end_channel = CHANNEL_UNUSED, int n_values = 1000)

Parameters:

• tagger – Time tagger object.

• click_channel – Channel on which clicks are received, gated by begin_channel and end_channel.

• begin_channel – Channel that triggers the beginning of counting and stepping to the next value.

• end_channel – Channel that triggers the end of counting (optional, default: CHANNEL_UNUSED)

• n_values – Number of values stored (data buffer size) (default: 1000)

int[] getData()

Returns:

Array of size n_values containing the acquired counter values.

timestamp_t[] getIndex()

Returns:

Vector of size n_values containing the time in ps of each start click in respect to the very first start click.

timestamp_t[] getBinWidths()

Returns:

Vector of size n_values containing the time differences of ‘start -> (next start or stop)’ for the acquired counter values.

bool ready()

Returns:

True when the entire array is filled.