Phase 1 documentation update

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.

docs/signals/cross_capacitance.rst

+.. title: Cross-capacitance
+
+Cross-capacitance
+=================
+The chemical potential of the quantum dots used in spin-qubit devices determines the amount of electrons that
+will be loaded in the quantum dot. The chemical potential is controlled by a plunger gate close to the quantum dot.
+However, due to the small distance between quantum dots the potential of a quantum dot is also affected
+by neighbouring plunger and barrier gates. This is the capacitive cross-talk, or cross-capacitance, from a gate to
+other quantum dots. This cross-capacitance is classical in nature and can be corrected by pulse_lib using
+"virtual gates".
+
+A virtual gate is a pulse_lib channel that outputs a pulse sequence on multiple AWG channels
+such that only a single chemical potential or single tunnel coupling will be affected by the pulses.
+Virtual gates are defined by a virtual gate matrix.
+
+
+Virtual Gate Matrix
+===================
+
+A virtual gate matrix is a matrix that relates the virtual gate voltages to the real voltages.
+
+	:math:`\begin{pmatrix} vP1 \\ vP2 \\ vP3 \end{pmatrix} = M \begin{pmatrix} P1 \\ P2 \\ P3 \end{pmatrix}`
+
+When there would me no cross effects, this matrix would look like:
+
+	:math:`M = \begin{pmatrix} 1  & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{pmatrix}`
+
+Which gives a one to one map of the virtual gate voltages to the real voltages.
+In reality, this will not be the case. There will be cross-capacitances.
+
+	:math:`M = \begin{pmatrix} 1  & C_{12} & C_{13} \\ C_{21} & 1 & C_{23} \\ C_{31} & C_{32} & 1 \end{pmatrix}`
+
+The values on the diagonal are kept equal to 1. The lever arm of :math:`vP1` will then be equal to the lever
+arm of :math:`P1`.
+A correct virtual matrix will remove the slant from the lines in the charge stability diagram without stretching it.
+
+See *Loading a quantum-dot based "Qubyte" register*, C. Volk (2019), for a detailed description
+of cross-capacitance and virtual gates.
+
+
+Virtual gate matrix in pulse_lib
+--------------------------------
+
+Pulse_lib inverts cross-capacitance matrix :math:`M` to calculate the voltages on the output channels.
+
+	:math:`\begin{pmatrix} P1 \\ P2 \\ P3 \end{pmatrix} = M^{-1} \begin{pmatrix} vP1 \\ vP2 \\ vP3 \end{pmatrix}`
+
+The cross-capacitance matrix (real-to-virtual) can be passed to pulse_lib, but also the inverted
+matrix (virtual-to-real) can be passed. The cross-capacitance matrix has to be a square matrix, because it
+must be invertible. The virtual-to-real matrix doesn't have to be square.
+
+Example:
+  .. code-block:: python
+
+      pl.add_virtual_matrix(
+        name='virtual-gates',
+        real_gate_names=['B0', 'P1', 'B1', 'P2', 'B2'],
+        virtual_gate_names=['vB0', 'vP1', 'vB1', 'vP2', 'vB2'],
+        matrix=[
+            [1.00, 0.25, 0.05, 0.00, 0.00],
+            [0.14, 1.00, 0.12, 0.02, 0.00],
+            [0.05, 0.16, 1.00, 0.11, 0.01],
+            [0.02, 0.09, 0.18, 1.00, 0.16],
+            [0.00, 0.01, 0.013 0.21, 1.00]
+            ],
+        real2virtual=True)
+
+
+Combining virtual gates to a combined parameter
+-----------------------------------------------
+
+The use of the virtual matrix is not restricted to the definition of virtual gates to compensate
+for the cross-capacitance. It can also be used to define a new channel for voltage pulses that is
+a linear combination of virtual gates, e.g. to define a detuning parameter.
+
+Example:
+  A detuning parameter e12 and a energy parameter U12 is defined using a virtual-to-real matrix.
+
+  .. code-block:: python
+
+      pl.add_virtual_matrix(
+        name='detuning12',
+        real_gate_names=['vP1', 'vP2'],
+        virtual_gate_names=['e12', 'U12'],
+        matrix=[
+            [+0.5, +1.0],
+            [-0.5, +1.0],
+            ],
+        real2virtual=False)
+
+

docs/signals/delays.rst

+.. title: Signal delay
+
+Signal delays
+=============
+
+It takes time for a signal to get from the AWG to the target device and from the device to the digitizer.
+Pulses with equal start time but on different channels should arrive at the same time on the target device.
+This is not by default true, because signals travel along different paths with different travel times.
+Pulse_lib can compensate for these difference in signal delays.
+
+Signal delays in pulse and acquisition paths are caused by:
+
+* propagation through cables, which is approximately 3 ns / m.
+* propagation through vector signal generator, which takes 20 - 50 ns.
+* propagation through RF up-convertor, down-converter.
+* processing time in AWG
+* processing time in digitizer
+
+The delay can be specified per channel. It is specified as the delay added to the channel.
+
+Example:
+ If the MW signal is delayed by the VSG and arrives 45 ns later than the signals of gates P1 and P2,
+ then you can add 45 ns to the gates P1 and P2.
+
+ .. code-block:: python
+
+     pl.add_channel_delay('P1', 45)
+     pl.add_channel_delay('P2', 45)
+
+ Alternatively, you can also subtract 45 ns for the I and Q channel.
+
+ .. code-block:: python
+
+     pl.add_channel_delay('I1', -45)
+     pl.add_channel_delay('Q1', -45)
+