qmi.instruments.picoquant.hydraharp

QMI instrument driver for the PicoQuant HydraHarp 400 instrument.

The instrument driver makes use of the manufacturer provided software libraries, “hhlib.so” for Linux OS, or “hhlib.dll” or “hhlib64.dll” for 32-bit and 64-bit Windows OS, respectively. Please find the licence terms for these files in the dedicated software package for the HydraHarp instrument at https://www.picoquant.com/products/category/tcspc-and-time-tagging-modules/hydraharp-400-multichannel-picosecond-event-timer-tcspc-module –> “Software” tab –> download link in “Current software and developer’s library version”.

Classes

PicoQuant_HydraHarp400(context, name, ...[, ...])

Instrument driver for the PicoQuant HydraHarp 400.

class qmi.instruments.picoquant.hydraharp.PicoQuant_HydraHarp400(context: QMI_Context, name: str, serial_number: str, max_pending_events: int = 100000000)

Instrument driver for the PicoQuant HydraHarp 400.

clear_histogram_memory() → None

Reset the histogram state to all-zeros.

Clear the histogram memory of all channels. Only meaningful in histogramming mode.

Raises:: QMI_InstrumentException – in case of a library error.

close() → None

Close the device.

Stops the background event fetching thread and closes the underlying device.

force_unlock() → None

Forcefully unlock the remote object.

This unlocks the object, regardless of who owns the lock. This allows you to unlock an object if the locking proxy has been destroyed without unlocking.

Use this with care.

Do not override this stub method in subclasses. It has already been implemented in QMI_RpcProxy.

get_all_histograms() → ndarray

Get histogram data array from a specific channel. The multidimensional array receiving the data must be: shaped according to the number of input channels of the device and the chosen histogram length.

Returns:: Histogram data arrays of all channels.
Raises:: QMI_InstrumentException – in case of a library error.

get_base_resolution() → tuple[float, int]

Get the resolution and binsteps of the device.

Returns:: A tuple (resolution, binsteps) where resolution (float) is the base resolution in picoseconds; binsteps (int) is the number of allowed binning steps.

classmethod get_category() → str | None

Return the optional name of the category this object belongs to.

A category name is a free-form string that has no special significance. Its purpose is to distinguish between groups of RPC objects that fulfill similar roles.

get_count_rate(channel: int) → int

Return input channel rate in events per second (determined every 100 ms).

Allow at least 100 ms after initialize() to get a stable rate meter reading. Similarly, wait at least 100 ms to get a new reading (100 ms is the gate time of the counter).

Parameters:: channel – Channel index (range from 0 to number_of_channels - 1).
Returns:: Channel event rate in events per second.
Raises:: QMI_InstrumentException – in case of a library error.

get_debug_info() → str

Get debugging info of the device.

Call this immediately after receiving an error from any library call or after detecting a SYSERROR from get_flags. In case of SYSERROR, please provide this information to support.

Returns:: A debug info string (65,655 characters, max).
Raises:: QMI_InstrumentException – in case of a library error.

get_elapsed_measurement_time() → float

Get elapsed measurement time.

Obtain the elapsed measurement time of a measurement. This relates to the current measurement when still running or to the previous measurement when already finished.

Returns:: The elapsed measurement time, in [ms].
Raises:: QMI_InstrumentException – in case of a library error.

get_error_string(error_code: int) → str

Get the error string for an error code number.

Inputs:: error_code: The error code number to be translated

Returns:: Error code’s description string.

get_events() → ndarray

Return events recorded by the instrument in T2 or T3 mode.

While a measurement is active, a background thread continuously reads event records from the instrument and stores the events in a buffer. This method takes all pending events, removes them from the buffer and returns them.

Events are returned as an array of event records. Each event record contains two fields: | type (uint8): The channel index where the event was recorded, or 64 for a SYNC event. | timestamp (uint64): Event timestamp as a multiple of the instrument base resolution.

This method may only be used in T2 or T3 mode.

Returns:: Numpy array containing event records.

get_features() → list[str]

Get device features.

This function is usually not needed by the user. It is mainly for integration in PicoQuant system software such as SymPhoTime in order to figure out in a standardized way the capabilities the device has.

Note

This function can only be used after the initialize() method was successfully called.

Returns:: A list of strings, each describing a feature of the device.
Raises:: QMI_InstrumentException – in case of a library error.

get_hardware_info() → tuple[str, str, str]

Get model, part nr, and version of the device.

Note

This function can only be used after the initialize() method was successfully called.

