Add execution time to core operations and documentation

b_asic/core_operations.py

@@ -22,12 +22,23 @@ class Constant(AbstractOperation):
     Gives a specified value that remains constant for every iteration.
 
     output(0): self.param("value")
+
+    Parameters
+    ==========
+
+    value : Number, default: 0
+        The constant value.
+    name : Name, optional
+        Operation name.
+
     """
 
     _execution_time = 0
 
     def __init__(self, value: Number = 0, name: Name = Name("")):
-        """Construct a Constant operation with the given value."""
+        """
+        Construct a Constant operation with the given value.
+        """
         super().__init__(
             input_count=0,
             output_count=1,
@@ -61,6 +72,31 @@ class Addition(AbstractOperation):
     Gives the result of adding two inputs.
 
     output(0): input(0) + input(1)
+
+
+    Parameters
+    ==========
+
+    src0, src1 : SignalSourceProvider, optional
+        The two signals to add.
+    name : Name, optional
+        Operation name.
+    latency: int, optional
+        Operation latency (delay from input to output in time units).
+    latency_offsets: dict[str, int], optional
+        Used if inputs have different arrival times, e.g.,
+        ``{"in0": 0, "in1": 1}`` which corresponds to *src1* arriving one
+        time unit later than *src0*. If not provided and *latency* is
+        provided, set to zero if not explicitly provided. So the previous
+        example can be written as ``{"in1": 1}`` only.
+    execution_time: int, optional
+        Operation execution time (time units before operator can be
+        reused).
+
+    See also
+    ========
+    AddSub
+
     """
 
     def __init__(
@@ -70,8 +106,11 @@ class Addition(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
-        """Construct an Addition operation."""
+        """
+        Construct an Addition operation.
+        """
         super().__init__(
             input_count=2,
             output_count=1,
@@ -79,6 +118,7 @@ class Addition(AbstractOperation):
             input_sources=[src0, src1],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -96,6 +136,29 @@ class Subtraction(AbstractOperation):
     Gives the result of subtracting the second input from the first one.
 
     output(0): input(0) - input(1)
+
+    Parameters
+    ==========
+
+    src0, src1 : SignalSourceProvider, optional
+        The two signals to subtract.
+    name : Name, optional
+        Operation name.
+    latency: int, optional
+        Operation latency (delay from input to output in time units).
+    latency_offsets: dict[str, int], optional
+        Used if inputs have different arrival times, e.g.,
+        ``{"in0": 0, "in1": 1}`` which corresponds to *src1* arriving one
+        time unit later than *src0*. If not provided and *latency* is
+        provided, set to zero if not explicitly provided. So the previous
+        example can be written as ``{"in1": 1}`` only.
+    execution_time: int, optional
+        Operation execution time (time units before operator can be
+        reused).
+
+    See also
+    ========
+    AddSub
     """
 
     def __init__(
@@ -105,8 +168,11 @@ class Subtraction(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
-        """Construct a Subtraction operation."""
+        """
+        Construct a Subtraction operation.
+        """
         super().__init__(
             input_count=2,
             output_count=1,
@@ -114,6 +180,7 @@ class Subtraction(AbstractOperation):
             input_sources=[src0, src1],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -132,6 +199,34 @@ class AddSub(AbstractOperation):
 
     output(0): input(0) + input(1) if is_add = True
     output(0): input(0) - input(1) if is_add = False
+
+    This is used to later map additions and subtractions to the same
+    operator.
+
+    Parameters
+    ==========
+
+    is_add : bool, default: True
+        If True, the operation is an addition, if False, a subtraction.
+    src0, src1 : SignalSourceProvider, optional
+        The two signals to add or subtract.
+    name : Name, optional
+        Operation name.
+    latency: int, optional
+        Operation latency (delay from input to output in time units).
+    latency_offsets: dict[str, int], optional
+        Used if inputs have different arrival times, e.g.,
+        ``{"in0": 0, "in1": 1}`` which corresponds to *src1* arriving one
+        time unit later than *src0*. If not provided and *latency* is
+        provided, set to zero if not explicitly provided. So the previous
+        example can be written as ``{"in1": 1}`` only.
+    execution_time: int, optional
+        Operation execution time (time units before operator can be
+        reused).
+
+    See also
+    ========
+    Addition, Subtraction
     """
 
     def __init__(
@@ -142,8 +237,11 @@ class AddSub(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
-        """Construct an Addition operation."""
+        """
+        Construct an Addition/Subtraction operation.
+        """
         super().__init__(
             input_count=2,
             output_count=1,
@@ -151,6 +249,7 @@ class AddSub(AbstractOperation):
             input_sources=[src0, src1],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
         self.set_param("is_add", is_add)
 
@@ -179,6 +278,26 @@ class Multiplication(AbstractOperation):
     Gives the result of multiplying two inputs.
 
     output(0): input(0) * input(1)
+
+    Parameters
+    ==========
+
+    src0, src1 : SignalSourceProvider, optional
+        The two signals to multiply.
+    name : Name, optional
+        Operation name.
+    latency: int, optional
+        Operation latency (delay from input to output in time units).
+    latency_offsets: dict[str, int], optional
+        Used if inputs have different arrival times, e.g.,
+        ``{"in0": 0, "in1": 1}`` which corresponds to *src1* arriving one
+        time unit later than *src0*. If not provided and *latency* is
+        provided, set to zero if not explicitly provided. So the previous
+        example can be written as ``{"in1": 1}`` only.
+    execution_time: int, optional
+        Operation execution time (time units before operator can be
+        reused).
+
     """
 
     def __init__(
@@ -188,8 +307,11 @@ class Multiplication(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
-        """Construct a Multiplication operation."""
+        """
+        Construct a Multiplication operation.
+        """
         super().__init__(
             input_count=2,
             output_count=1,
@@ -197,6 +319,7 @@ class Multiplication(AbstractOperation):
             input_sources=[src0, src1],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -223,6 +346,7 @@ class Division(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
         """Construct a Division operation."""
         super().__init__(
@@ -232,6 +356,7 @@ class Division(AbstractOperation):
             input_sources=[src0, src1],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -247,9 +372,10 @@ class Min(AbstractOperation):
     Binary min operation.
 
     Gives the minimum value of two inputs.
-    NOTE: Non-real numbers are not supported.
 
     output(0): min(input(0), input(1))
+
+    .. note:: Only real-valued numbers are supported.
     """
 
     def __init__(
@@ -259,6 +385,7 @@ class Min(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
         """Construct a Min operation."""
         super().__init__(
@@ -268,6 +395,7 @@ class Min(AbstractOperation):
             input_sources=[src0, src1],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -290,6 +418,8 @@ class Max(AbstractOperation):
     NOTE: Non-real numbers are not supported.
 
     output(0): max(input(0), input(1))
+
+    .. note:: Only real-valued numbers are supported.
     """
 
     def __init__(
@@ -299,6 +429,7 @@ class Max(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
         """Construct a Max operation."""
         super().__init__(
@@ -308,6 +439,7 @@ class Max(AbstractOperation):
             input_sources=[src0, src1],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -323,12 +455,12 @@ class Max(AbstractOperation):
 
 
 class SquareRoot(AbstractOperation):
-    """
+    r"""
     Square root operation.
 
     Gives the square root of its input.
 
-    output(0): sqrt(input(0))
+    $$y = \sqrt{x}$$
     """
 
     def __init__(
@@ -337,6 +469,7 @@ class SquareRoot(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
         """Construct a SquareRoot operation."""
         super().__init__(
@@ -346,6 +479,7 @@ class SquareRoot(AbstractOperation):
             input_sources=[src0],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -371,6 +505,7 @@ class ComplexConjugate(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
         """Construct a ComplexConjugate operation."""
         super().__init__(
@@ -380,6 +515,7 @@ class ComplexConjugate(AbstractOperation):
             input_sources=[src0],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -405,6 +541,7 @@ class Absolute(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
         """Construct an Absolute operation."""
         super().__init__(
@@ -414,6 +551,7 @@ class Absolute(AbstractOperation):
             input_sources=[src0],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -440,6 +578,7 @@ class ConstantMultiplication(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
         """Construct a ConstantMultiplication operation with the given value.
         """
@@ -450,6 +589,7 @@ class ConstantMultiplication(AbstractOperation):
             input_sources=[src0],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
         self.set_param("value", value)
 
@@ -489,6 +629,7 @@ class Butterfly(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
         """Construct a Butterfly operation."""
         super().__init__(
@@ -498,6 +639,7 @@ class Butterfly(AbstractOperation):
             input_sources=[src0, src1],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -526,6 +668,7 @@ class MAD(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
         """Construct a MAD operation."""
         super().__init__(
@@ -535,6 +678,7 @@ class MAD(AbstractOperation):
             input_sources=[src0, src1, src2],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
 
     @classmethod
@@ -561,6 +705,7 @@ class SymmetricTwoportAdaptor(AbstractOperation):
         name: Name = Name(""),
         latency: Optional[int] = None,
         latency_offsets: Optional[Dict[str, int]] = None,
+        execution_time: Optional[int] = None,
     ):
         """Construct a Butterfly operation."""
         super().__init__(
@@ -570,6 +715,7 @@ class SymmetricTwoportAdaptor(AbstractOperation):
             input_sources=[src0, src1],
             latency=latency,
             latency_offsets=latency_offsets,
+            execution_time=execution_time,
         )
         self.set_param("value", value)