Virtual Channels

Virtual channels are software-defined channels as compared to the real input channels. Virtual channels can be understood as a stream flow processing units. They have an input through which they receive time-tags from a real or another virtual channel and output to which they send processed time-tags.

Virtual channels are used as input channels to the measurement classes the same way as real channels. Since the virtual channels are created during run-time, the corresponding channel number(s) are assigned dynamically and can be retrieved using getChannel() or getChannels() methods of virtual channel object.

Available virtual channels

Note

In MATLAB, the Virtual Channel names have common prefix TT*. For example: Combiner is named as TTCombiner. This prevents possible name collisions with existing MATLAB or user functions.

Coincidence

Detects coincidence clicks on two or more channels within a given time window.

Coincidences

Detects coincidence clicks on multiple channel groups within a given time window.

Combinations

Detects coincidence clicks on all possible combinations of given channels within a given time window, preceded and followed by two guard windows of the same width without any events on these channels.

Combiner

Merges events from multiple channels into a single channel.

ConstantFractionDiscriminator

Detects rising and falling edges of an input signal and returns the average time.

DelayedChannel

Creates a delayed replica of an input channel.

EventGenerator

Generates a signal pattern for each trigger event.

FrequencyMultiplier

Multiplies the frequency of a periodic signal on a channel.

GatedChannel

Passes input signals only while the gate is open, defined by start and stop trigger channels.

TriggerOnCountrate

Generates an event when the count rate of a given channel crosses given threshold value.

Common methods

VirtualChannel.getChannel()

VirtualChannel.getChannels()

Returns the channel number(s) corresponding to the virtual channel(s). Use this channel number the very same way as the channel number of physical channel, for example, as an input to a measurement class or another virtual channel.

Important

Virtual channels operate on the time tags that arrive at their input. These time tags can be from rising or falling edges of the physical signal. However, the virtual channels themselves do not support such a concept as an inverted channel.

getConfiguration()

Returns configuration data of the virtual channel object. The configuration includes the name, values of the current parameters and the channel numbers. Information returned by this method is also provided with getConfiguration().

Returns:

Configuration data of the virtual channel object.

Return type:

dict

Coincidence

class Coincidence : public Coincidences

Detects coincidence clicks on two or more channels within a given window. Every time a coincidence is detected on the input channels (AND logic), Coincidence emits a tag on the virtual channel. The timestamp assigned to the coincidence on the virtual channel can be set using the parameter timestamp. By default, the timestamp from the last event received to complete the coincidence is used.

See all common methods

Public Functions

Coincidence(TimeTaggerBase tagger, channel_t[] channels, timestamp_t coincidenceWindow = 1000, CoincidenceTimestamp timestamp = CoincidenceTimestamp::Last)

Parameters:

• tagger – Time Tagger object instance.

• channels – List of channels on which coincidence will be detected in the virtual channel.

• coincidenceWindow – Maximum time between all events for a coincidence in picoseconds (default: 1000).

• timestamp – Type of timestamp for the virtual channel (default: Last).

Coincidences

class Coincidences : public IteratorBase

Detects coincidence clicks on multiple channel groups within a given window. If several different coincidences are required with the same window size, Coincidences provides better performance compared to multiple virtual Coincidence channels. One object of the Coincidence class is limited to 64 unique channels in the list of channel groups (coincidenceGroups).

Example code:

from TimeTagger import Coincidence, Coincidences, CoincidenceTimestamp, createTimeTagger
tagger = createTimeTagger()

coinc = Coincidences(tagger, [[1,2], [2,3,5]], coincidenceWindow=10000, timestamp=CoincidenceTimestamp.ListedFirst)
coinc_chans = coinc.getChannels()
coinc1_ch = coinc_chans[0]  # double coincidence in channels [1,2] with timestamp of channel 1
coinc2_ch = coinc_chans[1]  # triple coincidence in channels [2,3,5] with timestamp of channel 2

# or equivalent but less performant
coinc1 = Coincidence(tagger, [1,2], coincidenceWindow=10000, timestamp=CoincidenceTimestamp.ListedFirst)
coinc2 = Coincidence(tagger, [2,3,5], coincidenceWindow=10000, timestamp=CoincidenceTimestamp.ListedFirst)
coinc1_ch = coinc1.getChannel()  # double coincidence in channels [1,2] with timestamp of channel 1
coinc2_ch = coinc2.getChannel()  # triple coincidence in channels [2,3,5] with timestamp of channel 2

