Measurement Classes

The Time Tagger library includes several classes that implement various measurements. All measurements are derived from a base class called IteratorBase that is described further down. As the name suggests, it uses the iterator programming concept.

All measurements provide a set of methods to start and stop the execution and to access the accumulated data. In a typical application, the following steps are performed (see example):

Create an instance of a measurement
Wait for some time
Retrieve the data accumulated by the measurement by calling a .getData() method.

Available measurement classes

Note

In MATLAB, the Measurement names have common prefix TT*. For example: Correlation is named as TTCorrelation. This prevents possible name collisions with existing MATLAB or user functions.

Correlation: Computes auto- and cross-correlations between channels.
CountBetweenMarkers: Counts events on a channel within gates defined by one or two marker channels.
Counter: Counts events on one or more channels using fixed-width bins and a circular buffer output.
Countrate: Measures the average event rate on one or more channels.
Dump: Deprecated - please use FileWriter instead. Writes raw time-tags to file in an uncompressed binary format.
FileReader: Reads time-tags from a compressed file written by the FileWriter measurement.
FileWriter: Writes time-tags into a file with a lossless compression. It replaces the Dump class.
Flim: Measures time histograms for fluorescence lifetime imaging.
FrequencyCounter: Measures frequency and phase evolution of periodic signals at periodic sampling intervals.
FrequencyStability: Analyzes the frequency stability of periodic signals at different time scales.
Histogram: Accumulates a histogram of time differences between two channels.
Histogram2D: Accumulates a 2D histogram of correlated time differences.
HistogramLogBins: Accumulates a histogram of time differences using logarithmic binning.
HistogramND: Accumulates an N-dimensional histogram of time differences.
IteratorBase: Provides a base class for implementing custom measurements.
PulsePerSecondMonitor: Monitors the timing and stability of 1 pulse-per-second (PPS) signals.
Sampler: Samples the digital state of channels triggered by another channel.
Scope: Detects signal edges for visualization, similar to a ultrafast logic analyzer.
StartStop: Accumulates a histogram of start-stop time differences between two channels.
SynchronizedMeasurements: Synchronizes multiple measurement instances for parallel acquisition and control.
TimeDifferences: Accumulates histograms of time differences between two channels, optionally swept using one or two trigger channels.
TimeDifferencesND: Accumulates multi-dimensional histograms of asynchronous time differences.
TimeTagStream: Provides low-level access to the raw time-tag stream for custom processing. See Raw Time-Tag-Stream access to get on overview about the possibilities for the raw time-tag-stream access.

Common methods

class IteratorBase

void clear(): Discards accumulated measurement data, initializes the data buffer with zero values, and resets the state to the initial state.

void start(): Starts or continues data acquisition. This method is implicitly called when a measurement object is created.

void startFor(timestamp_t capture_duration, bool clear = true)

Starts or continues the data acquisition for the given duration (in ps). After the duration time, the method stop() is called and isRunning() will return False. Whether the accumulated data is cleared at the beginning of startFor() is controlled with the second parameter clear, which is True by default.

Parameters:

capture_duration – Acquisition duration in picoseconds.
clear – Resets the accumulated data at the beginning (default: True).

void stop(): After calling this method, the measurement will stop processing incoming tags. Use start() or startFor() to continue or restart the measurement.

void abort(): Immediately aborts the measurement, discarding accumulated measurement data, and resets the state to the initial state.

Warning

After calling abort(), the last block of data might become irreversibly corrupted. Please always use stop() to end a measurement.

bool isRunning()

Returns True if the measurement is collecting the data. This method will return False if the measurement was stopped manually by calling stop() or automatically after calling startFor() and the duration has passed.

Note

All measurements start accumulating data immediately after their creation.

Returns:: True if the measurement is still running.

bool waitUntilFinished(int timeout = -1)

Blocks the execution until the measurement has finished. Can be used with startFor(). This is roughly equivalent to a polling loop with sleep().

measurement.waitUntilFinished(timeout=-1)
# is roughly equivalent to
while measurement.isRunning():
    sleep(0.01)

Parameters:: timeout – Timeout in milliseconds. Negative value means no timeout, zero returns immediately.
Returns:: True if the measurement has finished, False on timeout.

timestamp_t getCaptureDuration()

Total capture duration since the measurement creation or last call to clear().

Returns:: Capture duration in ps.

str getConfiguration()

Returns configuration data of the measurement object. The configuration includes the measurement name, and the values of the current parameters. Information returned by this method is also provided with TimeTaggerBase::getConfiguration().

Returns:: Configuration data of the measurement object.

Event counting

Countrate

class Countrate : public IteratorBase 

../_images/Countrate.svg

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 

../_images/Counter.svg

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(), including 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.

CountBetweenMarkers

class CountBetweenMarkers : public IteratorBase 

../_images/CountBetweenMarkers.svg

Counts events on a single channel within the time indicated by a “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 a vector of length 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 the click_channel. When the next tag is detected on the begin_channel it stores the current counter value as the next entry in the data vector, resets the counter to zero and starts accumulating counts again. If an end_channel is specified, the measurement stores the current counter value and resets the counter 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 vector are filled.

See all common methods

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.

Time histograms

This section describes various measurements that calculate time differences between events and accumulate the results into a histogram.

StartStop

class StartStop : public IteratorBase 

../_images/StartStop.svg

A simple start-stop measurement. This class performs a start-stop measurement between two channels and stores the time differences in a histogram. The histogram resolution is specified beforehand (binwidth) but the histogram range is unlimited. It is adapted to the largest time difference that was detected. Thus all pairs of subsequent clicks are registered. Only non-empty bins are recorded.

See all common methods

Public Functions

StartStop(TimeTaggerBase tagger, channel_t click_channel, channel_t start_channel = CHANNEL_UNUSED, timestamp_t binwidth = 1000)

Parameters:

tagger – Time tagger object instance.
click_channel – Channel on which stop clicks are received.
start_channel – Channel on which start clicks are received (default: CHANNEL_UNUSED).
binwidth – Bin width in ps (default: 1000).

timestamp_t[,] getData()

Returns:: An array of tuples (array of shape Nx2) containing the times (in ps) and counts of each bin. Only non-empty bins are returned.

Histogram

class Histogram : public IteratorBase 

../_images/Histogram.svg

Accumulate time differences into a histogram. This is a simple multiple start, multiple stop measurement. This is a special case of the more general TimeDifferences measurement. Specifically, the measurement waits for clicks on the start_channel, and for each start click, it measures the time difference between the start clicks and all subsequent clicks on the click_channel and stores them in a histogram. The histogram range and resolution are specified by the number of bins and the bin width specified in ps. Clicks that fall outside the histogram range are ignored. Data accumulation is performed independently for all start clicks. This type of measurement is frequently referred to as a ‘multiple start, multiple stop’ measurement and corresponds to a full auto- or cross-correlation measurement.

See all common methods

Public Functions

Histogram(TimeTaggerBase tagger, channel_t click_channel, channel_t start_channel = CHANNEL_UNUSED, timestamp_t binwidth = 1000, int n_bins = 1000)

Parameters:

tagger – Time tagger object instance.
click_channel – Channel on which clicks are received.
start_channel – Channel on which start clicks are received (default: CHANNEL_UNUSED).
binwidth – Bin width in ps (default: 1000).
n_bins – The number of bins in the histogram (default: 1000).

int[] getData()

Returns:: A one-dimensional array of size n_bins containing the histogram.

timestamp_t[] getIndex()

Returns:: A vector of size n_bins containing the time bins in ps.

HistogramLogBins

class HistogramLogBins : public IteratorBase 

../_images/HistogramLogBins.svg

The HistogramLogBins measurement is similar to Histogram but the bin edges are spaced logarithmically. As the bins do not have a homogeneous binwidth, a proper normalization is required to interpret the raw data.

For excluding time ranges from the histogram evaluation while maintaining a proper normalization, HistogramLogBins optionally takes two gating arguments of type ChannelGate. This can, e.g., be used to pause the acquisition during erroneous ranges that have to be identified by virtual channels. The same mechanism automatically applies to overflow ranges.

The acquired histogram $H(t)$ is normalized by

$\widetilde{H}(\tau) = I(\tau) \cdot C_\mathrm{click} \cdot C_\mathrm{start},$

with an estimation of counts $I(\tau)$ and the click and start channel count rates, $C_\mathrm{click} = N_\mathrm{click}/t_\mathrm{click}$ and $C_\mathrm{start} = N_\mathrm{start}/t_\mathrm{start}$ , respectively. Typically, this will be used to calculate

