The TimeTagger Library

The Time Tagger Library contains classes for hardware access and data processing. This section covers the units and terminology definitions as well as describes constants and functions defined at the library level.

Units of measurement

timestamp_t: Time is measured and specified in picoseconds. Time-tags indicate time since device start-up, which is represented by a 64-bit integer number. Note that this implies that the time variable will roll over once approximately every 107 days. This will most likely not be relevant to you unless you plan to run your software continuously over several months, and you are taking data at the instance when the rollover is happening.

Analog voltage levels are specified in volts.

Channel numbers

channel_t

You can use the Time Tagger to detect both rising and falling edges. Throughout the software API, the rising edges are represented by positive channel numbers starting from 1 and the falling edges are represented by negative channel numbers. Virtual channels will automatically obtain numbers higher than the positive channel numbers.

The Time Taggers delivered before mid 2018 have a different channel numbering. More details can be found in the Channel Number Schema 0 and 1 section.

Unused channels

There might be the need to leave a parameter undefined when calling a class constructor. Depending on the programming language you are using, you pass an undefined channel via the static constant CHANNEL_UNUSED, which can be found in the TT class for .NET and in the TimeTagger class in MATLAB.

Constants

constexpr channel_t CHANNEL_UNUSED: Can be used instead of a channel number when no specific channel is assumed. In MATLAB, use TimeTagger.CHANNEL_UNUSED.

Enumerations

enum class AccessMode

Controls how the Time Tagger server delivers the data-blocks to the connected clients, and if the clients are allowed to change the hardware settings.

Values:

enumerator Listen: Clients cannot change settings on the Time Tagger and only subscribe to the exposed channels. The data-blocks are delivered asynchronously to every client.

enumerator SynchronousListen: The same as AccessMode::Listen but the data is delivered synchronously to every client.

Warning

This mode is not recommended for general use. The server will attempt to deliver a data-block to every connected client before sending the next data-block. Therefore, the data transmission will always be limited by the slowest client. If any of the clients cannot handle the data rate fast enough compared to the data-rate produced by the Time Tagger hardware, all connected clients will be affected and the Time Tagger hardware buffer may overflow. This can happen due to the network speed limit or insufficient CPU speed on any of the connected clients.

enumerator Control: Clients have control over all settings on the Time Tagger. The data-blocks are delivered asynchronously to every client.

enumerator SynchronousControl: The same as AccessMode::Control but the data is delivered synchronously to every client.

Warning

This mode is not recommended for general use. The server will attempt to deliver a data-block to every connected client before sending the next data-block. Therefore, the data transmission will always be limited by the slowest client. If any of the clients cannot handle the data rate fast enough compared to the data-rate produced by the Time Tagger hardware, all connected clients will be affected and the Time Tagger hardware buffer may overflow. This can happen due to the network speed limit or insufficient CPU speed on any of the connected clients.

enum class ChannelEdge : int

Selects the channels that TimeTaggerHardware::getChannelList() returns.

Values:

enumerator All: Rising and falling edges of channels with HighRes and Standard resolution.

enumerator Rising: Rising edges of channels with HighRes and Standard resolution.

enumerator Falling: Falling edges of channels with HighRes and Standard resolution.

enumerator HighResAll: Rising and falling of channels edges with HighRes resolution.

enumerator HighResRising: Rising edges of channels with HighRes resolution.

enumerator HighResFalling: Falling edges of channels with HighRes resolution.

enumerator StandardAll: Rising and falling edges of channels with Standard resolution.

enumerator StandardRising: Rising edges of channels with Standard resolution.

enumerator StandardFalling: Falling edges of channels with Standard resolution.

enum class CoincidenceTimestamp

Defines what timestamp to use for a coincidence event in Coincidence / Coincidences.

Values:

enumerator Last: Use the last time-tag to define the timestamp of the coincidence.

enumerator Average: Calculate the average timestamp of all time-tags in the coincidence and use it as the timestamp of the coincidence.

enumerator First: Use the first time-tag to define the timestamp of the coincidence.

enumerator ListedFirst: Use the timestamp of the channel at the first position of the list when Coincidence or a group of Coincidences is instantiated.

enum class FpgaLinkInterface

Determines which Ethernet Port on the Time Tagger X should be used in TimeTagger::enableFpgaLink().

Values:

enumerator SFPP_10GE: Use the SFP+ Port on the Time Tagger X for FPGA link output.

enumerator QSFPP_40GE: Use the QSFP+ Port on the Time Tagger X for FPGA link output.

enum class GatedChannelInitial

The initial state of a GatedChannel.

Values:

enumerator Closed: The gate is closed initially.

enumerator Open: The gate is open initially.

enum class Resolution

Defines the resolution mode of the Time Tagger on connection using createTimeTagger(). Details on the available inputs are listed in the hardware overview .

Values:

enumerator Standard: Use one time-to-digital conversion per channel. All physical inputs can be used.

enumerator HighResA: Use two time-to-digital conversions per channel. The resolution is increased by a factor of $\simeq\sqrt{2}$ compared to the Standard mode, but only a reduced number of certain inputs can be used. Some inputs may remain in Standard mode depending on your license.

