Merge branch 'dev' into qblox

CHANGELOG.md

 # Changelog
 All notable changes to Pulselib will be documented in this file.
 
-## \[1.4.0] - @@@@
+## \[1.5.0] - 2022-05-@@@
 ### Added
 - Support for Qblox modules: QCM and QRM
 - Added sequencer.get_measurement_data
@@ -9,17 +9,40 @@ All notable changes to Pulselib will be documented in this file.
 - Added sequencer.get_acquisition_param with automatic upload/play
 - Added channel acquire(..., n_repeat= , interval= )
 - Added qblox_fast_scan 1D and 2D
-- Improved sequencer sweep index parameters
 
-## \[1.3.2] - 2022-03014
-## \[1.3.3] - 2022-03-014
+
+## \[1.4.0] - 2022-05-17
+### Changed
+- Renamed Tektronix backend 'Tektronix_5014' after refactoring:
+    - Faster and allow fast switching between multiple uploaded sequences.
+    - Amplitude output has been corrected. It is 2x previous output. Correct attenuation per channel!!
+    - Use sequence.play(release=False) to call play multiple times after a single upload.
+    - Use infinite looping when n_rep > 65535
+### Added
+- Added sequencer.repetition_aligment to align the duration of the sequence with an external clock or signal frequency.
+  (currently only implemented for Tektronix)
+- Added argument reset_time to wait()
+- Several pages of documentation (not finished yet..)
+
+## \[1.3.5] - 2022-03-29
+### Fixed
+- Error when rendering section with low sample rate extends into segment with high sample rate.
+
+## \[1.3.4] - 2022-03-23
+### Improved
+- QuantumSequencer use waveform with low sample rate for long DC compensation pulse.
+
+## \[1.3.3] - 2022-03-14
 ### Fixed
 - QuantumSequencer bugs in 1.3.2
 
-## \[1.3.2] - 2022-03-014
+## \[1.3.2] - 2022-03-14
 ### Fixed
 - Fixed long wait (> 160 ms) for QuantumSequencer
 
+### Added
+- Added attribute 'values' to sequence loop parameters
+
 ## \[1.3.1] - 2022-03-07
 ### Fixed
 - Fixed rendering of segments with different sample rates

Readme.md

 # Introduction
 
-This is a pulse library that is build to make pulses that are commonly used to control spin qubits coherenly. A lot of attention is given to performance, structure and ease of use. At the moment the library only has a back-end that is suited for Keysight PXI AWG systems
-
-Features now include:
-* support for arbitrary baseband/microwave based sequences
-* Fully multidimensional. Execute any command as a loop in any dimension.
-* Short and clean syntax. No sympy.
-* Native support for virtual gates.
-* IQ toolkit and IQ virtual channels -- Full suppport for single sideband modulation (Along with PM/AM/FM) and out of the box pulse shaping. Automatic softare downconversion from MW pulse to IQ, which can later on be upconverted in hardware by mixing with the IF.
-* Automatic compenstation for DC offsets.
-* High speed uploader for Keysight PXI systems which supports upload during playback (up to ~ 100 experiments per second (record~350))
-
-!! keysight AWG's their waveforms need to have a length of modulo 10 !! (related to the clock of the AWG)
---> segments are concatenated for this purose when uploading (e.g. upload happens in one big chunk)
+Pulse_lib is a library to control multi-channel AWG pulse sequences and digitizer acquisitions
+with a simple API using physical units. It is designed to control qubit experiments, especially quantum dot
+and spin qubit experiments.
+
+Sequences can contain direct voltage pulses, phase coherent microwave (MW) pulses, digital markers, triggers,
+and digitizer acquisitions.
+The MW pulses in a sequence are phase coherent to enable construction of sequences of quantum gates.
+Pulse_lib uses IQ output pairs to generate the MW pulses with a vector signal generator.
+
+Parameters of the pulses in a sequence can be swept across a range of values. This turns the sequence in a
+multi-dimensional measurement.
+
+Pulses in pulse_lib are specified in the physical units in the context of the target device:
+* Amplitudes are specified in millivolts
+* Time is specified in nanoseconds
+* MW pulses are specified for a specific qubit and resonance and drive frequency in Hz
+* Channels are identified with a logical name
+
+Pulse_lib translates the specified pulse sequence to output signals of the AWG. It takes care of:
+* Phase coherence of pulses per qubit
+* Capacitive coupling of plunger and barrier gates of quantum dots using a virtual matrix
+* Signal delays due to vector signal generator and cables
+* MW up conversion by vector signal generator
+* Attenuators between AWG and target device
+* DC charging of bias-T, which acts as a high pass filter for AWG signals
+
+Pulses in pulse_lib can be made conditional on a measurement in the same sequence. However, this feature
+is currently only supported by the QuTech QuantumSequencer for Keysight PXI.
+
+Pulse_lib supports the following hardware:
+* Keysight PXI M3202A AWG and M3201A digitizer
+* Tektronix AWG5014 with Spectrum M4i digitizer
+* Qblox Pulsar QCM and QRM
+* QuTech QuantumSequencer for Keysight PXI
+
+The communication with the AWGs has been optimized to minimize the overhead between measurements.
+The compilation of pulse sequences and the communication with the AWGs will be further optimized
+with every new release of the software.
 
 # Requirements
