pulsed module#

Pulse-based experiment design and measurement.

Detailed information is provided in the documentation for each class.

`Pulsed`	Use the hardware in pulsed mode.
`LongDrive`	Container for a long drive.
`Event`	Container for hardware events.
`Template`	An output pulse event.
`Match`	A template-matching event.
`MeasurementHandle`	Handle to a running measurement.
`MeasurementStatus`	Enumeration for current status of the measurement

Module constants:

presto.pulsed.MAX_LUT_ENTRIES: int = 512#

maximum length of frequency/phase and scale look-up tables

presto.pulsed.MAX_COMMANDS: int = 10736#

maximum number of commands (trigger events) in an experiment sequence

presto.pulsed.MAX_STORE_LEN: int = 1048576#

maximum number of samples in a contiguous acquisition window (store())

presto.pulsed.MAX_TEMPLATE_LEN: int = 2044#

maximum number of data points in a single template slot in direct mode. See also get_max_template_len()

presto.pulsed.MAX_THRESHOLD: float = 8590458904.000975#

maximum threshold/result value for a template match()

Pulsed class#

class presto.pulsed.Pulsed(ext_ref_clk=False, force_reload=False, dry_run=False, address=None, port=None, adc_mode=AdcMode.Direct, adc_fsample=None, dac_mode=DacMode.Direct, dac_fsample=None, force_config=False)#

Use the hardware in pulsed mode.

Warning

Create only one instance at a time. Use each instance for only one measurement. This class is designed to be instantiated with Python’s with statement, see Examples section.

Parameters:

ext_ref_clk (Union[None, bool, int, float]) – if None or False use internal reference clock; if True use external reference clock (10 MHz); if float or int use external reference clock at ext_ref_clk Hz
force_reload (bool) – if True re-configure clock and reload firmware even if there’s no change from the previous settings.
dry_run (bool) – if True don’t connect to hardware, for testing only.
address (Optional[str]) – IP address or hostname of the hardware. If None, use factory default "192.168.42.50".
port (Optional[int]) – port number of the server running on the hardware. If None, use factory default 7878.
adc_mode (AdcMode or list) – configure the inputs to sample in direct mode (default), or to use the digital mixers for downconversion. See Notes.
adc_fsample (AdcFSample or list) – configure the inputs sampling rate. If None (default), choose optimal rate automatically. See Notes.
dac_mode (DacMode or list) – configure the outputs to work in direct mode (default), or to use the digital mixers for upconversion. See Notes.
dac_fsample (DacFSample or list) – configure the outputs sampling rate. If None (default), choose optimal rate automatically. See Notes.
force_config (bool) – if True skip checks on DacModes not recommended for high DAC sampling rates.

Raises:

ValueError – if adc_mode or dac_mode are not valid Converter modes; if adc_fsample or dac_fsample are not valid Converter rates.

Notes

In all the Examples, it is assumed that the imports import numpy as np and from presto import pulsed have been performed, and that this class has been instantiated in the form pls = pulsed.Pulsed(), or, much much better, using the with pulsed.Pulsed() as pls construct as below.

For an introduction to adc_mode and dac_mode, see Direct and Mixed mode. For valid values of adc_mode and dac_mode, see Converter modes. For valid values of adc_fsample and dac_fsample, see Converter rates. For advanced configuration, e.g. different converter rates on different ports, see Advanced tile configuration.

Examples

Output a 2 ns pulse on output port 1 every 100 μs, and sample 1 μs of data from input port 1. Repeat 10 times, average 10k times.

>>> from presto import pulsed
>>> with pulsed.Pulsed() as pls:
>>>     pls.set_store_ports(1)
>>>     pls.set_store_duration(1e-6)
>>>     pulse = pls.setup_template(
>>>         output_port=1,
>>>         group=0,
>>>         template=np.ones(4),
>>>     )
>>>     pls.output_pulse(0.0, pulse)
>>>     pls.store(0.0)
>>>     pls.run(
>>>         period=100e-6,
>>>         repeat_count=10,
>>>         num_averages=10_000,
>>>         print_time=True,
>>>     )
>>>     t_arr, data = pls.get_store_data()
connecting to 192.168.42.50 port 7878
Expected runtime: 10.0s
Total time: 10.2s
Transfering data: 3.0ms