enumerator HighResB: Use four time-to-digital conversions per channel. The resolution is increased by a factor of $\simeq 2$ compared to the Standard mode, but only a reduced number of certain inputs can be used. Some inputs may remain in Standard mode depending on your license.

enumerator HighResC: Use eight time-to-digital conversions per channel. The resolution is increased by a factor of $\simeq\sqrt{8}$ compared to the Standard mode, but only a reduced number of certain inputs can be used. Some inputs may remain in Standard mode depending on your license.

enum class Tag::Type

Specifies the type of a time tag.

Values:

enumerator TimeTag: Indicates a standard event corresponding to a detected signal edge.

enumerator Error: Indicates a hardware or communication-related error condition (e.g., plugging an external clock source, invalidating the global time base).

enumerator OverflowBegin: Marks the beginning of an interval with incomplete data because of too high data rates.

enumerator OverflowEnd: Marks the point where the internal overflow condition ended, resuming normal event tagging.

enumerator MissedEvents: A virtual event indicating the number of lost events per channel within an overflow interval. This event might be sent repeatedly if the number of lost events is large.

enum class UsageStatisticsStatus

Values:

enumerator Disabled: Usage statistics collection and upload is disabled.

enumerator Collecting: Enable usage statistics collection local but without automatic uploading. This option might be useful to collect usage statistics for debugging purpose.

enumerator CollectingAndUploading: Enable usage statistics collection and automatic upload

Functions

TimeTagger createTimeTagger(str serial = "", Resolution resolution = Resolution::Standard)

Establishes the connection to a first available Time Tagger device and creates a TimeTagger object. Optionally, the connection to a specific device can be achieved by specifying the device serial number.

If the HighRes mode is available, it can be selected from Resolution. Details on the available inputs are listed in the hardware overview .

In MATLAB, this function is accessed as TimeTagger.createTimeTagger.

Parameters:

serial – Serial number string of the device or empty string.
resolution – Select the resolution of the Time Tagger. The default is Resolution::Standard.

Throws:

RuntimeError – if no Time Tagger devices are available or if the serial number is not correct.

Returns:

A Time Tagger object

TimeTaggerVirtual createTimeTaggerVirtual(str filename = "", timestamp_t begin = 0, timestamp_t duration = -1)

Creates a TimeTaggerVirtual object. Virtual Time Tagger uses files generated by the FileWriter as data source instead of the Time Tagger hardware. This allows you to use all Time Tagger library measurements for offline processing of the dumped time tag stream. For example, you can repeat the analysis of your experiment with different parameters, like different binwidths etc.

The file parameter can specify a header file or single specific file as shown in the following example.

# Assume we have following the files in the current directory:
#   filename.ttbin
#   filename.1.ttbin
#   filename.2.ttbin

# Replay all files named "filename.NN.ttbin" sequentially
replay_source.appendFile('filename.ttbin')

# Replay a single file "filename.1.ttbin"
replay_source.appendFile('filename.1.ttbin')

In MATLAB, this function is accessed as TimeTagger.createTimeTaggerVirtual.

Parameters:

filename – File name of the initial file. This file defines the available external channels. Default is an empty string which creates a simulated Time Tagger with 18 channels.
begin – Time offset from the beginning of the file in ps to start the replay at. Default is 0.
duration – Duration in picoseconds to be read from the file. duration=-1 will replay everything. Default is -1.

Returns:

Time Tagger Virtual object

TimeTaggerNetwork createTimeTaggerNetwork(str[] addresses)

Creates a new TimeTaggerNetwork object. During creation, the object tries to open a connection to the specified Time Tagger servers that have been created by TimeTagger::startServer(). This makes the remote time-tag stream locally available.

When more than one server is specified, the channel number of the n-th server is offset by n * 1000, e.g., channel 3 of the second server will become 2003. Moreover, the different servers must be synchronized to an external clock. If the connection fails, the method will throw an exception.

In MATLAB, this function is accessed as TimeTagger.createTimeTaggerNetwork.

Parameters:

addresses – IP addresses, or hostnames, of the servers. Use hostname:port for each server.

Throws:

RuntimeError – if the connection to the server cannot be made.
RuntimeError – if the address string has an invalid format.
RuntimeError – if attempting to connect to multiple non-synchronized servers.

Returns:

Time Tagger Network object

str getTimeTaggerServerInfo(str address = "localhost:41101")

Returns Time Tagger configuration, exposed channels, hardware channels and virtual channels as a JSON formatted string.

Parameters:

address – IP address, hostname or domain-name of the server, where the Time Tagger server is running. The port number is optional and can be specified if server listens on a port other than default 41101.

Throws:

RuntimeError – if the connection to the server cannot be made.
ValueError – if the address string has an invalid format.

Returns:

Information about server, available channels and exposed channels.

void freeTimeTagger(TimeTaggerBase tagger)

Releases all Time Tagger resources and terminates the active connection.

Parameters:: tagger – Time Tagger Base object to disconnect