$g^{(2)}(\tau) = \frac{H(\tau)}{\widetilde{H}(\tau)}.$

For $t \gg 10^\mathrm{exp\_stop} \,\mathrm{s}$ and without interruptions, $I(\tau) / t$ will approach the binwidth of the respective bin. During the early acquisition and in case of interruptions, $I(\tau)$ can be significantly smaller, which compensates for counts that are excluded from $H(\tau)$ .

See all common methods

Public Functions

HistogramLogBins(TimeTaggerBase tagger, channel_t click_channel, channel_t start_channel, float exp_start, float exp_stop, int n_bins, ChannelGate click_gate = None, ChannelGate start_gate = None)

Parameters:

tagger – Time tagger object instance.
click_channel – Channel on which clicks are received.
start_channel – Channel on which start clicks are received.
exp_start – Exponent 10^exp_start in seconds where the very first bin begins.
exp_stop – Exponent 10^exp_stop in seconds where the very last bin ends.
n_bins – The number of bins in the histogram.
click_gate – Optional evaluation gate for the click_channel.
start_gate – Optional evaluation gate for the start_channel.

HistogramLogBinsData getDataObject()

Returns:: A data object containing raw and normalization data.

timestamp_t[] getBinEdges()

Returns:: A vector of size n_bins+1 containing the bin edges in picoseconds.

int[] getData()

Deprecated:: Since version 2.17.0. Please use getDataObject() and HistogramLogBinsData::getCounts() instead.

Returns:: A one-dimensional array of size n_bins containing the histogram.

float[] getDataNormalizedCountsPerPs()

Deprecated:: Since version 2.17.0.

Returns:: The counts normalized by the binwidth of each bin.

float[] getDataNormalizedG2()

Deprecated:: Since version 2.17.0. Please use getDataObject() and HistogramLogBinsData::getG2() instead.

Returns:: The counts normalized by the binwidth of each bin and the average count rate.

class HistogramLogBinsData

Contains the histogram counts $H(\tau)$ and the corresponding normalization function $\widetilde{H}(\tau)$ .

Public Functions

float[] getG2()

Returns:: A one-dimensional array of size n_bins containing the normalized histogram $H(\tau)/\widetilde{H}(\tau)$ .

int[] getCounts()

Returns:: A one-dimensional array of size n_bins containing the raw histogram $H(\tau)$ .

float[] getG2Normalization()

Returns:: A one-dimensional array of size n_bins containing the normalization $\widetilde{H}(\tau)$ .

Histogram2D

class Histogram2D : public IteratorBase 

../_images/Histogram2D.svg

This measurement is a 2-dimensional version of the Histogram measurement. The measurement accumulates two-dimensional histogram where stop signals from two separate channels define the bin coordinate. For instance, this kind of measurement is similar to that of typical 2D NMR spectroscopy. The data within the histogram is acquired via a single-start, single-stop analysis for each axis. The first stop click of each axis is taken after the start click to evaluate the histogram counts.

See all common methods

Public Functions

Histogram2D(TimeTaggerBase tagger, channel_t start_channel, channel_t stop_channel_1, channel_t stop_channel_2, timestamp_t binwidth_1, timestamp_t binwidth_2, int n_bins_1, int n_bins_2)

Parameters:

tagger – Time tagger object
start_channel – Channel on which start clicks are received
stop_channel_1 – Channel on which stop clicks for the time axis 1 are received
stop_channel_2 – Channel on which stop clicks for the time axis 2 are received
binwidth_1 – Bin width in ps for the time axis 1
binwidth_2 – Bin width in ps for the time axis 2
n_bins_1 – The number of bins along the time axis 1
n_bins_2 – The number of bins along the time axis 2

int[,] getData()

Returns:: A two-dimensional array of size n_bins_1 by n_bins_2 containing the 2D histogram.

timestamp_t[,,] getIndex()

Returns a 3D array containing two coordinate matrices (meshgrid) for time bins in ps for the time axes 1 and 2. For details on meshgrid please take a look at the respective documentation either for Matlab or Python NumPy.

Returns:: A three-dimensional array of size n_bins_1 x n_bins_2 x 2.

timestamp_t[] getIndex_1()

Returns:: A vector of size n_bins_1 containing the bin locations in ps for the time axis 1.

timestamp_t[] getIndex_2()

Returns:: A vector of size n_bins_2 containing the bin locations in ps for the time axis 2.

HistogramND

class HistogramND : public IteratorBase 

This measurement is the generalization of Histogram2D to an arbitrary number of dimensions. The data within the histogram is acquired via a single-start, single-stop analysis for each axis. The first stop click of each axis is taken after the start click to evaluate the histogram counts.

HistogramND can be used as a 1D Histogram with single-start single-stop behavior.

See all common methods

Public Functions

HistogramND(TimeTaggerBase tagger, channel_t start_channel, channel_t[] stop_channels, timestamp_t[] binwidths, int[] n_bins)

Parameters:

tagger – Time tagger object.
start_channel – Channel on which start clicks are received.
stop_channels – Channel list on which stop clicks are received defining the time axes.
binwidths – Bin width in ps for the corresponding time axis.
n_bins – The number of bins along the corresponding time axis.

int[] getData()

Returns a one-dimensional array of the size of the product of n_bins containing the histogram data. The array order is in row-major. For example, with stop_channels=[ch1, ch2] and n_bins=[2, 2], the 1D array would represent 2D bin indices in the order [(0,0), (0,1), (1,0), (1,1)], with (index of ch1, index of ch2). Please reshape the 1D array to get the N-dimensional array. The following code demonstrates how to reshape the returned 1D array into multidimensional array using NumPy:

channels = [2, 3, 4, 5]
n_bins = [5, 3, 4, 6]
binwidths = [100, 100, 100, 50]
histogram_nd = HistogramND(tagger, 1, channels, binwidths, n_bins)
sleep(1)  # Wait to accumulate the data
data = histogram_nd.getData()
multidim_array = numpy.reshape(data, n_bins)

Returns:: Flattened array of histogram bins.

timestamp_t[] getIndex(int dim = 0)

Returns:: A vector of size n_bins[dim] containing the bin locations in ps for the corresponding time axis.

Correlation

class Correlation : public IteratorBase 

../_images/Correlation.svg

Accumulates time differences between clicks on two channels into a histogram, where all clicks are considered both as “start” and “stop” clicks and both positive and negative time differences are calculated.

See all common methods

Public Functions

Correlation(TimeTaggerBase tagger, channel_t channel_1, channel_t channel_2 = CHANNEL_UNUSED, timestamp_t binwidth = 1000, int n_bins = 1000)

Parameters:

tagger – Time tagger object.
channel_1 – Channel on which (stop) clicks are received.
channel_2 – Channel on which reference clicks (start) are received (when left empty or set to CHANNEL_UNUSED -> an auto-correlation measurement is performed, which is the same as setting channel_1 = channel_2) (default: CHANNEL_UNUSED).
binwidth – Bin width in ps (default: 1000).
n_bins – The number of bins in the resulting histogram (default: 1000).

int[] getData()

Returns:: A one-dimensional array of size n_bins containing the histogram.

float[] getDataNormalized()

Return the data normalized as:

$g^{(2)}(\tau) = \frac{\Delta{t}}{binwidth(\tau) \cdot N_1 \cdot N_2} \cdot histogram(\tau),$

where $\Delta{t}$ is the capture duration, $N_1$ and $N_2$ are number of events in each channel.

Returns:: Data normalized by the binwidth and the average count rate.

timestamp_t[] getIndex()

Returns:: A vector of size n_bins containing the time bins in ps.

TimeDifferences

class TimeDifferences : public IteratorBase 

../_images/TimeDifferences.svg

A one-dimensional array of time-difference histograms with the option to include up to two additional channels that control how to step through the indices of the histogram array. This is a very powerful and generic measurement. You can use it to record consecutive cross-correlation, lifetime measurements, fluorescence lifetime imaging and many more measurements based on pulsed excitation. Specifically, the measurement waits for a tag on the start_channel, then measures the time difference between the start tag and all subsequent tags on the click_channel and stores them in a histogram. If no start_channel is specified, the click_channel is used as start_channel corresponding to an auto-correlation measurement. The histogram has a number n_bins of bins of bin width binwidth. Clicks that fall outside the histogram range are discarded. Data accumulation is performed independently for all start tags. This type of measurement is frequently referred to as ‘multiple start, multiple stop’ measurement and corresponds to a full auto- or cross-correlation measurement.