close()#

Gracely disconnect from the hardware.

Call this method if the class was instantiated without a with statement. This method is called automatically when exiting a with block and before the object is destructed.

get_clk_T()#

Period of the programmable logic clock in seconds.

This is also the granularity of the time grid for defining events in the experiment sequence.

Return type:: float

get_clk_f()#

Frequency of the programmable logic clock in Hz.

Return type:: float

get_fs(which)#

Get sampling frequency for which converter in Hz.

Parameters:: which (str) – "adc" for input and "dac" for output.
Raises:: ValueError – if which is unknown.
Return type:: float

get_histogram_data()#

Obtain from hardware the result of the sparse real-time histogram.

Only valid after the measurement is performed.

Return type:

dict

Returns:

a dictionary with the following keys defined.

For a 1D histogram:

"bins" (ndarray, dtype=np.float64): left-hand edges of the
histogram bins
"counts" (ndarray, dtype=np.int64): the values (counts) of the
histogram

For a 2D histogram:

"bins_x" (ndarray, dtype=np.float64): left-hand edges of the
histogram bins along the x axis
"bins_y" (ndarray, dtype=np.float64): left-hand edges of the
histogram bins along the y axis
"counts" (ndarray, dtype=np.int64): the values (counts) of the
histogram

Note

histogram bins are not sorted and sparse, i.e. bins with no counts are not returned

Raises:

RuntimeError – If no template-matching data is available.
TypeError – If input_pairs contains unrecognized objects.

Examples

Get and plot histogram data:

>>> hist = pls.get_histogram_data()
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> ax.plot(hist["bins"], hist["counts"], '.')
>>> fig.show()

Sort histogram data:

>>> hist = pls.get_histogram_data()
>>> idx = np.argsort(hist["bins"])
>>> bins_sorted = hist["bins"][idx]
>>> counts_sorted = hist["counts"][idx]

get_max_template_len()#

Maximum number of data points in a single template slot.

Equal to MAX_TEMPLATE_LEN when in direct mode (dac_mode is DacMode.Direct), and half of it when using digital upconversion (dac_mode is one of DacMode.Mixedxx).

Return type:: int

get_nr_ports()#

The number of available input/output ports in the hardware.

Return type:: int

get_store_data(use_compression=False)#

Obtain from hardware the result of the (averaged) stores.

Only valid after the measurement is performed.

Parameters:

use_compression (bool) – if True, use lossless compression when downloading measurement data. See Notes section below.

Return type:

Tuple[ndarray, ndarray]

Returns:

A tuple of (t_arr, data) where

t_arr (ndarray): The time axis in seconds during one acquisition. dtype is float.
data (ndarray): The acquired data with get_fs("adc") sample rate and scaled to +/-1.0 being full-scale input. The shape of the array is (num_stores * repeat_count, num_ports, smpls_per_store), where num_stores is number of store events programmed in a sequence with the store() method, num_ports is the number of inputs ports set with set_store_ports(), and smpls_per_store is the number of samples in one acquisition set by set_store_duration().

Notes

When using digital downconversion (adc_mode=AdcMode.Mixed), the returned data is complex (dtype=np.complex128); in direct mode (adc_mode=AdcMode.Direct) data is real (dtype=np.float64).

Using lossless compression when downloading measurement data (compression=True) requires the third-party Python package lz4 which can be installed from PyPI with pip install lz4 or from Anaconda with conda install lz4.

Raises:

RuntimeError – If no store data is available.
ImportError – if the Python package lz4 is not installed when using compression=True, see Notes section above.

See also

store() run()

get_template_matching_data(input_pairs, use_compression=False)#

Obtain from hardware the result of the template matching.

Only valid after the measurement is performed.

Parameters:

input_pairs (Union[Match, List[Match]]) – One or more template-matching pairs as defined by setup_template_matching_pair().
use_compression (bool) – if True, use lossless compression when downloading measurement data. See Notes section below.

Return type:

List[ndarray]

Returns:

A list ret where, for each element (input template) of input_pairs, ret contains a numpy.ndarray with the template-matching results for that template. Therefore, len(input_pairs) == len(ret). dtype is float. The data is scaled such that a perfect match of a full-scale cosine over N data samples is 0.5 * N.