See all common methods

Note

Only C++ and python support jagged arrays (array of arrays, like uint[][]) which are required to combine several coincidence groups and pass them to the constructor of the Coincidences class. Hence, the API differs for Matlab, which requires a cell array of 1D vectors to be passed to the constructor (see Matlab examples provided with the installer). For LabVIEW, a CoincidencesFactory-Class is available to create a Coincidences object, which is also shown in the LabVIEW examples provided with the installer).

Subclassed by Coincidence

Public Functions

Coincidences(TimeTaggerBase tagger, channel_t[][] coincidenceGroups, timestamp_t coincidenceWindow, CoincidenceTimestamp timestamp = CoincidenceTimestamp::Last)

Parameters:

• tagger – Time Tagger object instance.

• coincidenceGroups – List of channel groups on which coincidence will be detected in the virtual channel.

• coincidenceWindow – Maximum time between all events for a coincidence in picoseconds.

• timestamp – Type of timestamp for the virtual channel (default: Last).

Combinations

class Combinations : public IteratorBase

A combination is a group of clicks on a set of channels within a given time window. This time window is surrounded by two guard windows of the same width. These guard windows do not contain any events on the channels being monitored.

The heralding guard window precedes the first click in the combination. The following guard window starts at the time of the last event within the combination window. If there is a click on one of the monitored channels within the guard windows, no combination event is generated. A new combination window then starts with the next click after an empty guard window.

Every time a combination is detected on the monitored channels, Combinations emits a tag on the corresponding virtual channel. The timestamp on this virtual channel is the time of the last event included in the combination. Given input channels to be monitored, there will be possible combinations, each having a corresponding virtual channel number.

In addition, extra virtual channels called SumChannels are created. This class emits a click on the n-th of these channels on each n-fold combination, regardless of the channels that contributed to the combination. For instance, this is useful for pseudo-photon-number-resolution with detector arrays.

See all common methods

Note

Multiple events on the same channel within one time window are counted as one.

Public Functions

Combinations(TimeTaggerBase tagger, channel_t[] channels, timestamp_t window_size)

Parameters:

• tagger – Time Tagger object instance.

• channels – List of channels on which the combinations will be detected.

• window_size – Maximum time between all events to make a combination, minimum time without any event detected before and after the combination window, expressed in picoseconds.

channel_t getChannel(channel_t[] input_channels)

Returns the virtual channel number corresponding to the combination formed by the given set of input channels.

Warning

The Combinations class enables the virtual channel corresponding to a specific combination of input channels only after an explicit call to getChannel(). This is essential to manage computational demands, as the number of possible combinations increases exponentially with the number of input channels.

Parameters:

input_channels – List of channels forming the combination monitored by the returned virtual channel.

Returns:

Virtual channel number monitoring the combination.

channel_t[] getChannels(channel_t[][] list_of_input_channel_sets)

Returns a list of virtual channel numbers corresponding to the combinations formed by the given list of sets of input channels.

Warning

This method can quickly increase the computational demands of the Combinations class, as all returned virtual channels are automatically enabled.

Parameters:

list_of_input_channel_sets – List of sets of channels forming the combination monitored by the returned virtual channel.

Returns:

List of virtual channel numbers monitoring the set of combinations.

channel_t[] getCombination(channel_t virtual_channel)

Returns the set of input channels forming a combination event on the given virtual channel virtual_channel.

Parameters:

virtual_channel – Virtual channel storing the clicks from the combination formed by the returned channels.

Returns:

List of channels forming the combination monitored by the input virtual channel.

channel_t getSumChannel(int n_channels)

Returns the virtual channel number on which an event is generated when any combination of exactly n_channels clicks is detected within the window_size.

Parameters:

n_channels – Length of the combinations monitored by the returned virtual channel.

Returns:

Virtual channel number monitoring all combinations of n_channel clicks.

Combiner

class Combiner : public IteratorBase

Merges two or more channels into one. Every time an event is detected on any of the input channels (OR logic), Combiner emits a tag on the corresponding virtual channel.

See all common methods

Public Functions

Combiner(TimeTaggerBase tagger, channel_t[] channels)

Parameters:

• tagger – Time Tagger object instance.

• channels – List of channels to be combined into a single virtual channel.

ConstantFractionDiscriminator

class ConstantFractionDiscriminator : public IteratorBase

