Add execution time to core operations and documentation

b_asic/core_operations.py

@@ -16,12 +16,12 @@ from b_asic.port import SignalSourceProvider
 
 
 class Constant(AbstractOperation):
-    """
+    r"""
     Constant value operation.
 
     Gives a specified value that remains constant for every iteration.
 
-    output(0): self.param("value")
+    .. math:: y = \text{value}
 
     Parameters
     ==========
@@ -36,9 +36,7 @@ class Constant(AbstractOperation):
     _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,
@@ -71,8 +69,7 @@ class Addition(AbstractOperation):
 
     Gives the result of adding two inputs.
 
-    output(0): input(0) + input(1)
-
+    .. math:: y = x_0 + x_1
 
     Parameters
     ==========
@@ -81,15 +78,15 @@ class Addition(AbstractOperation):
         The two signals to add.
     name : Name, optional
         Operation name.
-    latency: int, optional
+    latency : int, optional
         Operation latency (delay from input to output in time units).
-    latency_offsets: dict[str, int], optional
+    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
+    execution_time : int, optional
         Operation execution time (time units before operator can be
         reused).
 
@@ -135,7 +132,7 @@ class Subtraction(AbstractOperation):
 
     Gives the result of subtracting the second input from the first one.
 
-    output(0): input(0) - input(1)
+    .. math:: y = x_0 - x_1
 
     Parameters
     ==========
@@ -144,15 +141,15 @@ class Subtraction(AbstractOperation):
         The two signals to subtract.
     name : Name, optional
         Operation name.
-    latency: int, optional
+    latency : int, optional
         Operation latency (delay from input to output in time units).
-    latency_offsets: dict[str, int], optional
+    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
+    execution_time : int, optional
         Operation execution time (time units before operator can be
         reused).
 
@@ -170,9 +167,7 @@ class Subtraction(AbstractOperation):
         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,
@@ -192,13 +187,16 @@ class Subtraction(AbstractOperation):
 
 
 class AddSub(AbstractOperation):
-    """
+    r"""
     Two-input addition or subtraction operation.
 
     Gives the result of adding or subtracting two inputs.
 
-    output(0): input(0) + input(1) if is_add = True
-    output(0): input(0) - input(1) if is_add = False
+    .. math::
+        y = \begin{cases}
+        x_0 + x_1,& \text{is_add} = \text{True}\\
+        x_0 - x_1,& \text{is_add} = \text{False}
+        \end{cases}
 
     This is used to later map additions and subtractions to the same
     operator.
@@ -212,15 +210,15 @@ class AddSub(AbstractOperation):
         The two signals to add or subtract.
     name : Name, optional
         Operation name.
-    latency: int, optional
+    latency : int, optional
         Operation latency (delay from input to output in time units).
-    latency_offsets: dict[str, int], optional
+    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
+    execution_time : int, optional
         Operation execution time (time units before operator can be
         reused).
 
@@ -239,9 +237,7 @@ class AddSub(AbstractOperation):
         latency_offsets: Optional[Dict[str, int]] = None,
         execution_time: Optional[int] = None,
     ):