Raises:

RuntimeError – If no template-matching data is available.
TypeError – If input_pairs contains unrecognized objects.

hardware: Hardware#: interface to hardware features common to all modes of operation

join()#

match(at_time, match_info)#

Program hardware to perform template matching at given time.

Parameters:

at_time (float) – At what time in seconds the template(s) should be matched. Must be a multiple of get_clk_T()
template_info – The information about one or more template-matching pairs as obtained from setup_template_matching_pair().

Raises:

ValueError – if at_time is not a multiple of get_clk_T()
TypeError – if template_info contains unrecognized objects.

See also

setup_template_matching_pair()

next_frequency(at_time, output_ports, group=None)#

Program the hardware to move to the next frequency/phase at given time.

Parameters:

at_time (float) – At what time in seconds the change should happen. Must be a multiple of get_clk_T()
output_ports (int or array_like) – What output ports should be affected by the change. Valid ports are in the interval [1, get_nr_ports()].
group (int or array_like) – Valid groups are in the interval [0, 1]. If None, move the carrier for both groups to the next entry.

Raises:

ValueError – if at_time is not a multiple of get_clk_T(); if any of output_ports is out of [1, get_nr_ports()]; if group is out of [0, 1].

See also

setup_freq_lut() select_frequency()

next_scale(at_time, output_ports, group=None)#

Program the hardware to move to the next output scale at given time.

Parameters:

at_time (float) – At what time in seconds the change should happen. Must be a multiple of get_clk_T()
output_ports (int or array_like) – What output ports should be affected by the change. Valid ports are in the interval [1, get_nr_ports()].
group (int or array_like) – Valid groups are in the interval [0, 1]. If None, move both groups to the next entry.

Raises:

ValueError – if at_time is not a multiple of get_clk_T(); if any of output_ports is out of [1, get_nr_ports()]; if group is out of [0, 1].

See also

setup_scale_lut() select_scale()

output_dc_bias(at_time, bias, port)#

Program hardware to output a DC bias at given time.

Parameters:

at_time (float) – at what time in seconds the bias should be output. Must be a multiple of get_clk_T()
bias (float) – DC bias value in volts.
port (int or array_like) – output port(s) the DC bias should be output from. Valid values are in [1, 16]. See Notes for behavior when more than one port is addressed.

Notes

It is not possible to change the DC range during an experimental sequence. Only the bias value can be changed. It is required to use Hardware.set_dc_bias() to configure the range and the initial DC-bias value for port before programming the experimental sequence. It is also recommended to use Hardware.set_dc_bias() to reset the value to zero after the experiment terminated, i.e. after a call to run().

Updating the DC bias on one port takes 1 μs, during which no other DC bias event should be scheduled. Updating the bias on n ports takes n μs, and all ports will switch to the new value simultaneously.

Raises:

ValueError – if port is out of range; if at_time is not a multiple of get_clk_T(); if bias is larger than the current setting for DC-bias range on port.
RuntimeError – if the DC range for port was not set.

output_digital_marker(at_time, duration, ports)#

Program hardware to output a digital marker at given time.

Parameters:

at_time (float) – at what time in seconds the marker should be output. Must be a multiple of get_clk_T()
duration (float) – for how long in seconds the marker should be output. Must be a multiple of get_clk_T()
port (int or array_like) – digital output port(s) the marker should be output from. Valid values are in [1, 4]

Raises:

ValueError – if ports is out of range; if at_time is not a multiple of get_clk_T()

output_pulse(at_time, pulse_info)#

Program hardware to output pulse(s) at given time.

Parameters:

at_time (float) – at what time in seconds the pulse(s) should be output. Must be a multiple of get_clk_T()
pulse_info (Union[Template, LongDrive, List[Union[Template, LongDrive]]]) – information about one or more pulses as obtained from setup_template() or setup_long_drive()

Raises:

ValueError – if at_time is not a multiple of get_clk_T()
TypeError – if pulse_info contains unrecognized objects

perform_measurement(*args, **kwargs)#: Deprecated since version 2.0.0: Use run() instead.

reset_phase(at_time, output_ports, group=None)#

Program the hardware to reset the phase of group at given time.

The phase will be reset to the current entry of the frequency/phase look-up table.