Returns:: A 3-tuple of consisting of (model, partno, version) strings.
Raises:: QMI_InstrumentException – in case of a library error.

get_histogram(channel: int, clear: int | None = None) → ndarray

Get histogram data array from a specific channel. Note that MH_GetHistogram cannot be used with the shortest two histogram lengths of 1024 and 2048 bins. You need to use MH_GetAllHistograms in this case.

Parameters:

channel – Channel index (range from 0 to number_of_channels - 1).
clear – Optional input for HydraHarp only: 0 = keep histogram in buffer, 1 = clear buffer

Returns:

Histogram data array for given input channel.

Raises:

QMI_InstrumentException – in case of a library error.

get_measurement_active() → bool

Check if measurement is active.

This method will return False if a measurement has expired on its own, even if the method stop_measurement() has not yet been called.

Returns:

True - acquisition time still running.

False - acquisition time has ended.

Raises:

QMI_InstrumentException – in case of a library error.

get_measurement_start_time() → float

Return the approximate POSIX timestamp of the start of the current measurement.

The returned timestamp is based on the computer system clock. Its accuracy depends on the latency of USB communication with the instrument, process scheduling delay and the accuracy of the system clock.

Returns:: POSIX timestamp as a floating point number

get_name() → str

Return the name of this object.

Returns:: name attribute.

get_number_of_input_channels() → int

Get number of input channels of the device.

Note

This function can only be used after the initialize() method was successfully called.

Returns:: Number of input channels. When a channel index is passed to another method of this driver, the valid range of channel index is from 0 to number_of_channels - 1.
Raises:: QMI_InstrumentException – in case of a library error.

get_resolution() → float

Get time resolution.

Returns:: The resolution at the current binning (histogram bin width) as a float, in [ps]. Not meaningful in T2 mode.
Raises:: QMI_InstrumentException – in case of a library error.

get_serial_number() → str

Get the device serial number.

Note

This function can only be used after the initialize() method was successfully called.

Returns:: The serial number for example ‘1035683’.
Raises:: QMI_InstrumentException – in case of a library error.

get_signals() → list[SignalDescription]

Return a list of signals that can be published by this object.

Returns:: List consisting of qmi_signals attributes.

get_sync_period() → float

Get the sync period.

This method only gives meaningful results while a measurement is running and after two sync periods have elapsed. The return value is undefined in all other cases. Resolution is that of the device’s base resolution. Accuracy is determined by single shot jitter and clock stability.

Returns:: The sync period in [s].
Raises:: QMI_InstrumentException – in case of a library error.

get_sync_rate() → int

Return SYNC rate in events per second (determined every 100 ms).

Allow at least 100 ms after initialize() or setSyncDivider() to get a stable rate meter reading. Similarly, wait at least 100 ms to get a new reading (100 ms is the gate time of the counter).

Returns:: Sync event rate in events per second.
Raises:: QMI_InstrumentException – in case of a library error.

get_timestamped_events() → tuple[float, ndarray]

Return events recorded by the instrument in T2 or T3 mode.

While a measurement is active, a background thread continuously reads event records from the instrument and stores the events in a buffer. This method takes all pending events, removes them from the buffer and returns them.

Events are returned as an array of event records. Each event record contains two fields: | type (uint8): The channel index where the event was recorded, or 64 for a SYNC event. | timestamp (uint64): Event timestamp as a multiple of the instrument base resolution.

This method may only be used in T2 or T3 mode.

Returns:: Tuple (timestamp, events) where timestamp is the approximate wall-clock time where the last event record was received, and events is a Numpy array containing the event records.

get_warnings_text(warnings: int) → str

Translates warnings into human-readable text.

Parameters:: warnings – integer bitfield obtained from MH_GetWarnings
Returns:: The warning text string.
Raises:: QMI_InstrumentException – in case of a library error.

is_locked() → bool

Query if the remote object is locked.

Do not override this stub method in subclasses. It has already been implemented in QMI_RpcProxy.

is_open() → bool: Return True if the instrument is open (ready for interaction).

lock(timeout: float = 0.0, lock_token: str | None = None) → bool

Lock the remote object. If timeout is given, try every 0.1s within the given timeout value. The remote object can be locked with an optional custom lock token by giving a string into lock_token keyword argument.

If successful, this proxy is the only proxy that can invoke RPC methods on the remote object; other proxies will receive an “object is locked” response. The return value indicates if the lock was granted; a denied lock means the object was already locked by another proxy.

