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 andisRunning()
will return False. Whether the accumulated data is cleared at the beginning ofstartFor()
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()
orstartFor()
to continue or restart the measurement.
-
void abort()
Immediately aborts the measurement, discarding accumulated measurement data, and resets the state to the initial state.
-
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 callingstartFor()
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.
-
void clear()
Event counting
Countrate
-
class Countrate : public IteratorBase
Measures the average count rate on one or more channels. Specifically, it determines the counts per second on the specified channels starting from the very first tag arriving after the instantiation or last call to
clear()
of the measurement. TheCountrate
works correctly even when the USB transfer rate or backend processing capabilities are exceeded.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.
-
Countrate(TimeTaggerBase tagger, channel_t[] channels)
Counter
-
class Counter : public IteratorBase
Time trace of the count rate on one or more channels. Specifically, this measurement repeatedly counts tags within a time interval binwidth and stores the results in a two-dimensional array of size number of channels by n_values. The incoming data is first accumulated in a not-accessible bin. When the integration time of this bin has passed, the accumulated data is added to the internal buffer, which can be accessed via the getData… methods. Data stored in the internal circular buffer is overwritten when n_values are exceeded. You can prevent this by automatically stopping the measurement in time as follows
counter.startFor(duration=binwidth*n_values)
.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 theCounter
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.
-
Counter(TimeTaggerBase tagger, channel_t[] channels, timestamp_t binwidth = 1000000000, int n_values = 1)
-
class CounterData
Objects of this class are created and returned by
Counter::getDataObject()
, and contain a snapshot of the data accumulated by theCounter
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 toCounter::getDataObject
, these arrays can be concatenated to obtain a full index array.
-
timestamp_t[] getIndex()
CountBetweenMarkers
-
class CountBetweenMarkers : public IteratorBase
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.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.
-
CountBetweenMarkers(TimeTaggerBase tagger, channel_t click_channel, channel_t begin_channel, channel_t end_channel = CHANNEL_UNUSED, int n_values = 1000)
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
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.
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.
-
StartStop(TimeTaggerBase tagger, channel_t click_channel, channel_t start_channel = CHANNEL_UNUSED, timestamp_t binwidth = 1000)
Histogram
-
class Histogram : public IteratorBase
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.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.
-
Histogram(TimeTaggerBase tagger, channel_t click_channel, channel_t start_channel = CHANNEL_UNUSED, timestamp_t binwidth = 1000, int n_bins = 1000)
HistogramLogBins
-
class HistogramLogBins : public IteratorBase
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 typeChannelGate
. 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
is normalized by
and the click and start channel count rates,
and
, respectively. Typically, this will be used to calculate
and without interruptions,
will approach the binwidth of the respective bin. During the early acquisition and in case of interruptions,
can be significantly smaller, which compensates for counts that are excluded from
.
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()
andHistogramLogBinsData::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()
andHistogramLogBinsData::getG2()
instead.
- Returns:
The counts normalized by the binwidth of each bin and the average count rate.
-
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)
-
class HistogramLogBinsData
Contains the histogram counts
and the corresponding normalization function
.
Public Functions
-
float[] getG2()
- Returns:
A one-dimensional array of size n_bins containing the normalized histogram
.
-
int[] getCounts()
- Returns:
A one-dimensional array of size n_bins containing the raw histogram
.
-
float[] getG2Normalization()
- Returns:
A one-dimensional array of size n_bins containing the normalization
.
-
float[] getG2()
Histogram2D
-
class Histogram2D : public IteratorBase
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.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.
-
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)
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 1DHistogram
with single-start single-stop behavior.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]
andn_bins=[2, 2]
, the 1D array would represent 2D bin indices in the order[(0,0), (0,1), (1,0), (1,1)]
, with (index ofch1
, index ofch2
). 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.
-
HistogramND(TimeTaggerBase tagger, channel_t start_channel, channel_t[] stop_channels, timestamp_t[] binwidths, int[] n_bins)
Correlation
-
class Correlation : public IteratorBase
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.
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:
is the capture duration,
and
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.
-
Correlation(TimeTaggerBase tagger, channel_t channel_1, channel_t channel_2 = CHANNEL_UNUSED, timestamp_t binwidth = 1000, int n_bins = 1000)
TimeDifferences
-
class TimeDifferences : public IteratorBase
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.
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.
-
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)
TimeDifferencesND
-
class TimeDifferencesND : public IteratorBase
This is an implementation of the
TimeDifferences
measurement class that extends histogram indexing into multiple dimensions. Please read the documentation ofTimeDifferences
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 specifies 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.
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.
-
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)
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.
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.
-
bool isAcquiring()
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 overridingFlimBase
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 aFlimFrameInfo
object containing frame data with additional information collected at the same time instance.Warning
When overriding this class, you must set
pre_initialize=False
and then callinitialize()
at the end of your custom constructor code. Otherwise, you may experience unstable or erratic behavior of your program, as the callbackframeReady()
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.
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 binj
at indexi * 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.
-
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)
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.
-
int getFrameNumber()
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 subclassingFlim
instead.Warning
When overriding this class, you must set
pre_initialize=False
and then callinitialize()
at the end of your custom constructor code. Otherwise, you may experience unstable or erratic behavior of your program, as the callbackframeReady()
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.
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 binj
at indexi * 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.
-
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)
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
of a specific set of error samples
with a normalization factor
. The step size
together with the oscillator period
defines the time span
that is investigated by the sample. The error samples
are calculated from the phase samples
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
. For example, the Allan Deviation investigates the second derivative of the phase
using the sample
. The full formula of the Allan deviation for a set of
averaged timestamps is
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
. 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
for |ADEV|/|MDEV| and
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
. 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 =
ADEV
Modified Allan Deviation (ADEV)
Time Deviation TDEV =
MDEV
Hadamard Deviation (HDEV )
HDEVScaled =
HDEV
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
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.
-
FrequencyStability(TimeTaggerBase tagger, channel_t channel, int[] steps, timestamp_t average = 1000, int trace_len = 1000)
-
class FrequencyStabilityData
Public Functions
-
float[] getTau()
The
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
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:
.
- 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:
.
- 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:
.
- 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:
.
- Domain:
Time domain.
- Returns:
The standard deviation.
-
float[] getADEVScaled()
-
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.
-
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.
-
float[] getTraceIndex()
The time axis for
getTracePhase()
andgetTraceFrequency()
.- 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.
-
float[] getTau()
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.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 theFrequencyCounter
at the time this method is called. The event_divider argument can be used to scale the results according to the current setting ofTimeTagger::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.
-
FrequencyCounter(TimeTaggerBase tagger, channel_t[] channels, timestamp_t sampling_interval, timestamp_t fitting_window, int n_values = 0)
-
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()
andgetPeriodsFraction()
as the required precision can overflow a 64bit double precision within minutes. In doubt, please usegetPhase()
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).
-
timestamp_t[] getIndex()
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).
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 thePulsePerSecondMonitor
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.
-
PulsePerSecondMonitor(TimeTaggerBase tagger, channel_t reference_channel, channel_t[] signal_channels, str filename = "", timestamp_t period = 1E12)
-
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.
-
int[] getIndices()
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 |
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 |
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 viaTimeTagger::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 withFileWriter
measurement can be read usingFileReader
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 theTimeTaggerBase::getConfiguration()
method. The configuration is always written into every file.See also: FileReader , The TimeTaggerVirtual class , and mergeStreamFiles.
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 orFileReader
.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 aSynchronizedMeasurements
.Note
Compared to the
Dump
measurement, theFileWriter
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 withTimeTagger::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.
-
FileWriter(TimeTaggerBase tagger, str filename, channel_t[] channels)
FileReader
-
class FileReader
This class allows you to read data files store with
FileReader
. TheFileReader
reads a data block of the specified size into aTimeTagStreamBuffer
object and returns this object. The returned data object is exactly the same as returned by theTimeTagStream
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 theFileWriter
.- 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.
-
str getLastMarker()
- Returns:
The last processed marker from the file (see also
FileWriter::setMarker()
).
-
FileReader(str[] filenames)
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 .
Warning
The files created with this class are not readable by
TimeTaggerVirtual
andFileReader
. For storing time tag data intended for re-reading or postprocessing, use theFileWriter
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).
-
Dump(TimeTaggerBase tagger, str filename, int max_tags, channel_t[] channels = channel_t[]())
Scope
-
class Scope : public IteratorBase
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. Ifn_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.
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.
-
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)
-
struct Event
Pair of the timestamp and the new state returned by
Scope::getData
.
Sampler
-
class Sampler : public IteratorBase
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.
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:
0 -- low 1 -- high 2 -- 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.
-
Sampler(TimeTaggerBase tagger, channel_t trigger, channel_t[] channels, int max_triggers)
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 bygetTagger()
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 theTimeTagger
object created bycreateTimeTagger()
. You can create synchronized measurements with the proxy object the following way:Passing tagger as a constructor parameter would lead to the not synchronized behavior.tagger = TimeTagger.createTimeTagger() syncMeas = TimeTagger.SynchronizedMeasurements(tagger) taggerSync = syncMeas.getTagger() counter = TimeTagger.Counter(taggerSync, [1, 2]) countrate = TimeTagger.Countrate(taggerSync, [3, 4])
-
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.
-
SynchronizedMeasurements(TimeTaggerBase tagger)
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.- 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 usenumpy.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 theprocess()
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()