Parameters:

at_time (float) – at what time in seconds the pulse(s) should be output. Must be a multiple of get_clk_T()
output_ports (int or array_like) – what output ports should be affected by the reset. Valid ports are in the interval [1, get_nr_ports()].
group (int or array_like) – valid groups are in the interval [0, 1]. If None, reset the phase of both groups.

Raises:

ValueError – if at_time is not a multiple of get_clk_T(); if any of output_ports is out of [1, get_nr_ports()]; if index is out of [0, MAX_LUT_ENTRIES - 1]; if group is out of [0, 1].

round_time(t)#

Round t to a multiple of the clock period.

Parameters:: t (float) – time in seconds
Return type:: float
Returns:: the multiple of get_clk_T() that is closest to t

See also

get_clk_T() time_to_clk()

run(period, repeat_count, num_averages, print_time=True, verbose=False, trigger=TriggerSource.Internal, prefetch_matches=False)#

Execute the experiment planned so far. Can be time consuming!

This method will block until the measurement and the data transfer are completed. See run_async() for a non-blocking alternative.

Parameters:

period (float) – Measurement time in seconds for one repetition. Should be long enough to include the last event programmed. If longer, there will be some waiting time between repetitions. Must be a multiple of get_clk_T()
repeat_count (int or tuple of ints) – Number of times to repeat the experiment and stack the acquired data (no averaging). For multi-dimensional parameter sweeps, repeat_count is a tuple where each element specifies the number of repetitions along that axis. Multi-dimensional parameter sweeps are experimental and the API might be fine tuned in a future release.
num_averages (int) – Number of times to repeat the whole sequence (including the repetitions due to repeat_count) and average the acquired data.
print_time (bool) – If True, print to standard output the expected runtime before the experiment, the total runtime after the experiment, and print during the experiment the estimated time left at regular intervals.
verbose (bool) – If True, print debugging information.
trigger (TriggerSource) – Select trigger source to start measurement, default internal trigger (start immediately).
prefetch_matches (bool) – if True, download template-matching results from the hardware as they become available; if False (default), download results only at the end of the experiment.

Raises:

ValueError – if period is negative, too small to fit the last event, or not a multiple of get_clk_T(); if repeat_count is not positive; if num_averages is not positive.
RuntimeError – if the sequence requires more triggers than MAX_COMMANDS; if more than 8 templates/envelopes are used for the same group on the same port.

run_async(period, repeat_count, num_averages, print_time=False, verbose=False, trigger=TriggerSource.Internal, prefetch_matches=False)#

Same as run(), but non blocking. See run for full documentation.

Return type:: MeasurementHandle

select_frequency(at_time, index, output_ports, group=None)#

Program the hardware to select a frequency/phase at given time.

Parameters:

at_time (float) – At what time in seconds the change should happen. Must be a multiple of get_clk_T()
index (int) – Zero-based index in look-up table to select. Valid indexes are in the interval [0, MAX_LUT_ENTRIES - 1].
output_ports (int or array_like) – What output ports should be affected by the change. Valid ports are in the interval [1, get_nr_ports()].
group (int or array_like) – Valid groups are in the interval [0, 1]. If None, select new frequency/phase on both groups.

Raises:

ValueError – if at_time is not a multiple of get_clk_T(); f any of output_ports is out of [1, get_nr_ports()]; if index is out of [0, MAX_LUT_ENTRIES - 1]; if group is out of [0, 1].

See also

setup_freq_lut() next_frequency()

select_scale(at_time, index, output_ports, group=None)#

Program the hardware to select an output scale at given time.

Parameters:

at_time (float) – At what time in seconds the change should happen. Must be a multiple of get_clk_T()
index (int) – Zero-based index in look-up table to select. Valid indexes are in the interval [0, MAX_LUT_ENTRIES - 1].
output_ports (int or array_like) – What output ports should be affected by the change. Valid ports are in the interval [1, get_nr_ports()].
group (int or array_like) – Valid groups are in the interval [0, 1]. If None, select new scale on both groups.

Raises:

See also

setup_scale_lut() next_scale()

set_store_duration(T)#

Set the duration of all data acquisition events.

Parameters:

T (float) – Duration in seconds. Must be a multiple of get_clk_T()

