Phase 1 documentation update

docs/signals/iq_modulation.rst

+.. title: IQ modulation
+
+IQ Modulation
+=============
+
+Spin qubit resonant frequencies are typically 2 to 20 GHz. This is much higher than the bandwidth of the AWGs.
+In experiments microwave (MW) sources are used to manipulate the qubits. The microwave signals must be amplitude
+and phase modulated for full qubit control.
+A common solution for this modulation of MW signals is in-phase and quadrature (IQ) modulation.
+The in-phase and quadrature MW sinusoids are mixed with an IQ modulation pair from the AWG.
+See `In-phase and quadrature components <https://en.wikipedia.org/wiki/In-phase_and_quadrature_components>`_.
+
+  .. figure:: /img/IQ_mixing.png
+     :scale: 80 %
+
+     IQ mixing with carrier frequency :math:`f_c`
+
+The output of this mixer is:
+
+	:math:`y(t) = I(t) cos(\omega_c t) - Q(t) sin(\omega_c t)`
+
+
+IQ modulation can be used to create a single frequency output signal which is higher of lower in frequency
+than the MW source. For this the IQ modulation signals should be sinusoids with a 90 degrees shift.
+
+	:math:`I(t) = A(t) cos(\omega_m t + \phi(t))`
+
+	:math:`Q(t) = A(t) sin(\omega_m t + \phi(t))`
+
+	:math:`y(t) = A(t) [cos(\omega_m t + \phi(t)) cos(\omega_c t) - sin(\omega_m t + \phi(t)) sin(\omega_c t)]`
+
+	:math:`y(t) = A(t) cos((\omega_c + \omega_m) t + \phi(t))`
+
+
+IQ modulation allows frequency multiplexing, because it is a linear operation. The I and Q components can
+contain multiple frequencies which will all be shifted with :math:`f_c`.
+IQ modulation can also be used for fast chirps (frequency sweeps), because phase and frequency of the
+I and Q components can be swiftly changed by the AWG.
+
+
+IQ modulation in pulse_lib
+--------------------------
+Users of pulse_lib don't have to care about the calculation of I and Q outputs.
+They can specify the desired MW pulses after IQ modulation and pulse_lib calculates the I and Q output signals
+for the AWG.
+
+The user has to specify the I and Q output channels of the AWG as an IQ pair and pass the frequency of the
+vector signal generator, the LO frequency.
+For coherent qubit control every qubit needs a channel with the resonant frequency of the qubit.
+
+Example:
+  .. code-block:: python
+
+    pl.define_channel('I1','AWG1', 3)
+    pl.define_channel('Q1','AWG1', 4)
+
+    # define IQ output pair
+    IQ_pair_1 = IQ_channel_constructor(pl)
+    IQ_pair_1.add_IQ_chan("I1", "I")
+    IQ_pair_1.add_IQ_chan("Q1", "Q")
+    # frequency of the MW source
+    IQ_pair_1.set_LO(2.40e9)
+
+    # add 1 qubit: q1
+    IQ_pair_1.add_virtual_IQ_channel("q1", 2.415e6)
+
+
+IQ modulation errors
+--------------------
+
+Idealy the IQ mixer creates single side-band signal.
+
+.. figure:: /img/ideal_modulation.png
+
+   Ideal IQ modulation
+
+In practice the signals and electrical components are not perfect. Small differences between amplifiers,
+filters and path length result in small errors in the IQ output.
+
+The I and Q output of the AWG can have a voltage offset, a (frequency dependent) gain difference and
+a (frequency dependent) phase difference. The output signal after modulation will contain the carrier frequency
+and the mirror side-band.
+
+.. figure:: /img/real_modulation.png
+
+   IQ modulation in practice with remainder of the carrier frequency and a mirrored side-band.
+
+Offset error
+~~~~~~~~~~~~
+
+A voltage offset in the AWG output results in the output of the carrier frequency.
+
+	:math:`y(t) = [a+cos(\omega_m t)] cos(\omega_c t) - [b + sin(\omega_m t)] sin(\omega_c t)]`
+
+	:math:`y(t) = cos((\omega_c + \omega_m) t) + a \cdot cos(\omega_c t) - b \cdot sin(\omega_c t)`
+
+.. figure:: /img/IQ_offset_error.png
+
+   Remainder of carrier frequency due to offset error.
+
+
+Gain error
+~~~~~~~~~~
+
+A difference in gain between I and Q components add the mirrored side-band frequency,
+:math:`f_c - f_m`, to the output.
+
+	:math:`y(t) = (1 + a) cos(\omega_m t) cos(\omega_c t) - sin(\omega_m t) sin(\omega_c t)`
+
+	:math:`y(t) = (1+\frac{a}{2}) cos((\omega_c + \omega_m) t) + \frac{a}{2} cos((\omega_c - \omega_m) t)`
+
+
+.. figure:: /img/IQ_gain_error.png
+
+   Mirrored side-band due to gain error.
+
+Phase error
+~~~~~~~~~~~
+
+When the phase difference between the I and Q components is not exactly 90 degrees then the mirrored
+side-band frequency is output as well. The resulting output is similar to the output with a gain error.
+
+	:math:`y(t) = cos(\omega_m t + \frac{a}{2}) cos(\omega_c t) - sin(\omega_m t - \frac{a}{2}) sin(\omega_c t)`
+
+	:math:`y(t) = cos(\frac{a}{2}) cos((\omega_c + \omega_m) t) - sin(\frac{a}{2}) sin((\omega_c - \omega_m) t)`
+
+
+
+IQ corrections in pulse_lib
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A vector signal generator will have options to correct the offset, phase and gain error of the IQ input, but
+only with a frequency independent correction.
+Pulse_lib can also correct for these errors, where gain and phase corrections are frequency dependent.
+
+Example:
+  Add offset correction to I and Q components.
+
+  .. code-block:: python
+
+    pl.add_channel_offset('I1', 10)
+    pl.add_channel_offset('Q1', -5)
+
+  Add gain and phase offset to qubit channels.
+
+  .. code-block:: python
+
+    IQ_pair_1.add_virtual_IQ_channel("q2", 2.421e9,
+                                     correction_gain=(1.0, 0.9))
+    IQ_pair_1.add_virtual_IQ_channel("q3", 2.473e9,
+                                     correction_gain=(0.98, 1.0),
+                                     correction_phase=0.3)