Do not override this stub method in subclasses. It has already been implemented in QMI_RpcProxy.

open() → None

Open the device.

This method also starts a background thread which will be responsible for fetching event data from the instrument.

release_rpc_object() → None: Give a warning if the instrument is removed while still open.

set_binning(binning: int) → None

Set time binning.

Parameters:

binning –

the following values can be used:

= 1× base resolution,
= 2× base resolution,
= 4× base resolution,
= 8× base resolution, and so on.

Range is 0 to (BINSTEPSMAX - 1).

Raises:

QMI_InstrumentException – in case of a library error.

set_block_events(blocked: bool) → None

Enable or disable blocking event data.

This feature can be used to “pause” the event data stream. The instrument will continue measuring and tagging events, but all event records will be discarded by the QMI driver.

While events are blocked, the instrument will maintain its time base such that time intervals between events before and after the pause will be correctly represented.

If real-time histograms are enabled, these will still be updated while events are blocked.

This function only affects measurements in T2 mode.

Parameter:: block: True to block all event data, False to resume reporting event data.

set_event_filter(reset_filter: bool = False, channel_filter: dict[int, EventFilterMode] | None = None, sync_aperture: tuple[int, int] | None = None) → None

Configure the event filter.

When measuring in T2 mode, incoming events are passed through a filter to reject uninteresting events. This event filter is implemented in the QMI driver software (not inside the instrument).

The filter is configured separately for each event type. Event types 0 to 7 correspond to the normal input channels. Event type 64 represents SYNC events.

Each event type can be configured either to reject all events (EventFilterMode.NO_EVENTS), or to accept all events (EventFilterMode.ALL_EVENTS) or to accept only events that occur within a specific time window after a SYNC event (EventFilterMode.APERTURE).

If EventFilterMode.APERTURE is selected for the SYNC channel, the filter accepts only the SYNC events that are either preceded or followed by a non-SYNC events. This mode can be used to discard redundant SYNCs when nothing interesting is happening.

Parameters:

reset_filter – Configure the filter so that all normal events and SYNC events are accepted.
channel_filter – Mapping from event type to the new event filter mode to be configured. Any event types not specified in the mapping are left in their current setting.
sync_aperture – Tuple (delta_min, delta_max) in multiples of the instrument base resolution, defining a time window following each SYNC event. If unspecified or None, the current aperture setting is left unchanged.

set_histogram_length(lencode: int) → int

Set the length of the histogram.

Set the number of bins of the collected histograms. The histogram length is 65536 which is also the default after initialization if set_histogram_length is not called.

Parameters:: lencode – The histogram length code requesting a histogram of (1024 * 2**`lencode`) bins. Valid range is from 0 to 6.
Returns:: The current length (time bin count) of histograms calculated as (1024 * 2**`lencode`).
Raises:: QMI_InstrumentException – in case of a library error.

set_input_channel_enable(channel: int, enable: bool) → None

Enable or disable the input channel.

Parameters:

channel – Channel index (range from 0 to number_of_channels - 1).
enable – True to enable the channel, False to disable.

Raises:

QMI_InstrumentException – in case of a library error.

set_input_channel_offset(channel: int, value: int) → None

Set input channel offset.

This is equivalent to changing the cable delay on the chosen input. Actual resolution is the device’s base resolution.

Parameters:

channel – Channel index (range from 0 to number_of_channels - 1).
value – channel offset, in [ps]. A value ranging from -99999 ps to +99999 ps.

Raises:

QMI_InstrumentException – in case of a library error.

set_marker_edges(me0_str: str, me1_str: str, me2_str: str, me3_str: str) → None

Set marker edges.

Change the active edge on which the external TTL signals connected to the marker inputs are triggering. Only meaningful in TTTR mode.

Parameters:

me0_str (str) – edge of marker signal 0.
me1_str (str) – edge of marker signal 1.
me2_str (str) – edge of marker signal 2.
me3_str (str) – edge of marker signal 3.

Raises:

QMI_InstrumentException – in case of a library error.

set_marker_enable(en0: bool, en1: bool, en2: bool, en3: bool) → None

Set marker enable.

Used to enable or disable the external TTL marker inputs. Only meaningful in TTTR mode.

Parameters:

en0 – edge of marker signal 0.
en1 – edge of marker signal 1.
en2 – edge of marker signal 2.
en3 – edge of marker signal 3.

Raises:

QMI_InstrumentException – in case of a library error.

set_marker_holdoff_time(holdofftime: int) → None

Set marker hold-off time.