Raises:

ValueError – if T is not a multiple of get_clk_T(); if a store T on all channels configured with set_store_ports() results in an acquisition window with more than MAX_STORE_LEN samples.
RuntimeError – If set_store_ports() was never called before.

See also

set_store_ports() store()

set_store_ports(input_ports)#

Set input port(s) for all store events.

Parameters:: input_ports (int or list of int) – Valid ports are in the interval [1, get_nr_ports()].
Raises:: ValueError – If any of input_ports is out of [1, get_nr_ports()].

setup_condition(input_pairs, output_templates_true, output_templates_false=None)#

Setup a template-matching condition for one or more output pulses.

The pulses in output_templates_true (output_templates_false) will be marked as conditional, and will be output if and only if all the template-matching conditions defined in input_pairs are (not) satisfied.

Parameters:

input_pairs (Match or array_like) – One or more template-matching pairs as defined by setup_template_matching_pair().
output_templates_true (Template, LongDrive or array_like) – Output in case of a successful match comparison. One or more pulses as defined by setup_template() and/or setup_long_drive(). Set to None or to an empty list [] if no pulse is desired.
output_templates_false (Template, LongDrive or array_like) – Output in case of a unsuccessful match comparison. One or more pulses as defined by setup_template() and/or setup_long_drive(). Set to None or to an empty list [] if no pulse is desired (default).

setup_freq_lut(output_ports, group, frequencies, phases, phases_q=None, axis=-1)#

Setup look-up table for frequency generator.

Parameters:

output_ports (int or array_like) – valid ports are in the interval [1, get_nr_ports()].
group (int) – valid groups are in the interval [0, 1].
frequencies (float or array_like) – frequency/ies in Hz for the generator.
phases (float or array_like) – phase(s) in radians for the generator. Must be same length as frequencies. When dac_mode is not DacMode.Direct, this are the phases of the I quadrature to the upconversion digital mixer.
phases_q (float or array_like) – phase(s) in radians for Q quadrature to the upconversion digital mixer. Must be specified if and only if dac_mode is not DacMode.Direct.
axis (int) – For multi-dimensional parameter sweeps, axis over which next_frequency() should increment frequency/phase index. If not given, the last (innermost) axis is used. Multi-dimensional parameter sweeps are experimental and the API might be fine tuned in a future release.

Raises:

ValueError – If any of output_ports is out of [1, get_nr_ports()]; if any of frequencies is out of [0.0, get_fs("dac")); if group is out of [0, 1]; if phases doesn’t have the same shape as frequencies; if the LUTs are longer than MAX_LUT_ENTRIES; if phases_q is specified when not using the digital upconversion mixer (dac_mode=DacMode.Direct); if phases_q is not specified when using the digital upconversion mixer (dac_mode=DacMode.Mixedxx).

See also

next_frequency() select_frequency()

setup_histogram(match)#

Set up the hardware to calculate a sparse histogram in real time.

Results from different template-matching objects are binned separately.

Parameters:

match (Match) – One template-matching object as obtained from setup_template_matching_pair().

Raises:

TypeError – if match is an unrecognized object.
RuntimeError – if another histogram was already set up.

setup_histogram_2d(match_x, match_y)#

Set up the hardware to calculate a sparse 2D histogram in real time.

Results from different template-matching objects are binned separately.

Parameters:

match_x (Match) – A template-matching object for binning in the x coordinate, as obtained from setup_template_matching_pair().
match_x – A template-matching object for binning in the y coordinate

Raises:

RuntimeErrir – if another histogram was already set up.

setup_long_drive(output_port, group, duration, *, amplitude=1.0, amplitude_q=None, rise_time=0.0, fall_time=0.0, envelope=True, output_marker=None)#

Create a long output pulse with constant amplitude.

Useful for using fewer templates.

Parameters:

