TimeTagger classes

The Time Tagger classes represent the different time-tag sources for your measurements and analysis. These objects are created by factory functions in the Time Tagger library:

Time Tagger

The TimeTagger represents a hardware device and allows access to hardware settings. To connect to a hardware Time Tagger and to get a TimeTagger object, use createTimeTagger().

Virtual Time Tagger

The TimeTaggerVirtual allows replaying files created with the FileWriter. To create a TimeTaggerVirtual object, use createTimeTaggerVirtual().

Network Time Tagger

The TimeTaggerNetwork allows the (remote) access to a Time Tagger made available via startServer(). The TimeTaggerNetwork object is created with createTimeTaggerNetwork() which also establishes a client connection to the server.

All these objects share a common interface defined by the TimeTaggerBase and TimeTaggerSource classes. In addition, hardware-specific methods, for use with TimeTagger and TimeTaggerNetwork objects, are defined in the TimeTaggerHardware class.

General Time Tagger features

class TimeTaggerSource

This class defines methods used to configure a source of time tags, being either a TimeTaggerBase object, or a TimeTagger-like object such as a TimeTaggerServer. All Time Tagger classes implement these methods by subclassing TimeTaggerBase which itself subclasses TimeTaggerSource.

Subclassed by TimeTaggerBase, TimeTaggerServer

Public Functions

void setInputDelay(channel_t channel, timestamp_t delay)

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

Parameters:

  • channel – Channel number.

  • delay – Delay time in picoseconds.

timestamp_t getInputDelay(channel_t channel)

Convenience method that returns the sum of getDelaySoftware() and getDelayHardware().

Parameters:

channel – Channel number.

Returns:

Delay time in picoseconds.

void setDelayHardware(channel_t channel, timestamp_t delay)

Sets 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 also affects the Conditional Filter . If you exceed the maximum hardware delay range, please use setDelaySoftware() instead.

Note

Method is not available for the Time Tagger 20.

Parameters:

  • channel – Channel number.

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

timestamp_t getDelayHardware(channel_t channel)

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

Note

Method is not available for the Time Tagger 20.

Parameters:

channel – Channel number.

Returns:

Delay time in picoseconds.

timestamp_t[] getDelayHardwareRange(channel_t channel)

Returns a vector containing the minimum and the maximum allowable values for the hardware input delay for the specified channel.

Parameters:

channel – Channel number.

Returns:

Minimum and maximum hardware input delay in picoseconds.

void setDelaySoftware(channel_t channel, timestamp_t delay)

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

Note

This method has the best performance when less than 100 events arrive within the time of the largest delay set. For example, if the rate over all channels used is 10 MTags/s, the signal can be delayed efficiently up to 10 µs. For larger delays, please consider using DelayedChannel instead.

Parameters:

  • channel – Channel number.

  • delay – Delay time in picoseconds.

timestamp_t getDelaySoftware(channel_t channel)

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

Parameters:

channel – Channel number.

Returns:

Delay time in picoseconds.

timestamp_t setDeadtime(channel_t channel, timestamp_t deadtime)

Sets the dead time of a channel in picoseconds. The minimum dead time is defined by the internal clock period, which is 6 ns for the Time Tagger 20, 2 ns for the Time Tagger Ultra, and 1.333 ns for the Time Tagger X. For the Time Tagger 20, the requested dead time will be rounded to the nearest multiple of the 6 ns clock cycle. The other models allow for arbitrary dead times greater than the respective minimum dead time.

As the dead time passed as an input might be altered to the rounded value, the rounded value will be returned. The maximum dead time is 393 µs for the Time Tagger 20, 2147 µs for the Time Tagger Ultra, and 716 µs for the Time Tagger X. Larger dead times will result in an exception.

Note

The specified dead time is 2.1 ns for Time Tagger Ultra and 1.5 ns for Time Tagger X. With the default setting of the hardware dead time filter, an event arriving between the default hardware dead time and the specified dead time after the last event of that channel might be dropped (e.g., an event arriving between 2 ns and 2.1 ns after the last event on that channel for Time Tagger Ultra).

Parameters:

  • channel – Channel number.

  • deadtime – Dead time value in picoseconds.

Returns:

Resulting dead time in picoseconds, that might be rounded to the nearest valid value (minimum dead time or multiple of the clock period).

timestamp_t getDeadtime(channel_t channel)

Returns the dead time value for the specified channel.

Parameters:

channel – Channel number.

Returns:

Dead time value in picoseconds.

timestamp_t[] getDeadtimeRange(channel_t channel)

Returns a vector containing the minimum and the maximum allowable values for the dead time for the specified channel.

Parameters:

channel – Channel number.

Returns:

Minimum and maximum dead time values in picoseconds.

void setConditionalFilter(channel_t[] trigger, channel_t[] filtered)

Activates or deactivates the conditional 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 of channel numbers

  • filtered – List of channel numbers

void clearConditionalFilter()

Deactivates the event filter. Equivalent to setConditionalFilter([], []).

channel_t[] getConditionalFilterTrigger()

Returns the collection of trigger channels for the conditional filter.

Returns:

List of channel numbers.

channel_t[] getConditionalFilterFiltered()

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

Returns:

List of channel numbers.

