The TimeTagger class

This class provides access to the hardware and exposes methods to control hardware settings. It allows controlling the trigger levels, input delay, dead time, event filter, and test signals. Behind the scenes, it opens the USB connection, initializes the device and receives and manages the time-tag-stream. Every measurement and virtual channel requires a reference to the TimeTagger object with which it will be associated.

class TimeTagger
reset()

Reset the Time Tagger to the start-up state.

setTriggerLevel(channel, voltage)

Set the trigger level of an input channel in Volts.

Parameters
  • channel (int) – Physical channel number

  • voltage (float) – Trigger level in Volts

getTriggerLevel(channel)

Returns trigger level for the specified physical channel number.

Parameters

channel (int) – Physical channel number

Returns

The applied trigger voltage level, which might differ from the input parameter due to the DAC discretization.

Return type

float

setDelayHardware(channel, delay)

Caution

Time Tagger Ultra only.

Set an artificial delay per channel. The delay can be positive or negative. This delay is applied onboard the Time Tagger directly after the time-to-digital conversion, so it affects also the Conditional Filter.

Parameters
  • channel (int) – Channel number

  • delay (int) – Delay time in picoseconds, the maximum/minimum value allowed is ±2000000 (±2 µs)

getDelayHardware(channel)

Caution

Time Tagger Ultra only.

Returns the value of the delay applied onboard the Time Tagger in picoseconds for the specified channel.

Parameters

channel (int) – Channel number

Returns

Delay time in picoseconds

Return type

int

setDelaySoftware(channel, delay)

Set an artificial delay per channel. The delay can be positive or negative. This delay is applied on the computer, so it does not affect onboard processes such as the Conditional Filter.

Parameters
  • channel (int) – Channel number

  • delay (int) – Delay time in picoseconds

getDelaySoftware(channel)

Returns the value of the delay applied on the computer in picoseconds for the specified channel.

Parameters

channel (int) – Channel number

Returns

Delay time in picoseconds

Return type

int

setInputDelay(channel, delay)

This is a convenience method. It calls TimeTagger.setDelaySoftware() if you use a Time Tagger 20 or the delay is > 2 µs, otherwise TimeTagger.setDelayHardware() is called.

Parameters
  • channel (int) – Channel number

  • delay (int) – Delay time in picoseconds

getInputDelay(channel)

This is a convenience method. It will return the sum of TimeTagger.getDelaySoftware() and TimeTagger.getDelayHardware().

Parameters

channel (int) – Channel number

Returns

Delay time in picoseconds

Return type

int

getHardwareDelayCompensation(channel)

Get the hardware input delay compensation for the given channel in picoseconds.

This compensation can be understood as an implicit part of TimeTagger.setDelayHardware() and TimeTagger.setDelaySoftware(). If your device is able to set an arbitrary delay onboard, this applies to the hardware delay compensation as well.

Parameters

channel (int) – Channel number

Returns

Hardware delay compensation in picoseconds

Return type

int

setConditionalFilter(trigger, filtered, hardwareDelayCompensation=True)

Activates or deactivates the event filter. Time tags on the filtered channels are discarded unless they were preceded by a time tag on one of the trigger channels, which reduces the data rate. More details can be found in the In Depth Guide: Conditional Filter.

Parameters
  • trigger (list[int]) – List of channel numbers

  • filtered (list[int]) – List of channel numbers

  • hardwareDelayCompensation (bool) – optional, default: True. If set to False, the physical hardware delay will not be compensated. This is only relevant for devices without TimeTagger.setDelayHardware(), do not set this value to False if your device is capable of onboard delay compensation. Without onboard delay compensation, setting the value to False guarantees that the trigger tag of the conditional filter is always in before the triggered tag when the InputDelays are set to 0.

clearConditionalFilter()

Deactivates the event filter. Equivalent to setConditionalFilter([], [], True). Enables the physical hardware delay compensation again if it was deactivated by setConditionalFilter().

getConditionalFilterTrigger()

Returns the collection of trigger channels for the conditional filter.

Returns

List of channel numbers

Return type

list[int]

getConditionalFilterFiltered()

Returns the collection of channels to which the conditional filter is currently applied.

Returns

List of channel numbers

Return type

list[int]

setEventDivider(channel, divider)
../_images/EventDivider.svg