docs/tutorials/basic_example.rst

+.. title: Basic example
+
+Basic example
+=============
+
+
+
+Configure pulse_lib
+-------------------
+
+Create a pulse_lib object with gates for voltage pulses and 2 qubit channels for MW pulses.
+
+.. code-block:: python
+
+    pl = pulse_lib(backend='Keysight')
+
+    # add AWGs and digitizers
+    pl.add_awg(awg1)
+    p1.add_digitizer(digitizer)
+
+    # gates (voltage channels)
+    pl.define_channel('P1', awg1, 1)
+    pl.define_channel('P2', awg1, 2)
+
+    # IQ output pair
+    pl.define_channel('I1', awg1, 3)
+    pl.define_channel('Q1', awg1, 4)
+    IQ_pair_1 = IQ_channel_constructor(pl)
+    IQ_pair_1.add_IQ_chan("I1", "I")
+    IQ_pair_1.add_IQ_chan("Q1", "Q")
+
+    # set frequency of the MW source for down-conversion
+    IQ_pair_1.set_LO(mw_source.freq)
+
+    # add qubit channels
+    IQ_pair_1.add_virtual_IQ_channel("q1", q1_freq)
+    IQ_pair_1.add_virtual_IQ_channel("q2", q2_freq)
+
+    # acquisition channel
+    pl.define_digitizer_channel('S1', digitizer, 1)
+
+    pl.finish_init()
+
+
+Create a sequence
+-----------------
+
+A sequence is made of one or more segments. Here we use a single segment.
+
+.. code-block:: python
+
+    seg = pl.create_segment()
+
+Initialize the qubit with a voltage pulse on the gates.
+After the pulse the voltage returns to (0.0, 0.0)
+
+Voltage pulses on multiple channels can be added with ``add_block`` and ``add_ramp`` on the segment.
+The start and end time of a pulse are relative to a reference time in the segment.
+The reference time is moved to the end of the last pulse with reset_time.
+
+.. code-block:: python
+
+    gates = ['P1','P2']
+    # initialize qubit with 200 ns pulse of P1,P2 to v_init
+    v_init = (46.0, 25.5)
+    seg.add_block(0, 200, gates, v_init, reset_time=True)
+    seg.wait(40, reset_time=True)
+
+Generate a Ramsey pulse sequence with two MW pulses for qubit 1 with a wait time in between.
+Channels can be accessed as an attribute of the segment (``seg.q1``), and as an index in the segment (``seg['q1']``).
+
+.. code-block:: python
+
+    seg.q1.add_MW_pulse(0, q1_X90_t, q1_X90_amplitude)
+    seg.q1.wait(t_wait, reset_time=True)
+    seg.q1.add_MW_pulse(0, q1_X90_t, q1_X90_amplitude)
+    seg.wait(20, reset_time=True)
+
+Move the qubit to the readout point and start measurement 140 ns after start of the block pulse.
+
+.. code-block:: python
+
+    v_readout = (46.0, 25.5)
+    seg.add_ramp(0, 200, gates, (0.0, 0.0), v_readout, reset_time=True)
+    seg.S1.acquire(140, t_measure=1500)
+    seg.add_block(0, 1700, gates, v_readout, reset_time=True)
+
+Execute the sequence
+--------------------
+
+The segments have to be compiled to a sequence. The sequence has to be uploaded to the AWGs before execution.
+The acquired data can be retrieved with the acquisition parameter. This is a qcodes MultiParameter.
+
+.. code-block:: python
+
+    seq = pl.make_sequence([seg])
+    acq_param = seq.get_acquisition_param()
+
+    # upload sequence data to AWG
+    seq.upload()
+    # play the sequence
+    seq.play()
+
+    # retrieve measurement data
+    data = acq_param()
+

