Helper classes

CustomMeasurement

class CustomMeasurement(tagger)

Python and C# wrapper for CustomMeasurementBase.

Parameters:

tagger (TimeTaggerBase) – Time Tagger object instance.

process(incoming_tags, begin_time, end_time)

Override this method to implement the measurement logic. The method is called whenever a new chunk of time tags is available.

Parameters:

  • incoming_tags – Chunk of incoming time tags for this call.

  • begin_time (int) – Begin timestamp of the processed chunk.

  • end_time (int) – End timestamp of the processed chunk.

This method is executed on the Time Tagger backend thread and is the performance-critical part of a custom measurement. The incoming_tags buffer is only valid during the current call and may be overwritten by the next one. If you need to store tags, create a copy. In Python, it is usually advisable to use numpy.array() and vectorized NumPy operations, or compiled code such as Numba if explicit iteration over the tags is required.

Note

In Python, the incoming_tags are a structured Numpy array. You can access single tags as well as arrays of tag entries directly:

first_tag = incoming_tags[0]
all_timestamps = incoming_tags['time']
mutex

Context manager object (see Context Manager Types) that locks the mutex when used and automatically unlocks it when the code block exits. For example, it is intended for use with Python’s “with” keyword as

class MyMeasurement(CustomMeasurement):

    def getData(self):
        # Acquire a lock for this instance to guarantee that
        # self.data is not modified in other parallel threads.
        # This ensures to return a consistent data.
        with self.mutex:
            return self.data.copy()

Note

You can find an example of how to use the CustomMeasurement in the installation folder. Further custom measurement examples are available in the Time-Tagger-Custom-Measurements repository.

class CustomMeasurementBase : public IteratorBase

Base class for implementing custom measurements in C++, C#, and Python.

This helper class provides low-overhead access to the raw time tag stream and can be used to implement custom measurement logic in wrapper languages.

Typical usage:

  • derive a custom measurement class,

  • register all channels that should be forwarded to the measurement,

  • call finalize_init() once construction is complete,

  • implement the processing callback.

The processing callback is executed on the Time Tagger backend thread. Therefore, it should return quickly and avoid unnecessary overhead.

See all common methods

Public Functions

void register_channel(channel_t channel)

Registers a channel whose tags should be forwarded to this measurement.

Parameters:

channel – Channel number to register.

void unregister_channel(channel_t channel)

Unregisters a previously registered channel.

Parameters:

channel – Channel number to unregister.

void finalize_init()

Finalizes the initialization of the measurement.

Call this after all required channels have been registered and the custom measurement object has been fully constructed.

bool is_running()

Returns whether the measurement is currently running.

Returns:

true if the measurement is running, otherwise false.

Public Static Functions

static void stop_all_custom_measurements()

Stops all currently running custom measurements.

This can be used during shutdown of the target language runtime to avoid races with still active custom measurement callbacks.

SynchronizedMeasurements

class SynchronizedMeasurements

The SynchronizedMeasurements class allows for synchronizing multiple measurement classes in a way that ensures all these measurements to start, stop simultaneously and operate on exactly the same time tags. You can pass a Time Tagger proxy-object returned by getTagger() to every measurement you create. This will simultaneously disable their autostart and register for synchronization.

Public Functions

SynchronizedMeasurements(TimeTaggerBase tagger)
Parameters:

tagger – The time tagger object instance.

TimeTaggerBase getTagger()

Returns a proxy tagger object which can be passed to the constructor of a measurement class to register the measurements at initialization to the synchronized measurement object. Those measurements will not start automatically.

Note

The proxy tagger object returned by getTagger() is not identical with the TimeTagger object created by createTimeTagger(). You can create synchronized measurements with the proxy object the following way: 

tagger = TimeTagger.createTimeTagger()
syncMeas = TimeTagger.SynchronizedMeasurements(tagger)
taggerSync = syncMeas.getTagger()
counter = TimeTagger.Counter(taggerSync, [1, 2])
countrate = TimeTagger.Countrate(taggerSync, [3, 4])
Passing tagger as a constructor parameter would lead to the not synchronized behavior.

void start()

Calls IteratorBase::start() for every registered measurement in a synchronized way.

void startFor(timestamp_t capture_duration, bool clear = true)

Calls IteratorBase::startFor() for every registered measurement in a synchronized way.

Parameters:

  • capture_duration – Acquisition duration in picoseconds.

  • clear – Resets the accumulated data at the beginning (default: True).

void stop()

Calls IteratorBase::stop() for every registered measurement in a synchronized way.

void clear()

Calls IteratorBase::clear() for every registered measurement in a synchronized way.

bool waitUntilFinished(int timeout = -1)

Equivalent to IteratorBase::waitUntilFinished() for synchronized measurements.

Parameters:

timeout – Timeout in milliseconds. Negative value means no timeout, zero returns immediately.

Returns:

True if the synchronized measurements have finished, False on timeout.

bool isRunning()

Calls IteratorBase::isRunning() for every registered measurement and returns true if any measurement is running.

void registerMeasurement(IteratorBase measurement)

Registers the measurement object into a pool of the synchronized measurements.

Note

Registration of the measurement classes with this method does not synchronize them. In order to start/stop/clear these measurements synchronously, call these functions on the SynchronizedMeasurements object after registering the measurement objects, which should be synchronized.

Parameters:

measurement – Any measurement (IteratorBase) object.

void unregisterMeasurement(IteratorBase measurement)

Unregisters the measurement object out of the pool of the synchronized measurements.

Note

This method does nothing if the provided measurement is not currently registered.

Parameters:

measurement – Any measurement (IteratorBase) object.