Documentation and some refactoring in instructions.py.

doc/source/qctoolkit.pulses.rst

@@ -9,110 +9,110 @@ qctoolkit.pulses.branch_pulse_template module
 
 .. automodule:: qctoolkit.pulses.branch_pulse_template
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.conditions module
 ----------------------------------
 
 .. automodule:: qctoolkit.pulses.conditions
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.function_pulse_template module
 -----------------------------------------------
 
 .. automodule:: qctoolkit.pulses.function_pulse_template
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.instructions module
 ------------------------------------
 
 .. automodule:: qctoolkit.pulses.instructions
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.interpolation module
 -------------------------------------
 
 .. automodule:: qctoolkit.pulses.interpolation
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.loop_pulse_template module
 -------------------------------------------
 
 .. automodule:: qctoolkit.pulses.loop_pulse_template
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.parameters module
 ----------------------------------
 
 .. automodule:: qctoolkit.pulses.parameters
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.plotting module
 --------------------------------
 
 .. automodule:: qctoolkit.pulses.plotting
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.pulse_template module
 --------------------------------------
 
 .. automodule:: qctoolkit.pulses.pulse_template
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.repetition_pulse_template module
 -------------------------------------------------
 
 .. automodule:: qctoolkit.pulses.repetition_pulse_template
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.sequence_pulse_template module
 -----------------------------------------------
 
 .. automodule:: qctoolkit.pulses.sequence_pulse_template
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.sequencing module
 ----------------------------------
 
 .. automodule:: qctoolkit.pulses.sequencing
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 qctoolkit.pulses.table_pulse_template module
 --------------------------------------------
 
 .. automodule:: qctoolkit.pulses.table_pulse_template
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 
 Module contents
 ---------------
 
 .. automodule:: qctoolkit.pulses
     :members:
-    :undoc-members:
     :show-inheritance:
+    :special-members: __init__

doc/source/qctoolkit.rst

@@ -19,9 +19,8 @@ qctoolkit.comparable module
 
 .. automodule:: qctoolkit.comparable
     :members:
-    :undoc-members:
     :show-inheritance:
-    :inherited-members:
+    :special-members: __init__
 
 qctoolkit.expressions module
 ----------------------------

qctoolkit/pulses/instructions.py

@@ -1,47 +1,65 @@
+"""This module defines the abstract hardware instruction model of the qc-toolkit.
+
+Classes:
+    Waveform: An instantiated pulse which can be sampled to a raw voltage value array.
+    Trigger: Representation of a hardware trigger.
+    Instruction: Base class for hardware instructions.
+    CJMPInstruction: Conditional jump instruction.
+    EXECInstruction: Instruction to execute a waveform.
+    GOTOInstruction: Unconditional jump instruction.
+    STOPInstruction: Instruction which indicates the end of execution.
+    InstructionBlock: A block of instructions which are not yet embedded in a global sequence
+    InstructionSequence: A single final sequence of instructions.
+    InstructionPointer: References an instruction's location in a sequence.
+"""
+
 from abc import ABCMeta, abstractmethod, abstractproperty
-from typing import List, Tuple, Any, NamedTuple
+from typing import List, Any
 import numpy
 
-"""RELATED THIRD PARTY IMPORTS"""
-
-"""LOCAL IMPORTS"""
 from qctoolkit.comparable import Comparable
 
-from qctoolkit.pulses.interpolation import InterpolationStrategy
-
 # TODO lumip: add docstrings
 