The time-difference data can be accumulated into a single histogram or into multiple subsequent histograms. In this way, you can record a sequence of time-difference histograms. To switch from one histogram to the next one you have to specify a channel that provide switch markers (next_channel parameter). Also you need to specify the number of histograms with the parameter n_histograms. After each tag on the next_channel, the histogram index is incremented by one and reset to zero after reaching the last valid index. The measurement starts with the first tag on the next_channel.

You can also provide a synchronization marker that resets the histogram index by specifying a sync_channel. The measurement starts when a tag on the sync_channel arrives with a subsequent tag on next_channel. When a rollover occurs, the accumulation is stopped until the next sync and subsequent next signal. A sync signal before a rollover will stop the accumulation, reset the histogram index and a subsequent signal on the next_channel starts the accumulation again.

Typically, you will run the measurement indefinitely until stopped by the user. However, it is also possible to specify the maximum number of rollovers of the histogram index. In this case, the measurement stops when the number of rollovers has reached the specified value.

See all common methods

Public Functions

TimeDifferences(TimeTaggerBase tagger, channel_t click_channel, channel_t start_channel = CHANNEL_UNUSED, channel_t next_channel = CHANNEL_UNUSED, channel_t sync_channel = CHANNEL_UNUSED, timestamp_t binwidth = 1000, int n_bins = 1000, int n_histograms = 1)

Note

A rollover occurs on a next_channel event while the histogram index is already in the last histogram. If sync_channel is defined, the measurement will pause at a rollover until a sync_channel event occurs and continues at the next next_channel event. With undefined sync_channel, the measurement will continue without interruption at histogram index 0.

Parameters:

tagger – Time tagger object instance.
click_channel – Channel on which stop clicks are received.
start_channel – Channel that sets start times relative to which clicks on the click channel are measured.
next_channel – Channel that increments the histogram index.
sync_channel – Channel that resets the histogram index to zero.
binwidth – Binwidth in picoseconds.
n_bins – Number of bins in each histogram.
n_histograms – Number of histograms.

int[,] getData()

Returns:: A two-dimensional array of size n_bins by n_histograms containing the histograms.

timestamp_t[] getIndex()

Returns:: A vector of size n_bins containing the time bins in ps.

void setMaxCounts(int max_counts)

Sets the number of rollovers at which the measurement stops integrating. To integrate infinitely, set the value to 0, which is the default value.

Parameters:: max_counts – Maximum number of sync/next clicks.

int getHistogramIndex()

Returns:

The index of the currently processed histogram or the waiting state. Possible return values are:

-2: Waiting for an event on sync_channel (only if sync_channel is defined)
-1: Waiting for an event on next_channel (only if sync_channel is defined)
0 … (n_histograms - 1): Index of the currently processed histogram.

int getCounts()

Returns:: The number of rollovers (histogram index resets).

bool ready()

Returns:: True when the required number of rollovers set by setMaxCounts() has been reached.

TimeDifferencesND

class TimeDifferencesND : public IteratorBase 

../_images/TimeDifferencesND.svg

This is an implementation of the TimeDifferences measurement class that extends histogram indexing into multiple dimensions. Please read the documentation of TimeDifferences first.

It captures many multiple start - multiple stop histograms, but with many asynchronous next_channel triggers. After each tag on each next_channel, the histogram index of the associated dimension is incremented by one and reset to zero after reaching the last valid index. The elements of the parameter n_histograms specify the number of histograms per dimension. The accumulation starts when next_channel has been triggered on all dimensions.

You should provide a synchronization trigger by specifying a sync_channel per dimension. It will stop the accumulation when an associated histogram index rollover occurs. A sync event will also stop the accumulation and reset the histogram index of the associated dimension. A subsequent event on the corresponding next_channel will start the accumulation again. The synchronization is done asynchronously, so an event on the next_channel increments the histogram index even if the accumulation is stopped. The accumulation will start when a tag on the sync_channel arrives with a subsequent tag on next_channel for all dimensions.

Please use TimeTaggerBase::setInputDelay() to adjust the latency of all channels. In general, the order of the provided triggers including maximum jitter should be:

old start trigger -> all sync triggers -> all next triggers -> new start trigger.

See all common methods

Public Functions

TimeDifferencesND(TimeTaggerBase tagger, channel_t click_channel, channel_t start_channel, channel_t[] next_channels, channel_t[] sync_channels, int[] n_histograms, timestamp_t binwidth, int n_bins)

Parameters:

tagger – Time tagger object instance.
click_channel – Channel on which stop clicks are received.
start_channel – Channel that sets start times relative to which clicks on the click channel are measured.
next_channels – Vector of channels that increments the histogram index.
sync_channels – Vector of channels that resets the histogram index to zero.
n_histograms – Vector of numbers of histograms per dimension.
binwidth – Width of one histogram bin in ps.
n_bins – Number of bins in each histogram.

int[,] getData()

Returns:: A two-dimensional array of size n_bins by n_histograms containing the histograms.

timestamp_t[] getIndex()

Returns:: A vector of size n_bins containing the time bins in ps.

Fluorescence-lifetime imaging (FLIM)

This section describes the FLIM related measurements classes of the Time Tagger API.

FlimAbstract

class FlimAbstract : public IteratorBase 

This is an interface class for FLIM measurements that defines common methods.

Subclassed by Flim, FlimBase

Public Functions

bool isAcquiring()

Tells if the class is still acquiring data. It can only reach the false state if stop_after_outputframe > 0.

This method is different from isRunning() and indicates if the specified number of frames is acquired. After acquisition completed, it can’t be started again.

Returns:: True/False.

Flim

Changed in version 2.7.2.

Note

The Flim (beta) implementation is not final yet. It has a very advanced functionality, but details are subject to change. Please give us feedback (support@swabianinstruments.com) when you encounter issues or when you have ideas for additional functionality.

Fluorescence-lifetime imaging microscopy (FLIM) is an imaging technique for producing an image based on the differences in the exponential decay rate of the fluorescence from a sample.

Fluorescence lifetimes can be determined in the time domain by using a pulsed source. When a population of fluorophores is excited by an ultrashort or delta-peak pulse of light, the time-resolved fluorescence will decay exponentially.

This measurement implements a line scan in a FLIM image that consists of a sequence of pixels. This could either represent a single line of the image, or - if the image is represented as a single meandering line - this could represent the entire image.

We provide two different classes that support FLIM measurements: Flim and FlimBase. Flim provides a versatile high-level API. FlimBase instead provides the essential functionality with no overhead to perform Flim measurements. FlimBase is based on a callback approach.

Please visit the Python example folder for a reference implementation.

Note

Up to version 2.7.0, the Flim implementation was very limited and has been fully rewritten in version 2.7.2. You can use the following 1 to 1 replacement to get the old Flim behavior:

# FLIM before version 2.7.0:
Flim(tagger, click_channel=1, start_channel=2, next_channel=3,
    binwidth=100, n_bins=1000, n_pixels=320*240)

# FLIM 2.7.0 replacement using TimeDifferences
TimeDifferences(tagger, click_channel=1, start_channel=2,
    next_channel=3, sync_channel=CHANNEL_UNUSED,
    binwidth=100, n_bins=1000, n_histograms=320*240)

class Flim : public FlimAbstract 

High-Level class for implementing FLIM measurements. The Flim class includes buffering of images and several analysis methods.

This class supports expansion of functionality with custom FLIM frame processing by overriding virtual/abstract frameReady() callback. If you need custom implementation with minimal overhead and highest performance, consider overriding FlimBase class instead.

The data query methods are organized into a few groups.

The methods getCurrentFrame...() relate to the active frame which is currently being acquired.

The methods getReadyFrame...() relate to the last completely acquired frame.

The methods getSummedFrames...() operate to all frames which have been acquired so far. Optional parameter only_ready_frames selects if the current incomplete frame shall be included or excluded from calculation.

The methods get...Ex instead of an array return a FlimFrameInfo object containing frame data with additional information collected at the same time instance.

See all common methods

Warning

When overriding this class, you must set pre_initialize=False and then call initialize() at the end of your custom constructor code. Otherwise, you may experience unstable or erratic behavior of your program, as the callback frameReady() may be called before construction of the subclass completed.

Public Functions

Flim(TimeTaggerBase tagger, channel_t start_channel, channel_t click_channel, channel_t pixel_begin_channel, int n_pixels, int n_bins, timestamp_t binwidth, channel_t pixel_end_channel = CHANNEL_UNUSED, channel_t frame_begin_channel = CHANNEL_UNUSED, int finish_after_outputframe = 0, int n_frame_average = 1, bool pre_initialize = true)

