Introduction.md

-Pulse_lib is a library to control multi-channel AWG pulse sequences and digitizer acquisitions
+[TOC]
+
+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.
+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.
+Pulse-lib can use I/Q output pairs to generate the MW pulses with a vector signal generator.
 
 **Physical units**
 
-Pulses in pulse_lib are specified in the physical units in the context of the target device:
+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
 
+**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.
+
 **Quantum device signal processing**
 
-Pulse_lib translates the specified pulse sequence to output signals of the AWG. It takes care of:
+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
@@ -28,15 +30,85 @@ Pulse_lib translates the specified pulse sequence to output signals of the AWG.
 * 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.
+Pulses in pulse-lib can be made **conditional** on a measurement in the same sequence.
 This supported for Qblox Cluster and QuTech QuantumSequencer for Keysight PXI.
 
-Pulse_lib supports the following hardware:
+**Backends**
+
+Pulse-lib supports the following hardware:
 * Keysight PXI M3202A AWG and M3201A digitizer
 * Tektronix AWG5014 with Spectrum M4i digitizer
-* Qblox Pulsar QCM and QRM
+* Qblox Cluster with 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.
+
+See [Backends](Backends)
+
+# Channels
+
+## Pulse channels (gates)
+
+Standard pulse channels are used to apply voltage pulses to a gate 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
+
+See [Pulse channels](Sequence/Pulse channels)
+
+## Qubit channels
+
+A qubit channel is used to apply phase coherent drive pulses to a qubit.
+This drive pulse can be added to the output of a pulse channel, or to an I/Q output.
+Multiple qubit channels can be assigned to a pulse channel or an I/Q output pair. (See backends for limitations.)
+
+Every qubit channel has a resonance frequency (Larmor frequency) used track the
+signal phase between pulses. See [Qubit Channels](Sequence/Qubit channels).
+
+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.
+* I/Q 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/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.