str[] scanTimeTagger()

Returns a list of the serial numbers of the connected but not instantiated Time Taggers. It may return serials blocked by other processes or already disconnected some milliseconds later.

In MATLAB this function is accessible as TimeTagger.scanTimeTagger().

Returns:: List of serial numbers

str[] scanTimeTaggerServers()

Scans the network for available Time Tagger servers.

Note

The server discovery algorithm uses multicast UDP messages sent to the address 239.255.255.83:41102. This method is expected to work well in most situations, however there is a possibility when it could fail. The servers may not be discoverable if the system firewall rejects multicast traffic or blocks access to UDP port 41102. Additionally, multicast traffic is typically not forwarded to other IP networks by routers.

Returns:: A list of addresses of the Time Tagger servers that are available in the network.

logger_callback setLogger(logger_callback callback)

Registers a callback function, e.g. for customized error handling. Please see the examples in the installation folder on how to use it. Callback function shall have the following signature callback(level, message). By default, the log messages are printed into the console.

Python example:

def logger_func(level, message):
    print(level, message)
setLogger(logger_func)

Matlab example:

function logger_func(level, message)
    fprintf('%d : %s\n', level, message)
end
TimeTagger.setLogger(@logger_func)

void setTimeTaggerChannelNumberScheme(int scheme)

Deprecated:: Since version 2.17 all values of scheme except for 1 are deprecated

Selects whether the first physical channel starts with 0 or 1.

This method is deprecated and will be removed soon. The only purpose of this method is to call setTimeTaggerChannelNumberScheme(TT_CHANNEL_NUMBER_SCHEME_ONE) with TT_CHANNEL_NUMBER_SCHEME_ONE = 2) before createTimeTagger for old devices (channel numbers starting with 0) which will suppress a deprecation warning.

Attention: The method must be called before the first call to createTimeTagger.

int getTimeTaggerChannelNumberScheme()

Deprecated:: Since version 2.17 all values of scheme except for 1 are deprecated

Returns the currently used channel scheme.

Returns:: Channel scheme

void mergeStreamFiles(str output_filename, str[] input_filenames, int[] channel_offsets, timestamp_t[] time_offsets, bool overlap_only)

This function merges a list of time tag stream files into one file. The merged stream file can be loaded into the TimeTaggerVirtual for processing. The file merging combines streams into one with the possibility of specifying a constant time offset for each input stream file. Additionally, it is possible to specify channel number offset if the input stream files were recorded from the same channel numbers, for instance, using two Time Tagger devices The parameters input_filenames, channel_offsets, and time_offsets shall be of equal length.

This function handles the *.ttbin files the same way as the TimeTaggerVirtual::replay().

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

Note

When merging multiple stream files recorded at different times or from different devices, you have to be aware of possible time base differences. This function does not rescale the data into a common time base as this would require additional information and external synchronization signal. If you want to improve the synchronicity of the time base between two devices, please send the reference clock signal to any of the available inputs of each Time Tagger and set up the software clock TimeTaggerBase::setSoftwareClock().

Parameters:

output_filename – Filename where to store the merge result *.ttbin.
input_filenames – List of dump files that will be merged.
channel_offsets – Channel number offset for each *.ttbin file. Useful when input files have the same channel numbers.
time_offsets – Time offset for each *.ttbin file in picoseconds.
overlap_only – If True, then merge only the regions where the time is overlapping.

str getVersion()

Get the version of the Time Tagger software installed.

Returns:: Version of the Time Tagger software.

Usage statistics data collection

See also the section Usage Statistics Collection.

void setUsageStatisticsStatus(UsageStatisticsStatus new_status)

This function allows a user to override the system-wide default setting on collection and submission of the usage statistics data. This function operates within the scope of a current OS user. The system-wide default setting is given during the installation of the Time Tagger software. Please run the installer again to allow collection and uploading or to disable the usage statistics.

Parameters:: new_status – New status of the usage statistics data collection.

UsageStatisticsStatus getUsageStatisticsStatus()

Get the current status of the usage statistics for the current user. The status is described by the UsageStatisticsStatus.

Returns:: Current status of the usage statistics for the current user.

str getUsageStatisticsReport()

This function returns the current state of the usage statistics report as a JSON formatted string. If there is no report data available or it was submitted just now, the output is a message: Info: No report data available yet. If you had given your consent earlier and then revoked it, this function will still return earlier accumulated report data.

Returns:: Usage statistics data encoded as JSON string.

Helper classes

class ChannelGate

Public Functions

ChannelGate(channel_t gate_open_channel, channel_t gate_close_channel, GatedChannelInitial initial = GatedChannelInitial::Open)

This object defines an evaluation gate that is passed to a measurement class. The time-tag stream itself is not modified but sections of the stream can be excluded from the evaluation. In contrast to time-tag stream based gating (see GatedChannel), this concept allows the measurement class to calculate the correct data normalization.

Parameters:

gate_open_channel – Number of the channel that opens the evaluation gate.
gate_close_channel – Number of the channel that closes the evaluation gate.
initial – Initial state of the evaluation gate.