Parameters:

tagger – Time tagger object instance.
start_channel – Channel on which start clicks are received for the time differences histogramming.
click_channel – Channel on which clicks are received for the time differences histogramming.
pixel_begin_channel – Start marker of a pixel (histogram).
n_pixels – Number of pixels (histograms) of one frame.
n_bins – Number of histogram bins for each pixel.
binwidth – Bin size in picoseconds.
pixel_end_channel – End marker of a pixel - incoming clicks on the click_channel will be ignored afterwards (optional, default: CHANNEL_UNUSED).
frame_begin_channel – Start the frame, or reset the pixel index (optional, default: CHANNEL_UNUSED).
finish_after_outputframe – Sets the number of frames stored within the measurement class. After reaching the number, the measurement will stop. If the number is 0, one frame is stored and the measurement runs continuously (optional, default: 0).
n_frame_average – Average multiple input frames into one output frame (default: 1).
pre_initialize – Initializes the measurement on constructing (optional, default: True). On subclassing, you must set this parameter to False, and then call initialize() at the end of your custom constructor method.

int[,] getCurrentFrame()

Returns:: The histograms for all pixels of the currently active frame, 2D array with dimensions [n_bins, n_pixels].

FlimFrameInfo getCurrentFrameEx()

Returns:: The currently active frame data with additional information collected at the same instance of time.

float[] getCurrentFrameIntensity()

Returns:: The intensities of all pixels of the currently active frame. The pixel intensity is defined by the number of counts acquired within the pixel divided by the respective integration time.

int getFramesAcquired()

Returns:: The number of frames that have been completed so far, since the creation or last clear of the object.

timestamp_t[] getIndex()

Returns:: A vector of size n_bins containing the time bins in ps.

int[,] getReadyFrame(int index = -1)

Parameters:: index – Index of the frame to be obtained. If -1, the last frame which has been completed is returned. (optional, default: -1).
Returns:: The histograms for all pixels according to the frame index given. If index is -1, it will return the last frame, which has been completed. When stop_after_outputframe is 0, the index value must be -1. If index >= stop_after_outputframe, it will throw an error. 2D array with dimensions [n_bins, n_pixels]

FlimFrameInfo getReadyFrameEx(int index = -1)

Parameters:: index – Index of the frame to be obtained. If -1, the last frame which has been completed is returned. (optional, default: -1).
Returns:: The frame according to the index given. If index is -1, it will return the latest completed frame. When stop_after_outputframe is 0, index must be -1. If index >= stop_after_outputframe, it will throw an error.

float[] getReadyFrameIntensity(int index = -1)

Parameters:: index – Index of the frame to be obtained. If -1, the last frame which has been completed is returned. (optional, default: -1).
Returns:: The intensities according to the frame index given. If index is -1, it will return the intensity of the last frame, which has been completed. When stop_after_outputframe is 0, the index value must be -1. If index >= stop_after_outputframe, it will throw an error. The pixel intensity is defined by the number of counts acquired within the pixel divided by the respective integration time.

int[,] getSummedFrames(bool only_ready_frames = true, bool clear_summed = false)

Parameters:

only_ready_frames – If true, only the finished frames are added. On false, the currently active frame is aggregated. (optional, default: True).
clear_summed – If True, the summed frames memory will be cleared. (optional, default: False).

Returns:

The histograms for all pixels. The counts within the histograms are integrated since the start or the last clear of the measurement.

FlimFrameInfo getSummedFramesEx(bool only_ready_frames = true, bool clear_summed = false)

Parameters:

only_ready_frames – If true, only the finished frames are added. On false, the currently active frame is aggregated. (optional, default: True).
clear_summed – If True, the summed frames memory will be cleared. (optional, default: False).

Returns:

A sum of all acquired frames with additional information collected at the same instance of time.

float[] getSummedFramesIntensity(bool only_ready_frames = true, bool clear_summed = false)

Parameters:

only_ready_frames – If true, only the finished frames are added. On false, the currently active frame is aggregated. (optional, default: True).
clear_summed – If True, the summed frames memory will be cleared. (optional, default: False).

Returns:

The intensities of all pixels summed over all acquired frames. The pixel intensity is the number of counts within the pixel divided by the integration time.

void initialize(): This function initialized the Flim object and starts execution. It does nothing if constructor parameter pre_initialize==True.

Protected Functions

virtual void frameReady(int frame_number, int[] data, timestamp_t[] pixel_begin_times, timestamp_t[] pixel_end_times, timestamp_t frame_begin_time, timestamp_t frame_end_time)

The method is called automatically by the Time Tagger engine for each completely acquired frame. In its parameters, it provides FLIM frame data and related information. You have to override this method with your own implementation.

Warning

The code of override must be fast, as it is executed in context of Time Tagger processing thread and blocks the processing pipeline. Slow override code may lead to the buffer overflows.

Parameters:

frame_number – Current frame number.
data – 1D array containing the raw histogram data, with the data of pixel i and time bin j at index i * n_bins + j.
pixel_begin_times – Start time for each pixel.
pixel_end_times – End time for each pixel.
frame_begin_time – Start time of the frame.
frame_end_time – End time of the frame.

FlimFrameInfo

class FlimFrameInfo

This is a simple class that contains FLIM frame data and provides convenience accessor methods.

Note

Objects of this class are returned by the methods of the |FLIM| classes. Normally user will not construct FlimFrameInfo objects themselves.

Public Functions

int getFrameNumber()

Returns:: The frame number, starting from 0 for the very first frame acquired. If the index is -1, it is an invalid frame which is returned on error.

bool isValid()

Returns:: A boolean which tells if this frame is valid or not. Invalid frames are possible on errors, such as requesting the last completed frame when no frame has been completed so far.

int getPixelPosition()

Returns:: A value which tells how many pixels were processed for this frame.

int[,] getHistograms()

Returns:: All histograms of the frame, 2D array with dimensions [n_bins, n_pixels].

float[] getIntensities()

Returns:: The summed counts of each histogram divided by the integration time.

int[] getSummedCounts(): The summed counts of each histogram.

timestamp_t[] getPixelBegins(): An array of the start timestamps of each pixel.

timestamp_t[] getPixelEnds(): An array of the end timestamps of each pixel.

Public Members

int pixels: Number of pixels in the frame.

int bins: Number of bins of each histogram.

int frame_number: Current frame number.

int pixel_position: Current pixel position.

FlimBase

The FlimBase provides only the most essential functionality for FLIM tasks. The benefit from the reduced functionality is that it is very memory and CPU efficient. The class provides the FlimBase.frameReady callback, which must be used to analyze the data.

class FlimBase : public FlimAbstract 

This is a minimal class that acquires a FLIM frame and calls virtual/abstract frameReady() callback method with the frame data as parameters. This class is intended for custom implementations of fast FLIM frame processing with minimal overhead. You can reach frame acquisition rates suitable for realtime video observation.

If you need custom FLIM frame processing implementation while retaining functionality present in the Flim class, consider subclassing Flim instead.

See all common methods

Warning

When overriding this class, you must set pre_initialize=False and then call initialize() at the end of your custom constructor code. Otherwise, you may experience unstable or erratic behavior of your program, as the callback frameReady() may be called before construction of the subclass completed.

Public Functions

FlimBase(TimeTaggerBase tagger, channel_t start_channel, channel_t click_channel, channel_t pixel_begin_channel, int n_pixels, int n_bins, timestamp_t binwidth, channel_t pixel_end_channel = CHANNEL_UNUSED, channel_t frame_begin_channel = CHANNEL_UNUSED, int finish_after_outputframe = 0, int n_frame_average = 1, bool pre_initialize = true)

Parameters:

tagger – Time tagger object instance.
start_channel – Channel on which start clicks are received for the time differences histogramming.
click_channel – Channel on which clicks are received for the time differences histogramming.
pixel_begin_channel – Start marker of a pixel (histogram).
n_pixels – Number of pixels (histograms) of one frame.
n_bins – Number of histogram bins for each pixel.
binwidth – Bin size in picoseconds.
pixel_end_channel – End marker of a pixel - incoming clicks on the click_channel will be ignored afterwards (optional, default: CHANNEL_UNUSED).
frame_begin_channel – Start the frame, or reset the pixel index (optional, default: CHANNEL_UNUSED).
finish_after_outputframe – Sets the number of frames stored within the measurement class. After reaching the number, the measurement will stop. If the number is 0, one frame is stored and the measurement runs continuously (optional, default: 0).
n_frame_average – Average multiple input frames into one output frame (default: 1).
pre_initialize – Initializes the measurement on constructing (optional, default: True). On subclassing, you must set this parameter to False, and then call initialize() at the end of your custom constructor method.