Constant Fraction Discriminator (CFD) detects rising and falling edges of an input pulse and returns the average time of both edges. This is useful in situations when precise timing of the pulse position is desired for the pulses of varying durations and amplitudes.

For example, the figure above shows four input pulses separated by 15 nanoseconds. The first two pulses have equal widths but different amplitudes, the middle two pulses have equal amplitude but different durations, and the last pulse has a duration longer than the search_window and is therefore skipped. For such input signal, if we measure the time of the rising edges only, we get an error in the pulse positions, while with CFD this error is eliminated for symmetric pulses.

See all common methods

Note

The virtual CFD requires the time tags of the rising and falling edge. This leads to:

• The transferred data of the input channel is twice the regular input rate.

• When you shift the signal, e.g., via TimeTaggerBase::setInputDelay(), you have to shift both edges.

• When you use the conditional filter, apply the trigger from both channels.

In addition, you may encounter data rate limitations due the computational complexity of this virtual channel. Consider using TimeTagger::xtra_setAvgRisingFalling() for similar functionality when the variation between pulse durations is small. There, the computations are performed on the Time Tagger hardware instead of on your PC, and only half the data rate needs to be transferred for the same result.

Public Functions

ConstantFractionDiscriminator(TimeTaggerBase tagger, channel_t[] channels, timestamp_t search_window)

Parameters:

• tagger – Time Tagger object instance.

• channels – List of channels on which to perform the CFD. Specify rising edges only; corresponding falling edges will be registered automatically.

• search_window – Maximum pulse duration, in picoseconds, for detection.

DelayedChannel

class DelayedChannel : public IteratorBase

Clones input channels, which can be delayed by a time specified with the delay parameter in the constructor or the DelayedChannel::setDelay() method. A negative delay will delay all other events.

See all common methods

Note

If you want to set a global delay for one or more input channels, TimeTaggerBase::setInputDelay() is recommended as long as the delays are small, which means that not more than 100 events on all channels should arrive within the maximum delay set.

Public Functions

DelayedChannel(TimeTaggerBase tagger, channel_t input_channel, timestamp_t delay)

Parameters:

• tagger – Time Tagger object instance.

• input_channel – Channel to be delayed.

• delay – Time by which the input is delayed, expressed in picoseconds.

void setDelay(timestamp_t delay)

Allows modifying the delay time.

Warning

Calling this method with a reduced delay time may result in a partial loss of the internally buffered time tags.

Parameters:

delay – Delay time in picoseconds.

EventGenerator

class EventGenerator : public IteratorBase

Emits an arbitrary pattern of timestamps for every trigger event. The number of trigger events can be reduced by trigger_divider. The start of a new pattern does not abort the execution of unfinished patterns, so patterns may overlap. The execution of all running patterns can be aborted by a click of the stop_channel, i.e. overlapping patterns can be avoided by setting the stop_channel to the trigger_channel.

See all common methods

Public Functions

EventGenerator(TimeTaggerBase tagger, channel_t trigger_channel, timestamp_t[] pattern, int trigger_divider = 1, int divider_offset = 0, channel_t stop_channel = CHANNEL_UNUSED)

Parameters:

• tagger – Time Tagger object instance.

• trigger_channel – Channel number of the trigger signal.

• pattern – List of relative timestamps defining the pattern executed upon a trigger event.

• trigger_divider – Factor by which the number of trigger events is reduced (default: 1).

• divider_offset – If trigger_divider > 1, the divider_offset the number of trigger clicks to be ignored before emitting the first pattern (default: 0).

• stop_channel – Channel number of the stop channel.

FrequencyMultiplier

class FrequencyMultiplier : public IteratorBase

The FrequencyMultiplier inserts copies of the original input events from the input_channel and adds additional events to match the upscaling factor. The algorithm used assumes a constant frequency and calculates out of the last two incoming events the intermediate time stamps to match the frequency given by the multiplier parameter.

The FrequencyMultiplier can be used to restore the actual frequency applied to an input_channel which was reduces via the EventDivider to lower the effective data rate.

See all common methods

Warning

Very high output frequencies create a high CPU load, eventually leading to overflows .

Public Functions

FrequencyMultiplier(TimeTaggerBase tagger, channel_t input_channel, int multiplier)

Parameters:

• tagger – Time Tagger object instance.

• input_channel – Channel on which the upscaling of the frequency is based on.

• multiplier – Frequency upscaling factor.

GatedChannel