Applies an event divider filter with the specified factor to a channel, which reduces the data rate. Only every n-th event from the input stream passes through the filter, as shown in the image. Note that if the conditional filter is also active, the conditional filter is applied first.

Parameters
  • channel (int) – Physical channel number

  • divider (int) – Divider factor.

getEventDivider(channel)

Gets the event divider filter factor for the given channel.

Parameters

channel (int) – Channel number

Returns

Divider factor value

Return type

int

setNormalization(state)

Enables or disables Gaussian normalization of the detection jitter. Enabled by default.

Parameters

state (bool) – True/False

getNormalization()

Returns true if Gaussian normalization is enabled.

Returns

True/False

Return type

bool

setDeadtime(channel, deadtime)

Sets the dead time of a channel in picoseconds. The requested time will be rounded to the nearest multiple of the clock time, which is 6 ns for the Time Tagger 20 and 2 ns for the Time Tagger Ultra. The minimum dead time is one clock cycle. As the deadtime passed as an input will be altered to the rounded value, the rounded value will be returned. The maximum dead time is 393 µs for the Time Tagger 20 and 131 µs for the Time Tagger Ultra.

Note

The specified deadtime of the Time Tagger Ultra is 2.1 ns. With the default hardware deadtime filter of 2 ns, an event arriving between 2 ns and 2.1 ns after the last event might be dropped.

Parameters
  • channel (int) – Channel number.

  • deadtime (int) – Deadtime value in picoseconds.

Returns

Deadtime in picoseconds rounded to the nearest valid value ( multiple of the clock period not exceeding maximum dead time).

Return type

int

getDeadtime(channel)

Returns the dead time value for the specified channel.

Parameters

channel (int) – Physical channel number

Returns

Deadtime value in picoseconds

Return type

int

setTestSignal(channels, bool state)

Connect or disconnect the channels with the on-chip uncorrelated signal generator.

Parameters
  • channels (list[int]) – List of physical channel numbers

  • state (bool) – True/False

getTestSignal(channel)

Returns true if the internal test signal is activated on the specified channel.

Parameters

channel (int) – Physical channel number

Returns

True/False

Return type

bool

getSerial()

Returns the hardware serial number.

Returns

Serial number string

Return type

str

getModel()
Returns

Model name as string

Return type

str

getOverflows()

Returns the number of overflows (missing blocks of time tags due to limited USB data rate) that occurred since start-up or last call to clearOverflows().

Returns

Number of overflows

Return type

int

getOverflowsAndClear()

Returns the number of overflows that occurred since start-up and sets them to zero (see, clearOverflows()).

Returns

Number of overflows

Return type

int

clearOverflows()

Set the overflow counter to zero.

getFence(alloc_fence=True)

Generate a new fence object, which validates the current configuration and the current time. This fence is uploaded to the earliest pipeline stage of the Time Tagger. Waiting on this fence ensures that all hardware settings such as trigger levels, channel registrations, etc., have propagated to the FPGA and are physically active. Synchronizes the Time Tagger internal memory, so that all tags arriving after the waitForFence call were actually produced after the getFence call. The waitForFence function waits until all tags, which are present at the time of the function call within the internal memory of the Time Tagger, are processed. This call might block to limit the number of active fences.

Parameters

alloc_fence (bool) – optional, default: True. If False, a reference to the most recently created fence will be returned instead

Returns

The allocated fence

Return type

int

waitForFence(fence, timeout=- 1)

Wait for a fence in the data stream. See getFence() for more details.

Parameters
  • fence (int) – fence object, which shall be waited on

  • timeout (int) – optional, default: -1. timeout in milliseconds. Negative means no timeout, zero returns immediately.

Returns

True if the fence has passed, false on timeout

Return type

bool

sync(timeout)

Ensure that all hardware settings such as trigger levels, channel registrations, etc., have propagated to the FPGA and are physically active. Synchronizes the Time Tagger internal memory, so that all tags arriving after a sync call were actually produced after the sync call. The sync function waits until all tags, which are present at the time of the function call within the internal memory of the Time Tagger, are processed. It is equivalent to waitForFence(getFence()).

Parameters

timeout (int) – optional, default: -1. timeout in milliseconds. Negative means no timeout, zero returns immediately.

Returns

True if the synchronization was successful, false on timeout

Return type

bool

getPcbVersion()