output_port (int or array_like) – valid ports are in the interval [1, get_nr_ports()].
group (int) – the group to use for this pulse, valid group are in the interval [0, 1].
duration (float) – total length of the pulse in seconds. Must be a multiple of get_clk_T()
amplitude (Union[float, complex]) – amplitude of the flat part of the pulse. Should be real when dac_mode is DacMode.Direct, and complex when using digital upconversion (DacMode.Mixedxx). Alternatively, use parameter amplitude_q.
amplitude_q (Optional[float]) – amplitude of the Q quadrature of the flat part of the pulse. Only used when dac_mode is one of DacMode.Mixedxx. Alternatively, use a complex value for the amplitude argument.
rise_time (float) – smoothen the initial rise_time seconds of the pulse. Must be a multiple of get_clk_T(). See Notes.
fall_time (float) – smoothen the final fall_time seconds of the pulse. Must be a multiple of get_clk_T(). See Notes.
envelope (bool) – If True (default) set up an envelope instead of a template: the envelope will be multiplied by the carrier in group. If False, set up a template: the template will be output as is. In both cases, the resulting waveform will be scaled by the scaler in group.
output_marker (Optional[int]) – output a high value from digital output number output_marker for the duration of the pulse. If None (default), no marker is output. Valid ports are in [1, 4].

Return type:

LongDrive

Returns:

the newly created LongDrive object

Raises:

RuntimeError – If there are not enough templates available for the pair output_port-group.
ValueError – if output_port is out of [1, get_nr_ports()]; if group is out of [0, 1]; if amplitude is out of [-1.0, +1.0]; if duration, rise_time or fall_time are invalid.

Notes

Regardless of duration, only one template is consumed for a flat long drive.

The amplitude of the pulse is affected by the group scaler configured with setup_scale_lut(). The parameter amplitude is applied “in series”.

When rise_time and/or fall_time are nonzero, one additional template is used for each rise and fall segments. The rise and fall times are subtracted from the flat time, so that the total duration of the pulse including transients is duration. The rise and fall shapes are \(\sin(\frac{\pi}{2}x)^2\) and \(\cos(\frac{\pi}{2}x)^2\), respectively, with \(x \in [0, 1)\). The segments rise_time and fall_time are limited to 1022 ns (one template slot each).

See also

setup_template() : create a custom template/envelope. output_pulse() : program hardware to output the generated pulse.

setup_scale_lut(output_ports, group, scales, axis=-1)#

Setup look-up table for global output scale.

Parameters:

output_ports (int or array_like) – Valid ports are in the interval [1, get_nr_ports()].
group (int) – Valid groups are in the interval [0, 1].
scales (float or array_like) – Output scale in ratio of full scale.
axis (int) – For multi-dimensional parameter sweeps, axis over which next_scale() should increment scale index. If not given, the last (innermost) axis is used. Multi-dimensional parameter sweeps are experimental and the API might be fine tuned in a future release.

Raises:

ValueError – If any of output_ports is out of [1, get_nr_ports()]; if any of scales is out of [-1.0, +1.0]; if the LUT is longer than MAX_LUT_ENTRIES; if group is out of [0, 1].

See also

next_scale() select_scale()

setup_template(output_port, group, template, template_q=None, *, envelope=False, output_marker=None)#

Create an output template or envelope.

Parameters:

output_port (int or array_like) – Valid ports are in the interval [1, get_nr_ports()].
group (int) – The group to use for this pulse, valid group are in the interval [0, 1].
template (array_like of float or complex) – Data points for the template/envelope with get_fs("dac") sampling rate. Valid range is [-1.0, +1.0]. Array elements should be real when dac_mode is DacMode.Direct, and complex when using digital upconversion (DacMode.Mixedxx). Alternatively, use parameter template_q.
template_q (array_like of float) – data points for the Q quadrature to the digital upconversion mixer. Only used when dac_mode is one of DacMode.Mixedxx. Alternatively, use elements with complex value for the template argument.
envelope (bool) – If True set up an envelope instead of a template: the envelope will be multiplied by the carrier in group. If False (default), set up a template: the template will be output as is. In both cases, the resulting waveform will be scaled by the scaler in group.
output_marker (Optional[int]) – Output a high value from digital output number output_marker for the duration of the pulse. If None (default), no marker is output. Valid ports are in [1, 4].

Return type:

Template

Returns:

the newly created Template object.

Raises:

RuntimeError – If there are not enough templates available for the pair output_port-group.
ValueError – If any of output_port is out of [1, get_nr_ports()]; if any sample in template is out of [-1.0, +1.0]; if group is out of [0, 1].

Notes