-        """
-        Construct an Addition/Subtraction operation.
-        """
+        """Construct an Addition/Subtraction operation."""
         super().__init__(
             input_count=2,
             output_count=1,
@@ -272,12 +268,12 @@ class AddSub(AbstractOperation):
 
 
 class Multiplication(AbstractOperation):
-    """
+    r"""
     Binary multiplication operation.
 
     Gives the result of multiplying two inputs.
 
-    output(0): input(0) * input(1)
+    .. math:: y = x_0 \times x_1
 
     Parameters
     ==========
@@ -286,15 +282,15 @@ class Multiplication(AbstractOperation):
         The two signals to multiply.
     name : Name, optional
         Operation name.
-    latency: int, optional
+    latency : int, optional
         Operation latency (delay from input to output in time units).
-    latency_offsets: dict[str, int], optional
+    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
+    execution_time : int, optional
         Operation execution time (time units before operator can be
         reused).
 
@@ -309,9 +305,7 @@ class Multiplication(AbstractOperation):
         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,
@@ -331,12 +325,13 @@ class Multiplication(AbstractOperation):
 
 
 class Division(AbstractOperation):
-    """
+    r"""
     Binary division operation.
 
     Gives the result of dividing the first input by the second one.
 
-    output(0): input(0) / input(1)
+    .. math:: y = \frac{x_0}{x_1}
+
     """
 
     def __init__(
@@ -368,12 +363,12 @@ class Division(AbstractOperation):
 
 
 class Min(AbstractOperation):
-    """
+    r"""
     Binary min operation.
 
     Gives the minimum value of two inputs.
 
-    output(0): min(input(0), input(1))
+    .. math:: y = \min\{x_0 , x_1\}
 
     .. note:: Only real-valued numbers are supported.
     """
@@ -411,13 +406,12 @@ class Min(AbstractOperation):
 
 
 class Max(AbstractOperation):
-    """
+    r"""
     Binary max operation.
 
     Gives the maximum value of two inputs.
-    NOTE: Non-real numbers are not supported.
 
-    output(0): max(input(0), input(1))
+    .. math:: y = \max\{x_0 , x_1\}
 
     .. note:: Only real-valued numbers are supported.
     """
@@ -460,7 +454,7 @@ class SquareRoot(AbstractOperation):
 
     Gives the square root of its input.
 
-    $$y = \sqrt{x}$$
+    .. math:: y = \sqrt{x}
     """
 
     def __init__(
@@ -496,7 +490,7 @@ class ComplexConjugate(AbstractOperation):
 
     Gives the complex conjugate of its input.
 
-    output(0): conj(input(0))
+    .. math:: y = x^*
     """
 
     def __init__(
@@ -532,7 +526,7 @@ class Absolute(AbstractOperation):
 
     Gives the absolute value of its input.
 
-    output(0): abs(input(0))
+    .. math:: y = |x|
     """
 
     def __init__(
@@ -563,12 +557,12 @@ class Absolute(AbstractOperation):
 
 
 class ConstantMultiplication(AbstractOperation):
-    """
+    r"""
     Constant multiplication operation.
 
     Gives the result of multiplying its input by a specified value.
 
-    output(0): self.param("value") * input(0)
+    .. math:: y = x_0 \times \text{value}
     """
 
     def __init__(
@@ -612,14 +606,17 @@ class ConstantMultiplication(AbstractOperation):
 
 
 class Butterfly(AbstractOperation):
-    """
-    Butterfly operation.
+    r"""
+    Radix-2 Butterfly operation.
 
     Gives the result of adding its two inputs, as well as the result of
     subtracting the second input from the first one.
 
-    output(0): input(0) + input(1)
-    output(1): input(0) - input(1)
+    .. math::
+        \begin{eqnarray}
+        y_0 = x_0 + x_1\\
+        y_1 = x_0 - x_1
+        \end{eqnarray}
     """
 
     def __init__(
@@ -651,13 +648,13 @@ class Butterfly(AbstractOperation):
 
 
 class MAD(AbstractOperation):
-    """
+    r"""
     Multiply-add operation.
 
     Gives the result of multiplying the first input by the second input and
     then adding the third input.
 
-    output(0): (input(0) * input(1)) + input(2)
+    .. math:: y = x_0 \times x_1 + x_2
     """
 
     def __init__(
@@ -690,11 +687,14 @@ class MAD(AbstractOperation):
 
 
 class SymmetricTwoportAdaptor(AbstractOperation):
-    """
+    r"""
     Symmetric twoport-adaptor operation.
 
-    output(0): input(1) + value*(input(1) - input(0)
-    output(1): input(0) + value*(input(1) - input(0)
+    .. math::
+        \begin{eqnarray}
+        y_0 = x_1 + \text{value}\times\left(x_1 - x_0\right)\\
+        y_1 = x_0 + \text{value}\times\left(x_1 - x_0\right)
+        \end{eqnarray}
     """
 
     def __init__(