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: Auto- and Cross-correlation measurement.
CountBetweenMarkers: Counts tags on one channel within bins which are determined by triggers on one or two other channels. Uses a static buffer output. Use this to implement a gated counter, a counter synchronized to external signals, etc.
Counter: Counts the clicks on one or more channels with a fixed bin width and a circular buffer output.
Countrate: Average tag rate on one or more channels.
Flim: Fluorescence lifetime imaging.
FrequencyCounter: Analyze the phase evolution of multiple channels at periodic sampling points.
FrequencyStability: Analyzes the frequency stability of period signals.
PulsePerSecondMonitor: Monitors the synchronicity of 1 pulse per second (PPS) signals.
IteratorBase: Base class for implementing custom measurements (only C++).
Histogram: A simple histogram of time differences. This can be used to measure lifetime, for example.
Histogram2D: A 2-dimensional histogram of correlated time differences. This can be used in measurements similar to 2D NMR spectroscopy. (Single-Start, Single-Stop)
HistogramND: A n-dimensional histogram of correlated time differences. (Single-Start, Single-Stop)
HistogramLogBins: Accumulates time differences into a histogram with logarithmic increasing bin sizes.
Scope: Detects the rising and falling edges on a channel to visualize the incoming signals similar to an ultrafast logic analyzer.
StartStop: Accumulates a histogram of time differences between pairs of tags on two channels. Only the first stop tag after a start tag is considered. Subsequent stop tags are discarded. The histogram length is unlimited. Bins and counts are stored in an array of tuples. (Single-Start, Single-Stop)
TimeDifferences: Accumulates the time differences between tags on two channels in one or more histograms. The sweeping through of histograms is optionally controlled by one or two additional triggers.
TimeDifferencesND: A multidimensional implementation of the TimeDifferences measurement for asynchronous next histogram triggers.
SynchronizedMeasurements: Helper class that allows synchronization of the measurement classes.
Dump: Deprecated - please use FileWriter instead. Dump measurement writes all time-tags into a file.
TimeTagStream: This class provides you with access to the time-tag stream and allows you to implement your own on-the-fly processing. See Raw Time-Tag-Stream access to get on overview about the possibilities for the raw time-tag-stream access.
Sampler: The Sampler class allows sampling the state of a set of channels via a trigger channel.
FileWriter: This class writes time-tags into a file with a lossless compression. It replaces the Dump class.
FileReader: Allows you to read time-tags from a file written by the FileWriter.

Common methods

class IteratorBase

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

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

