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.

FlatPulse

Container for a (long) flat pulse.

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, downsampling=1)

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.

  • downsampling (int) – reduce the intermediate-frequency sampling rate by this factor. Must be an integer >= 1. When downsampling=1 (default), the IF sampling rate is 2 GS/s in real/direct mode and 1 GS/s in complex/mixed mode.

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.setup_store(1, 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.

See also

setup_histogram() setup_histogram_2d() run()

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, and num_ports and smpls_per_store are the number of inputs ports and the number of samples in one acquisition set up with setup_store().

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

See also

setup_template_matching_pair() match() run()

hardware: Hardware

interface to hardware features common to all modes of operation

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:

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:
Raises:
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].

See also

setup_freq_lut() next_frequency() select_frequency()

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.

See also

get_store_data() get_template_matching_data()

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:

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

See also

setup_scale_lut() next_scale()

set_store_duration(T)

Deprecated since version 2.13.0: Use setup_store() instead.

set_store_ports(input_ports)

Deprecated since version 2.13.0: Use setup_store() instead.

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:

See also

setup_template_matching_pair() match()

setup_flat_matching_pair(input_port, duration, weight1, weight2=None, *, threshold=0.0, compare_next_port=False)

Create a pair of constant input templates for template matching with given duration.

The reference templates created with this method are flat, i.e. have a constant weight, and use a single memory slot each regardless of duration. See setup_template_matching_pair() for reference templates with arbitrary shape.

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 weight1 plus the match with weight2 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.

  • duration (float) – length of the template matching in seconds. Must be a multiple of get_clk_T().

  • weight1 (Union[float, complex])

  • weight2 (Union[float, complex, None]) – amplitudes for the reference templates for template matching. Valid range is [-1.0, +1.0] for both real and imaginary part. If weight2 is not provided, it is set to zero. Type 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 weight1 from input_port and weight2 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 the real or imaginary parts of weight1 or weight2 are not in [-1.0, +1.0]; if abs(threshold) is bigger than MAX_THRESHOLD.

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 weight1 plus the match using weight2 is greater than or equal to threshold, the match is considered successful.

See also

setup_template_matching_pair() setup_condition() match() get_template_matching_data()

setup_flat_pulse(output_port, group, duration, amplitude=None, *, rise_time=0.0, fall_time=0.0, envelope=False, output_marker=None)

Create an output pulse with constant amplitude and optional rise/fall segments.

Useful for using fewer templates with very long pulses, and for dynamically changing the duration of the pulse.

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, None]) – 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). If no value is passed, use 1.0 in direct mode and 1+1j in mixed mode.

  • 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) – set to True to 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:

FlatPulse

Returns:

the newly created FlatPulse 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 pulse.

The duration of the pulse can be changed dynamically by using the methods set_total_duration() and set_flat_duration() on the returned FlatPulse object.

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

See also

setup_template_matching_pair() setup_histogram_2d() get_histogram_data()

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.

See also

setup_template_matching_pair() setup_histogram() get_histogram_data()

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.

Deprecated since version 2.14.0: New code should use setup_flat_pulse() instead. When migrating to the new method, pay attention to the change in defaults for parameters amplitude and envelope:

  • envelope default value changes from True to False;

  • amplitude default value changes from 1+0j to 1+1j when using digital upconversion.

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:

FlatPulse

Returns:

the newly created FlatPulse 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_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_store(input_ports, duration)

Set input port(s) and duration for all store events (data acquisition).

Parameters:
Raises:

ValueError – if any of input_ports is out of [1, get_nr_ports()]; if duration is not a multiple of get_clk_T(); if a store duration on all input_ports results in an acquisition window with more than MAX_STORE_LEN samples.

See also

store()

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_flat_pulse(): 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:

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.

Each memory slot for reference templates can store up to get_max_template_len() data points. If template1 and template2 are longer than that, they will be split into multiple sub-templates spanning multiple memory slots.

See also

setup_flat_matching_pair() setup_condition() match() get_template_matching_data()

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:

Notes

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

See also

setup_store()

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

FlatPulse class

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

Container for a (long) flat pulse.

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

Return type of setup_flat_pulse(); 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

See also

get_total_duration() get_flat_duration()

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

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.

LongDrive class

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

Deprecated since version 2.14.0: See FlatPulse instead.

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

get_duration()

Get the duration of the template in seconds.

Return type:

float

class presto.pulsed.Match(events, 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 reference template in seconds.

Return type:

float

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=<not given>, *values, 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