void initialize(): This function initialized the Flim object and starts execution. It does nothing if constructor parameter pre_initialize==True.

Protected Functions

virtual void frameReady(int frame_number, int[] data, timestamp_t[] pixel_begin_times, timestamp_t[] pixel_end_times, timestamp_t frame_begin_time, timestamp_t frame_end_time)

The method is called automatically by the Time Tagger engine for each completely acquired frame. In its parameters, it provides FLIM frame data and related information. You have to override this method with your own implementation.

Warning

The code of override must be fast, as it is executed in context of Time Tagger processing thread and blocks the processing pipeline. Slow override code may lead to the buffer overflows.

Parameters:

frame_number – Current frame number.
data – 1D array containing the raw histogram data, with the data of pixel i and time bin j at index i * n_bins + j.
pixel_begin_times – Start time for each pixel.
pixel_end_times – End time for each pixel.
frame_begin_time – Start time of the frame.
frame_end_time – End time of the frame.

Phase & frequency analysis

This section describes measurements that expect periodic signals, e.g., oscillator outputs.

FrequencyStability

class FrequencyStability : public IteratorBase 

Frequency Stability Analysis is used to characterize periodic signals and to identify sources of deviations from the perfect periodicity. It can be employed to evaluate the frequency stability of oscillators, for example. A set of established metrics provides insights into the oscillator characteristics on different time scales. The most prominent metric is the Allan Deviation (ADEV). FrequencyStability class executes the calculation of often used metrics in parallel and conforms to the IEEE 1139 standard. For more information, we recommend the Handbook of Frequency Stability Analysis.

The calculated deviations are the root-mean-square $\sqrt{f_n \sum_i\left(E_i^{(n)}\right)^2}$ of a specific set of error samples $E^{(n)}$ with a normalization factor $f_n$ . The step size $n$ together with the oscillator period $T$ defines the time span $\tau_n = n T$ that is investigated by the sample. The error samples $E^{(n)}$ are calculated from the phase samples $t$ that are generated by the FrequencyStability class by averaging over the timestamps of a configurable number of time-tags. To investigate the averaged phase samples directly, a trace of configurable length is stored to display the current evolution of frequency and phase errors.

Each of the available deviations has its specific sample $E^{(n)}$ . For example, the Allan Deviation investigates the second derivative of the phase $t$ using the sample $E_i^{(n)} = t_i - 2 t_{i+n} + t_{i+2n}$ . The full formula of the Allan deviation for a set of $N$ averaged timestamps is

$\mathrm{ADEV}(\tau_n) = \sqrt{\frac{1}{2(N-2n)\tau_n^2} \sum_{i=1}^{N-2n}\left(t_i - 2 t_{i+n} + t_{i+2n}\right)^2}.$

The deviations can be displayed in the Allan domain or in the time domain. For the time domain, the Allan domain data is multiplied by a factor proportional to $\tau$ . This means that in a log-log plot, all slopes of the time domain curves are increased by +1 compared to the Allan ones. The factor $\sqrt{3}$ for |ADEV|/|MDEV| and $\sqrt{10/3}$ for |HDEV|, respectively, is used so that the scaled deviations of a white phase noise distortion correspond to the standard deviation of the averaged timestamps $t$ . In some cases, there are different established names for the representations. The FrequencyStability class provides numerous metrics for both domains:

Allan domain	Time domain
	Standard Deviation (STDD)
Allan Deviation (ADEV)	ADEVScaled = $\frac{\tau}{\sqrt{3}}$ ADEV
Modified Allan Deviation (ADEV)	Time Deviation TDEV = $\frac{\tau}{\sqrt{3}}$ MDEV
Hadamard Deviation (HDEV )	HDEVScaled = $\frac{\tau}{\sqrt{10 / 3}}$ HDEV

See all common methods

Public Functions

FrequencyStability(TimeTaggerBase tagger, channel_t channel, int[] steps, timestamp_t average = 1000, int trace_len = 1000)

Note

Use average and TimeTagger::setEventDivider() with care: The event divider can be used to save USB bandwidth. If possible, transfer more data via USB and use average to improve your results.

Parameters:

tagger – Time tagger object.
channel – The input channel number.
steps – The step sizes to consider in the calculation. The length of the list determines the maximum number of data points. Because the oscillator frequency is unknown, it is not possible to define $\tau$ directly.
average – The number of time-tags to average internally. This downsampling allows for a reduction of noise and memory requirements (default: 1000).
trace_len – Number of data points in the phase and frequency error traces, calculated from averaged data. The trace always contains the latest data (default: 1000).

FrequencyStabilityData getDataObject()

Returns:: An object that allows access to the current metrics.

class FrequencyStabilityData

Public Functions

float[] getTau()

The $\tau$ axis for all deviations. This is the product of the steps parameter of the FrequencyStability measurement and the measured average period of the signal.

Returns:: The $\tau$ values.

float[] getADEV()

The overlapping Allan deviation, the most common analysis framework. In a log-log plot, the slope allows one to identify the type of noise:

-1: white or flicker phase noise like discretization or analog noisy delay
-0.5: white period noise
0: flicker period noise like electric noisy oscillator
0.5: integrated white period noise (random walk period)
1: frequency drift, e.g., induced thermally.

Sample:: $E_i^{(n)} = t_i - 2 t_{i+n} + t_{i+2n}$ .
Domain:: Allan domain.
Returns:: The overlapping Allan Deviation.

float[] getMDEV()

Modified overlapping Allan deviation. It averages the second derivate before calculating the RMS. This splits the slope of white and flicker phase noise:

-1.5: white phase noise, like discretization
-1.0: flicker phase noise, like an electric noisy delay.

The metric is more commonly used in the time domain, see getTDEV():

Sample:: $E_i^{(n)} = \frac{1}{n} \sum_{j=0}^{n-1} \left(t_{i+j} - 2 t_{i+j+n} + t_{i+j+2n}\right)$ .
Domain:: Allan domain.
Returns:: The overlapping MDEV.

float[] getHDEV()

The overlapping Hadamard deviation uses the third derivate of the phase. This cancels the effect of a constant phase drift and converges for more divergent noise sources at higher slopes:

1: integrated flicker period noise (flicker walk period)
1.5: double integrated white period noise (random run period).

It is scaled to match the ADEV for white period noise.

Sample:: $E_i^{(n)} = t_i - 3 t_{i+n} + 3 t_{i+2n} - t_{i+3n}$ .
Domain:: Allan domain.
Returns:: The overlapping HDEV.

float[] getSTDD()

Standard deviation of the periods.

Warning

The standard deviation is not recommended as a measure of frequency stability because it is non-convergent for some types of noise commonly found in frequency sources, most noticeable the frequency drift.

Sample:: $E_i^{(n)} = t_i - t_{i+n} - \mathrm{mean}_k(t_k - t_{k+n})$ .
Domain:: Time domain.
Returns:: The standard deviation.

float[] getADEVScaled()

Domain:: Time domain.
Returns:: The scaled version of the overlapping Allan Deviation, equivalent to getADEV() * getTau() / $\sqrt{3}$ .

float[] getTDEV()

The Time Deviation (TDEV) is the common representation of the Modified overlapping Allan deviation getMDEV(). Taking the log-log slope +1 and the splitting of the slope of white and flicker phase noise into account, it allows an easy identification of the two contributions:

-0.5: white phase noise, like discretization
0: flicker phase noise, like an electric noisy delay.

Domain:: Time domain.
Returns:: The overlapping Time Deviation, equivalent to getMDEV()* getTau() / $\sqrt{3}$ .

float[] getHDEVScaled()

Warning

While HDEV is scaled to match ADEV for white period noise, this function is scaled to match the TDEV for white phase noise. The difference of period vs phase matching is roughly 5% and easy to overlook.

Domain:: Time domain.
Returns:: The scaled version of the overlapping Hadamard Deviation, equivalent to getHDEV() * getTau() / $\sqrt{10 / 3}$ .

float[] getTraceIndex()

The time axis for getTracePhase() and getTraceFrequency().

Returns:: The time index in seconds of the phase and frequency error trace.

float[] getTracePhase()

Provides the time offset of the averaged timestamps from a linear fit over the last trace_len averaged timestamps.

Returns:: A trace of the last trace_len phase samples in seconds.

float[] getTraceFrequency()

Provides the relative frequency offset from the average frequency during the last trace_len + 1 averaged timestamps.