-You need python3.x and a c/c++ compiler. For the c-compiler, the following is recommended
-* windows: the Visual Studio SDK C/C++ compiler (tested)
-* linux: gcc is fine.
-* ox x : gcc or clang both work
+You need python 3.7+ and qcodes.
 
-To install the upload libraries for the keysight system, you will need:
-* the Keysight SD1 software
-* openMP (comes by default in visual studio)
-(At the moment this is a requirement, will be removed as a requirement at a later time)
+To use pulse_lib with Keysight you also need Keysight SD1 software, Keysight FPGA Test Sync Executive, hvi2-script
+and hvi2 schedules.
+
+To use pulse_lib with Qblox you also need [Q1Pulse](https://github.com/sldesnoo-Delft/q1pulse).
 
 # Quick start
 The pulse library can be installed by cloning the library from github on your computer.
@@ -31,20 +53,9 @@ Navigate in the github folder and run the following in the terminal:
 ```bash
 	python3 setup.py install
 ```
-The python scrip will also take care of compiling the c code. On windows, it is recommended to do this in a Anaconda promt. You will need to run the promt with administarator privelages.
 
 # Documentation
 Documentation for the library can be found at:
 
 https://pulse-lib.readthedocs.io
 
-# TODO
-TODO list:
-* Support for calibration arguments? -- this should be engineered well.
-* HVI2 integration
-
-TODO bugs and small things to fix,
-* remove finish init
-* Keysight FPGA pulse correction not there? --> investigation needed. + correction for long time scale pulses
-New functionality (prioritized):
-* TODO : automate phase compensation of microwave pulses. (master clock already there for the HVI markers)

docs/conf.py

@@ -16,6 +16,7 @@ import os
 import sys
 sys.path.insert(0, os.path.abspath('../'))
 
+#import sphinx_rtd_theme
 
 # -- Project information -----------------------------------------------------
 
@@ -24,9 +25,9 @@ copyright = '2019, Stephan Philips'
 author = 'Stephan Philips'
 
 # The short X.Y version
-version = ''
+version = '1.3'
 # The full version, including alpha/beta/rc tags
-release = '0.2 alpha'
+release = '1.3'
 
 
 # -- General configuration ---------------------------------------------------
@@ -44,6 +45,8 @@ extensions = [
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
+    'sphinx.ext.napoleon',
+    #'sphinx_rtd_theme',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -80,6 +83,7 @@ pygments_style = None
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
+#html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/index.rst

@@ -3,28 +3,81 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to pulse lib's documentation
-====================================
-This is a pulse library designed to provide all the control signals that are needed control spin qubits coherenly.
-A lot of attention is given to performance, structure and ease of use.
+Pulse_lib
+=========
 
-Features now include:
-	- Support for arbitrary pulse/sine wave based sequences (phase coherent atm).
-	- Fully multidimensional. Execute any command as a loop in any dimension.
-	- Short and clean syntax. No sympy.
-	- Native support for virtual gates.
-	- IQ toolkit and IQ virtual channels -- Full suppport for single sideband modulation (Along with PM/AM/FM).
-	- Automatic compenstation for DC offsets.
-	- High speed uploader for Keysight PXI systems which supports upload during playback.
+Pulse_lib is a library to control multi-channel AWG pulse sequences and digitizer acquisitions
+with a simple API using physical units. It is designed to control qubit experiments, especially quantum dot
+and spin qubit experiments.
 
-Getting started:
+Sequences can contain direct voltage pulses, phase coherent microwave (MW) pulses, digital markers, triggers,
+and digitizer acquisitions. Parameters of the pulses in a sequence can be swept across a range of values. This turns the sequence in a
+multi-dimensional measurement.
 
-	- :ref:`struct_lib`
-	- :ref:`init_lib`
-	- :ref:`simple_pulse`
+Pulse_lib translates the specified pulse sequence to output signals of the AWG. It takes care of:
+
+* Phase coherence of pulses per qubit
+* Capacitive coupling of plunger and barrier gates of quantum dots using a virtual matrix
+* Signal delays due to vector signal generator and cables
+* MW up conversion by vector signal generator
+* Attenuators between AWG and target device
+* DC charging of bias-T, which acts as a high pass filter for AWG signals
+
+Pulses can be conditional on a measurement in the same sequence. However, this feature
+is currently only supported by the QuTech QuantumSequencer for Keysight PXI.
+
+Pulse_lib supports the following hardware:
+
+* Keysight PXI M3202A AWG and M3201A digitizer
+* Tektronix AWG5014 with Spectrum M4i digitizer
+* Qblox Pulsar QCM and QRM
+* QuTech QuantumSequencer for Keysight PXI
+
+
+.. toctree::
+	:maxdepth: 2
+	:caption: Getting started
+	:name: getting_started
+
+	introduction
+	installation
+	tutorials/basic_example
+
+.. toctree::
+	:maxdepth: 2
+	:caption: Signal physics
+
+	signals/delays
+	signals/attenuation
+	signals/bias_T
+	signals/cross_capacitance
+	signals/iq_modulation
+
+.. toctree::
+	:maxdepth: 1
+	:caption: User Guide
+
+	user/configuration
+	user/segments
+	user/timeline
+	user/voltage_channels
+	user/mw_channels
+	user/marker_channels
+	user/digitizer_channels
+	user/parameter_sweep
+	user/plotting_segments
+	user/acquisition_parameter
+	user/executing_sequence
+
+*TODO:*
+
+
+.. Getting started:
+
+..	- :ref:`struct_lib`
+..	- :ref:`init_lib`
+..	- :ref:`simple_pulse`
 
-..    :caption: Getting started
-..    :titlesonly:
 
 ..    struct
 ..    tutorials/init_lib
@@ -36,23 +89,6 @@ Getting started:
 ..    tutorials/example_PT
 ..    tutorials/example_RB
 
-When using the library in combination with the keysight PXI AWG's, playback of the waveforms is also supported:
-	- How does a upload work? What are the different steps?
-	- Your first simple upload.
-	- Integrating HVI.
-	- More advanced upload options, running uploads at high speeds.
-
-An overview of all the functions in the classes can be found at
-	- sequence
-	- segment containers
-	- segment base
-	- segment IQ
-
-API documentation for developers
-	- Requesting data from the sequence object.
-
-
-
 
 Indices and tables
 ==================

docs/installation.rst

+.. title:: Installation
+
+Installation
+============
+
+Pulse_lib
+---------
+
+Clone the `sources of Pulse_lib <https://github.com/stephanlphilips/pulse_lib>`_ from GitHub.
+
+.. code-block:: console
+
+	pip install ./pulse_lib
+
+or
+
+.. code-block:: console
+
+	python3 setup.py install
+
+Pulse_lib uses the packages qcodes and qcodes_contrib_drivers.
+
+
+Keysight PXI
+------------
+
+To use pulse_lib with Keysight M3202A AWG and M3102A digitizer you have to install:
+
+* Keysight SD1 software
+* Keysight FPGA Test Sync Executive
+* Git clone `hvi2-script <https://github.com/QuTech-Delft/hvi2_script>`_ branch SD1_3.1
+* Git clone `core tools <https://github.com/stephanlphilips/core_tools>`_
+
+The core tools package contains the HVI2 schedules required to trigger the AWGs and digitzers.
+It contains the schedules for video mode and single shot measurements.
+
+The core tools package also contains a driver for the M3102A digitizer.
+
+
+Tektronix AWG5014
+-----------------
+
+No additional software is needed to use pulse_lib with AWG5014.
+
+A schedule to use AWG5014 with Spectrum M4i digitizer and Zurich Instruments UHFLI is included in pulse_lib.
+
+
+Qblox Pulsar QCM and QRM
+------------------------
+
+Note: Support for Qblox is still in development on a separate branch of pulse_lib.
+
+To use pulse_lib with Qblox you have to install:
+
+* package qblox_instruments (available on PyPi)
+* `Q1Pulse<https://github.com/sldesnoo-Delft/q1pulse>`_
+
+
+QuTech QuantumSequencer
+-----------------------
+
+The QuantumSequencer uses QuTech developed FPGA images for Keysight M3202A and M3102A.

docs/introduction.rst

+.. title:: Introduction
+
+Introduction
+============
+
+Pulse_lib is a library to control multi-channel AWG pulse sequences and digitizer acquisitions
+with a simple API using physical units. It is designed to control qubit experiments, especially quantum dot
+and spin qubit experiments.
+
+
+Pulses are specified on user-defined channels. A channel can be used for either voltage pulses,
+microwave (MW) pulses, marker on-off pulses, or digitizer acquisition.
+
+
+Gates (voltage channels)
+------------------------
+
+A gate is used to apply voltage pulses on the target device. The pulses are output to one AWG channel, or in
+the case of a virtual gate to multiple AWG channels.
+A virtual gate is a combination of channels that can be used to compensate capacitive coupling.
+A virtual gate can also be a combination of other virtual gates, e.g. to define a detuning voltage.
+
+Voltage pulses are additive, i.e. pulses which overlap in time are summed.
+The following pulses can be added to a sequence on a (virtual) gate:
+
+* block pulses
+* ramps
+* sinusoidal pulses
+* custom pulses of arbitrary shape
+
+The pulse_lib configuration has settings to compensate the voltage pulses for:
+
+* Signal delays due to cables and filters
+* Attenuation between AWG and target device
+* DC charging of bias-T, which acts as a high pass filter for AWG signals
+* Capacitive coupling of plunger and barrier gates of quantum dots using a virtual matrix
+
+
+Qubit (MW) channels
+-------------------
+
+A qubit channel is used to apply phase coherent MW pulses to the target device.
+It should be assigned to an IQ output pair of the AWG. Multiple qubit channels can be assigned
+to one IQ output pair. (See hardware for limitations.)
+
+Every qubit channel has a reference frequency (or resonance frequency) used track the
+signal phase between pulses.
+
+The following pulses can be added to a sequence on a qubit channel:
+
+* MW pulse with optional envelope for amplitude and phase modulation
+* phase shift for virual-Z gates or phase correction after another gate
+* Frequency chirps
+
+The pulse_lib configuration has settings to compensate the MW pulses for:
+
+* Signal delays due to vector signal generator and cables
+* MW up conversion by vector signal generator
+* IQ mixer phase and amplitude errors
+
+
+Marker channels
+---------------
+
+A marker channel is a digital I/O or an AWG output channel used for example to trigger
+another instrument or to mute/unmute a signal.
+
+A marker channel can be linked to a MW channel to automatically mute/unmute the output of the MW source.
+It can be offset in time to unmute the MW source ahead of the MW pulse.
+
+
+Acquisition channels
+--------------------
+
+Acquisition channels are used to add acquisitions to a sequence. The input for the acquisition channel
+can be single digitizer input channel, or an input pair representing I and Q inputs.
+The input can be demodulated and phase shifted.
+
+The acquisition can specify to return averaged the data or a down-sampled time trace.
+A threshold can be set on the averaged value to convert it to a qubit state measurement.
+
+
+Physical units
+--------------
+
+Pulses in pulse_lib are specified in physical units like they should arrive on the target device:
+
+* Amplitudes are specified in millivolts
+* Time is specified in nanoseconds
+* MW pulses are specified for a specific qubit and resonance and drive frequency in Hz
+* Channels are identified with a logical name
+
+Parameter sweeps
+----------------
+
+Parameters of the pulses in a sequence can be swept across a range of values. This turns the sequence in a
+multi-dimensional measurement.
+
+Conditional pulses
+------------------
+
+Pulses can be made conditional on one or more measurements in the same sequence.
+The conditional pulses can be used to create classical controlled qubit gates.
+
+This feature is currently only supported by the QuTech QuantumSequencer for Keysight PXI.
+
+Supported hardware
+------------------
+
+Pulse_lib supports the following hardware:
+
+* Keysight PXI M3202A AWG and M3201A digitizer
+* Tektronix AWG5014 with Spectrum M4i digitizer, AlazarTech ATS or Zurich Instruments UHFLI
+* Qblox Pulsar QCM and QRM
+* QuTech QuantumSequencer for Keysight PXI
+
+See the hardware specific sections for supported features and limitations.
+
+The communication with the AWGs has been optimized to minimize the overhead between measurements.
+The compilation of pulse sequences and the communication with the AWGs will be further optimized
+with every new release of the software.
+

docs/signals/attenuation.rst

+.. title: Attenuation
+
+Signal attenuation
+==================
+
+The signal from AWG to device is electrically attenuated to reduce the amount of noise on the device.
+The signal-to-noise ratio of the AWG is high when the signal has a high amplitude. On the device the
+required signal amplitude is much lower and must be attenuated.
+
+Pulselib compensates for this attenuation. The value should be specified as the fraction of the signal
+transmitted to the device.
+
+Example:
+  If the attenuation is 12 dB, then the amplitude at the device will be 0.25 of the amplitude at the AWG.
+  An attenuation of 0.25 should be specified for the channel.
+
+  .. code-block:: python
+
+      pl.add_channel_attenuation('P1', 0.25)

docs/signals/bias_T.rst

+.. title: Bias-T
+
+Bias-T
+======
+
+The plunger and barrier gates of quantum dots have a DC voltage offset to maintain the desired operational regime.
+The gates are pulsed for the initialization, manipulation and readout of the qubit state.
+The DC voltage source and the AWG-generated pulses are combined by means of a bias-T.
+
+.. figure:: /img/bias_T.png
+    :scale: 50%
+
+    Bias-T connecting the high frequency AWG and the low frequency DAC to the device.
+
+The bias-T is a T-like component which acts as a high-pass filter for the AWG pulses and as a low-pass filter
+for the DC voltage. It consists of a resistor and a capacitor with values in the order of 1 MOhm and 100 nF
+giving an RC-time in the order of 0.1 s.
+The a cut-off frequency :math:`f_c = 1/2\pi R C` is in the order of a few Hz.
+
+he high-pass filter on the AWG signal results in amplitude decays for long pulses and
+accumulation of an offset when the average voltage of a sequence is not zero.
+This offset will grow with every repetition of the sequence until the offset is has the negative voltage
+of the average of the sequence.
+
+.. figure:: /img/bias_T_block_pulse.png
+    :scale: 75%
+
+    Decay of the amplitude of a long block pulse due to the bias-T high pass filtering with RC-time = 0.1 s.
+
+
+.. figure:: /img/bias_T_sequence.png
+    :scale: 90%
+
+    The deviation after 2 pulses of ~0.5 ms is only 1.6 mV. After 100 repetitions the deviation is > 50 mV.
+
+
+DC-compensation
+---------------
+
+The average voltage of a sequence should be 0.0 V to avoid a growing voltage offset due to the bias-T
+high pass filtering.
+Pulse_lib will automatically add a DC-compensation pulse when the average of a sequence is not zero.
+This DC-compensation is enabled for all channels where the channel compensation limits are set.
+
+Note: Contrary to all other settings, the compensation limits are set in AWG voltage, not the device voltage.
+
+Example:
+  Enable DC-compensation for channels P1 and P2 with limits of -200 and +500 mV.
+
+  .. code-block:: python
+
+    pl.add_channel_compensation_limit('P1', (-200, 500))
+    pl.add_channel_compensation_limit('P2', (-200, 500))
+
+.. figure:: /img/DC_compensation_pulses.png
+    :scale: 75%
+
+    DC compensation with automatically added pulses of -200 mV at the end of the sequence.
+
+
+Bias-T compensation
+-------------------
+
+Sequences with long pulses or long sequences with the average voltage not equal to zero will
+be distorted by the bias-T when the duration exceeds a few percent of the RC-time.
+Pulse_lib will compensate for the bias-T high-pass filtering when the bias-T time compensation is
+configured.
+This bias-T correction will increase the sequence compilation time with a small percentage.
+
+The bias-T compensation can correct pulses with a duration in the order of the RC-time.
+Pulses that are longer than a few times the RC-time will eventually hit the limits of the AWG output range,
+because the bias-T compensation increases the amplitude of the signal.
+A good correction of long pulses is only possible when the configured RC-time is accurate enough.
+An error of 2% in the configured RC-time gives an error of 10% in the amplitude at the end of a pulse
+with a duration of 5 times the RC-time.
+
+Note: The time of the bias-T is specified in seconds!
+
+Example:
+  Enable bias-T compensation for channels P1 and P2.
+
+  .. code-block:: python
+
+        pulse.add_channel_bias_T_compensation('P1', 0.102)
+        pulse.add_channel_bias_T_compensation('P2', 0.106)
+
+.. figure:: /img/long_pulses_with_compensation.png
+    :scale: 75%
+
+    Bias-T compensated pulses. The dashed lines show the signal after bias-T with the desired rectangular pulses.