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

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

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

CHANNEL_UNUSED

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

Enums

class Resolution

This Enum is used to determine the resolution mode in createTimeTagger(). Details on the available inputs are listed in the hardware overview.

Standard

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

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.

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.

HighResC

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

class ChannelEdge

This Enum is used to select the channels that TimeTagger.getChannelList() returns.

All

Rising and falling edges of channels with HighRes and Standard resolution.

Rising

Rising edges of channels with HighRes and Standard resolution.

Falling

Falling edges of channels with HighRes and Standard resolution.

HighResAll

Rising and falling of channels edges with HighRes resolution.

HighResRising

Rising edges of channels with HighRes resolution.

HighResFalling

Falling edges of channels with HighRes resolution.

StandardAll

Rising and falling edges of channels with Standard resolution.

StandardRising

Rising edges of channels with Standard resolution.

StandardFalling

Falling edges of channels with Standard resolution.

class CoincidenceTimestamp

This Enum is used to select the timestamp that is attributed to a coincidence event in Coincidence/Coincidences.

Last

Use the last time-tag to define the timestamp of the coincidence.

Average

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

First

Use the first time-tag to define the timestamp of the coincidence.

ListedFirst

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

Functions

createTimeTagger(serial='', 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 the TimeTagger object is created by instantiating the class directly as tagger = TimeTagger([serial, resolution]).

Parameters
  • serial (str) – Serial number string of the device or empty string

  • resolution (Resolution) – Select the resolution of the Time Tagger. The default is Resolution.Standard.

Returns

TimeTagger object

Return type

TimeTagger

createTimeTaggerVirtual()

Creates a virtual Time Tagger object. Virtual Time Tagger uses time-tag dump file(s) as a data source instead of 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 bin-widths,

In MATLAB the TimeTaggerVirtual object is created by instantiating the class directly as tagger = TimeTaggerVirtual().

Returns

TimeTaggerVirtual object

Return type

TimeTagger

freeTimeTagger(tagger)

Releases all Time Tagger resources and terminates the active connection.

Parameters

tagger (TimeTagger) – TimeTagger object to disconnect

scanTimeTagger()

Returns a list of the serial numbers of the connected but not instantiated Time Taggers.

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

Returns

List of serial numbers

Return type

list[str]

setLogger(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)
setTimeTaggerChannelNumberScheme(int scheme)

Selects whether the first physical channel starts with 0 or 1

TT_CHANNEL_NUMBER_SCHEME_AUTO - the scheme is detected automatically, according to the channel labels on the device (default).

TT_CHANNEL_NUMBER_SCHEME_ONE - force the first channel to be 1.

TT_CHANNEL_NUMBER_SCHEME_ZERO - force the first channel to be 0.

Important

The method must be called before the first call to createTimeTagger().

getTimeTaggerChannelNumberScheme()

Returns the currently used channel schema, which is either TT_CHANNEL_NUMBER_SCHEME_ZERO or TT_CHANNEL_NUMBER_SCHEME_ONE.

Returns

Channel schema

Return type

int

Usage statistics data collection

See also the section Usage Statistics Collection.

setUsageStatisticsStatus(status)
Parameters

status (UsageStatisticsStatus) – New status of the usage statistics data collection.

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.

getUsageStatisticsStatus()
Returns

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

Return type

UsageStatisticsStatus

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.

Return type

str

class UsageStatisticsStatus(enum)
Disabled = 0

Usage statistics collection and upload is disabled.

Collecting = 1

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

CollectingAndUploading = 2

Enable usage statistics collection and automatic upload