-
-
-__all__ = ["WaveformTable", "WaveformTableEntry", "Waveform", "Trigger", "InstructionPointer", "Instruction",
-           "CJMPInstruction", "EXECInstruction", "GOTOInstruction", "STOPInstruction", "InstructionBlock",
-           "InstructionSequence", "InstructionBlockNotYetPlacedException", "InstructionBlockAlreadyFinalizedException",
+__all__ = ["Waveform", "Trigger", "InstructionPointer",
+           "Instruction", "CJMPInstruction", "EXECInstruction", "GOTOInstruction",
+           "STOPInstruction", "InstructionBlock", "InstructionSequence",
+           "InstructionBlockNotYetPlacedException", "InstructionBlockAlreadyFinalizedException",
            "MissingReturnAddressException"
           ]
 
 
-WaveformTableEntry = NamedTuple("WaveformTableEntry", [('t', float), ('v', float), ('interp', InterpolationStrategy)])
-WaveformTable = Tuple[WaveformTableEntry, ...]
-
-
 class Waveform(Comparable, metaclass=ABCMeta):
+    """Represents an instantiated PulseTemplate which can be sampled to retrieve arrays of voltage
+    values for the hardware."""
 
     @abstractproperty
     def duration(self) -> float:
-        """Return the duration of the waveform in time units."""
+        """The duration of the waveform in time units."""
 
     @abstractmethod
     def sample(self, sample_times: numpy.ndarray, first_offset: float=0) -> numpy.ndarray:
-        """Sample the waveform.
-
-        Will be sampled at the given sample_times. These, however, will be normalized such that the lie in the range
-        [0, waveform.duration] for interpolation.
-        first_offset is the offset of the discrete first sample from the actual beginning of the waveform
-        in a continuous time domain.
+        """Sample the waveform at given sample times.
+
+        The only requirement on the provided sample times is that they must be monotonously
+        increasing. The must not lie in the range of [0, waveform.duration] (but will be normalized
+        internally into that range for the sampling). For example, if this Waveform had a duration
+        of 5 and the given sample times would be [11, 15, 20], the result would be the samples of
+        this Waveform at [0, 2.5, 5] in the Waveforms domain. This allows easier sampling of
+        multiple subsequent Waveforms.
+
+        Args:
+            numpy.ndarray sample_times: Times at which this Waveform will be sampled. Will be
+                normalized such that they lie in the range [0, waveform.duration] for interpolation.
+            float first_offset: Offset of the discrete first sample from the actual beginning of
+                the waveform in a continuous time domain.
+        Result:
+            numpy.ndarray of the sampled values of this Waveform at the provided sample times.
         """
 
 
 class Trigger(Comparable):
+    """Abstract representation of a hardware trigger for hardware based branching decisions."""
 
     def __init__(self) -> None:
         super().__init__()
@@ -55,6 +73,10 @@ def __str__(self) -> str:
 
 
 class InstructionPointer(Comparable):
+    """Reference to the location of an InstructionBlock.
+
+    Used
+    """
 
     def __init__(self, block: 'InstructionBlock', offset: int) -> None:
         super().__init__()
@@ -68,24 +90,30 @@ def get_absolute_address(self) -> int:
 
     @property
     def compare_key(self) -> Any:
-        return (id(self.block), self.offset)
+        return id(self.block), self.offset
 
     def __str__(self) -> str:
         try:
             return "{}".format(self.get_absolute_address())
-        finally:
+        except InstructionBlockNotYetPlacedException:
             return "IP:{0}#{1}".format(self.block, self.offset)
 
 
-class Instruction(Comparable, metaclass = ABCMeta):
+class Instruction(Comparable, metaclass=ABCMeta):
+    """A hardware instruction."""
 
     def __init__(self) -> None:
         super().__init__()
 
+    @abstractmethod
+    def compare_key(self) -> Any:
+        pass
+
 
 class CJMPInstruction(Instruction):
+    """A conditional jump hardware instruction."""
 
-    def __init__(self, trigger: Trigger, block: 'InstructionBlock', offset: int = 0) -> None:
+    def __init__(self, trigger: Trigger, block: 'InstructionBlock', offset: int=0) -> None:
         super().__init__()
         self.trigger = trigger
         self.target = InstructionPointer(block, offset)
@@ -100,7 +128,7 @@ def __str__(self) -> str:
 
 class GOTOInstruction(Instruction):
 
-    def __init__(self, block: 'InstructionBlock', offset: int = 0) -> None:
+    def __init__(self, block: 'InstructionBlock', offset: int=0) -> None:
         super().__init__()
         self.target = InstructionPointer(block, offset)
 
@@ -146,9 +174,11 @@ def __str__(self) -> str:
 
 
 class InstructionBlockNotYetPlacedException(Exception):
-    """Indicates that an attempt was made to obtain the start address of an InstructionBlock that was not yet placed inside the corresponding outer block."""
+    """Indicates that an attempt was made to obtain the start address of an InstructionBlock that
+    was not yet placed inside the corresponding outer block."""
     def __str__(self) -> str:
-        return "An attempt was made to obtain the start address of an InstructionBlock that was not yet finally placed inside the corresponding outer block."
+        return "An attempt was made to obtain the start address of an InstructionBlock that was " \
+               "not yet finally placed inside the corresponding outer block."
 
 
 class MissingReturnAddressException(Exception):
@@ -162,7 +192,7 @@ def __str__(self) -> str:
 
 class InstructionBlock(Comparable):
 
-    def __init__(self, outer_block: 'InstructionBlock' = None) -> None:
+    def __init__(self, outer_block: 'InstructionBlock'=None) -> None:
         super().__init__()
         self.__instruction_list = [] # type: InstructionSequence
         self.__embedded_blocks = [] # type: List[InstructionBlock]
@@ -184,10 +214,13 @@ def add_instruction(self, instruction: Instruction) -> None:
     def add_instruction_exec(self, waveform: Waveform) -> None:
         self.add_instruction(EXECInstruction(waveform))
 
-    def add_instruction_goto(self, target_block: 'InstructionBlock', offset: int = 0) -> None:
+    def add_instruction_goto(self, target_block: 'InstructionBlock', offset: int=0) -> None:
         self.add_instruction(GOTOInstruction(target_block, offset))
 
-    def add_instruction_cjmp(self, trigger: Trigger, target_block: 'InstructionBlock', offset: int = 0) -> None:
+    def add_instruction_cjmp(self,
+                             trigger: Trigger,
+                             target_block: 'InstructionBlock',
+                             offset: int=0) -> None:
         self.add_instruction(CJMPInstruction(trigger, target_block, offset))
 
     def add_instruction_stop(self) -> None:
@@ -216,15 +249,16 @@ def compile_sequence(self) -> InstructionSequence:
         if self.__outer_block is None:
             self.__compiled_sequence.append(STOPInstruction())
         elif self.return_ip is not None:
-            self.__compiled_sequence.append(GOTOInstruction(self.return_ip.block, self.return_ip.offset))
+            self.__compiled_sequence.append(
+                GOTOInstruction(self.return_ip.block, self.return_ip.offset))
         else:
             self.__compiled_sequence = None
             raise MissingReturnAddressException()
 
         for block in self.__embedded_blocks:
             block.__offset = len(self.__compiled_sequence)
-            blockSequence = block.compile_sequence()
-            self.__compiled_sequence.extend(blockSequence)
+            block_sequence = block.compile_sequence()
+            self.__compiled_sequence.extend(block_sequence)
 
         return self.__compiled_sequence
 
@@ -244,4 +278,4 @@ def compare_key(self) -> Any:
         return id(self)
 
     def __str__(self) -> str:
-        return str(hash(self))
+        return str(hash(self))