compiled-knowledge 4.0.0a16__cp312-cp312-win_amd64.whl → 4.0.0a18__cp312-cp312-win_amd64.whl

ck/circuit/__init__.py

@@ -1,5 +1,12 @@
-# from .circuit_py import (
-from .circuit import (
+# There are two implementations of the `circuit` module are provided
+# for developer R&D purposes. One is pure Python and the other is Cython.
+# Which implementation is used can be selected here.
+# A similar selection can be made for the `circuit_table` module.
+# Note that if the Cython implementation is chosen for `circuit_table` then
+# the Cython implementation must be chosen for `circuit`.
+
+# from ._circuit_py import (
+from ._circuit_cy import (
     Circuit,
     CircuitNode,
     VarNode,

ck/circuit/_circuit_cy.pxd

@@ -0,0 +1,33 @@
+cdef class Circuit:
+    cdef public list[VarNode] vars
+    cdef public list[OpNode] ops
+    cdef public object zero
+    cdef public object one
+    cdef dict[object, ConstNode] _const_map
+    cdef object __derivatives
+
+    cdef OpNode op(self, int symbol, tuple[CircuitNode, ...] nodes)
+    cdef void _remove_unreachable_op_nodes(self, list[CircuitNode] nodes)
+    cdef list[OpNode] _reachable_op_nodes(self, list[CircuitNode] nodes)
+    cdef list[CircuitNode] _check_nodes(self, object nodes)
+    cdef void __check_nodes(self, object nodes, list[CircuitNode] result)
+    cdef object _derivatives(self, CircuitNode f)
+    cdef object _derivatives(self, CircuitNode f)
+
+cdef class CircuitNode:
+    cdef public Circuit circuit
+    cdef public bint is_zero
+    cdef public bint is_one
+
+cdef class ConstNode(CircuitNode):
+    cdef public object value
+
+cdef class VarNode(CircuitNode):
+    cdef public int idx
+    cdef object _const
+
+    cpdef int is_const(self) except*
+
+cdef class OpNode(CircuitNode):
+    cdef public tuple[object, ...] args
+    cdef public int symbol

ck/circuit/{circuit.pyx → _circuit_cy.pyx}

@@ -4,7 +4,7 @@ For more documentation on this module, refer to the Jupyter notebook docs/6_circ
 from __future__ import annotations
 
 from itertools import chain
-from typing import Dict, Tuple, Optional, Iterable, Sequence, List, overload, Set, Any
+from typing import Dict, Tuple, Optional, Iterable, Sequence, List, overload
 
 # Type for values of ConstNode objects
 ConstValue = float | int | bool
@@ -15,6 +15,8 @@ Args = CircuitNode | ConstValue | Iterable[CircuitNode | ConstValue]
 ADD: int = 0
 MUL: int = 1
 
+cdef int c_ADD = ADD
+cdef int c_MUL = MUL
 
 cdef class Circuit:
     """
@@ -29,13 +31,6 @@ cdef class Circuit:
     `VarNode` may be temporarily be set to a constant value.
     """
 
-    cdef public list[VarNode] vars
-    cdef public list[OpNode] ops
-    cdef public object zero
-    cdef public object one
-    cdef dict[Any, ConstNode] _const_map
-    cdef object __derivatives
-
     def __init__(self, zero: ConstValue = 0, one: ConstValue = 1):
         """
         Construct a new, empty circuit.
@@ -48,8 +43,11 @@ cdef class Circuit:
         self.ops: List[OpNode] = []
         self._const_map: Dict[ConstValue, ConstNode] = {}
         self.__derivatives: Optional[_DerivativeHelper] = None  # cache for partial derivatives calculations.
-        self.zero: ConstNode = self.const(zero)
-        self.one: ConstNode = self.const(one)
+        self.zero: ConstNode = ConstNode(self, zero, is_zero=True)
+        self.one: ConstNode = ConstNode(self, one, is_one=True)
+
+        self._const_map[zero] = self.zero
+        self._const_map[one] = self.one
 
     @property
     def number_of_vars(self) -> int:
@@ -124,72 +122,57 @@ cdef class Circuit:
             self._const_map[value] = node
         return node
 
-    cdef object _op(self, int symbol, tuple[CircuitNode, ...] nodes):
-        cdef object node = OpNode(self, symbol, nodes)
-        self.ops.append(node)
-        return node
-
     def add(self, *nodes: Args) -> OpNode:
         """
         Create and return a new 'addition' node, applied to the given arguments.
         """
-        cdef list[object] args = self._check_nodes(nodes)
-        return self._op(ADD, tuple(args))
+        cdef list[CircuitNode] args = self._check_nodes(nodes)
+        return self.op(c_ADD, tuple(args))
 
     def mul(self, *nodes: Args) -> OpNode:
         """
         Create and return a new 'multiplication' node, applied to the given arguments.
         """
-        cdef list[object] args = self._check_nodes(nodes)
-        return self._op(MUL, tuple(args))
+        cdef list[CircuitNode] args = self._check_nodes(nodes)
+        return self.op(c_MUL, tuple(args))
 
-    cpdef object optimised_add(self, object nodes: Iterable[CircuitNode]):  # -> CircuitNode:
-        # Optimised circuit node addition.
-        #
-        # Performs the following optimisations:
-        # * addition to zero is avoided: add(x, 0) = x,
-        # * singleton addition is avoided: add(x) = x,
-        # * empty addition is avoided: add() = 0.
-
-        cdef list[object] to_add = []
-        cdef object n
-        for n in nodes:
-            if n.circuit is not self:
-                raise RuntimeError('node does not belong to this circuit')
-            if not n.is_zero():
-                to_add.append(n)
-        cdef int len_to_add = len(to_add)
-        if len_to_add == 0:
+    def optimised_add(self, *args: Args) -> CircuitNode:
+        """
+        Optimised circuit node addition.
+
+        Performs the following optimisations:
+        * addition to zero is avoided: add(x, 0) = x,
+        * singleton addition is avoided: add(x) = x,
+        * empty addition is avoided: add() = 0,
+        """
+        cdef tuple[CircuitNode] to_add = tuple(n for n in self._check_nodes(args) if not n.is_zero)
+        cdef size_t num_to_add = len(to_add)
+        if num_to_add == 0:
             return self.zero
-        elif len_to_add == 1:
+        if num_to_add == 1:
             return to_add[0]
-        else:
-            return self._op(ADD, tuple(to_add))
+        return self.op(c_ADD, to_add)
 
-    cpdef object optimised_mul(self, object nodes: Iterable[CircuitNode]):  # -> CircuitNode:
-        # Optimised circuit node multiplication.
-        #
-        # Performs the following optimisations:
-        # * multiplication by zero is avoided: mul(x, 0) = 0,
-        # * multiplication by one is avoided: mul(x, 1) = x,
-        # * singleton multiplication is avoided: mul(x) = x,
-        # * empty multiplication is avoided: mul() = 1.
-        cdef list[object] to_mul = []
-        cdef object n
-        for n in nodes:
-            if n.circuit is not self:
-                raise RuntimeError('node does not belong to this circuit')
-            if n.is_zero():
-                return self.zero
-            if not n.is_one():
-                to_mul.append(n)
-        cdef int len_to_mul = len(to_mul)
-        if len_to_mul == 0:
+    def optimised_mul(self, *args: Args) -> CircuitNode:
+        """
+        Optimised circuit node multiplication.
+
+        Performs the following optimisations:
+        * multiplication by zero is avoided: mul(x, 0) = 0,
+        * multiplication by one is avoided: mul(x, 1) = x,
+        * singleton multiplication is avoided: mul(x) = x,
+        * empty multiplication is avoided: mul() = 1,
+        """
+        cdef tuple[CircuitNode] to_mul = tuple(n for n in self._check_nodes(args) if not n.is_one)
+        if any(n.is_zero for n in to_mul):
+            return self.zero
+        cdef size_t num_to_mul = len(to_mul)
+
+        if num_to_mul == 0:
             return self.one
-        elif len_to_mul == 1:
+        if num_to_mul == 1:
             return to_mul[0]
-        else:
-            return self._op(MUL, tuple(to_mul))
+        return self.op(c_MUL, to_mul)
 
     def cartesian_product(self, xs: Sequence[CircuitNode], ys: Sequence[CircuitNode]) -> List[CircuitNode]:
         """
@@ -206,7 +189,7 @@ cdef class Circuit:
         xs: List[CircuitNode] = self._check_nodes(xs)
         ys: List[CircuitNode] = self._check_nodes(ys)
         return [
-            self.optimised_mul((x, y))
+            self.optimised_mul(x, y)
             for x in xs
             for y in ys
         ]
@@ -300,19 +283,8 @@ cdef class Circuit:
         Args:
             *nodes: may be either a node or a list of nodes.
         """
-        seen: Set[int] = set()  # set of object ids for all reachable op nodes.
-        for node in self._check_nodes(nodes):
-            _reachable_op_nodes_seen_r(node, seen)
-
-        if len(seen) < len(self.ops):
-            # Invalidate unreadable op nodes
-            for op_node in self.ops:
-                if id(op_node) not in seen:
-                    op_node.circuit = None
-                    op_node.args = ()
-
-            # Keep only reachable op nodes, in the same order as `self.ops`.
-            self.ops = [op_node for op_node in self.ops if id(op_node) in seen]
+        nodes = self._check_nodes(nodes)
+        self._remove_unreachable_op_nodes(nodes)
 
     def reachable_op_nodes(self, *nodes: Args) -> List[OpNode]:
         """
@@ -328,11 +300,8 @@ cdef class Circuit:
             Returned nodes are not repeated.
             The result is ordered such that if result[i] is referenced by result[j] then i < j.
         """
-        seen: Set[int] = set()  # set of object ids for all reachable op nodes.
-        result: List[OpNode] = []
-        for node in self._check_nodes(nodes):
-            _reachable_op_nodes_r(node, seen, result)
-        return result
+        nodes = self._check_nodes(nodes)
+        return self._reachable_op_nodes(nodes)
 
     def dump(
             self,
@@ -397,7 +366,41 @@ cdef class Circuit:
             args_str = ' '.join(node_name[id(arg)] for arg in op.args)
             print(f'{next_prefix}{op_name}: {args_str}')
 
-    cdef list[object] _check_nodes(self, object nodes: Iterable[Args]):  # -> Sequence[CircuitNode]:
+    cdef OpNode op(self, int symbol, tuple[CircuitNode, ...] nodes):
+        cdef OpNode node = OpNode(self, symbol, nodes)
+        self.ops.append(node)
+        return node
+
+    cdef list[OpNode] _reachable_op_nodes(self, list[CircuitNode] nodes):
+        # Set of object ids for all reachable op nodes
+        cdef set[int] seen = set()
+
+        cdef list[OpNode] result = []
+
+        cdef CircuitNode node
+        for node in nodes:
+            _reachable_op_nodes_r(node, seen, result)
+        return result
+
+    cdef void _remove_unreachable_op_nodes(self, list[CircuitNode] nodes):
+        # Set of object ids for all reachable op nodes
+        cdef set[int] seen = set()
+
+        cdef CircuitNode node
+        for node in nodes:
+            _reachable_op_nodes_seen_r(node, seen)
+
+        if len(seen) < len(self.ops):
+            # Invalidate unreadable op nodes
+            for op_node in self.ops:
+                if id(op_node) not in seen:
+                    op_node.circuit = None
+                    op_node.args = ()
+
+            # Keep only reachable op nodes, in the same order as `self.ops`.
+            self.ops = [op_node for op_node in self.ops if id(op_node) in seen]
+
+    cdef list[CircuitNode] _check_nodes(self, object nodes: Iterable[Args]):  # -> Sequence[CircuitNode]:
         # Convert the given circuit nodes to a tuple, flattening nested iterables as needed.
         #
         # Args:
@@ -405,11 +408,11 @@ cdef class Circuit:
         #
         # Raises:
         #     RuntimeError: if any node does not belong to this circuit.
-        cdef list[object] result = []
+        cdef list[CircuitNode] result = []
         self.__check_nodes(nodes, result)
         return result
 
-    cdef __check_nodes(self, nodes: Iterable[Args], list[object] result):
+    cdef void __check_nodes(self, object nodes: Iterable[Args], list[CircuitNode] result):
         # Convert the given circuit nodes to a tuple, flattening nested iterables as needed.
         #
         # Args:
@@ -428,7 +431,7 @@ cdef class Circuit:
             else:
                 self.__check_nodes(node, result)
 
-    cdef object _derivatives(self, object f: CircuitNode):  # -> _DerivativeHelper:
+    cdef object _derivatives(self, CircuitNode f):
         # Get a _DerivativeHelper for `f`.
         # Checking the derivative cache.
         derivatives: Optional[_DerivativeHelper] = self.__derivatives
@@ -437,7 +440,6 @@ cdef class Circuit:
             self.__derivatives = derivatives
         return derivatives
 
-
 cdef class CircuitNode:
     """
     A node in an arithmetic circuit.
@@ -452,16 +454,11 @@ cdef class CircuitNode:
     A var node may be temporarily set to be a constant node, which may
     be useful for optimising a compiled circuit.
     """
-    cdef public object circuit
 
-    def __init__(self, circuit):
+    def __init__(self, circuit: Circuit, is_zero: bool, is_one: bool):
         self.circuit = circuit
-
-    cpdef int is_zero(self) except*:
-        return False
-
-    cpdef int is_one(self) except*:
-        return False
+        self.is_zero = is_zero
+        self.is_one = is_one
 
     def __add__(self, other: CircuitNode | ConstValue):
         return self.circuit.add(self, other)
@@ -469,24 +466,14 @@ cdef class CircuitNode:
     def __mul__(self, other: CircuitNode | ConstValue):
         return self.circuit.mul(self, other)
 
-
 cdef class ConstNode(CircuitNode):
-    cdef public object value
-
     """
     A node in a circuit representing a constant value.
     """
-    def __init__(self, circuit, value: ConstValue):
-        super().__init__(circuit)
-        self.value: ConstValue = value
-
-    cpdef int is_zero(self) except*:
-        # noinspection PyProtectedMember
-        return self is self.circuit.zero
 
-    cpdef int is_one(self) except*:
-        # noinspection PyProtectedMember
-        return self is self.circuit.one
+    def __init__(self, circuit, value: ConstValue, is_zero: bool = False, is_one: bool = False):
+        super().__init__(circuit, is_zero, is_one)
+        self.value: ConstValue = value
 
     def __str__(self) -> str:
         return 'const(' + str(self.value) + ')'
@@ -497,25 +484,16 @@ cdef class ConstNode(CircuitNode):
         else:
             return False
 
-
 cdef class VarNode(CircuitNode):
     """
     A node in a circuit representing an input variable.
     """
-    cdef public int idx
-    cdef object _const
 
     def __init__(self, circuit, idx: int):
-        super().__init__(circuit)
+        super().__init__(circuit, False, False)
         self.idx = idx
         self._const = None
 
-    cpdef int is_zero(self) except*:
-        return self._const is not None and self._const.is_zero()
-
-    cpdef int is_one(self) except*:
-        return self._const is not None and self._const.is_one()
-
     cpdef int is_const(self) except*:
         return self._const is not None
 
@@ -527,8 +505,13 @@ cdef class VarNode(CircuitNode):
     def const(self, value: ConstValue | ConstNode | None) -> None:
         if value is None:
             self._const = None
+            self.is_zero = False
+            self.is_one = False
         else:
-            self._const = self.circuit.const(value)
+            const_node: ConstNode = self.circuit.const(value)
+            self._const = const_node
+            self.is_zero = const_node.is_zero
+            self.is_one = const_node.is_one
 
     def __lt__(self, other) -> bool:
         if isinstance(other, VarNode):
@@ -546,13 +529,11 @@ cdef class OpNode(CircuitNode):
     """
     A node in a circuit representing an arithmetic operation.
     """
-    cdef public tuple[object, ...] args
-    cdef public int symbol
 
     def __init__(self, object circuit, symbol: int, tuple[object, ...] args: Tuple[CircuitNode]):
-        super().__init__(circuit)
+        super().__init__(circuit, False, False)
         self.args = tuple(args)
-        self.symbol = int(symbol)
+        self.symbol = <int> symbol
 
     def __str__(self) -> str:
         return f'{self.op_str()}\\{len(self.args)}'
@@ -561,9 +542,9 @@ cdef class OpNode(CircuitNode):
         """
         Returns the op node operation as a string.
         """
-        if self.symbol == MUL:
+        if self.symbol == c_MUL:
             return 'mul'
-        elif self.symbol == ADD:
+        elif self.symbol == c_ADD:
             return 'add'
         else:
             return '?' + str(self.symbol)
@@ -661,7 +642,7 @@ class _DerivativeHelper:
             elif d is self.one:
                 d_node.derivative_self_mul = node
             else:
-                d_node.derivative_self_mul = self.circuit.optimised_mul((d, node))
+                d_node.derivative_self_mul = self.circuit.optimised_mul(d, node)
 
         return d_node.derivative_self_mul
 
@@ -673,13 +654,13 @@ class _DerivativeHelper:
         to_add: Sequence[CircuitNode] = tuple(
             value
             for value in (self._derivative_prod(prods) for prods in d_node.sum_prod)
-            if not value.is_zero()
+            if not value.is_zero
         )
         # we can release the temporary memory at this DNode now
         d_node.sum_prod = None
 
         # Construct the addition operation
-        d_node.derivative = self.circuit.optimised_add(to_add)
+        d_node.derivative = self.circuit.optimised_add(*to_add)
 
         return d_node.derivative
 
@@ -700,7 +681,7 @@ class _DerivativeHelper:
                 to_mul.append(arg)
 
         # Construct the multiplication operation
-        return self.circuit.optimised_mul(to_mul)
+        return self.circuit.optimised_mul(*to_mul)
 
     def _mk_derivative_r(self, d_node: _DNode) -> None:
         """
@@ -712,11 +693,11 @@ class _DerivativeHelper:
         node: CircuitNode = d_node.node
 
         if isinstance(node, OpNode):
-            if node.symbol == ADD:
+            if node.symbol == c_ADD:
                 for arg in node.args:
                     child_d_node = self._add(arg, d_node, [])
                     self._mk_derivative_r(child_d_node)
-            elif node.symbol == MUL:
+            elif node.symbol == c_MUL:
                 for arg in node.args:
                     prod = [arg2 for arg2 in node.args if arg is not arg2]
                     child_d_node = self._add(arg, d_node, prod)
@@ -748,6 +729,8 @@ class _DerivativeHelper:
 
     def _get(self, node: CircuitNode) -> _DNode:
         """
+        Helper for derivatives.
+
         Get the DNode for the given circuit node.
         If no DNode exist for it yet, then one will be constructed.
         """
@@ -759,21 +742,20 @@ class _DerivativeHelper:
         return d_node
 
 
-cdef void _reachable_op_nodes_r(object node: CircuitNode, set seen: Set[int], list result: List[OpNode]):
+cdef void _reachable_op_nodes_r(CircuitNode node, set[int] seen, list[OpNode] result):
     # Recursive helper for `reachable_op_nodes`. Performs a depth-first search.
     #
     # Args:
     #     node: the current node being checked.
     #     seen: keep track of seen op node ids (to avoid returning multiple of the same node).
-    #     result: a list where the nodes are added
+    #     result: a list where the seen nodes are added.
     if isinstance(node, OpNode) and id(node) not in seen:
         seen.add(id(node))
         for arg in node.args:
             _reachable_op_nodes_r(arg, seen, result)
         result.append(node)
 
-
-cdef void _reachable_op_nodes_seen_r(object node: CircuitNode, set seen: Set[int]):
+cdef void _reachable_op_nodes_seen_r(CircuitNode node, set[int] seen):
     # Recursive helper for `remove_unreachable_op_nodes`. Performs a depth-first search.
     #
     # Args:

ck/circuit/{circuit_py.py → _circuit_py.py}

@@ -181,7 +181,7 @@ class Circuit:
         * singleton addition is avoided: add(x) = x,
         * empty addition is avoided: add() = 0,
         """
-        to_add = tuple(n for n in self._check_nodes(args) if not n.is_zero())
+        to_add = tuple(n for n in self._check_nodes(args) if not n.is_zero)
         match len(to_add):
             case 0:
                 return self.zero
@@ -200,8 +200,8 @@ class Circuit:
         * singleton multiplication is avoided: mul(x) = x,
         * empty multiplication is avoided: mul() = 1,
         """
-        to_mul = tuple(n for n in self._check_nodes(args) if not n.is_one())
-        if any(n.is_zero() for n in to_mul):
+        to_mul = tuple(n for n in self._check_nodes(args) if not n.is_one)
+        if any(n.is_zero for n in to_mul):
             return self.zero
         match len(to_mul):
             case 0:
@@ -485,12 +485,14 @@ class CircuitNode:
     def __init__(self, circuit: Circuit):
         self.circuit = circuit
 
+    @property
     def is_zero(self) -> bool:
         """
         Does this node represent the constant zero.
         """
         return False
 
+    @property
     def is_one(self) -> bool:
         """
         Does this node represent the constant one.
@@ -522,10 +524,12 @@ class ConstNode(CircuitNode):
     def value(self) -> ConstValue:
         return self._value
 
+    @property
     def is_zero(self) -> bool:
         # noinspection PyProtectedMember
         return self is self.circuit.zero
 
+    @property
     def is_one(self) -> bool:
         # noinspection PyProtectedMember
         return self is self.circuit.one
@@ -569,11 +573,13 @@ class VarNode(CircuitNode):
         else:
             self._const = self.circuit.const(value)
 
+    @property
     def is_zero(self) -> bool:
-        return self._const is not None and self._const.is_zero()
+        return self._const is not None and self._const.is_zero
 
+    @property
     def is_one(self) -> bool:
-        return self._const is not None and self._const.is_one()
+        return self._const is not None and self._const.is_one
 
     def __lt__(self, other) -> bool:
         if isinstance(other, VarNode):
@@ -707,13 +713,15 @@ class _DerivativeHelper:
         to_add: Sequence[CircuitNode] = tuple(
             value
             for value in (self._derivative_prod(prods) for prods in d_node.sum_prod)
-            if not value.is_zero()
+            if not value.is_zero
         )
         # We can release the temporary memory at this DNode now
+        # Warning disabled as we will never use this field again - doing so would be an error.
+        # noinspection PyTypeChecker
         d_node.sum_prod = None
 
         # Construct the addition operation
-        d_node.derivative = self.circuit.optimised_add(to_add)
+        d_node.derivative = self.circuit.optimised_add(*to_add)
 
         return d_node.derivative
 
@@ -734,7 +742,7 @@ class _DerivativeHelper:
                 to_mul.append(arg)
 
         # Construct the multiplication operation
-        return self.circuit.optimised_mul(to_mul)
+        return self.circuit.optimised_mul(*to_mul)
 
     def _mk_derivative_r(self, d_node: _DNode) -> None:
         """