class GatedChannel : public IteratorBase

Transmits the signal from an input_channel to a new virtual channel between an edge detected at the gate_start_channel and the gate_stop_channel.

See all common methods

Note

If you assign the same channel to input_channel and to gate_start_channel or gate_stop_channel, respectively, the internal execution order of the transmission decision and the gate operation (opening or closing) becomes important: For each tag on the input_channel, the decision is made based on the previous state. After this decision is made for itself, the tag might toggle the gate state.

• input_channel == gate_stop_channel: If the gate is open prior to the arrival of the tag, the tag will pass the gate and close it afterward. All subsequent tags will be eliminated until an event on gate_start_channel opens the gate again. This means that after the gate has been opened, only a single tag will pass the gate, which is exactly the behavior of the Conditional Filter with with gate_start_channel acting as the trigger and input_channel acting as the filtered channel.

• input_channel == gate_start_channel: If the gate is open prior to the arrival of the tag, the tag itself will be blocked but opens the gate afterward. All subsequent tags will pass the gate until an event on gate_stop_channel closes the gate again. This means that every event on gate_stop_channel will eliminate exactly the next event on the input_channel.

This behavior applies to all software versions starting from 2.10.8.

Public Functions

GatedChannel(TimeTaggerBase tagger, channel_t input_channel, channel_t gate_start_channel, channel_t gate_stop_channel, GatedChannelInitial initial = GatedChannelInitial::Closed)

Note

Note that gate_stop_channel == gate_start_channel will result in an exception.

Parameters:

• tagger – Time Tagger object instance.

• input_channel – Channel which is gated.

• gate_start_channel – Channel on which a signal detected will start the transmission of the input_channel through the gate.

• gate_stop_channel – Channel on which a signal detected will stop the transmission of the input_channel through the gate.

• initial – The initial state of the gate. If overflows occur, the gate will be reset to this state as well (default: GatedChannelInitial::Closed).

TriggerOnCountrate

class TriggerOnCountrate : public IteratorBase

Measures the count rate inside a rolling time window and emits tags when a defined reference_countrate is crossed. A TriggerOnCountrate object provides two virtual channels: the above and the below channels. The above channel is triggered when the count rate exceeds the threshold (transition from below to above). The below channel is triggered when the count rate falls below the threshold (transition from above to below).

To avoid the emission of multiple trigger tags in the transition area, the hysteresis count rate modifies the threshold with respect to the transition direction: An event in the above channel will be triggered when the channel is in the below state and rises to reference_countrate + hysteresis or above. Vice versa, the below channel fires when the channel is in the above state and falls to the limit of reference_countrate - hysteresis or below.

The time tags are always injected at the end of the integration window. You can use the DelayedChannel to adjust the temporal position of the trigger tags with respect to the integration time window.

The very first tag of the virtual channel will be emitted a time_window after the instantiation of the object and will reflect the current state, so either above or below.

See all common methods

Public Functions

TriggerOnCountrate(TimeTaggerBase tagger, channel_t input_channel, float reference_countrate, float hysteresis, timestamp_t time_window)

Parameters:

• tagger – Time Tagger object instance.

• input_channel – Channel number of the channel whose count rate will control the trigger channels.

• reference_countrate – The reference count rate in Hz that separates the above range from the below range.

• hysteresis – The threshold count rate in Hz for transitioning to the above threshold state is countrate \>= reference_countrate + hysteresis, whereas it is countrate \<= reference_countrate - hysteresis for transitioning to the below threshold state. The hysteresis avoids the emission of multiple trigger tags upon a single transition.

• time_window – Rolling time window size in picoseconds. The count rate is analyzed within this time window and compared to the threshold count rate.

channel_t getChannelAbove()

Get the channel number of the above channel.

channel_t getChannelBelow()

Get the channel number of the below channel.

channel_t[] getChannels()

Get both virtual channel numbers: [getChannelAbove(), getChannelBelow()].

float getCurrentCountrate()

Get the current count rate averaged within the time_window.

bool injectCurrentState()

Emits a time tag into the respective channel according to the current state. This is useful if you start a new measurement that requires the information. The function returns whether it was possible to inject the event. The injection is not possible if the Time Tagger is in overflow mode or the time window has not passed yet. The function call is non-blocking.

bool isAbove()

Returns whether the Virtual Channel is currently in the above state.

bool isBelow()

Returns whether the Virtual Channel is currently in the below state.