Merge pull request #783 from qutech/issues/779_program_loop

Move _program._loop to program.loop

changes.d/779.feature

@@ -0,0 +1 @@
+Promote parts of the private subpackage `qupulse._program` to the public subpackage `qupulse.program`, i.e. `loop`, `volatile`, `transformation` and `waveforms`. This allows external packages/drivers to rely on stability of the `Loop` class.

doc/source/concepts/program.rst

@@ -4,14 +4,19 @@ Instantiated Pulse: Program
 ---------------------------
 
 In qupulse an instantiated pulse template is called a program as it is something that an arbitrary waveform generator
-(AWG) can execute/playback. It is created by the `create_program` method of the pulse template which returns a hardware
-independent representation which is currently of type ``Loop``. Opposed to the `PulseTemplate` interfaces the interface of the program is currently not covered by the qupulse backward compatibility and stability guarantee.
-This is reflected by the fact that it lives in the private module ``qupulse._program._loop``.
+(AWG) can execute/playback.
+It is created by the ``create_program`` method of the pulse template which returns a hardware
+independent representation which is of type ``Loop``.
+This ``Loop`` object is the root node of a tree ``Loop``s of arbitrary depth.
+Each node consists of a repetition count and either a waveform or a sequence of nodes which are repeated that many times.
+Iterations like the ```ForLoopPT`` cannot be represented natively but are unrolled into a sequence of items.
+The repetition count is currently the only property of a program that can be defined as volatile. This means that the AWG driver tries to upload the program in a way, where the repetition count can quickly be changed. This is implemented via the ```VolatileRepetitionCount`` class.
 
-There is no description of the details of the program object here to avoid outdated documentation.
+There is no description of the details of the program object here to avoid duplicated and outdated documentation.
 The documentation is in the docstrings of the source code.
 The program can be thought of as compact representation of a mapping :math:`\{t | 0 \le t \le t_{\texttt{duration}}} \rightarrow \mathbb{R}^n` from the time while the program lasts :math:´t´ to an n-dimensional voltage space :math:´\mathbb{R}^n´.
 The dimensions are named by the channel names.
 
-The subpackage ``_qupulse._program`` also contains hardware specific translations of the programs for example a
-transpiler to Zurich Instruments sequencing C in ``_qupulse._program.seqc``.
+The ``Loop`` class and its constituents ``Waveform`` and ``VolatileRepetitionCount`` are defined in the ``qupulse.program`` subpackage and it's submodules.
+The private subpackage ``qupulse._program`` contains AWG driver internals that can change with any release, for example a
+transpiler to Zurich Instruments sequencing C in ``qupulse._program.seqc``.