docs/user/configuration.rst

+.. title: pulse_lib configuration
+
+Configuration
+=============
+
+The configuration of pulse_lib is stored in a pulselib object.
+This object is needed to create segments and sequences.
+
+Create pulselib object with specific backend
+---------------------------------------------
+
+A pulselib object must created for a specific backend for the hardware.
+
+.. code-block:: python
+
+    from pulse_lib.base_pulse import pulselib
+
+    pl = pulselib('Keysight')
+
+    # Add channels ...
+    # Configure channels ....
+
+At the end, after adding and configuring all channels, ``pl.finish_init()``
+must be called to complete the initialization.
+
+
+Add AWGs and digitizers
+-----------------------
+
+.. code-block:: python
+
+    pl.add_awg(awg1)
+    pl.add_awg(awg2)
+    pl.add_digitizer(digitizer)
+
+Note: Qblox QRM should be added as a digitizer. See @@@
+
+Gates (voltage channels)
+------------------------
+
+Gates (voltage channels) should be defined with a name for the channel and
+a name and channel number of the AWG.
+
+The channel delay specifies the amount of delay that should be added to the signal.
+The channel attenuation is expressed in the fraction of the amplitude after attenuation.
+The DC compensation limits are specified in AWG voltage before attenuation.
+
+.. code-block:: python
+
+    pl.add_channel("P1', awg1.name, 1)
+    pl.add_channel_delay('P1', 17)
+
+    # 0.01 = -20 dB attenuation
+    pl.add_channel_attenuation('P1', 0.01)
+
+    # Add limits on voltages for DC channel compensation.
+    # When no limit is specified then no DC compensation is performed.
+    # Limits are specified in AWG voltage before attenuation.
+    pl.add_channel_compensation_limit('P1', (-200, 500))
+
+    # Add compensation for bias-T with RC-time of 0.109 s
+    pl.add_channel_bias_T_compensation('P1', 0.109)
+
+Virtual matrix
+--------------
+
+``keep_square`` and @@@ are optional parameters that can only be set when ``real2virtual=True``. ???
+
+.. 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,
+        keep_square=Tue,
+        @@@)
+
+      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)
+
+Qubit channels (MW channels)
+----------------------------
+
+.. code-block:: python
+
+    from pulse_lib.virtual_channel_constructors import IQ_channel_constructor
+
+    pl.add_channel("I1', awg2.name, 3)
+    pl.add_channel("Q1', awg2.name, 4)
+    pl.add_channel_delay('I1', -52)
+    pl.add_channel_delay('Q1', -52)
+
+    # define IQ output pair
+    IQ_pair_1 = IQ_channel_constructor(pulse)
+    IQ_pair_1.add_IQ_chan("I1", "I")
+    IQ_pair_1.add_IQ_chan("Q1", "Q")
+
+    # frequency of the MW source
+    IQ_pair_1.set_LO(lo_freq)
+
+    # add channel for qubit q1
+    IQ_pair_1.add_virtual_IQ_channel("q1", 3.213e9)
+
+IQ phase-gain compensation
+Offset
+add marker
+
+
+Marker channels
+---------------
+
+delay
+
+
+Digitizer channels
+------------------
+
+Note: Digitizers  triggers
+
+.. code-block:: python
+
+    pl.define_digitizer_channel('SD1', digitizer.name, 1)
+
+IQ input pair
+
+RF-source
+