If the length of the pulse is longer than a single template slot (get_max_template_len() samples), the pulse is automatically split into multiple segments of appropriate length. Therefore, the pulse might use more than one template slot.

See also

setup_long_drive(): create a long flat pulse using fewer templates. output_pulse(): program hardware to output the generated template.

setup_template_matching_pair(input_port, template1, template2=None, threshold=0.0, compare_next_port=False)#

Create a pair of input templates for template matching.

The result of template matching can be obtained after the measurement with get_template_matching_data(). The matching also defines a condition that can be used to mask one or more output templates during the measurement with setup_condition(). The template-matching condition is True if the match with template1 plus the match with template2 is greater or equal than threshold, False otherwise.

Parameters:

input_port (int) – valid ports are in the interval [1, get_nr_ports()]. If compare_next_port=True, it must be odd.
template1 (array_like of float or complex) –
template2 (array_like of float or complex) – data points for the templates with get_fs("adc") sampling rate. Valid range is [-1.0, +1.0]. If template2 is not provided, it will be set to all zeros. dtype is float when adc_mode=AdcMode.Direct and complex when adc_mode=AdcMode.Mixed (when using digital downconversion).
threshold (float) – level for discrimination between a successful and failed comparison. The scale is such that a perfect match of a full-scale cosine over N data samples results in 0.5 * N.
compare_next_port (bool) – if True, match template1 from input_port and template2 from input_port+1. If False, match both from input_port.

Return type:

List[Match]

Returns:

a list of newly created Match objects

Raises:

RuntimeError – if there are not enough templates available for input_port.
ValueError – if input_port is out of [1, get_nr_ports()]; if any sample in the templates is out of [-1.0, +1.0]; if the templates are longer than get_max_template_len(); if abs(threshold) is bigger than MAX_THRESHOLD.
NotImplementedError – if the templates have different length.

Notes

To evaluate a match, the input data acquired from port input_port is first multiplied with each template element-wise, and then summed. If the match using template1 plus the match using template2 is greater than or equal to threshold, the match is considered successful.

store(at_time)#

Program hardware to acquire data from the input ports at given time.

Parameters:

at_time (float) – at what time in seconds the acquisition should start. Must be a multiple of get_clk_T()

Raises:

ValueError – if at_time is not a multiple of get_clk_T();
RuntimeError – if the store duration and the input ports have not been set up.

Notes

The input ports and the duration of the acquisition are set up separately, see section See also below.

test1(x)#

test2()#

time_to_clk(t)#

Convert t to an integer number of clock cycles, raising an Exception if rounding is needed.

Parameters:: t (float) – time in seconds
Return type:: int
Returns:: number of clock cycles
Raises:: ValueError – if t is not an integer multiple of get_clk_T(); if t is negative.

See also

round_time() get_clk_T()

LongDrive class#

class presto.pulsed.LongDrive(rise, flat, fall, dig_out, pls)#

Container for a long drive.

The user doesn’t need to instantiate this class in any common situation.

Return type of setup_long_drive(); input type of output_pulse().

get_duration()#

Get the duration of the pulse in seconds.

Includes rise and fall segments. Same as get_total_duration().

Return type:: float

get_events()#

Return type:: List[Event]

get_flat_duration()#

Duration of the flat segment of the pulse in seconds.

Does not include rise and fall segments.

Return type:: float

See also

get_duration() get_total_duration()

get_templates()#

Return a list of the individual templates that make up the long drive.

Return type:: List[RawTemplate]

get_total_duration()#

Total duration of the pulse in seconds.

Includes rise and fall segments. Same as get_duration().

Return type:: float

See also

get_duration() get_flat_duration()

pls()#

Return type:: Pulsed

set_flat_duration(new_duration)#

Update the pulse by changing the duration of the flat part.

Rise and fall times are not affected. The new total duration will be new_duration + rise_time + fall_time.

Parameters:: new_duration (float) – New duration in seconds for the flat part of the long pulse. Must be a multiple of Pulsed.get_clk_T()
Raises:: ValueError – if new_duration is not valid.

set_total_duration(new_duration)#

Update the pulse by changing the total duration of the pulse.

Rise and fall times are not affected. The new duration of the flat part will be new_duration - rise_time - fall_time.

