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.

Converter modes (re-exported from hardware module):

class presto.pulsed.AdcMode(value)

Configuration for analog-to-digital converters (ADC), i.e. input channels

See AdcMode for full documentation

class presto.pulsed.DacMode(value)

Configuration for digital-to-analog converters (DAC), i.e. output channels

See DacMode for full documentation

Converter sampling rates (re-exported from hardware module):

class presto.pulsed.AdcFSample(value)

Sampling rate setting for analog-to-digital converters (ADC), i.e. input channels

See AdcFSample for full documentation

class presto.pulsed.DacFSample(value)

Sampling rate setting for digital-to-analog converters (DAC), i.e. output channels

See DacFSample for full documentation

Module constants:

presto.pulsed.MAX_LUT_ENTRIES = 512

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

presto.pulsed.MAX_COMMANDS = 10736

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

presto.pulsed.MAX_STORE_LEN = 1048576

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

presto.pulsed.MAX_TEMPLATE_LEN = 2044

maximum number of data points in a single template slot

presto.pulsed.MAX_THRESHOLD = 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: 0>, adc_fsample=<AdcFSample.G2: 0>, dac_mode=<DacMode.Direct: 0>, dac_fsample=<DacFSample.G4: 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 (optional) – 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, optional) – if True re-configure clock and reload firmware even if there’s no change from the previous settings.

  • dry_run (bool, optional) – if False don’t connect to hardware, for testing only.

  • address (str, optional) – IP address or hostname of the hardware. If None, use factory default “192.168.42.50”.

  • port (int, optional) – port number of the server running on the hardware. If None, use factory default 7878.

  • adc_mode (hardware.AdcMode or list, optional) – configure the inputs to sample in direct mode (default), or to use the digital mixers for downconversion. See Notes.

  • adc_fsample (hardware.AdcFSample or list, optional) – configure the inputs sampling rate (default 2 GS/s). See Notes.

  • dac_mode (hardware.DacMode or list, optional) – configure the outputs to work in direct mode (default), to use the digital mixers for upconversion. See Notes.

  • dac_fsample (hardware.DacFSample or list, optional) – configure the outputs sampling rate (default 4 GS/s). See Notes.

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 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 \(\mu\)s, and sample 1 \(\mu\)s of data from input port 1. Repeat 10 times, average 10_000 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.

Returns

Return type

float

get_clk_f()

Frequency of the programmable logic clock in Hz.

Returns

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.

get_nr_ports()

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

Returns

Return type

int

get_store_data()

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

Only valid after the measurment is performed.

Returns

  • t_arr (numpy.ndarray) – The time axis in seconds during one acquisition. dtype is float.

  • data (numpy.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(). dtype is float.

Notes

When using the digital downconversion (adc_mode=AdcMode.Mixed), the returned data is a 2-tuple (data_I, data_Q) with data from the I and Q quadrature of the digital mixer.

Raises

RuntimeError – If no store data is available.

See also

store, run

get_template_matching_data(input_pairs)

Obtain from hardware the result of the template matching.

Only valid after the measurment is performed.

Parameters

input_pairs (Match or list of Match) – One or more template-matching pairs as defined by setup_template_matching_pair().

Returns

ret – 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.

Return type

list

Raises
  • RuntimeError – If no template-matching data is available.

  • TypeError – If input_pairs contains unrecognized objects.

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 (Match or list of Match) – The information about one or more template-matching pairs as obtained from setup_template_matching_pair().

Raises
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 list of int) – What output ports should be affected by the change. Valid ports are in the interval [1, get_nr_ports()].

  • group (int, optional) – 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].

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 list of int) – What output ports should be affected by the change. Valid ports are in the interval [1, get_nr_ports()].

  • group (int, optional) – 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].

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 list of int) – 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 list of int) – what output ports should be affected by the reset. Valid ports are in the interval [1, get_nr_ports()].

  • group (int, optional) – 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

Returns

the closest multiple of get_clk_T() to t

Return type

float

run(period, repeat_count, num_averages, print_time=True, verbose=False, arm=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) – Number of times to repeat the experiment and stack the acquired data (no averaging).

  • 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, optional) – 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, optional) – If True, print debugging information.

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=True, verbose=False, arm=False)

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

Returns

thread

Return type

Thread

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 list of int) – What output ports should be affected by the change. Valid ports are in the interval [1, get_nr_ports()].

  • group (int, optional) – 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].

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 list of int) – What output ports should be affected by the change. Valid ports are in the interval [1, get_nr_ports()].

  • group (int, optional) – 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].

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
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
setup_freq_lut(output_ports, group, frequencies, phases, phases_q=None)

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.

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

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

Create a long output pulse with constant amplitude.

Useful for using fewer templates.

Parameters
  • output_port (int) – 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 (float, optional) – amplitude of the flat part of the pulse.

  • amplitude_q (float, optional) – amplitude of the Q quadrature of the flat part of the pulse. Only used when dac_mode is one of DacMode.Mixedxx. If None, use same as amplitude.

  • rise_time (float, optional) – smoothen the initial rise_time seconds of the pulse. Must be a multiple of get_clk_T(). See Notes.

  • fall_time (float, optional) – smoothen the final fall_time seconds of the pulse. Must be a multiple of get_clk_T(). See Notes.

  • output_marker (int, optional) – 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].

Returns

long_drive

Return type

LongDrive

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

A long drive is always used as an envelope, i.e. it’s always multiplied by a carrier.

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)\). For implementation details, 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)

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.

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

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 list of int) – 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 (np.ndarray of np.float64) – Data points for the template/envelope with get_fs("dac") sampling rate. Valid range is [-1.0, +1.0].

  • template_q (np.ndarray of np.float64) – data points for the Q quadrature to the digital upconversion mixer. Must be specified if and only if dac_mode is one of DacMode.Mixedxx (not DacMode.Direct).

  • envelope (bool, optional) – 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 (int, optional) – 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].

Returns

Return type

Template

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 (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 (numpy.ndarray) –

  • template2 (numpy.ndarray, optional) – 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

  • threshold (float, optional) – 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 0.5 * N.

  • compare_next_port (bool, optional) – if True, match template1 from input_port and template2 from input_port+1. If False, match both from input_port.

Returns

Return type

list of Match

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.

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 See also section below.

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

Returns

number of clock cycles

Return type

int

Raises

ValueError – if t is not an integer multiple of get_clk_T()

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

Returns

Return type

float

get_events()
get_flat_duration()

Duration of the flat segment of the pulse in seconds.

Does not include rise and fall segments.

Returns

Return type

float

get_templates()

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

Returns

Return type

list of RawTemplate

get_total_duration()

Total duration of the pulse in seconds.

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

Returns

Return type

float

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.

Returns

Return type

Event

get_duration()

Get the duration of the event in seconds.

Returns

Return type

float

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

Bases: presto.pulsed.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.

Returns

Return type

float

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

Bases: presto.pulsed.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.