Returns:: A trace of the last trace_len normalized frequency error data points in pp1.

float[] getTraceFrequencyAbsolute(float input_frequency = 0.0)

Provides the absolute frequency offset from a given input_frequency during the last trace_len + 1 averaged timestamps.

Parameters:: input_frequency – Nominal frequency of the periodic signal (default: 0 Hz).
Returns:: A trace of the last trace_len frequency data points in Hz.

FrequencyCounter

class FrequencyCounter : public IteratorBase 

This measurement calculates the phase of a periodic signal at evenly spaced sampling times. If the SoftwareClock is active, the sampling times will automatically align with the SoftwareClockState::ideal_clock_channel. Multiple channels can be analyzed in parallel to compare the phase evolution in time. Around every sampling time, the time tags within an adjustable fitting_window are used to fit the phase.

See all common methods

Public Functions

FrequencyCounter(TimeTaggerBase tagger, channel_t[] channels, timestamp_t sampling_interval, timestamp_t fitting_window, int n_values = 0)

Parameters:

tagger – Time Tagger object instance.
channels – List of channels to analyze.
sampling_interval – The sampling interval in picoseconds. If the SoftwareClock is active, it is recommended to set this value to an integer multiple of the SoftwareClockState::clock_period.
fitting_window – Time tags within this range around a sampling point are fitted for phase calculation.
n_values – Maximum number of sampling points to store.

FrequencyCounterData getDataObject(int event_divider = 1, bool remove = false, bool channels_last_dim = false)

Returns a FrequencyCounterData object containing a snapshot of the data accumulated in the FrequencyCounter at the time this method is called. The event_divider argument can be used to scale the results according to the current setting of TimeTagger::setEventDivider(). The remove argument allows you to control whether the data should be removed from the internal buffer or not.

Parameters:

event_divider – Compensate for the EventDivider (default: 1).
remove – Control if data is removed from the internal buffer (default: True).
channels_last_dim – Determines the memory layout of the output data (default: False).
- If true, data is stored with channels as the last dimension (row-major order for channels).
- If false, data is stored with channels as the first dimension (column-major order for channels).

Returns:

An object providing access to a snapshot data.

class FrequencyCounterData

Public Functions

timestamp_t[] getIndex()

Index of the samples. The reference sample would have index 0, counting starts with 1 at the first sampling point.

Returns:: The index of the samples.

timestamp_t[] getTime()

Array of timestamps of the sampling points.

Returns:: The timestamps of the sampling points.

timestamp_t[,] getPeriodsCount()

The integer part of the phase, i.e. full periods of the oscillation.

Returns:: Full cycles per channel and sampling point.

float[,] getPeriodsFraction()

The fraction of the current period at the sampling time.

Warning

Be careful with adding getPeriodsCount() and getPeriodsFraction() as the required precision can overflow a 64bit double precision within minutes. In doubt, please use getPhase() with the expected frequency instead.

Returns:: A fractional value in range [0, 1) per channel and sampling point.

float[,] getPhase(float reference_frequency = 0)

The relative phase with respect to a numerical reference signal, typically at the expected frequency. The reference signal starts at phase 0 at index 0, so the return value of this method is identical to that of getPeriodsFraction() for index 0.

Parameters:: reference_frequency – The reference frequency in Hz to subtract (default: 0.0 Hz).
Returns:: Relative phase values per channel and sampling point.

float[,] getFrequency(timestamp_t time_scale = 1000000000000)

The frequency derived from the accumulated phase difference since the last sampling interval. At index 0, there is no previous phase value to compare with, so the method returns an undefined value 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 sampling_interval.
Returns:: A frequency value per channel and sampling point.

float[,] getFrequencyInstantaneous()

The instantaneous frequency with respect to the current fitting window. This value corresponds to the slope of the linear fit.

Returns:: An instantaneous frequency value per channel and sampling point.

int[,] getOverflowMask()

If an overflow range overlaps with a fitting window, the values are invalid. This mask array indicates invalid elements and can be used to filter the results of the other getters.

Returns:: 1 indicates that the sampling point was affected by an overflow range, 0 indicates valid data.

Public Members

int size: Number of sampling points represented by the object.

timestamp_t overflow_samples: Number of sampling points affected by an overflow range since the start of the measurement.

bool align_to_reference: Indicates if the sampling grid has been aligned to the SoftwareClock.

timestamp_t sampling_interval: The sampling interval in picoseconds.

timestamp_t sample_offset: Index offset of the first sampling point in the object.

bool channels_last_dim

The memory layout of the output data:

If True, the data is stored with channels as the last dimension (row-major order for channels).
If False, the data is stored with channels as the first dimension (column-major order for channels).

PulsePerSecondMonitor

Note

PulsePerSecondMonitor and PulsePerSecondData are part of the Experimental namespace, and their properties may change in future software versions without further notice. They can be accessed as:

TimeTagger.Experimental.PulsePerSecondMonitor(tagger, reference_channel=1, signal_channels=[2,3],
                                              filename="output", period=1E12)

class PulsePerSecondMonitor : public IteratorBase 

This measurement allows the user to monitor the synchronicity of different sources of 1 pulse per second (PPS) signals with respect to a reference source. For each signal from the reference PPS source, comparative offsets are calculated for the other signal channels. Upon processing, a UTC timestamp from the system time is associated with each reference pulse.

The monitoring starts on the first signal from the reference source and will run uninterrupted until the measurement is stopped. If a signal from a channel is not detected within one and a half periods, its respective offset will not be calculated but the measurement will continue nonetheless.

By specifying an output file name, the monitoring data can be continuously written to a comma-separated value file (.csv).

See all common methods

Public Functions

PulsePerSecondMonitor(TimeTaggerBase tagger, channel_t reference_channel, channel_t[] signal_channels, str filename = "", timestamp_t period = 1E12)

Parameters:

tagger – Time Tagger object instance.
reference_channel – The channel number corresponding to the PPS reference source.
signal_channels – A list of channel numbers with PPS signals to be compared to the reference.
filename – The name of the .csv file to store measurement data. By default, no data is written to file (default: “”).
period – The assumed period of the reference source, typically one second, in picoseconds (default: 1e12).

PulsePerSecondData getDataObject(bool remove = false)

Returns a PulsePerSecondData object containing a snapshot of the data accumulated in the PulsePerSecondMonitor at the time this method is called. To remove the data from the internal memory after each call, set remove to True.

Parameters:: remove – Controls if the returned data shall be removed from the internal buffer.
Returns:: An object providing access to a snapshot data.

class PulsePerSecondData

Public Functions

int[] getIndices()

The indices of each reference pulse in the PulsePerSecondData object. The first reference pulse will have index 0, each subsequent pulse from the reference source increments the index by one. In case of overflows in the reference channel, this index will be incremented by the number of missed pulses.

Returns:: A list of indices for each pulse from the reference source.

float[] getReferenceOffsets()

A list of offsets of each reference pulse with respective to its predecessor, with the period subtracted. For a perfect PPS source, this offset would always be zero. The offset of the first pulse is always defined to be zero. If a reference signal is missing, its offset is defined to be NaN.

Returns:: A list of the offsets of each reference with respect to the previous.

float[,] getSignalOffsets()

For each reference contained in the PulsePerSecondData object a list of offsets for each signal channel is given, in the channel order given by signal_channels. If any signal is missing, its offset is defined to be NaN.

Returns:: A list of lists of offsets for each signal_channel for given reference pulses.

float[] getUtcSeconds()

The number of elapsed seconds from the beginning of the Unix epoch (1st of January 1970) to the time at which each reference pulse is processed, as a floating point number.

Returns:: A list of the number of seconds since the Unix epoch to the time of processing, for each reference pulse.

str[] getUtcDates()

The UTC timestamps for the system time at which each reference pulse is processed, as a string with ISO 8601 formatting (YYYY-MM-DD hh:mm:ss.ssssss).

Returns:: A list of the UTC timestamp at processing time, for each reference pulse.

bool[] getStatus()

A list of booleans values describing whether all signals, including from the reference source, were detected. True corresponds to a complete collection of signals, False otherwise.

Returns:: A list of bools describing the signal integrity for each reference pulse.

Public Members

int size: Number of reference pulses contained in the PulsePerSecondData object.

Time-tag-streaming

Measurement classes described in this section provide direct access to the time tag stream with minimal or no pre-processing.

Time tag format

The time tag contain essential information about the detected event and have the following format:

Size	Type	Description
8 bit	enum `Tag::Type`	overflow type
8 bit	–	reserved
16 bit	uint16	number of missed events
32 bit	int32	channel number
64 bit	int64	time in ps from device start-up