startFor(duration[, 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.

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

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/False
Return type:: bool

waitUntilFinished(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 (int) – timeout in milliseconds. Negative value means no timeout, zero returns immediately.
Returns:: True if the measurement has finished, False on timeout
Return type:: bool

getCaptureDuration()

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

Returns:: Capture duration in ps
Return type:: int

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.
Return type:: dict

Event counting

Countrate

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.

class Countrate(tagger, channels)

Parameters:

tagger (TimeTaggerBase) – time tagger object instance
channels (list[int]) – channels for which the average count rate is measured

See all common methods

getData()

Returns:: Average count rate in counts per second.
Return type:: 1D_array[float]

getCountsTotal()

Returns:: The total number of events since the instantiation of this object.
Return type:: 1D_array[int]

Counter

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).

class Counter(tagger, channels[, binwidth=1e9, n_values=1])

Parameters:

tagger (TimeTaggerBase) – time tagger object
channels (list[int]) – channels used for counting tags
binwidth (int) – bin width in ps (default: 1e9)
n_values (int) – number of bins (default: 1)

See all common methods

getData([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 (bool) – Controls how the counter array is filled.
Returns:: An array of size ‘number of channels’ by n_values containing the counts in each fully integrated bin.
Return type:: 2D_array[int]

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.
Return type:: 1D_array[int]

getDataNormalized([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.

Return type:: 2D_array[float]

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.
Return type:: 1D_array[int]

getDataObject(remove=False)

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

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

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.

size: int: Number of returned bins.

dropped_bins: int: Number of bins which have been dropped because n_values of the Counter has been exceeded.

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

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.
Return type:: 1D_array[int]

getData()

Returns:: An array of size ‘number of channels’ by size containing only fully integrated bins.
Return type:: 2D_array[int]

getDataNormalized()

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

Return type:: 2D_array[float]

getFrequency(time_scale: int = 1_000_000_000_000)

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.
Return type:: 2D_array[float]

getDataTotalCounts()

Returns the total number of events per channel since the last call to 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.
Return type:: 1D_array[int]

getTime()

This is similar to getIndex() but it returns the absolute timestamps of the bins. For subsequent calls to 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 CounterData.getData() in ps.
Return type:: 1D_array[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.
Return type:: 1D_array[int]

CountBetweenMarkers

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.

class CountBetweenMarkers(tagger, click_channel, begin_channel[, end_channel=CHANNEL_UNUSED, n_values=1000])

Parameters:

tagger (TimeTaggerBase) – time tagger object
click_channel (int) – channel on which clicks are received, gated by begin_channel and end_channel
begin_channel (int) – channel that triggers the beginning of counting and stepping to the next value
end_channel (int) – channel that triggers the end of counting (optional, default: CHANNEL_UNUSED)
n_values (int) – number of values stored (data buffer size) (default: 1000)

See all common methods

getData()

Returns:: Array of size n_values containing the acquired counter values.
Return type:: 1D_array[int]

getIndex()

Returns:: Vector of size n_values containing the time in ps of each start click in respect to the very first start click.
Return type:: 1D_array[int]

getBinWidths()

Returns:: Vector of size n_values containing the time differences of ‘start -> (next start or stop)’ for the acquired counter values.
Return type:: 1D_array[int]

ready()

Returns:: True when the entire array is filled.
Return type:: bool

Time histograms

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

StartStop

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 (number of bins) 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.

class StartStop(tagger, click_channel[, start_channel=CHANNEL_UNUSED, binwidth=1000])

Parameters:

tagger (TimeTaggerBase) – time tagger object instance
click_channel (int) – channel on which stop clicks are received
start_channel (int) – channel on which start clicks are received (default: CHANNEL_UNUSED)
binwidth (int) – bin width in ps (default: 1000)

See all common methods

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.
Return type:: 2D_array[int]

Histogram

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.

class Histogram(tagger, click_channel[, start_channel=CHANNEL_UNUSED, binwidth=1000, n_bins=1000])

Parameters:

tagger (TimeTaggerBase) – time tagger object instance
click_channel (int) – channel on which clicks are received
start_channel (int) – channel on which start clicks are received (default: CHANNEL_UNUSED)
binwidth (int) – bin width in ps (default: 1000)
n_bins (int) – the number of bins in the histogram (default: 1000)

See all common methods

getData()

Returns:: A one-dimensional array of size n_bins containing the histogram.
Return type:: 1D_array[int]

getIndex()

Returns:: A vector of size n_bins containing the time bins in ps.
Return type:: 1D_array[int]

HistogramLogBins

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)$ .

class HistogramLogBins(tagger, click_channel, start_channel, exp_start, ex_stop, n_bins, click_gate=None, start_gate=None)

Parameters:

tagger (TimeTaggerBase) – time tagger object instance
click_channel (int) – channel on which clicks are received
start_channel (int) – channel on which start clicks are received
exp_start (float) – exponent 10^exp_start in seconds where the very first bin begins
exp_stop (float) – exponent 10^exp_stop in seconds where the very last bin ends
n_bins (int) – the number of bins in the histogram
click_gate (ChannelGate) – optional evaluation gate for the click_channel
start_gate (ChannelGate) – optional evaluation gate for the start_channel

See all common methods

getDataObject()

Returns:: A data object containing raw and normalization data.
Return type:: HistogramLogBinsData

getBinEdges()

Returns:: A vector of size n_bins+1 containing the bin edges in picoseconds.
Return type:: 1D_array[int]

getData()

Deprecated since version 2.17.0: please use HistogramLogBins.getDataObject() and HistogramLogBinsData.getCounts() instead.

Returns:: A one-dimensional array of size n_bins containing the histogram.
Return type:: 1D_array[int]

getDataNormalizedCountsPerPs()

Deprecated since version 2.17.0.

Returns:: The counts normalized by the binwidth of each bin.
Return type:: 1D_array[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.
Return type:: 1D_array[float]

class HistogramLogBinsData

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

getG2()

Returns:: A one-dimensional array of size n_bins containing the normalized histogram $H(\tau)/\widetilde{H}(\tau)$ .
Return type:: 1D_array[float]

getCounts()

Returns:: A one-dimensional array of size n_bins containing the raw histogram $H(\tau)$ .
Return type:: 1D_array[int]

getG2Normalization()

Returns:: A one-dimensional array of size n_bins containing the normalization $\widetilde{H}(\tau)$ .
Return type:: 1D_array[float]

Histogram2D

This measurement is a 2-dimensional version of the Histogram measurement. The measurement accumulates a 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.

class Histogram2D(tagger, start_channel, stop_channel_1, stop_channel_2, binwidth_1, binwidth_2, n_bins_1, n_bins_2)

Parameters:

tagger (TimeTaggerBase) – time tagger object
start_channel (int) – channel on which start clicks are received
stop_channel_1 (int) – channel on which stop clicks for the time axis 1 are received
stop_channel_2 (int) – channel on which stop clicks for the time axis 2 are received
binwidth_1 (int) – bin width in ps for the time axis 1
binwidth_2 (int) – bin width in ps for the time axis 2
n_bins_1 (int) – the number of bins along the time axis 1
n_bins_2 (int) – the number of bins along the time axis 2

See all common methods

getData()

Returns:: A two-dimensional array of size n_bins_1 by n_bins_2 containing the 2D histogram.
Return type:: 2D_array[int]

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
Return type:: 3D_array[int]

getIndex_1()

Returns:: A vector of size n_bins_1 containing the bin locations in ps for the time axis 1.
Return type:: 1D_array[int]

getIndex_2()

Returns:: A vector of size n_bins_2 containing the bin locations in ps for the time axis 2.
Return type:: 1D_array[int]

HistogramND

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.

class HistogramND(tagger, start_channel, stop_channels, binwidths, n_bins)

Parameters:

tagger (TimeTagger) – time tagger object
start_channel (int) – channel on which start clicks are received
stop_channels (list[int]) – channel list on which stop clicks are received defining the time axes
binwidths (list[int]) – bin width in ps for the corresponding time axis
n_bins (list[int]) – the number of bins along the corresponding time axis

See all common methods

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.
Return type:: 1D_array[int]

getIndex(dim)

Returns:: Returns a vector of size n_bins[dim] containing the bin locations in ps for the corresponding time axis.
Return type:: 1D_array[int]

Correlation

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

class Correlation(tagger, channel_1[, channel_2=CHANNEL_UNUSED, binwidth=1000, n_bins=1000])

Parameters:

tagger (TimeTaggerBase) – time tagger object
channel_1 (int) – channel on which (stop) clicks are received
channel_2 (int) – 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 (int) – bin width in ps (default: 1000)
n_bins (int) – the number of bins in the resulting histogram (default: 1000)

See all common methods

getData()

Returns:: A one-dimensional array of size n_bins containing the histogram.
Return type:: 1D_array[int]

getDataNormalized()

Return the data normalized as:

$g^{(2)}(\tau) = \frac{\Delta{t}}{binwidth \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.
Return type:: 1D_array[float]

getIndex()

Returns:: A vector of size n_bins containing the time bins in ps.
Return type:: 1D_array[int]

TimeDifferences

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.

class TimeDifferences(tagger, click_channel, start_channel=CHANNEL_UNUSED, next_channel=CHANNEL_UNUSED, sync_channel=CHANNEL_UNUSED, binwidth=1000, n_bins=1000, n_histograms=1)

Parameters:

tagger (TimeTaggerBase) – time tagger object instance
click_channel (int) – channel on which stop clicks are received
start_channel (int) – channel that sets start times relative to which clicks on the click channel are measured
next_channel (int) – channel that increments the histogram index
sync_channel (int) – channel that resets the histogram index to zero
binwidth (int) – binwidth in picoseconds
n_bins (int) – number of bins in each histogram
n_histograms (int) – number of histograms

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.

See all common methods

getData()

Returns:: A two-dimensional array of size n_bins by n_histograms containing the histograms.
Return type:: 2D_array[int]

getIndex()

Returns:: A vector of size n_bins containing the time bins in ps.
Return type:: 1D_array[int]

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

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 next_channel is defined)
0 … (n_histograms - 1): Index of the currently processed histogram

Return type:

int

getCounts()

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

ready()

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

TimeDifferencesND

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, reset the histogram index of the associated dimension, and a subsequent event on the corresponding next_channel starts the accumulation again. The synchronization is done asynchronous, so an event on the next_channel increases the histogram index even if the accumulation is stopped. The accumulation starts 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

class TimeDifferencesND(tagger, click_channel, start_channel, next_channels, sync_channels, n_histograms, binwidth, n_bins)

Parameters:

tagger (TimeTaggerBase) – time tagger object instance
click_channel (int) – channel on which stop clicks are received
start_channel (int) – channel that sets start times relative to which clicks on the click channel are measured
next_channels (list[int]) – vector of channels that increments the histogram index
sync_channels (list[int]) – vector of channels that resets the histogram index to zero
n_histograms (int) – vector of numbers of histograms per dimension
binwidth (int) – width of one histogram bin in ps
n_bins (int) – number of bins in each histogram

See all common methods

See methods of TimeDifferences class.

Fluorescence-lifetime imaging (FLIM)

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

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(tagger, start_channel, click_channel, pixel_begin_channel, n_pixels, n_bins, binwidth[, pixel_end_channel=CHANNEL_UNUSED, frame_begin_channel=CHANNEL_UNUSED, finish_after_outputframe=0, n_frame_average=1, pre_initialize=True])

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.

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.

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.

Parameters:

tagger (TimeTaggerBase) – time tagger object instance
start_channel (int) – channel on which clicks are received for the time differences histogramming
click_channel (int) – channel on which start clicks are received for the time differences histogramming
pixel_begin_channel (int) – start marker of a pixel (histogram)
n_pixels (int) – number of pixels (histograms) of one frame
n_bins (int) – number of histogram bins for each pixel
binwidth (int) – bin size in picoseconds
pixel_end_channel (int) – end marker of a pixel - incoming clicks on the click_channel will be ignored afterward. (optional)
frame_begin_channel (int) – start the frame, or reset the pixel index. (optional)
finish_after_outputframe (int) – 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 (int) – average multiple input frames into one output frame, (optional, default: 1)
pre_initialize (bool) – 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.

See all common methods

getCurrentFrame()

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

getCurrentFrameEx()

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

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.
Return type:: 1D_array[float]

getFramesAcquired()

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

getIndex()

Returns:: A vector of size n_bins containing the time bins in ps.
Return type:: 1D_array[int]

getReadyFrame([index =-1])

Parameters:: index (int) – Index of the frame to be obtained. If -1, the last frame which has been completed is returned. (optional)
Returns:: The histograms for all pixels according to the frame index given. If the 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]
Return type:: 2D_array[int]

getReadyFrameEx([index =-1])

Parameters:: index (int) – Index of the frame to be obtained. If -1, the latest frame which has been completed is returned. (optional)
Returns:: The frame according to the index given. If the 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.
Return type:: FlimFrameInfo

getReadyFrameIntensity([index =-1])

Parameters:: index (int) – Index of the frame to be obtained. If -1, the last frame which has been completed is returned. (optional)
Returns:: The intensities according to the frame index given. If the 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.
Return type:: 1D_array[float]

getSummedFrames([only_ready_frames=True, clear_summed=False])

Parameters:

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

Returns:

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

Return type:

2D_array[int]

getSummedFramesEx([only_ready_frames=True, clear_summed=False])

Parameters:

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

Returns:

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

Return type:

FlimFrameInfo

getSummedFramesIntensity([only_ready_frames=True, clear_summed=False])

Parameters:

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

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.

Return type:

1D_array[float]

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
Return type:: bool

frameReady(frame_number, data, pixel_begin_times, pixel_end_times, frame_begin_time, frame_end_time)

Parameters:

frame_number (int) – current frame number
data (1D_array[int]) – 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 (list[int]) – start time for each pixel
pixel_end_times (list[int]) – end time for each pixel
frame_begin_time (int) – start time of the frame
frame_end_time (int) – end time of the frame

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.

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

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.

class FlimFrameInfo

pixels: int: number of pixels in the frame

bins: int: number of bins of each histogram

frame_number: int: current frame number

pixel_position: int: current pixel position

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.
Return type:: int

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.
Return type:: bool

getPixelPosition()

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

getHistograms()

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

getIntensities()

Returns:: The summed counts of each histogram divided by the integration time.
Return type:: 1D_array[float]

getSummedCounts()

Returns:: The summed counts of each histogram.
Return type:: 1D_array[int]

getPixelBegins()

Returns:: An array of the start timestamps of each pixel.
Return type:: 1D_array[int]

getPixelEnds()

Returns:: An array of the end timestamps of each pixel.
Return type:: 1D_array[int]

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 frameReady() callback, which must be used to analyze the data.

class FlimBase(tagger, start_channel, click_channel, pixel_begin_channel, n_pixels, n_bins, binwidth[, pixel_end_channel=CHANNEL_UNUSED, frame_begin_channel=CHANNEL_UNUSED, finish_after_outputframe=0, n_frame_average=1, pre_initialize=True])

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.

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.

Parameters:

tagger (TimeTaggerBase) – time tagger object instance
start_channel (int) – channel on which clicks are received for the time differences histogramming
click_channel (int) – channel on which start clicks are received for the time differences histogramming
pixel_begin_channel (int) – start marker of a pixel (histogram)
n_pixels (int) – number of pixels (histograms) of one frame
n_bins (int) – number of histogram bins for each pixel
binwidth (int) – bin size in picoseconds
pixel_end_channel (int) – end marker of a pixel - incoming clicks on the click_channel will be ignored afterward. (optional, default: CHANNEL_UNUSED)
frame_begin_channel (int) – start the frame, or reset the pixel index. (optional, default: CHANNEL_UNUSED)
finish_after_outputframe (int) – 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 (int) – average multiple input frames into one output frame. (optional, default: 1)
pre_initialize (bool) – 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.

See all common methods

isAcquiring()

Returns:: A boolean which tells the user if the class is still acquiring data. It can only reach the false state for stop_after_outputframe > 0. This is different from isRunning() as once frame(s) acquisition is done, it can’t be started again.
Return type:: bool

frameReady(frame_number, data, pixel_begin_times, pixel_end_times, frame_begin_time, frame_end_time)

Parameters:

frame_number (int) – current Frame number
data (1D_array[int]) – 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 (list[int]) – start time for each pixel
pixel_end_times (list[int]) – end time for each pixel
frame_begin_time (int) – start time of the frame
frame_end_time (int) – end time of the frame

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 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.

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

Phase & frequency analysis

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

FrequencyStability

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). The 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 (MDEV)

Time Deviation TDEV = $\frac{\tau}{\sqrt{3}}$ MDEV

Hadamard Deviation (HDEV )

HDEVScaled = $\frac{\tau}{\sqrt{10 / 3}}$ HDEV

class FrequencyStability(tagger, channel, steps, average, trace_len)

Parameters:

channel (int) – The input channel number.
steps (list[int]) – 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 (int) – The number of time-tags to average internally. This downsampling allows for a reduction of noise and memory requirements. Default is 1000.
trace_len (int) – Number of data points in the phase and frequency error traces, calculated from averaged data. The trace always contains the latest data. Default is 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.

getDataObject()

Returns:: An object that allows access to the current metrics
Return type:: FrequencyStabilityData

class FrequencyStabilityData

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.
Return type:: 1D_array[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.
Return type:: 1D_array[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.
Return type:: 1D_array[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 Hadamard Deviation.
Return type:: 1D_array[float]

getSTDD()

Caution

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.

Standard deviation of the periods.

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

getADEVScaled()

Domain:: Time domain
Returns:: The scaled version of the overlapping Allan Deviation, equivalent to getADEV() * getTau() / $\sqrt{3}$ .
Return type:: 1D_array[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}$ .
Return type:: 1D_array[float]

getHDEVScaled()

Caution

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}$ .
Return type:: 1D_array[float]

getTraceIndex()

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

Returns:: The time index in seconds of the phase and frequency error trace.
Return type:: 1D_array[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.
Return type:: 1D_array[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.
Return type:: 1D_array[float]

getTraceFrequencyAbsolute(input_frequency: float = 0.0)

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

Parameters:: input_frequency (float) – Nominal frequency of the periodic signal. Default is 0 Hz.
Returns:: A trace of the last trace_len frequency data points in Hz.
Return type:: 1D_array[float]

FrequencyCounter

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.

class FrequencyCounter(tagger, channels: list[int], sampling_interval: int, fitting_window: int, n_values: int = 0)

Parameters:

tagger (TimeTaggerBase) – Time Tagger object instance
channels (list[int]) – List of channels to analyze
sampling_interval (int) – 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 (int) – Time tags within this range around a sampling point are fitted for phase calculation
n_values (int) – Maximum number of sampling points to store

getDataObject(event_divider: int = 1, remove: bool = 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 (int) – Compensate for the EventDivider. Default: 1.
remove (bool) – Control if data is removed from the internal buffer. Default: True.

Returns:

An object providing access to a snapshot data.

Return type:

FrequencyCounterData

class FrequencyCounterData

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

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

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

sampling_interval: int: The sampling interval in picoseconds.

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

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
Return type:: 1D_array[int]

getTime()

Array of timestamps of the sampling points.

Returns:: The timestamps of the sampling points
Return type:: 1D_array[int]

getPeriodsCount()

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

Returns:: Full cycles per channel and sampling point.
Return type:: 2D_array[int]

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.
Return type:: 2D_array[float]

getPhase(reference_frequency: float = 0.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.
Return type:: 2D_array[float]

getFrequency(time_scale: int = 1_000_000_000_000)

The frequency with respect to the phase difference to the last sampling interval. At index 0, there is no previous phase value to compare with, so the method returns an undefined value NaN by definition.

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.
Return type:: 2D_array[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.
Return type:: 2D_array[float]

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.
Return type:: 2D_array[int]

PulsePerSecondMonitor

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).

class PulsePerSecondMonitor(tagger, reference_channel: int, signal_channels: list[int], filename: str = '', period: int = 1E12)

Parameters:

tagger (TimeTaggerBase) – Time Tagger object instance.
reference_channel (int) – the channel number corresponding to the PPS reference source.
signal_channels (list[int]) – a list of channel numbers with PPS signals to be compared to the reference.
filename (str) – the name of the .csv file to store measurement data. By default, no data is written to file.
period (int) – the assumed period of the reference source, typically one second, in picoseconds.

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 (bool) – Controls if the returned data shall be removed from the internal buffer.
Returns:: An object providing access to a snapshot data.
Return type:: PulsePerSecondData

class PulsePerSecondData

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

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.

Returns:: A list of indices for each pulse from the reference source.
Return type:: 1D_array[int]

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.
Return type:: 1D_array[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.
Return type:: 2D_array[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.
Return type:: 1D_array[float]

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.
Return type:: 1D_array[str]

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.
Return type:: 1D_array[bool]

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 `TagType`	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

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

class TimeTagStream(tagger, n_max_events, channels)

Parameters:

tagger (TimeTaggerBase) – time tagger object instance
n_max_events (int) – buffer size for storing time tags
channels (list[int]) – non-empty list of channels to be captured.

See all common methods

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.
Return type:: TimeTagStreamBuffer

class TimeTagStreamBuffer

size: int: 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.

hasOverflows: bool: 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.

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

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

getTimestamps()

Returns an array of timestamps.

Returns:: Event timestamps in picoseconds for all chosen channels.
Return type:: list[int]

getChannels()

Returns an array of channel numbers for every timestamp.

Returns:: Channel number for each detected event.
Return type:: list[int]

getOverflows(): Deprecated since version 2.5.0: please use getEventTypes() instead.

getEventTypes()

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

Returns:: Event type value for each detected event.
Return type:: 1D_array[int]

getMissedEvents()

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

Returns:: Missed events value for each detected event.
Return type:: 1D_array[int]

FileWriter

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 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.

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.

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 blocks
#    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.

class FileWriter(tagger, filename, channels)

Parameters:

tagger (TimeTaggerBase) – time tagger object
filename (str) – name of the file to store to
channels (list[int]) – non-empty list of real or virtual 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().

See all common methods

split([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 (str) – filename of the new file.

setMaxFileSize(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. (default: ~1 GByte)

getMaxFileSize()

Returns:: The maximal file size. See also FileWriter.setMaxFileSize().
Return type:: int

getTotalEvents()

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

getTotalSize()

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

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"])

class FileReader(filenames)

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

Parameters:: filenames (list[str]) – filename(s) of the files to read.

getData(size_t 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 (int) – Number of timetags to read from the file.
Returns:: A buffer of size n_events.
Return type:: TimeTagStreamBuffer

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.
Return type:: bool

getConfiguration()

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

getChannelList()

Returns:: all channels available within the input file
Return type:: list[int]

Dump

Deprecated since version 2.6.0: please use FileWriter instead.

Warning

The files created with this class are not readable by TimeTaggerVirtual and FileReader.

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

Please visit the programming examples provided in the installation folder of how to dump and load data.

class Dump(tagger, filename, max_tags, channels)

Parameters:

tagger (TimeTaggerBase) – time tagger object instance
filename (str) – name of the file to dump to
max_tags (int) – stop after this number of tags has been dumped. Negative values will dump forever
channels (list[int]) – list of real or virtual channels which are dumped to the file (when empty or not passed all active channels are dumped)

clear(): Delete current data in the file and restart data storage.

stop(): Stops data recording and closes data file.

Scope

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.

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.

class Scope(tagger, event_channels=[], trigger_channel, window_size, n_traces, n_max_events)

Parameters:

tagger (TimeTagger) – TimeTagger object
event_channels (list[int]) – List of channels
trigger_channel (int) – Channel number of the trigger signal
window_size (int) – Time window in picoseconds
n_traces (int) – Number of trigger events to be detected
n_max_events (int) – Max number of events to be detected

See all common methods

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.
Return type:: tuple[tuple[Event]]

ready()

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

triggered()

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

class Event

Pair of the timestamp and the new state.

time

Type:: int

state

Type:: State

class State

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

UNKNOWN

HIGH

LOW

Sampler

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.

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

class Sampler(tagger, trigger, channels, max_trigger)

Parameters:

tagger (TimeTagger) – TimeTagger object
trigger (int) – Channel number of the trigger signal
channels (list[int]) – List of channels to be sampled
max_trigger (int) – The number of triggers and their respective sampled data, which is stored within the measurement class.

See all common methods

getData()

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

[
    [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 state means:

low
high
undefined (after overflow)

Returns:: sampled data
Return type:: 2D_array[int]

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
Return type:: 2D_array[int]

Helper classes

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 SynchronizedMeasurements.getTagger() to every measurement you create. This will simultaneously disable their autostart and register for synchronization.

class SynchronizedMeasurements(tagger)

Parameters:: tagger (TimeTaggerBase) – TimeTagger object

registerMeasurement(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.

unregisterMeasurement(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.

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

startFor(duration[, clear=True]): Calls startFor() for every registered measurement in a synchronized way.

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

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

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

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.

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()