Parameters:: new_duration (float) – New total duration in seconds of the long pulse. Must be a multiple of Pulsed.get_clk_T()
Raises:: ValueError – if new_duration is not valid.

Other Event classes#

class presto.pulsed.Event#

Container for hardware events.

The user doesn’t need to instantiate this class or its derivatives in any common situation.

This is the base class of the return types of many methods of Pulsed.

copy()#

Return a shallow copy of this object.

Return type:: Event

class presto.pulsed.Template(channels, group, envelope, events, pls)#

Bases: Event

An output pulse event.

The user doesn’t need to instantiate this class in any common situation.

Return type of setup_template; input type of output_pulse().

append(evt)#

get_duration()#

Get the duration of the template in seconds.

Return type:: float

get_events()#

Return type:: List[Event]

get_templates()#

Return type:: List[RawTemplate]

pls()#

Return type:: Pulsed

class presto.pulsed.Match(group, index, duration, threshold, cross_group, pls)#

Bases: Event

A template-matching event.

The user doesn’t need to instantiate this class in any common situation.

Return type of setup_template_matching_pair(); input type of match(), get_template_matching_data() and setup_condition().

get_duration()#

Get the duration of the match in seconds.

Return type:: float

pls()#

Return type:: Pulsed

tag()#

Return type:: int

Async types#

class presto.pulsed.MeasurementHandle(pls)#

Handle to a running measurement.

Return type of run_async(), do not instantiate this class directly.

abort()#: Abort current measurement.

join()#: Block execution until the measurement is done.

status()#

Current status of the measurement

Return type:: MeasurementStatus

time_elapsed()#

Time elapsed since the start of the measurement.

Return type:: timedelta

Notes

The time elapsed keeps counting even if the measurement is completed. When dry_run=True, returns timedelta(0).

Examples

>>> te = handle.time_elapsed()
>>> te
datetime.timedelta(seconds=269, microseconds=455817)
>>> te.total_seconds()
269.455817
>>> str(te)
'0:04:29.455817'
>>> print(te)
0:04:29.455817
>>> from presto.utils import format_sec
'4m 29.5s'

time_end()#

Estimated end time of the measurement.

Return type:: datetime

Notes

If the measurement is completed, returns the actual time of completion. When dry_run=True, returns datetime.fromtimestamp(0).

Examples

>>> te = handle.time_end()
>>> te
datetime.datetime(2022, 6, 22, 14, 55, 2, 978135)
>>> te.isoformat()
'2022-06-22T14:55:02.978135'
>>> te.strftime('%Y-%m-%d %H:%M:%S')
'2022-06-22 14:55:02'
>>> str(te)
'2022-06-22 14:55:02.978135'
>>> print(te)
2022-06-22 14:55:02.978135

time_remaining()#

Estimated remaining time until the end of the measurement.

Return type:: timedelta

Notes

If the measurement is not RUNNING, returns timedelta(0).

Examples

>>> tr = handle.time_remaining()
>>> tr
datetime.timedelta(seconds=115, microseconds=897831)
>>> tr.total_seconds()
115.897831
>>> str(tr)
'0:01:55.897831'
>>> print(tr)
0:01:55.897831
>>> from presto.utils import format_sec
>>> format_sec(tr)
'1m 55.9s'

time_start()#

Start time of the measurement.

Return type:: datetime

Notes

When dry_run=True, returns datetime.fromtimestamp(0).

Examples

>>> ts = handle.time_start()
>>> ts
datetime.datetime(2022, 6, 22, 14, 52, 53, 850711)
>>> ts.isoformat()
'2022-06-22T14:52:53.850711'
>>> ts.strftime('%Y-%m-%d %H:%M:%S')
'2022-06-22 14:52:53'
>>> str(ts)
'2022-06-22 14:52:53.850711'
>>> print(ts)
2022-06-22 14:52:53.850711

class presto.pulsed.MeasurementStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Enumeration for current status of the measurement

IDLE#: standby

CHECKING#: checking user parameters for errors

UPLOADING#: uploading user parameters to the hardware

ARMED#: waiting for trigger

RUNNING#: measurement is running

DOWNLOADING#: measurement is done, downloading measurement data

DONE#: measurement complete

ABORTED#: measurement aborted by the user or by an error