TimeTagStream

class TimeTagStream : public IteratorBase 

Allows user to access a copy of the time tag stream. It allocates a memory buffer of the size max_tags which is filled with the incoming time tags that arrive from the specified channels. User shall call getData() method periodically to obtain the current buffer containing timetags collected. This action will return the current buffer object and create another empty buffer to be filled until the next call to getData().

See all common methods

Public Functions

TimeTagStream(TimeTaggerBase tagger, int n_max_events, channel_t[] channels)

Parameters:

tagger – Time tagger object instance.
n_max_events – Buffer size for storing time tags.
channels – List of channels to be captured.

TimeTagStreamBuffer getData()

Returns a TimeTagStreamBuffer object and clears the internal buffer of the TimeTagStream measurement. Clearing the internal buffer on each call to getData() guarantees that consecutive calls to this method will return every time-tag only once. Data loss may occur if getData() is not called frequently enough with respect to n_max_events.

Returns:: Buffer object containing timetags collected.

int getCounts()

Returns:: The number of stored tags since the last call to getData().

class TimeTagStreamBuffer

Public Functions

timestamp_t[] getTimestamps()

Returns an array of timestamps.

Returns:: Event timestamps in picoseconds for all chosen channels.

channel_t[] getChannels()

Returns an array of channel numbers for every timestamp.

Returns:: Channel number for each detected event.

int[] getOverflows()

Deprecated:: Since version 2.5. Please use getEventTypes() instead.

int[] getEventTypes()

Returns an array of event type for every timestamp. See, Time tag format . The method returns plain integers, but you can use Tag::Type to compare the values.

Returns:: Event type value for each detected event.

int[] getMissedEvents()

Returns an array of missed event counts during an stream overflow situation.

Returns:: Missed events value for each detected event.

Public Members

int size: Number of events stored in the buffer. If the size equals the maximum size of the buffer set in TimeTagStream via n_max_events, events have likely been discarded.

bool hasOverflows: Returns True if a stream overflow was detected in any of the tags received. Note: this is independent of an overflow of the internal buffer of TimeTagStream.

timestamp_t tStart: Return the data-stream time position when the TimeTagStream or FileWriter started data acquisition.

timestamp_t tGetData: Return the data-stream time position of the call to TimeTagStream::getData() method that created this object.

FileWriter

class FileWriter : public IteratorBase 

Writes the time-tag-stream into a file in a structured binary format with a lossless compression. The estimated file size requirements are 2-4 Bytes per time tag, not including the container the data is stored in. The continuous background data rate for the container can be modified via TimeTagger::setStreamBlockSize(). Data is processed in blocks and each block header has a size of 160 Bytes. The default processing latency is 20 ms, which means that a block is written every 20 ms resulting in a background data rate of 8 kB/s. By increasing the processing latency via TimeTagger::setStreamBlockSize(max_events=524288, max_latency=1000) to 1 s, the resulting data rate for the container is reduced to one 160 B/s. The files created with FileWriter measurement can be read using FileReader or loaded into the Virtual Time Tagger.

The FileWriter is able to split the data into multiple files seamlessly when the file size reaches a maximal size. For the file splitting to work properly, the filename specified by the user will be extended with a suffix containing sequential counter, so the filenames will look like in the following example:

fw = FileWriter(tagger, 'filename.ttbin', [1,2,3]) # Store tags from channels 1,2,3
# When splitting occurs the files with following names will be created
#    filename.ttbin     # the sequence header file with no data blocks
#    filename.1.ttbin   # the first file with data block
#    filename.2.ttbin
#    filename.3.ttbin
#    ...

In addition, the FileWriter will query and store the configuration of the Time Tagger in the same format as returned by the TimeTaggerBase::getConfiguration() method. The configuration is always written into every file.

See also: FileReader , The TimeTaggerVirtual class , and mergeStreamFiles.

See all common methods

Note

You can use the Dump for dumping into a simple uncompressed binary format. However, you will not be able to use this file with Virtual Time Tagger or FileReader.

Public Functions

FileWriter(TimeTaggerBase tagger, str filename, channel_t[] channels)

Class constructor. As with all other measurements, the data recording starts immediately after the class instantiation unless you initialize the FileWriter with a SynchronizedMeasurements.

Note

Compared to the Dump measurement, the FileWriter requires explicit specification of the channels. If you want to store timetags from all input channels, you can query the list of all input channels with TimeTagger::getChannelList().

Parameters:

tagger – The time tagger object.
filename – Name of the output file.
channels – List of real or virtual channels.

void split(str new_filename = "")

Close the current file and create a new one. If the new_filename is provided, the data writing will continue into the file with the new filename and the sequence counter will be reset to zero.

You can force the file splitting when you call this method without parameter or when the new_filename is an empty string.

Parameters:: new_filename – Filename of the new file. If empty, the old one will be used (default: empty).

void setMaxFileSize(int max_file_size)

Set the maximum file size on disk. When this size is exceeded a new file will be automatically created to continue recording.

The actual file size might be larger by one block.

Parameters:: max_file_size – Maximum file size in bytes (default: ~1 GByte).

int getMaxFileSize()

Returns:: The maximal file size in bytes. See also setMaxFileSize().

int getTotalEvents()

Returns:: The total number of events written into the file(s).

int getTotalSize()

Returns:: The total number of bytes written into the file(s).

void setMarker(str marker)

Writes a comment into the file. While reading the file using the FileReader, the last marker can be extracted.

Parameters:: marker – An arbitrary marker string to write at the current location in the file.

FileReader

class FileReader

This class allows you to read data files store with FileReader. The FileReader reads a data block of the specified size into a TimeTagStreamBuffer object and returns this object. The returned data object is exactly the same as returned by the TimeTagStream measurement and allows you to create a custom data processing algorithms that will work both, for reading from a file and for the on-the-fly processing.

The FileReader will automatically recognize if the files were split and read them too one by one.

Example:

# Lets assume we have following files created with the FileWriter
#  measurement.ttbin     # sequence header file with no data blocks
#  measurement.1.ttbin   # the first file with data blocks
#  measurement.2.ttbin
#  measurement.3.ttbin
#  measurement.4.ttbin
#  another_meas.ttbin
#  another_meas.1.ttbin

# Read all files in the sequence 'measurement'
fr = FileReader("measurement.ttbin")

# Read only the first data file
fr = FileReader("measurement.1.ttbin")

# Read only the first two files
fr = FileReader(["measurement.1.ttbin", "measurement.2.ttbin"])

# Read the sequence 'measurement' and then the sequence 'another_meas'
fr = FileReader(["measurement.ttbin", "another_meas.ttbin"])

See also: FileWriter , The TimeTaggerVirtual class , and mergeStreamFiles.

Public Functions

FileReader(str[] filenames)

This is the class constructor. The FileReader automatically continues to read files that were split by the FileWriter.

Parameters:: filenames – Filename(s) of the files to read.

TimeTagStreamBuffer getData(int n_events)

Reads the next n_events and returns the buffer object with the specified number of timetags. The FileReader stores the current location in the data file and guarantees that every timetag is returned once. If less than n_elements are returned, the reader has reached the end of the last file in the file-list filenames. To check if more data is available for reading, it is more convenient to use hasData().

Parameters:: n_events – Number of timetags to read from the file.
Returns:: A buffer of size n_events.

bool hasData()

Returns:: True if more data is available for reading, False if all data has been read from all the files specified in the class constructor.

str getConfiguration()

Returns:: A JSON formatted string (dict in Python) that contains the Time Tagger configuration at the time of file creation.

channel_t[] getChannelList()

Returns:: All channels available within the input file

str getLastMarker()

Returns:: The last processed marker from the file (see also FileWriter::setMarker()).

Dump

class Dump : public IteratorBase 

Writes the timetag stream into a file in a simple uncompressed binary format that store timetags as 128bit records, see Time tag format .

See all common methods

Warning

The files created with this class are not readable by TimeTaggerVirtual and FileReader. For storing time tag data intended for re-reading or postprocessing, use the FileWriter measurement class instead.

Public Functions

Dump(TimeTaggerBase tagger, str filename, int max_tags, channel_t[] channels = channel_t[]())

Parameters:

tagger – Time Tagger object instance.
filename – Name of the output file.
max_tags – Stop after this number of tags has been dumped. Negative values will dump forever.
channels – List of channels which are dumped to the file (when empty or not passed all active channels are dumped).

Scope

class Scope : public IteratorBase 

../_images/Scope.svg