Returns Time Tagger PCB version.

Returns

PCB version

Return type

str

getDACRange()

Return a vector containing the minimum and the maximum DAC voltage range for the trigger level.

Returns

Min and max voltage in Volt

Return type

(float, float)

registerChannel(channel)

Enable transmission of time tags on the specified channel.

Parameters

channel (int) – Channel number

unregisterChannel(channel)

Disable transmission of time tags on the specified channel.

Parameters

channel (int) – Channel number

getChannelList(type)

Returns a list of channels corresponding to the given type.

Parameters

type (ChannelEdge) – Defines what channels to be returned

Returns

List of channel numbers

Return type

list[int]

getInvertedChannel(channel)

Returns the channel number for the inverted edge of the channel passed in via the channel parameter. In case the given channel has no inverted channel, CHANNEL_UNUSED is returned.

Parameters

channel (int) – Channel number

Returns

Channel number

Return type

int

isChannelUnused(channel)

Returns true if the passed channel number is CHANNEL_UNUSED.

Parameters

channel (int) – Channel number

Returns

True/False

Return type

bool

setHardwareBufferSize(size)

Caution

Time Tagger Ultra only.

Sets the maximum buffer size within the Time Tagger Ultra. The default value is 64 MTags, but can be changed within the range of 32 kTags to 512 MTags. Please note that this buffer can only be filled with a total data rate of up to 500 MTags/s.

Parameters

size (int) – Buffer size, must be a positive number

autoCalibration()

Run an auto-calibration of the Time Tagger hardware using the built-in test signal.

Returns

the list of jitter of each input channel in ps based on the calibration data.

Return type

list[float]

getDistributionCount()

Returns the calibration data represented in counts.

Returns

Distribution data

Return type

2D_array[int]

getDistributionPSec()

Returns the calibration data in picoseconds.

Returns

Calibration data

Return type

2D_array[int]

getPsPerClock()

Returns the duration of a clock cycle in picoseconds. This is the inverse of the internal clock frequency.

Returns

Clock period in picoseconds

Return type

int

setStreamBlockSize(max_events=131072, max_latency=20)

This option controls the latency and the block size of the data stream. Depending on which of the two parameters is exceeded first, the block stream size is adjusted accordingly. The block size will be reduced automatically for blocks when no signal arrives for 512 ns on the Time Tagger Ultra and 1536 ns for the Time Tagger 20.

Parameters
  • max_events (int) – maximum number of events within one block (256 - 32M), default: 131072 events

  • max_latency (int) – maximum latency in milliseconds for constant input rates (1 to 10000), default: 20 ms.

setTestSignalDivider(divider)

Change the frequency of the on-chip test signal.

For the Time Tagger Ultra, the base frequency is 50 MHz and the default divider 63 corresponds to ~800 kCounts/s.

For the Time Tagger 20, the base frequency is 62.5 MHz and the default divider is 74 corresponds to ~850 kCounts/s.

Parameters

divider (int) – Division factor

getTestSignalDivider()

Returns the value of test signal division factor.

getSensorData()

Prints all available sensor data for the given board. The Time Tagger 20 has no onboard sensors.

Returns

Tabulated sensor data

Return type

str

setLED(bitmask)

Manually change the state of the Time Tagger LEDs. The power LED of the Time Tagger 20 cannot be programmed by software.

Example:

# Turn off all LEDs
tagger.setLED(0x01FF0000)

# Restore normal LEDs operation
tagger.setLED(0)
0 -> LED off
1 -> LED on
illumination bits
0-2: status, rgb - all Time Tagger models
3-5: power, rgb - Time Tagger Ultra only
6-8: clock, rgb - Time Tagger Ultra only
0 -> normal LED behavior, not overwritten by setLED
1 -> LED state is overwritten by the corresponding bit of 0-8
mask bits
16-18: status, rgb - all Time Tagger models
19-21: power, rgb - Time Tagger Ultra only
22-24: clock, rgb - Time Tagger Ultra only
Parameters

bitmask (int) – LED bitmask.

setSoundFrequency(freq_hz)

Set the Time Tagger’s internal buzzer to a frequency in Hz.

Parameters

freq_hz (int) – The sound frequency in Hz, use 0 to switch the buzzer off.

getConfiguration()

Returns a JSON formatted string containing a complete information on the Time Tagger settings.