Parameters:: holdofftime – hold-off time in [ns]. Ranges from 0 ns 25500 ns.
Raises:: QMI_InstrumentException – in case of a library error.

set_offset(offset: int) → None

Set time offset.

This offset only applies in histogramming and T3 mode. It affects only the difference between stop and start before it is put into the T3 record or is used to increment the corresponding histogram bin.

It is intended for situations where the range of the histogram is not long enough to look at “late” data. By means of the offset the “window of view” is shifted to a later range.

This is not the same as changing or compensating cable delays. If the latter is desired, use setSyncChannelOffset() and/or setInputChannelOffset().

Parameters:: offset – time offset in [ns], ranging from 0 ns to 100000000 ns.
Raises:: QMI_InstrumentException – in case of a library error.

set_realtime_countrate(sync_aperture: tuple[int, int], num_sync: int) → None

Configure real-time count rate reporting.

When measuring in T2 mode, the driver can optionally report real-time count rates. Events that fall in a specific time window after the SYNC pulse are counted. This counter is integrated during several SYNC periods. After a configurable number of SYNC events, the integrated counter values are published via sig_countrate.

Parameters:

sync_aperture – Tuple (delta_min, delta_max) as a multiple of the instrument base resolution, defining a time window after each SYNC pulse.
num_sync – Number of SYNC periods to integrate before publishing the counter value. Specify 0 to disable the real-time countrate monitoring.

set_realtime_histogram(channels: list[int], bin_resolution: int, num_bins: int, num_sync: int) → None

Configure real-time histograms.

When measuring in T2 mode, the driver can optionally report real-time histograms. Each received event is assigned to a histogram bin based on the time interval between the last SYNC and the event. The histogram is integrated during several SYNC periods. After a configurable number of SYNC events, the integrated histogram is published via sig_histogram.

Parameters:

channels – List of channels to include in the histogram (range 0 to 7).
bin_resolution – Resolution of each histogram bin as a multiple of the instrument base resolution.
num_bins – Number of bins in the histogram (determines the maximum time interval after SYNC).
num_sync – Number of SYNC periods to integrate before publishing the histogram. Specify 0 to disable real-time histograms.

set_stop_overflow(stop_ovfl: bool, stopcount: int) → None

Set stop overflow count value.

This setting determines if a measurement run will stop if any channel reaches the maximum set by the stopcount parameter.

If stop_ovfl is False, the measurement will continue but counts above STOPCNTMAX in any bin will be clipped.

Parameters:

stop_ovfl – If true, the measurement will stop once the limit is reached. If not, the measurement will continue.
stopcount – 1 to 4294967295.

Raises:

QMI_InstrumentException – in case of a library error.

set_sync_divider(divider: int) → None

Set the SYNC divider value.

The sync divider must be used to keep the effective sync rate at values < 78 MHz. It should only be used with sync sources of stable period.

Using a larger divider than strictly necessary does not do great harm but it may result in slightly larger timing jitter.

The readings obtained with get_count_rate() are internally corrected for the divider setting and deliver the external (undivided) rate. The sync divider should not be changed while a measurement is running.

Parameters:: divider – value ranging from 1 to 16.
Raises:: QMI_InstrumentException – in case of a library error.

set_sync_offset(sync_offset: int) → None

Set SYNC offset.

This function can replace an adjustable cable delay. A positive offset corresponds to inserting a cable in the sync input.

Parameters:: sync_offset – SYNC offset, in [ps]. A value ranging from -99999 ps to +99999 ps.
Raises:: QMI_InstrumentException – in case of a library error.

set_trigger_output(period: int) → None

Set trigger output.

Set the period of the programmable trigger output. The period 0 switches it off.

Parameters:: period – Period in units of 100 ns range is 0 to 16777215.
Raises:: QMI_InstrumentException – in case of a library error.

start_measurement(tacq: int) → None

Start a measurement.

Parameters:: tacq – acquisition time, in [ms], ranging from 1 to 360000000; corresponding to 100 hours)
Raises:: QMI_InstrumentException – in case of a library error.

stop_measurement() → None

Stop a running measurement.

This call can be used to force a stop before the acquisition time expires.

Important

For cleanup purposes, this must be called after a measurement, even if the measurement has expired on its own!

Raises:: QMI_InstrumentException – in case of a library error.

unlock(lock_token: str | None = None) → bool

Unlock the remote object.

Without optional parameters, this is only allowed by the proxy that initially locked the object. By giving the lock token as an input parameter, the specific object locked by this token can be unlocked. The return value indicates if the unlocking was successful.