The Scope class allows to visualize time tags for rising and falling edges in a time trace diagram similarly to an ultrafast logic analyzer. The trace recording is synchronized to a trigger signal which can be any physical or virtual channel. However, only physical channels can be specified to the event_channels parameter. Additionally, one has to specify the time window_size which is the timetrace duration to be recorded, the number of traces to be recorded and the maximum number of events to be detected. If n_traces < 1 then retriggering will occur infinitely, which is similar to the “normal” mode of an oscilloscope.

See all common methods

Note

Scope class implicitly enables the detection of positive and negative edges for every physical channel specified in event_channels. This accordingly doubles the data rate requirement per input.

Public Functions

Scope(TimeTaggerBase tagger, channel_t[] event_channels, channel_t trigger_channel, timestamp_t window_size = 1000000000, int n_traces = 1, int n_max_events = 1000)

Parameters:

tagger – The time tagger object instance.
event_channels – List of channels.
trigger_channel – Channel number of the trigger signal.
window_size – Time window in picoseconds (default: 1 ms).
n_traces – Number of trigger events to be detected (default: 1).
n_max_events – Max number of events to be detected (default: 1000).

Event[][] getData()

Returns a tuple of the size equal to the number of event_channels multiplied by n_traces, where each element is a tuple of Event.

Returns:: Event list for each trace.

bool ready()

Returns:: Returns whether the acquisition is complete which means that all traces (n_traces) are acquired.

int triggered()

Returns:: Returns number of trigger events have been captured so far.

timestamp_t getWindowSize()

Returns:: Returns the windows_size parameter.

struct Event

Pair of the timestamp and the new state returned by Scope::getData.

Public Members

timestamp_t time: Timestamp in ps.

State state: Input state.

enum State

Current input state. Can be unknown because no edge has been detected on the given channel after initialization or an overflow.

Values:

enumerator UNKNOWN

enumerator HIGH

enumerator LOW

Sampler

class Sampler : public IteratorBase 

../_images/Sampler.svg

The Sampler class allows sampling the state of a set of channels via a trigger channel.

For every event on the trigger input, the current state (low: 0, high: 1, unknown: 2) will be written to an internal buffer. Fetching the data of the internal buffer will clear its internal buffer, so every event will be returned only once.

Time Tagger detects pulse edges and therefore a channel will be in the unknown state until an edge detection event was received on that channel from the start of the measurement or after an overflow. The internal processing assumes that no event could be received within the channel’s deadtime otherwise invalid data will be reported until the next event on this input channel.

See all common methods

Note

The maximum number of channels is limited to 63 for one Sampler instance.

Public Functions

Sampler(TimeTaggerBase tagger, channel_t trigger, channel_t[] channels, int max_triggers)

Parameters:

tagger – The time tagger object instance.
trigger – Channel number of the trigger signal.
channels – List of channels to be sampled.
max_triggers – The number of triggers and their respective sampled data, which is stored within the measurement class.

timestamp_t[,] getData()

Returns and removes the stored data as a 2D array (n_triggers x (n_channels + 1)):

[timestamp of first trigger,  state of channel 0, state of channel 1, ...],
[timestamp of second trigger, state of channel 0, state of channel 1, ...],
...

Where the state means:

-- low
-- high
-- undefined (after overflow)

Returns:: Sampled data

timestamp_t[,] getDataAsMask()

Returns and removes the stored data as a 2D array (n_triggers x 2):

[timestamp of first trigger,  (state of channel 0) << 0 | (state of channel 1) << 1 | ... | any_undefined << 63],
[timestamp of second trigger, (state of channel 0) << 0 | (state of channel 1) << 1 | ... | any_undefined << 63],
...

Where state means:

0 -- low or undefined (after overflow)
1 -- high

If the highest bit (data[63]) is marked, one of the channels has been in an undefined state.

Returns:: Sampled data.

Helper classes

SynchronizedMeasurements

class SynchronizedMeasurements

The SynchronizedMeasurements class allows for synchronizing multiple measurement classes in a way that ensures all these measurements to start, stop simultaneously and operate on exactly the same time tags. You can pass a Time Tagger proxy-object returned by getTagger() to every measurement you create. This will simultaneously disable their autostart and register for synchronization.

Public Functions

SynchronizedMeasurements(TimeTaggerBase tagger)

Parameters:: tagger – The time tagger object instance.

TimeTaggerBase getTagger()

Returns a proxy tagger object which can be passed to the constructor of a measurement class to register the measurements at initialization to the synchronized measurement object. Those measurements will not start automatically.

Note

The proxy tagger object returned by getTagger() is not identical with the TimeTagger object created by createTimeTagger(). You can create synchronized measurements with the proxy object the following way:

tagger = TimeTagger.createTimeTagger()
syncMeas = TimeTagger.SynchronizedMeasurements(tagger)
taggerSync = syncMeas.getTagger()
counter = TimeTagger.Counter(taggerSync, [1, 2])
countrate = TimeTagger.Countrate(taggerSync, [3, 4])

Passing tagger as a constructor parameter would lead to the not synchronized behavior.

void start(): Calls IteratorBase::start() for every registered measurement in a synchronized way.

void startFor(timestamp_t capture_duration, bool clear = true)

Calls IteratorBase::startFor() for every registered measurement in a synchronized way.

Parameters:

capture_duration – Acquisition duration in picoseconds.
clear – Resets the accumulated data at the beginning (default: True).

void stop(): Calls IteratorBase::stop() for every registered measurement in a synchronized way.

void clear(): Calls IteratorBase::clear() for every registered measurement in a synchronized way.

bool waitUntilFinished(int timeout = -1)

Equivalent to IteratorBase::waitUntilFinished() for synchronized measurements.

Parameters:: timeout – Timeout in milliseconds. Negative value means no timeout, zero returns immediately.
Returns:: True if the synchronized measurements have finished, False on timeout.

bool isRunning(): Calls IteratorBase::isRunning() for every registered measurement and returns true if any measurement is running.

void registerMeasurement(IteratorBase measurement)

Registers the measurement object into a pool of the synchronized measurements.

Note

Registration of the measurement classes with this method does not synchronize them. In order to start/stop/clear these measurements synchronously, call these functions on the SynchronizedMeasurements object after registering the measurement objects, which should be synchronized.

Parameters:: measurement – Any measurement (IteratorBase) object.

void unregisterMeasurement(IteratorBase measurement)

Unregisters the measurement object out of the pool of the synchronized measurements.

Note

This method does nothing if the provided measurement is not currently registered.

Parameters:: measurement – Any measurement (IteratorBase) object.

Custom Measurements

The class CustomMeasurement allows you to access the raw time tag stream with very little overhead. By inheriting from CustomMeasurement, you can implement your fully customized measurement class. The CustomMeasurement.process() method of this class will be invoked as soon as new data is available.

Note

This functionality is only available for C++, C# and Python. You can find examples of how to use the CustomMeasurement in your examples folder.

class CustomMeasurement(tagger)

Parameters:: tagger (TimeTaggerBase) – TimeTagger object

The constructor of the CustomMeasurement class itself takes only the parameter tagger. When you sub-class your own measurement, you can add to your constructor any parameters that are necessary for your measurement. You can find detailed examples in your example folder.

See all common methods

process(incoming_tags, begin_time, end_time)

Parameters:

incoming_tags – Tag[][struct{type, missed_events, channel, time}], the chunk of time-tags to be processed in this call of process(). This is an external reference that is shared with other measurements and might be overwritten for the next call. So if you need to store tags, create a copy.
begin_time (int) – The begin time of the data chunk.
end_time (int) – The end time of the data chunk

Override the process() method to include your data processing. The method will be called by the Time Tagger backend when a new chunk of time-tags is available. You are free to execute any code you like, but be aware that this is the critical part when it comes to performance. In Python, it is advisable to use numpy.array() for calculation or even pre-compiled code with Numba if an explicit iteration of the tags is necessary. Check the examples in your examples folder carefully on how to design the process() method.

Note

In Python, the incoming_tags are a structured Numpy array. You can access single tags as well as arrays of tag entries directly:

first_tag = incoming_tags[0]
all_timestamps = incoming_tags['time']

mutex

Context manager object (see Context Manager Types) that locks the mutex when used and automatically unlocks it when the code block exits. For example, it is intended for use with Python’s “with” keyword as

class MyMeasurement(CustomMeasurement):

    def getData(self):
        # Acquire a lock for this instance to guarantee that
        # self.data is not modified in other parallel threads.
        # This ensures to return a consistent data.
        with self.mutex:
            return self.data.copy()