void setEventDivider(channel_t channel, int 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. The divider is a 16 bit integer, so the maximum value is 65535.

Note that if the conditional filter is also active, the conditional filter is applied first.

Also note that the event divider is not supported on the TimeTaggerVirtual.

Parameters:

  • channel – Physical channel number.

  • divider – Divider factor, min. 1 and max. 65535.

int getEventDivider(channel_t channel)

Gets the event divider filter factor for the given channel.

See setEventDivider for further details.

Parameters:

channel – Physical channel number.

Returns:

Divider factor value.

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

int getOverflowsAndClear()

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

Returns:

Number of overflows.

void clearOverflows()

Sets the overflow counter to zero.

void setReferenceClock(channel_t clock_channel, float clock_frequency = 10e6, float time_constant = 1e-3, channel_t synchronization_channel = CHANNEL_UNUSED, timestamp_t synchronization_offset = 0, bool wait_until_locked = true)

Defines in software one of the input channels as the base clock for all channels. This feature sets up a software phase-locked loop (PLL) and rescales all incoming time-tags according to the time base provided by the clock_channel. This clock frequency alignment is called “syntonization”.

The Reference Clock is able to handle signals decimated by setEventDivider() and it is possible to recover the dismissed tags in software. The new time base is characterized by “ideal clock tags” separated by exactly the defined clock_period = 1E12/clock_frequency. For measurements, you can use both, rescaled and ideal clock tags. The injection of ideal clock tags can be controlled by setConditionalFilter(), by default all tags are injected.

While the PLL is enabled but not locked, the time base of the instrument is invalid. In this case, the time-tag stream changes to the overflow mode. This means that after a call to setReferenceClock(), you will typically find overflows because the PLL starts from an unlocked state.

Beyond the clock syntonization, the Reference Clock can also take a synchronization_channel to align the absolute time base of the Time Tagger to an external time base. Currently, the synchronization channel expects one pulse per second (1PPS) that is aligned precisely to a UTC second. The corresponding UTC second is retrieved from the computer’s system clock which requires the use of a time standard via PTP. The synchronization feature is important for merging time-tag streams in the TimeTaggerNetwork.

Warning

For the Time Tagger 20, a phase error of 200 ps needs to be considered when using the reference clock.

Parameters:

  • clock_channel – The physical channel that is used as reference clock input.

  • clock_frequency – The frequency of the reference clock. The value should not deviate from the real frequency by more than a few percent. If the Event Divider is active on this channel, you still provide the original input frequency. Default: 10E6, for 10 MHz.

  • time_constant – The time period to average over in seconds. The suppression of discretization noise is improved by a higher time_constant. If the value is too large, however, this will result in increased phase jitter due to the drift of the internal clock or the applied software clock signal. Default: 1E-3, for 1 ms.

  • synchronization_channel – The physical channel that provides a 1PPS signal representing a UTC second.

  • synchronization_offset – Sets a manual offset to the computer’s system time in ps. This is necessary if the system time is badly aligned to the 1PPS signal of the synchronization system. As this might change from start-up to start-up, it is recommended to synchronize both, the synchronization system and the computer’s system time, to UTC. Default is 0.

  • wait_until_locked – Blocks the execution until the software clock is locked. Throws an exception on locking errors. All locking log messages are filtered while this call is executed. Default: True

void disableReferenceClock()

Disable the software-defined reference clock.

ReferenceClockState getReferenceClockState()

Provides an object representing the current state of the software-defined reference clock. This includes the configuration parameters as well as dynamic values generated based on the incoming signal.

class TimeTaggerBase : public virtual TimeTaggerSource

The TimeTaggerBase class defines methods and functionality present in all Time Tagger objects. Every measurement and virtual channel instance requires a reference to a TimeTaggerBase object to associate with.

Subclassed by TimeTagger, TimeTaggerNetwork, TimeTaggerVirtual

Public Functions

void setSoftwareClock(channel_t input_channel, float input_frequency = 10e6, float averaging_periods = 1000, bool wait_until_locked = true)

Defines in software one of the input channels as the base clock for all channels. This feature sets up a software phase-locked loop (PLL) and rescales all incoming time-tags according to the software clock defined. The PLL provides a new time base with “ideal clock tags” separated by exactly the defined clock_period. For measurements, you can use both, rescaled and ideal clock tags.

While the PLL is not locked, the time base of the instrument is invalid. In this case, the time-tag stream changes to the overflow mode. This means that after every call to setSoftwareClock(), you will find overflows because the PLL starts from an unlocked state.

Warning

It is often useful to apply this feature in combination with setEventDivider() on the input_channel. The values of input_frequency and averaging_periods correspond to the transferred time-tags, not to the physical frequency. Changing the divider independently after setting up the software clock may lead to a failure of the locking process. Do not add input_channel to the list of filtered channels in setConditionalFilter().

Warning

For the Time Tagger 20, a phase error of 200 ps needs to be considered when using the software clock.

Parameters:

  • input_channel – The physical channel that is used as software clock input.

  • input_frequency – The frequency of the software clock after application of setEventDivider() (e.g. a 10 MHz clock signal with divider = 20 has input_frequency = 500 000). The value should not deviate from the real frequency by more than a few percent. Default: 10E6, for 10 MHz.

  • averaging_periods – The number of cycles to average over. The suppression of discretization noise is improved by a higher averaging_periods. If the value is too large, however, this will result in increased phase jitter due to the drift of the internal clock or the applied software clock signal. Default: 1000.

  • wait_until_locked – Blocks the execution until the software clock is locked. Throws an exception on locking errors. All locking log messages are filtered while this call is executed. Default: True.

void disableSoftwareClock()

Disable the software clock.

Deprecated:

use disableReferenceClock

SoftwareClockState getSoftwareClockState()

Provides an object representing the current software clock state. This includes the configuration parameters as well as dynamic values generated based on the incoming signal.

Deprecated:

use getReferenceClock

Returns:

An object that contains the current state of the software clock.

int getFence(bool 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 – Optional. If False, a reference to the most recently created fence will be returned instead. Default: True.

Returns:

The allocated fence.

bool waitForFence(int fence, int timeout = -1)

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

Parameters:

  • fence – Fence object, which shall be waited on.

  • timeout – Optional. Timeout in milliseconds. Negative means no timeout, zero returns immediately. Default: -1.

Returns:

True if the fence has passed, false on timeout.

bool sync(int timeout = -1)

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

The operation of this method on the TimeTaggerNetwork depends on the server access mode. If the TimeTaggerNetwork is connected to the Time Tagger server started in AccessMode::Control or AccessMode::SynchronousControl, the synchronization will be done all way through the server and the hardware. If the Time Tagger server started in AccessMode::Listen or AccessMode::SynchronousListen, the client will be able to synchronize only with the server but will not synchronize with the Time Tagger Hardware. However, if a USB synchronization fence was created by the server side, the clients will also see it.

See also:

Parameters:

timeout – Optional. Timeout in milliseconds. Negative means no timeout, zero returns immediately. Default: -1.

Returns:

True if the synchronization was successful, false on timeout.

channel_t getInvertedChannel(channel_t 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 – Channel number.

Returns:

The inverted channel number.

bool isUnusedChannel(channel_t channel)

Returns true if the passed channel number is CHANNEL_UNUSED.

Parameters:

channel – Channel number.

Returns:

True/False.

str getConfiguration()

Returns a JSON formatted string (dict in Python) containing complete information on the Time Tagger settings. It also includes descriptions of measurements and virtual channels created on this Time Tagger instance.

Returns:

Time Tagger settings and currently existing measurements.

xtra methods

Note

The following xtra methods are mainly for development purposes and may be discontinued in future software versions without further notice.

void xtra_setAutoStart(bool auto_start)

Configures if the new measurements and virtual channels start automatically upon creation. This is true by default for all measurements and virtual channels in all TimeTaggers, but disabled by default for the SynchronizedMeasurements::getTagger() proxy objects.

Warning

Disabling the auto start of new measurements and virtual channels is not recommended for most of the use cases and requires the user to start all the defined measurements and virtual channels in the correct order manually, with explicit calls to IteratorBase::start() or IteratorBase::startFor(),

Parameters:

auto_start – Select whether the auto start of new measurements and virtual channel is enable.

bool xtra_getAutoStart()

Returns whether the auto start of new measurements and virtual channels is enabled.

Returns:

The current auto start state of new measurements and virtual channel.

Time Tagger

class TimeTaggerHardware

This class provides the basic methods for configuring TimeTagger hardware, directly via USB or over the network.

Subclassed by TimeTagger, TimeTaggerNetwork, TimeTaggerServer

Public Functions

void setTriggerLevel(channel_t channel, float voltage)

Set the trigger level of an input channel in Volts.

Parameters:

  • channel – Physical channel number

  • voltage – Trigger level in Volts

float getTriggerLevel(channel_t channel)

Returns trigger level for the specified physical channel number.

Parameters:

channel – Physical channel number

Returns:

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

timestamp_t getHardwareDelayCompensation(channel_t channel)

Get the hardware input delay compensation for the given channel in picoseconds. This compensation can be understood as an implicit part of TimeTaggerSource::setDelayHardware() and TimeTaggerSource::setDelaySoftware(). If your device is able to set an arbitrary delay onboard, this applies to the hardware delay compensation as well.

Parameters:

channel – Physical channel number

Returns:

Hardware delay compensation in picoseconds

void setHardwareDelayCompensationActive(bool use_compensation)

Activate the hardware delay compensation of a channel

The physical input delays are calibrated and compensated. However this compensation is implemented after the conditional filter and so affects its result. This function queries the effective input delay, which compensates the hardware delay.

Parameters:

use_compensation – set compensation state

void setInputImpedanceHigh(channel_t channel, bool high_impedance)

Sets the input impedance to High-Z for the specified channel. Before createTimeTagger, after TimeTagger::reset(), and after freeTimeTagger, If not set explicitly to High-Z by setInputImpedanceHigh, the input will switch to 50 Ohm by default as soon as the input is used.

# Upon initialization, all inputs are in the High-Z state:
tagger = TimeTagger.createTimeTagger()

# If you want to keep a channel in High-Z, set it right after initialization:
tagger.setInputImpedanceHigh(1, True)

# The Time Tagger will now stay in High-Z on channel 1, channel 2 will switch to 50 Ohm:
cr = TimeTagger.Countrate(tagger, [1, 2])

Note

Method is only available for the Time Tagger X.

Parameters:

  • channel – Physical channel number.

  • high_impedance – True/False.

bool getInputImpedanceHigh(channel_t channel)

Returns whether the input impedance is set to high-Z for the specified channel.

Note

Method is only available for the Time Tagger X.

Parameters:

channel – Physical channel number.

Returns:

State of high input impedance.

void setInputHysteresis(channel_t channel, int value)

Sets the input hysteresis value for the specified channel. Oscillations of the measured signal within the hysteresis range around the trigger value are ignored and therefore do not trigger new events. Supported values are 1 mV, 20 mV, 70 mV. Default input hysteresis value is 20 mV.

Note

Method is only available for the Time Tagger X.

Parameters:

  • channel – Physical channel number.

  • value – Hysteresis voltage value in mV (1, 20, 70).

int getInputHysteresis(channel_t channel)

Returns the voltage value in mV of the input hysteresis for the specified channel.

Note

Method is only available for the Time Tagger X.

Parameters:

channel – Physical channel number.

Returns:

Hysteresis voltage value in mV.

void setNormalization(channel_t[] channels, bool state)

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

Parameters:

  • channels – List of physical channel numbers.

  • state – True/False.

bool getNormalization(channel_t channel)

Returns whether the Gaussian normalization of the detection jitter is enabled for the specified channel.

Parameters:

channel – The physical channel to query

Returns:

True/False

str getSerial()

Returns the hardware serial number.

Returns:

Serial number string.

str getModel()

Returns the model name as string.

Returns:

Model name as string

str getPcbVersion()

Returns Time Tagger PCB (Printed circuit board) version.

Returns:

PCB version.

float[] getDACRange()

Return a vector containing the minimum and the maximum DAC (Digital-to-Analog Converter) voltage range for the trigger level.

Deprecated:

Since version 2.18. Please use getTriggerLevelRange() instead.

Returns:

Minimum and maximum voltage, in volts.

float[] getTriggerLevelRange(channel_t channel)

Return a vector containing the minimum and the maximum voltage range for the trigger level of a given channel.

Parameters:

channel – Physical channel number.

Returns:

Minimum and maximum voltage for the given channel, in volts.

channel_t[] getChannelList(ChannelEdge type = ChannelEdge::All)

Returns a list of channels corresponding to the given type.

Parameters:

type – Limits the returned channels to the specified channel edge type.

Returns:

List of channel numbers.

void setHardwareBufferSize(int size)

Sets the maximum buffer size within the Time Tagger. 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. See also, Synchronization of the Time Tagger pipeline .

Note

Time Tagger 20 uses by default the whole buffer of 8 MTags, which can be filled with a total data rate of up to 40 MTags/s.

Parameters:

size – Buffer size, must be a positive number.

int getHardwareBufferSize()

Returns the maximum buffer size within the Time Tagger.

Returns:

Maximum hardware buffer size.

timestamp_t getPsPerClock()

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

Returns:

The clock period in picoseconds.

void setStreamBlockSize(int max_events, int max_latency)

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.

Note

The block size will be reduced even further when no new tag arrives within roughly 1-2 µs.

Parameters:

  • max_events – Maximum number of events within one block (256 - 32M), default: 1M events

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

int getStreamBlockSizeEvents()

Returns the block size of the data stream. See setStreamBlockSize() for further details.

Returns:

The maximum number of events within one block.

int getStreamBlockSizeLatency()

Returns the latency of the data stream. See setStreamBlockSize() for further details.

Returns:

The maximum latency in milliseconds.

void setTestSignal(channel_t[] channel, bool enabled)

Connects or disconnects the channels with the on-chip uncorrelated signal generator.

Note

When used on a TimeTaggerVirtual object, this method activates a Gaussian signal generator with a 9 ps RMS jitter, on the specified channel. This functionality is primarily for development use and is not intended for general application.

Parameters:

  • channel – List of physical channel numbers.

  • enabled – True/False

bool getTestSignal(channel_t channel)

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

Parameters:

channel – Physical channel number.

Returns:

True/False.

void setTestSignalDivider(int divider)

Change the frequency of the on-chip test signal.

  • For the Time Tagger X, the base frequency is 333.333 MHz and the default divider 375 corresponds to ~890 kCounts/s.

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

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

Parameters:

divider – Frequency divisor factor.

int getTestSignalDivider()

Returns the value of test signal division factor.

Returns:

The frequency divisor factor.

str getDeviceLicense()

Returns a JSON formatted string (dict in Python) containing license information of the Time Tagger device, for instance, model, edition, and available channels.

Returns:

License information.

str getSensorData()

Prints a JSON formatted string (dict in Python) containing all available sensor data for the given board. The Time Tagger 20 has no onboard sensors.

Returns:

Sensor data.

void disableLEDs(bool disabled)

Disables all channel LEDs and back LEDs.

Note

This feature currently lacks support for disabling the power LED on the Time Tagger X.

Parameters:

disabled – True/False.

void setLED(int 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 – LED bitmask.

void setSoundFrequency(int freq_hz)

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

Parameters:

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

void setTimeTaggerNetworkStreamCompression(bool active)

Enables/disables the compression of TimeTags before they are streamed from the server to the clients.

Note

Activation can be helpful for slow network environments (<= 100 MBit/s) if the bandwidth is the limiting factor. For instance, the amount of streamed data of periodic signals is reduced by about a factor of 2. The compression, on the other hand, leads to increased CPU utilization and is not advantageous for fast networks (>= 1 GBit/s).

Parameters:

active – Flag defining whether the compression is enabled (default: False).

int getChannelNumberScheme()

Fetch the configured numbering scheme for this TimeTagger object.

Please see setTimeTaggerChannelNumberScheme() for details.

class TimeTagger : public virtual TimeTaggerBase, public virtual TimeTaggerHardware

This class provides access to the hardware and exposes methods to control hardware settings, such as trigger levels or even filters. Behind the scenes, it opens the USB connection, initializes the device and receives and manages the time-tag-stream.

Public Functions

void reset()

Reset the Time Tagger to the start-up state.

float[] autoCalibration()

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

Returns:

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

int[,] getDistributionCount()

Returns the calibration data represented in counts.

Returns:

Calibration data in counts.

float[,] getDistributionPSecs()

Returns the calibration data represented in picoseconds.

Returns:

Calibration data in picoseconds.

void enableFpgaLink(channel_t[] channels, str destination_mac, FpgaLinkInterface link_interface = FpgaLinkInterface::SFPP_10GE, bool exclusive = false)

Enable the FPGA link of the Time Tagger X.

Parameters:

  • channels – List of channels, which shall be streamed over the FPGA link.

  • destination_mac – Destination MAC, use an empty string for the broadcast address of “FF:FF:FF:FF:FF:FF”.

  • link_interface – Selects which interface shall be used, default is FpgaLinkInterface::SFPP_10GE.

  • exclusive – Determines if time tags should exclusively be transmitted over Ethernet, increasing Ethernet performance and avoiding USB issues, default is mixed USB and ethernet.

void disableFpgaLink()

Disable the FPGA link of the Time Tagger X.

void startServer(AccessMode access_mode, channel_t[] channels = channel_t[](), int port = 41101)

Start a Time Tagger server that can be accessed via TimeTaggerNetwork. The server access mode controls if the clients are allowed to change the hardware parameters. See also: AccessMode.

Throws:

RuntimeError – If server is already running.

Parameters:

  • access_mode – AccessMode in which the server should run. Either control or listen.

  • channels – Channels to be streamed. Used only when access_mode=AccessMode.Listen or access_mode=AccessMode.SynchronousListen.

  • port – Port at which this Time Tagger server will be listening on.

void stopServer()

Stops the Time Tagger server if currently running, otherwise does nothing.

bool isServerRunning()

Checks if the server is still running.

Returns:

True is server is running and False otherwise.

void setServerAddress(str ip_address)

By default a Time Tagger in server mode will bind to IP address 0.0.0.0, exposing the server via all IPv4 addresses of the local machine. This may be undesirable in the presence of multiple network hardware within the same machine. To prevent exposure to multiple networks, the binding IP address may be configured to refer to specific network hardware.

Parameters:

ip_address – The IP address, or hostname.

str getServerAddress()

Gets the IP address, or hostname, to which the Time Tagger server shall bind.

Returns:

The IP address, or hostname.

Device independent xtra methods

Note

The following xtra methods are mainly for development purposes and may be discontinued in future software versions without further notice. The xtra setter methods in this first section are only available for the Time Tagger Ultra and the Time Tagger X.

void xtra_setAvgRisingFalling(channel_t channel, bool enable)

Configures if the rising and falling events shall be averaged.

This is implemented on the device before any filter like event divider and it does not require to transfer both events.

They need to be manually delayed to be within a window of +-500 ps of error, else events might get lost. This method has no side effects on the channel getInvertedChannel(), you can still fetch the original events there. However if both are configured to return the averaged result, the timestamps will be identical.

Parameters:

  • channel – The channel, on which the average value shall be returned.

  • enable – Select whether the averaging feature is enabled.

bool xtra_getAvgRisingFalling(channel_t channel)

Return the state of the averaging of rising and falling edges.

Parameters:

channel – The channel for which the averaging state is returned.

Returns:

The current enable state.

void xtra_setHighPrioChannel(channel_t channel, bool enable)

Sets the priority state of a channel. This setting is applied on the hardware before USB transfer.

If a buffer overflow occurs, channels with high-priority state will interrupt the overflow mode and be transmitted as standard time-tags (Tag::Type::TimeTag). Timing information of low-priority channels is dismissed in overflow mode and only the number of counts is transmitted (Tag::Type::MissedEvents). A typical application of the high-priority channels is CountBetweenMarkers with high-priority markers. In this case, the overflow range will be ideally sliced by the markers.

Warning

Interrupting the overflow mode may break the protection mechanism the overflow mode provides. This may lead to irreversible loss of events, not only loss of their timing information. High priority should only be assigned to low-countrate channels, e.g. pixel triggers or similar control events.

Parameters:

  • channel – The channel on which the high-priority state shall be enabled.

  • enable – Select whether high priority is enabled.

bool xtra_getHighPrioChannel(channel_t channel)

Get the priority state of a channel.

Parameters:

channel – The channel for which the priority state is returned.

Returns:

The current enable state of the high-priority feature on this channel.

TTX-only xtra methods

Note

The following xtra methods are mainly for development purposes and may be discontinued in future software versions without further notice. The xtra setter methods in this second section are only available for the Time Tagger X.

void xtra_setAuxOut(int channel, bool enabled)

Enables/Disables the Aux Out signal for the specified Aux channel.

Parameters:

  • channel – Aux channel number.

  • enabled – True/False.

bool xtra_getAuxOut(int channel)

Returns whether the Aux Out signal is enabled for the specified Aux channel.

Parameters:

channel – Aux channel number.

Returns:

State of the Aux Out signal.

void xtra_setAuxOutSignal(int channel, int divider, float duty_cycle = 0.5)

Sets the signal shape, i.e., duty cycle and frequency, of the Aux out signal for the specified Aux channel.

Parameters:

  • channel – Aux channel number.

  • divider – Divider of the Aux Out base signal frequency (333 MHz).

  • duty_cycle – The duty cycle of the aux signal.

int xtra_getAuxOutSignalDivider(int channel)

Returns the divider for the frequency of the Aux Out signal generator or the specified Aux channel.

Parameters:

channel – Aux channel number.

Returns:

Divider for the frequency of the Aux Out signal generator,

float xtra_getAuxOutSignalDutyCycle(int channel)

Returns the duty cycle of the Aux Out signal for the specified Aux channel.

Parameters:

channel – Aux channel number.

Returns:

Duty cycle of the Aux Out signal generator.

float xtra_measureTriggerLevel(channel_t channel)

Measures and returns the applied voltage threshold of the specified channel.

Parameters:

channel – Channel number.

Returns:

Applied voltage threshold of a channel

void xtra_setClockSource(int source)

Specifies the different clock sources:

  • 0 - internal clock

  • 1 - external clock 10 Mhz

  • 2 - external clock 500 MHz.

Parameters:

source – Number of the clock source. Allowed values: 0, 1, 2.

int xtra_getClockSource()

Returns the used clock source:

  • -1: auto selecting of below options

  • 0: internal clock

  • 1: external 10 MHz

  • 2: external 500 MHz.

Returns:

Number of the clock source.

void xtra_setClockAutoSelect(bool enabled)

Enables/Disables the auto clocking function.

Parameters:

enabled – True/False.

bool xtra_getClockAutoSelect()

Returns whether the auto clocking function is enabled.

Returns:

State of auto clocking.

void xtra_setClockOut(bool enabled)

Activates/Deactivates the 10 MHz clock output.

Parameters:

enabled – True/False.

The TimeTaggerVirtual class

class TimeTaggerVirtual : public virtual TimeTaggerBase

The TimeTaggerVirtual allows replaying earlier stored time-tag dump files created by the FileWriter. Using the virtual Time Tagger, you can repeat your experiment data analysis with different parameters or even perform different measurements.

Here is a minimal code snippet showing how to replay your data setting one measurement: 

# Initialize the TimeTaggerVirtual by passing the name of the file to the constructor.
virtual_tagger = TimeTagger.createTimeTaggerVirtual("filename.ttbin")

# Define all the virtual channels and measurements by passing the TimeTaggerVirtual object
# to the tagger argument.
countrate = TimeTagger.Countrate(tagger=virtual_tagger, channels=[1,2])

# Start the replay of the data using the method run()
virtual_tagger.run()

# Wait until all time tags, or the selected chunk of it, are analyzed
virtual_tagger.waitUntilFinished()

# Retrieve the data
data = countrate.getData()

Note

The virtual Time Tagger requires a free software license, which is automatically acquired from the Swabian Instruments license server when createTimeTagger or createTimeTaggerVirtual is called while a Time Tagger is attached. Once received, the license is permanently stored on this PC and the Virtual Time Tagger will work without Time Tagger hardware attached.

Public Functions

int[] run(float speed = -1.0)

Start the replay at given speed factor. A value of speed=1.0 will replay at a real-time rate. All speed values < 0.0 will replay the data as fast as possible but stops at the end of all data. If no file for replay is queued, speed < 0.0 is replaced by speed = 1.0 for simulations. This automatic speed selection is also the default value. Extreme slow replay speed between 0.0 and 0.1 is not supported.

Parameters:

speed – Replay speed factor.

Returns:

IDs of the queued files.

int replay(str file, timestamp_t begin = 0, timestamp_t duration = -1, bool queue = true)

Deprecated:

Since version 2.18. Please use createTimeTaggerVirtual and run()/appendFile() instead.

Replay a dump file specified by its path file or add it to the replay queue. If the flag queue is false, the current queue will be discarded and file will be replayed immediately. The file parameter can specify a header file or single specific file as shown in the following example.

See also: FileWriter, FileReader, and mergeStreamFiles().

Warning

Replaying data in small chunks is not recommended for long recordings. Each replay() call reads the file from the beginning up to the specified begin, even though only the data between begin and begin + duration is processed. This leads to significant overhead for chunks with higher begin values. Replaying the whole file at once is more efficient.

Parameters:

  • file – The file to be replayed.

  • begin – Duration in picoseconds to skip at the beginning of the file. A negative time will generate a pause in the replay.

  • duration – Duration in picoseconds to be read from the file. duration=-1 will replay everything. (default: -1)

  • queue – flag if this file shall be queued. (default: True)

Returns:

ID of the queued file.

void stop()

This method stops the current file and clears the replay queue.

int appendFile(str filename, timestamp_t begin = 0, timestamp_t duration = -1, bool clear = false)

Add a new file to the queue of files to be replayed. If the file includes channels that are not present in the initial file passed to createTimeTaggerVirtual, these channels will be ignored during replay and are not accessible by measurements.

Parameters:

  • filename – The name of the file to be replayed.

  • begin – Duration in picoseconds to skip at the beginning of the file. A negative time will generate a pause in the replay.

  • duration – Duration in picoseconds to be read from the file. duration=-1 will replay everything. (default: -1)

  • clear – If True, the current queue is cleared and the given file starts a new queue. (default: False, i.e. append to existing queue)

Returns:

ID of the queued file.

bool waitForCompletion(int ID = 0, int timeout = -1)

Deprecated:

Since version 2.18. Use Please waitUntilFinished() instead.

Blocks the current thread until the replay is completed.

bool waitUntilFinished(int ID = 0, int timeout = -1)

Blocks the current thread until the replay is completed.

This method blocks the current execution and waits until the given file has finished its replay. If no ID is provided, it waits until all queued files are replayed.

This function does not block on a zero timeout. Negative timeouts are interpreted as infinite timeouts.

Warning

Calling waitUntilFinished() on a paused timebase, such as before calling run(), will block the current thread indefinitely.

Parameters:

  • ID – Selects which file to wait for. (default: 0)

  • timeout – Timeout in milliseconds.

Returns:

True if the file is complete, false on timeout.

void setReplaySpeed(float speed)

Deprecated:

Since version 2.18. Please use run() instead.

Configures the speed factor for the virtual tagger. A value of speed=1.0 will replay at a real-time rate. All speed values < 0.0 will replay the data as fast as possible but stops at the end of all data. This is the default value. Extreme slow replay speed between 0.0 and 0.1 is not supported.

Parameters:

speed – Replay speed factor.

float getReplaySpeed()

Returns the current speed factor. Please see also setReplaySpeed() for more details.

Returns:

The replay speed factor

The TimeTaggerNetwork class

In the Time Tagger software version 2.10, we have introduced a way of sending the time-tag stream to other applications and even remote computers for independent processing. We call this feature Network Time Tagger. You can use it with any Time Tagger hardware device by starting the time-tag stream server with startServer(). Once the server is running, the clients can connect to it by calling createTimeTaggerNetwork() and specifying the server address. Starting with version 2.18, a TimeTaggerNetwork client can connect to multiple servers and merge their time tag streams, provided the servers are synchronized (e.g. using the White Rabbit protocol). Once the servers are running, the clients can connect to them by calling createTimeTaggerNetwork() and specifying the servers addresses. A client can be any computer that can access the servers over the network or another process on the same computer. Servers and clients can run on different operating systems or use different programming languages.

Note on Performance

The Network Time Tagger server sends a time tag stream in a compressed format requiring about 4 bytes per time tag. Every client receives the data only from the channels required by the client. The maximum achievable data rate will depend on multiple factors, like server and client CPU performance, operating system, network adapter used, and network bandwidth, as well as the whole network infrastructure.

In a 1 Gbps Ethernet network, it is possible to achieve about 26 MTags/second of the total outgoing data rate from the server. Note that this bandwidth is shared among all clients connected. Likewise, a 10 Gbps Ethernet network allows reaching higher data rates while having more clients. In our tests, we reached up to 40 MTags/s per client.

When you run the server and the client on the same computer, the speed of the network adapters installed on your system becomes irrelevant. In this case, the operating system sends the data directly from the server to the client.

class TimeTaggerNetwork : public virtual TimeTaggerBase, public virtual TimeTaggerHardware

The TimeTaggerNetwork represents a client-side of the Network Time Tagger and provides access to the Time Tagger server. A server can be created on any physical Time Tagger by calling TimeTagger::startServer. The TimeTaggerNetwork object is created by calling createTimeTaggerNetwork.

Note

Although the TimeTaggerNetwork formally inherits from TimeTaggerBase, almost all methods of the hardware TimeTagger are available on the client (except for TimeTagger::startServer() and TimeTagger::stopServer()). These redundant methods are not listed in this section. A call to a method that exists on TimeTagger will be forwarded to the server. When using the TimeTaggerNetwork with multiple servers, these forwarded method calls are always directed to the first connected server. An exception is TimeTaggerHardware::getChannelList(), which is handled on the client and returns all channels available across all connected servers. To extract information or interact with a specific server, use getServer() to access a TimeTaggerServer object. Some methods on TimeTaggerNetwork offer similar functionality to those on the hardware TimeTagger, but are implemented on the client side and can be recognized by the suffix Client. If the server is running in AccessMode::Listen or AccessMode::SynchronousListen and a method call forwarded to the server would cause setting changes on the server-side, the call will raise an exception on the client. This scheme of forwarding may lead to unexpected behavior: If the server is started in AccessMode::Listen or AccessMode::SynchronousListen with a restricted set of channels and you call TimeTaggerHardware::getChannelList() on the client side, not all channels returned by this method can be accessed. You can request the list of accessible channels from the server with getTimeTaggerServerInfo.

Public Functions

bool isConnected()

Check if the Network Time Tagger is currently connected to a server.

Returns:

True/False.

void setDelayClient(channel_t channel, timestamp_t time)

Sets an artificial software delay per channel on the client side. To specify it on the server side, see setDelaySoftware() or setDelayHardware(). The latter is not available for the Time Tagger 20. This delay will be applied only on this object and will not affect the server settings or delays at any other clients connected to the same Time Tagger server.

Parameters:

  • channel – The channel number.

  • time – Delay time in picoseconds.

timestamp_t getDelayClient(channel_t channel)

Returns the value of the delay applied on the client-side in picoseconds for the specified channel.

Parameters:

channel – Channel number.

Returns:

Input delay in picoseconds.

int getOverflowsClient()

If the server is not able to send all the time-tags to the client, e.g. due to limited network bandwidth, the time-tag stream switches to the overflow mode. This means that the client might experience additional overflow events that are not originating from the hardware. This counter counts all missing blocks of time tags occurred in all the hardware devices and on the network since the client connection or last call to clearOverflowsClient() or getOverflowsAndClearClient().

Returns:

The value of the client-side overflow counter.

int getOverflowsAndClearClient()

The same as getOverflowsClient() but also clears the client-side counter. See getOverflowsClient() for more information on client-side overflows.

void clearOverflowsClient()

Clears the overflow counter on the client-side. A call to getOverflows() will return the information as it is available on the server. See getOverflowsClient() for more information on client-side overflows.

TimeTaggerServer getServer(str ip_address)
Parameters:

ip_address – the IP address, or hostname, of the desired TimeTagger server.

Throws:

ValueError – if ip_address does not match an address used in the call to createTimeTaggerNetwork().

Returns:

a TimeTaggerServer object, for configuration and control purposes.

TimeTaggerServer[] getServers()
Returns:

a list of pointers to all TimeTaggerServer objects making up the TimeTaggerNetwork client.

The TimeTaggerServer class contains all relevant control methods present in TimeTaggerBase and TimeTaggerHardware.

TimeTaggerServer objects allow control of a TimeTagger in server mode, provided has been created with AccessMode::Control privileges. However, unlike TimeTaggerBase, TimeTaggerServer cannot be used to perform measurements.

class TimeTaggerServer : public virtual TimeTaggerHardware, public virtual TimeTaggerSource

Control and configure individual TimeTagger servers via a TimeTaggerNetwork object.

Public Functions

str getAddress()
Returns:

the IP address, or hostname, of the server object.

AccessMode getAccessMode()
Returns:

the AccessMode of the underlying TimeTagger server.

channel_t getClientChannel(channel_t server_channel)
Returns:

the channel number on the TimeTaggerNetwork object corresponding to server_channel.

Additional classes

struct ReferenceClockState

Configuration State

timestamp_t clock_period

The rounded clock period matching the input frequency set in TimeTaggerSource::setReferenceClock().

channel_t clock_channel

The input channel of the periodic clock signal set in TimeTaggerSource::setReferenceClock().

channel_t synchronization_channel

The 1 pulse per second channel representing the (UTC) second TimeTaggerSource::setReferenceClock().

channel_t ideal_clock_channel

A virtual channel number to receive the ideal clock tags. During a locking period, these tags are separated by clock_period by definition. To receive the rescaled measured clock tags, use clock_channel.

float averaging_periods

The averaging periods set in TimeTaggerBase::setReferenceClock().

timestamp_t synchronization_offset

The manual offset to the computer’s system time in ps. This is necessary if the system time is badly aligned to the 1PPS signal of the synchronization system.

bool enabled

Indicates whether the reference clock is active or not.

int event_divider

The event divider of the clock_channel.

Runtime Information

Beyond the configuration state, the object provides current runtime information of the software clock:

bool is_locked

Indicates whether the PLL of the software clock was able to lock to the input signal.

bool is_synchronized

Indicates whether the absolute timebase is aligned to the synchronization_channel.

int error_counter

Amount of locking errors since the last TimeTaggerBase::setReferenceClock() call.

timestamp_t last_ideal_clock_event

Timestamp of the last ideal clock event in picoseconds.

float period_error

Current deviation of the measured clock period from the ideal period given by clock_period.

float phase_error_estimation

Current root of the squared differences of clock_input timestamps and ideal clock timestamps. This value includes the discretization noise of the clock_input channel.

struct SoftwareClockState

The SoftwareClockState object contains the current configuration state:

Configuration State

timestamp_t clock_period

The rounded clock period matching the input frequency set in TimeTaggerBase::setSoftwareClock().

channel_t input_channel

The input channel of the software clock set in TimeTaggerBase::setSoftwareClock().

channel_t ideal_clock_channel

A virtual channel number to receive the ideal clock tags. During a locking period, these tags are separated by clock_period by definition. To receive the rescaled measured clock tags, use clock_channel.

float averaging_periods

The averaging periods set in TimeTaggerBase::setSoftwareClock().

bool enabled

Indicates whether the software clock is active or not.

Runtime Information

Beyond the configuration state, the object provides current runtime information of the software clock:

bool is_locked

Indicates whether the PLL of the software clock was able to lock to the input signal.

int error_counter

Amount of locking errors since the last TimeTaggerBase::setSoftwareClock() call.

timestamp_t last_ideal_clock_event

Timestamp of the last ideal clock event in picoseconds.

float period_error

Current deviation of the measured clock period from the ideal period given by clock_period.

float phase_error_estimation

Current root of the squared differences of clock_input timestamps and ideal clock timestamps. This value includes the discretization noise of the clock_input channel.