Do not override this stub method in subclasses. It has already been implemented in QMI_RpcProxy.

initialize(mode_str: str, refsource_str: str) → None

Initialize the device.

This routine must be called before any of the other methods, except OpenDevice, CloseDevice, GetErrorString and GetLibraryVersion can be used.

Parameters:

mode_str (str) – Opening mode. Can be any of ‘HIST’, ‘T2’, ‘T3’, ‘CONT’. The latest driver version V3.0+ supports T2, T3 and CONT modes.
refsource_str (str) – Reference source for time. Can be any of ‘INTERNAL’, ‘EXTERNAL’.

Raises:

ValueError – if either argument is an unknown string value.
QMI_InstrumentException – in case of a library error.

get_module_info() → list[tuple[int, int]]

Get the model and version codes of all modules of the device.

Note

This function can only be used after the initialize() method was successfully called.

Returns:: List of tuples (modelcode, versioncode). This information may be needed for support queries. The meaning of these numbers is not documented.
Raises:: QMI_InstrumentException – in case of a library error.

set_sync_channel_offset(value: int) → None

Set SYNC channel offset.

This is equivalent to changing the cable delay on the sync input. Actual resolution is the device’s base resolution.

Parameters:: value – SYNC channel offset, in [ps]. A value ranging from -99999 ps to +99999 ps.
Raises:: QMI_InstrumentException – in case of a library error.

set_measurement_control(meascontrol_str: str, startedge_str: str, stopedge_str: str) → None

Set the measurement control mode.

This must be called before starting a measurement. The default after initialization (if this function is not called) is 0, i.e., software controlled acquisition time. The other modes 1..5 allow hardware triggered measurements through TTL signals at the control port or through White Rabbit. Note that this needs custom software.

Parameters:

meascontrol_str – Measurement control code. Any of ‘SINGLESHOT_CTC’, ‘C1_GATED’, ‘C1_START_CTC_STOP’, ‘C1_START_C2_STOP’, ‘WR_M2S’, ‘WR_S2M’.
startedge_str – Start edge selection. Either ‘RISING’ or ‘FALLING’.
stopedge_str – Stop edge selection. Either ‘RISING’ or ‘FALLING’.

Raises:

QMI_InstrumentException – in case of a library error.

get_flags() → list[str]

Get flags.

Returns:: A list of active flags, represented as short strings. See the definition of the FLAG type for possible values. <xxx> = multi, hydra, pico or time. The meaning of these flags is not fully documented.
Raises:: QMI_InstrumentException – in case of a library error.

get_warnings() → list[str]

Get a list of warnings.

Returns:: A list of strings. See the definition of the WARNING type for possible values. <xxx> = multi, hydra, pico or time.
Raises:: QMI_InstrumentException – in case of a library error.

calibrate() → None

Calibrate the <xxx>Harp instrument. <xxx> = Hydra, Pico

This method should be called before starting a measurement.

Calibrates the time measurement circuits. This is necessary whenever temperature changes > 5 K occurred. Calibrate after warming up of the instrument before starting serious measurements. Warming up takes about 20 to 30 minutes dependent on the lab temperature. It is completed when the cooling fan starts to run for the first time. Calibration takes only a few seconds. Calibration is only important for serious measurements. You can use the instrument during the warming-up period for set–up and preliminary measurements. For very long measurements, allow some more time for thermal stabilization, calibrate immediately before the measurement commences and try to maintain a stable room temperature during the measurement. The permissible ambient temperature is 15°C to 35 °C. Do not obstruct the cooling fan at the back and the air inlets at the bottom of the housing.

set_sync_cfd(level: int, zc: int) → None

Set Constant Fraction Discriminator (CFD) levels for SYNC input.

Notes

The values are given as a positive numbers although the electrical signals are actually negative.

Parameters:

level – CFD discriminator level in millivolts (mV) range 0 to 1000 representing 0 to -1000 mV.
zc – CFD zero cross level in millivolts (mV). range 0 to 40 mV representing 0 to 40 mV.

set_input_cfd(channel: int, level: int, zc: int) → None

Set Constant Fraction Discriminator (CFD) levels for input channel.

Parameters:

channel – Channel index (range from 0 to number_of_channels - 1).
level – CFD discriminator level in millivolts (mV) range 0 to 1000 representing 0 to -1000 mV.
zc – CFD zero cross level in millivolts (mV). range 0 to 40 mV representing 0 to 40 mV.