compiled-knowledge 4.0.0a17__cp312-cp312-win_amd64.whl → 4.0.0a19__cp312-cp312-win_amd64.whl

ck/circuit_compiler/cython_vm_compiler/_compiler.pyx

@@ -1,20 +1,20 @@
 from __future__ import annotations
 
-from typing import Dict, Tuple, Sequence
+from typing import Dict, Tuple
 
 import numpy as np
 import ctypes as ct
 
 from ck import circuit
-from ck.circuit import OpNode, VarNode, CircuitNode
-from ck.circuit_compiler.support.circuit_analyser import CircuitAnalysis, analyze_circuit
+from ck.circuit import OpNode
+from ck.circuit_compiler.support.circuit_analyser import CircuitAnalysis
 from ck.program.raw_program import RawProgramFunction
 from ck.utils.np_extras import NDArrayNumeric, DTypeNumeric
 
 from cpython.mem cimport PyMem_Malloc, PyMem_Realloc, PyMem_Free
+from cython.operator cimport dereference as deref, preincrement as incr, postdecrement
 
 cimport numpy as cnp
-cimport cython
 
 cnp.import_array()
 
@@ -22,20 +22,34 @@ DTYPE_FLOAT64 = np.float64
 ctypedef cnp.float64_t DTYPE_FLOAT64_t
 
 
+ctypedef fused cvm_type:
+    double
+    float
+    int
+    long
+    short
 
-def make_function(
-        var_nodes: Sequence[VarNode],
-        result_nodes: Sequence[CircuitNode],
-        dtype: DTypeNumeric,
-) -> Tuple[RawProgramFunction, int]:
+DTYPE_TO_CVM_TYPE: Dict[DTypeNumeric, str] = {
+    np.float64: 'double',
+    np.float32: 'float',
+    np.intc: 'int',
+    np.long: 'long',
+    np.short: 'short',
+}
+
+
+def make_function(analysis: CircuitAnalysis, dtype: DTypeNumeric) -> Tuple[RawProgramFunction, int]:
     """
     Make a RawProgram function that interprets the circuit.
 
+    Args:
+        analysis: A circuit analysis object defining the function.
+        dtype: a numpy data type that must be a key in the dictionary, DTYPE_TO_CVM_TYPE.
+
     Returns:
         (function, number_of_tmps)
     """
 
-    analysis: CircuitAnalysis = analyze_circuit(var_nodes, result_nodes)
     cdef Instructions instructions
     np_consts: NDArrayNumeric
     instructions, np_consts = _make_instructions_from_analysis(analysis, dtype)
@@ -43,23 +57,79 @@ def make_function(
     ptr_type = ct.POINTER(np.ctypeslib.as_ctypes_type(dtype))
     c_np_consts = np_consts.ctypes.data_as(ptr_type)
 
+    cvm_type_name: str = DTYPE_TO_CVM_TYPE[dtype]
+
     # RawProgramFunction = Callable[[ct.POINTER, ct.POINTER, ct.POINTER], None]
-    def function(vars_in: ct.POINTER, tmps: ct.POINTER, result: ct.POINTER) -> None:
-        cdef size_t vars_in_addr = ct.cast(vars_in, ct.c_void_p).value
-        cdef size_t tmps_addr = ct.cast(tmps, ct.c_void_p).value
-        cdef size_t consts_addr = ct.cast(c_np_consts, ct.c_void_p).value
-        cdef size_t result_addr = ct.cast(result, ct.c_void_p).value
-        cvm_float64(
-            <double*> vars_in_addr,
-            <double*> tmps_addr,
-            <double*> consts_addr,
-            <double*> result_addr,
-            instructions,
-        )
+    if cvm_type_name == 'double':
+        def function(vars_in: ct.POINTER, tmps: ct.POINTER, result: ct.POINTER) -> None:
+            cdef size_t vars_in_addr = ct.cast(vars_in, ct.c_void_p).value
+            cdef size_t tmps_addr = ct.cast(tmps, ct.c_void_p).value
+            cdef size_t consts_addr = ct.cast(c_np_consts, ct.c_void_p).value
+            cdef size_t result_addr = ct.cast(result, ct.c_void_p).value
+            cvm[double](
+                <double *> vars_in_addr,
+                <double *> tmps_addr,
+                <double *> consts_addr,
+                <double *> result_addr,
+                instructions,
+            )
+    elif cvm_type_name == 'float':
+        def function(vars_in: ct.POINTER, tmps: ct.POINTER, result: ct.POINTER) -> None:
+            cdef size_t vars_in_addr = ct.cast(vars_in, ct.c_void_p).value
+            cdef size_t tmps_addr = ct.cast(tmps, ct.c_void_p).value
+            cdef size_t consts_addr = ct.cast(c_np_consts, ct.c_void_p).value
+            cdef size_t result_addr = ct.cast(result, ct.c_void_p).value
+            cvm[float](
+                <float *> vars_in_addr,
+                <float *> tmps_addr,
+                <float *> consts_addr,
+                <float *> result_addr,
+                instructions,
+            )
+    elif cvm_type_name == 'int':
+        def function(vars_in: ct.POINTER, tmps: ct.POINTER, result: ct.POINTER) -> None:
+            cdef size_t vars_in_addr = ct.cast(vars_in, ct.c_void_p).value
+            cdef size_t tmps_addr = ct.cast(tmps, ct.c_void_p).value
+            cdef size_t consts_addr = ct.cast(c_np_consts, ct.c_void_p).value
+            cdef size_t result_addr = ct.cast(result, ct.c_void_p).value
+            cvm[int](
+                <int *> vars_in_addr,
+                <int *> tmps_addr,
+                <int *> consts_addr,
+                <int *> result_addr,
+                instructions,
+            )
+    elif cvm_type_name == 'long':
+        def function(vars_in: ct.POINTER, tmps: ct.POINTER, result: ct.POINTER) -> None:
+            cdef size_t vars_in_addr = ct.cast(vars_in, ct.c_void_p).value
+            cdef size_t tmps_addr = ct.cast(tmps, ct.c_void_p).value
+            cdef size_t consts_addr = ct.cast(c_np_consts, ct.c_void_p).value
+            cdef size_t result_addr = ct.cast(result, ct.c_void_p).value
+            cvm[long](
+                <long *> vars_in_addr,
+                <long *> tmps_addr,
+                <long *> consts_addr,
+                <long *> result_addr,
+                instructions,
+            )
+    elif cvm_type_name == 'short':
+        def function(vars_in: ct.POINTER, tmps: ct.POINTER, result: ct.POINTER) -> None:
+            cdef size_t vars_in_addr = ct.cast(vars_in, ct.c_void_p).value
+            cdef size_t tmps_addr = ct.cast(tmps, ct.c_void_p).value
+            cdef size_t consts_addr = ct.cast(c_np_consts, ct.c_void_p).value
+            cdef size_t result_addr = ct.cast(result, ct.c_void_p).value
+            cvm[short](
+                <short *> vars_in_addr,
+                <short *> tmps_addr,
+                <short *> consts_addr,
+                <short *> result_addr,
+                instructions,
+            )
+    else:
+        raise ValueError(f'cvm_type_name unexpected: {cvm_type_name!r}')
 
     return function, len(analysis.op_to_tmp)
 
-
 # VM instructions
 cdef int ADD = circuit.ADD
 cdef int MUL = circuit.MUL
@@ -71,14 +141,10 @@ cdef int TMPS = 1
 cdef int CONSTS = 2
 cdef int RESULT = 3
 
-
 cdef tuple[Instructions, cnp.ndarray] _make_instructions_from_analysis(
         object analysis: CircuitAnalysis,
         object dtype: DTypeNumeric,
-): # -> Tuple[Instructions, NDArrayNumeric]:
-    if dtype != np.float64:
-        raise RuntimeError(f'only DType {np.float64} currently supported')
-
+):
     # Store const values in a numpy array
     node_to_const_idx: Dict[int, int] = {
         id(node): i
@@ -89,7 +155,7 @@ cdef tuple[Instructions, cnp.ndarray] _make_instructions_from_analysis(
         np_consts[i] = node.value
 
     # Where to get input values for each possible node.
-    cdef dict[int, ElementID] node_to_element  = {}
+    cdef dict[int, ElementID] node_to_element = {}
     # const nodes
     for node_id, const_idx in node_to_const_idx.items():
         node_to_element[node_id] = ElementID(CONSTS, const_idx)
@@ -121,19 +187,16 @@ cdef tuple[Instructions, cnp.ndarray] _make_instructions_from_analysis(
 
     return instructions, np_consts
 
-
 cdef struct ElementID:
     int array  # VARS, TMPS, CONSTS, RESULT
     int index  # index into the array
 
-
 cdef struct Instruction:
     int             symbol  # ADD, MUL, COPY
-    int             num_args
+    Py_ssize_t      num_args
     ElementID*      args
     ElementID       dest
 
-
 cdef class Instructions:
     cdef Instruction* instructions
     cdef int allocated
@@ -142,14 +205,14 @@ cdef class Instructions:
     def __init__(self) -> None:
         self.num_instructions = 0
         self.allocated = 64
-        self.instructions = <Instruction*> PyMem_Malloc(self.allocated * sizeof(Instruction))
+        self.instructions = <Instruction *> PyMem_Malloc(self.allocated * sizeof(Instruction))
 
     cdef void append_copy(
             self,
             ElementID src,
             ElementID dest,
     ) except*:
-        c_args = <ElementID*> PyMem_Malloc(sizeof(ElementID))
+        c_args = <ElementID *> PyMem_Malloc(sizeof(ElementID))
         if not c_args:
             raise MemoryError()
 
@@ -158,14 +221,14 @@ cdef class Instructions:
 
     cdef void append_op(self, int symbol, object op_node: OpNode, dict[int, ElementID] node_to_element) except*:
         args = op_node.args
-        cdef int num_args = len(args)
+        cdef Py_ssize_t num_args = len(args)
 
         # Create the instruction arguments array
-        c_args = <ElementID*> PyMem_Malloc(num_args * sizeof(ElementID))
+        c_args = <ElementID *> PyMem_Malloc(num_args * sizeof(ElementID))
         if not c_args:
             raise MemoryError()
 
-        cdef int i = num_args
+        cdef Py_ssize_t i = num_args
         while i > 0:
             i -= 1
             c_args[i] = node_to_element[id(args[i])]
@@ -174,8 +237,7 @@ cdef class Instructions:
 
         self._append(symbol, num_args, c_args, dest)
 
-
-    cdef void _append(self, int symbol, int num_args, ElementID* c_args, ElementID dest) except *:
+    cdef void _append(self, int symbol, Py_ssize_t num_args, ElementID * c_args, ElementID dest) except*:
         cdef int i
 
         cdef int num_instructions = self.num_instructions
@@ -184,7 +246,7 @@ cdef class Instructions:
         cdef int allocated = self.allocated
         if num_instructions == allocated:
             allocated *= 2
-            self.instructions = <Instruction*> PyMem_Realloc(
+            self.instructions = <Instruction *> PyMem_Realloc(
                 self.instructions,
                 allocated * sizeof(Instruction),
             )
@@ -202,65 +264,117 @@ cdef class Instructions:
         self.num_instructions = num_instructions + 1
 
     def __dealloc__(self) -> None:
-        cdef Instruction* instructions = self.instructions
+        cdef Instruction * instructions = self.instructions
         if instructions:
             for i in range(self.num_instructions):
                 PyMem_Free(instructions[i].args)
             PyMem_Free(instructions)
 
-
-
-@cython.boundscheck(False) # turn off bounds-checking for entire function
-@cython.wraparound(False)  # turn off negative index wrapping for entire function
-cdef void cvm_float64(
-    double* vars_in,
-    double* tmps,
-    double* consts,
-    double* result,
-    Instructions instructions,
-) except *:
-    # Core virtual machine (for dtype float64).
-
-    cdef int i, symbol
-    cdef double accumulator
-    cdef ElementID* args
-    cdef ElementID  elem
+cdef void cvm(
+        cvm_type * vars_in,
+        cvm_type * tmps,
+        cvm_type * consts,
+        cvm_type * result,
+        Instructions instructions,
+):
+    # Core virtual machine (for fused type 'cvm_type').
+
+    cdef int symbol
+    cdef cvm_type accumulator
+    cdef ElementID * args
+    cdef ElementID * args_end
+    cdef ElementID * dest
 
     # Index the four arrays by constants VARS, TMPS, CONSTS, and RESULT
-    cdef (double*) arrays[4]
+    cdef (cvm_type *) arrays[4]
     arrays[VARS] = vars_in
     arrays[TMPS] = tmps
     arrays[CONSTS] = consts
     arrays[RESULT] = result
 
-    cdef Instruction* instruction_ptr = instructions.instructions
-    cdef int num_instructions = instructions.num_instructions
+    cdef Instruction * instruction_ptr = instructions.instructions
+    cdef Instruction * instruction_end = instruction_ptr + instructions.num_instructions
 
-    while num_instructions > 0:
-        num_instructions -= 1
+    while instruction_ptr < instruction_end:
 
         symbol = instruction_ptr.symbol
         args = instruction_ptr.args
 
-        elem = args[0]
-        accumulator = arrays[elem.array][elem.index]
+        accumulator = arrays[args.array][args.index]
 
         if symbol == ADD:
-            i = instruction_ptr.num_args
-            while i > 1:
-                i -= 1
-                elem = args[i]
-                accumulator += arrays[elem.array][elem.index]
+            args_end = args + instruction_ptr.num_args
+            incr(args)
+            while args < args_end:
+                accumulator += arrays[args.array][args.index]
+                incr(args)
         elif symbol == MUL:
-            i = instruction_ptr.num_args
-            while i > 1:
-                i -= 1
-                elem = args[i]
-                accumulator *= arrays[elem.array][elem.index]
+            args_end = args + instruction_ptr.num_args
+            incr(args)
+            while args < args_end:
+                accumulator *= arrays[args.array][args.index]
+                incr(args)
         # else symbol == COPY, nothing to do
 
-        elem = instruction_ptr.dest
-        arrays[elem.array][elem.index] = accumulator
+        dest = &instruction_ptr.dest
+        arrays[dest.array][dest.index] = accumulator
 
         # Advance the instruction pointer
-        instruction_ptr = &(instruction_ptr[1])
+        incr(instruction_ptr)
+
+
+# This is the older 4.0.0a17 version which seems to be 10% faster sometimes!
+#
+# cdef void cvm(
+#         cvm_type * vars_in,
+#         cvm_type * tmps,
+#         cvm_type * consts,
+#         cvm_type * result,
+#         Instructions instructions,
+# ):
+#     # Core virtual machine (for fused type 'cvm_type').
+#
+#     cdef int symbol
+#     cdef Py_ssize_t i
+#     cdef cvm_type accumulator
+#     cdef ElementID* args
+#     cdef ElementID  elem
+#
+#     # Index the four arrays by constants VARS, TMPS, CONSTS, and RESULT
+#     cdef (cvm_type*) arrays[4]
+#     arrays[VARS] = vars_in
+#     arrays[TMPS] = tmps
+#     arrays[CONSTS] = consts
+#     arrays[RESULT] = result
+#
+#     cdef Instruction* instruction_ptr = instructions.instructions
+#     cdef Py_ssize_t num_instructions = instructions.num_instructions
+#
+#     while num_instructions > 0:
+#         num_instructions -= 1
+#
+#         symbol = instruction_ptr.symbol
+#         args = instruction_ptr.args
+#
+#         elem = args[0]
+#         accumulator = arrays[elem.array][elem.index]
+#
+#         if symbol == ADD:
+#             i = instruction_ptr.num_args
+#             while i > 1:
+#                 i -= 1
+#                 elem = args[i]
+#                 accumulator += arrays[elem.array][elem.index]
+#         elif symbol == MUL:
+#             i = instruction_ptr.num_args
+#             while i > 1:
+#                 i -= 1
+#                 elem = args[i]
+#                 accumulator *= arrays[elem.array][elem.index]
+#         # else symbol == COPY, nothing to do
+#
+#         elem = instruction_ptr.dest
+#         arrays[elem.array][elem.index] = accumulator
+#
+#         # Advance the instruction pointer
+#         instruction_ptr = &(instruction_ptr[1])

ck/circuit_compiler/cython_vm_compiler/cython_vm_compiler.py

@@ -1,12 +1,13 @@
-from typing import Optional, Sequence
+from typing import Optional, Sequence, Tuple
 
 import numpy as np
 
 from ck.circuit import CircuitNode, Circuit, VarNode
 from ck.circuit_compiler.support.input_vars import InferVars, InputVars, infer_input_vars
-from ck.program.raw_program import RawProgram
+from ck.program.raw_program import RawProgram, RawProgramFunction
 from ck.utils.np_extras import DTypeNumeric
-from ._compiler import make_function as _make_function
+from . import _compiler
+from ..support.circuit_analyser import CircuitAnalysis, analyze_circuit
 
 
 def compile_circuit(
@@ -31,7 +32,11 @@ def compile_circuit(
     Raises:
         ValueError: if the circuit is unknown, but it is needed.
         ValueError: if not all nodes are from the same circuit.
+        ValueError: if the given dtype is not supported.
     """
+    if dtype not in _compiler.DTYPE_TO_CVM_TYPE.keys():
+        raise ValueError(f'dtype not supported: {dtype!r}')
+
     in_vars: Sequence[VarNode] = infer_input_vars(circuit, result, input_vars)
     return CythonRawProgram(in_vars, result, dtype)
 
@@ -70,7 +75,7 @@ class CythonRawProgram(RawProgram):
             'number_of_vars': self.number_of_vars,
             'number_of_tmps': self.number_of_tmps,
             'number_of_results': self.number_of_results,
-            'var_indices':self.var_indices,
+            'var_indices': self.var_indices,
             #
             'in_vars': self.in_vars,
             'result': self.result,
@@ -94,3 +99,23 @@ class CythonRawProgram(RawProgram):
             result_nodes=self.result,
             dtype=self.dtype,
         )
+
+
+def _make_function(
+        var_nodes: Sequence[VarNode],
+        result_nodes: Sequence[CircuitNode],
+        dtype: DTypeNumeric,
+) -> Tuple[RawProgramFunction, int]:
+    """
+    Make a RawProgram function that interprets the circuit.
+
+    Args:
+        var_nodes: The chosen input variable nodes of the circuit.
+        result_nodes: The chosen output result nodes of the circuit.
+        dtype: a numpy data type that must be a key in the dictionary, DTYPE_TO_CVM_TYPE.
+
+    Returns:
+        (function, number_of_tmps)
+    """
+    analysis: CircuitAnalysis = analyze_circuit(var_nodes, result_nodes)
+    return _compiler.make_function(analysis, dtype)

ck/circuit_compiler/support/circuit_analyser/__init__.py

@@ -0,0 +1,13 @@
+# There are two implementations of the `circuit_analyser` 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` module.
+# Note that if the Cython implementation is chosen for `circuit_analyser` then
+# the Cython implementation must be chosen for `circuit`.
+
+# from ._circuit_analyser_py import (
+from ._circuit_analyser_cy import (
+    CircuitAnalysis,
+    analyze_circuit,
+)

ck/circuit_compiler/support/circuit_analyser/_circuit_analyser_cy.pyx

@@ -0,0 +1,98 @@
+from dataclasses import dataclass
+from typing import List, Dict, Sequence, Set
+
+from ck.circuit._circuit_cy cimport Circuit, OpNode, VarNode, CircuitNode, ConstNode
+from cython.operator cimport postincrement
+
+
+@dataclass
+class CircuitAnalysis:
+    """
+    A data structure representing the analysis of a function defined by
+    a circuit which chosen input variables and output result nodes.
+    """
+
+    var_nodes: Sequence[VarNode]  # specified input var nodes
+    result_nodes: Sequence[CircuitNode]  # specified result nodes
+    op_nodes: Sequence[OpNode]  # in-use op nodes, in computation order
+    const_nodes: Sequence[ConstNode]  # in_use const nodes, in arbitrary order
+    op_to_result: Dict[int, int]  # op nodes in the result, op_node = result[idx]: id(op_node) -> idx
+    op_to_tmp: Dict[int, int]  # op nodes needing tmp memory, using tmp[idx]: id(op_node) -> idx
+
+
+def analyze_circuit(
+        var_nodes: Sequence[VarNode],
+        result_nodes: Sequence[CircuitNode],
+) -> CircuitAnalysis:
+    """
+    Analyzes a circuit as a function from var_nodes to result_nodes,
+    returning a CircuitAnalysis object.
+
+    Args:
+        var_nodes: The chosen input variable nodes of the circuit.
+        result_nodes: The chosen output result nodes of the circuit.
+
+    Returns:
+        A CircuitAnalysis object.
+    """
+    cdef list[CircuitNode] results_list = list(result_nodes)
+
+    # What op nodes are in use
+    cdef list[OpNode] op_nodes = _reachable_op_nodes(results_list)
+
+    # What constant values are in use
+    cdef set[int] seen_const_nodes = set()
+    cdef list[ConstNode] const_nodes  = []
+
+    def _register_const(_node: ConstNode) -> None:
+        nonlocal seen_const_nodes
+        nonlocal const_nodes
+        _node_id: int = id(_node)
+        if _node_id not in seen_const_nodes:
+            const_nodes.append(_node)
+            seen_const_nodes.add(_node_id)
+
+    # Register all the used constants
+    for op_node in op_nodes:
+        for node in op_node.args:
+            if isinstance(node, ConstNode):
+                _register_const(node)
+    for node in results_list:
+        if isinstance(node, ConstNode):
+            _register_const(node)
+    for node in var_nodes:
+        if node.is_const():
+            _register_const(node.const)
+
+    # What op nodes are in the result.
+    # Dict op_to_result maps id(OpNode) to result index.
+    cdef dict[int, int] op_to_result = {
+        id(node): i
+        for i, node in enumerate(result_nodes)
+        if isinstance(node, OpNode)
+    }
+
+    # Assign all other op nodes to a tmp slot.
+    # Dict op_to_tmp maps id(OpNode) to tmp index.
+    cdef int tmp_idx = 0
+    op_to_tmp: Dict[int, int] = {
+        id(op_node): postincrement(tmp_idx)
+        for op_node in op_nodes
+        if id(op_node) not in op_to_result
+    }
+
+    return CircuitAnalysis(
+        var_nodes=var_nodes,
+        result_nodes=result_nodes,
+        op_nodes=op_nodes,
+        const_nodes=const_nodes,
+        op_to_result=op_to_result,
+        op_to_tmp=op_to_tmp,
+    )
+
+
+cdef list[OpNode] _reachable_op_nodes(list[CircuitNode] results):
+    if len(results) == 0:
+        return []
+    cdef Circuit circuit = results[0].circuit
+    return circuit.find_reachable_op_nodes(results)

ck/circuit_compiler/support/{circuit_analyser.py → circuit_analyser/_circuit_analyser_py.py}

@@ -7,8 +7,13 @@ from ck.circuit import OpNode, VarNode, CircuitNode, ConstNode
 
 @dataclass
 class CircuitAnalysis:
-    var_nodes: Sequence[VarNode] # input var nodes, in VarNode idx order
-    result_nodes: Sequence[CircuitNode] # result nodes
+    """
+    A data structure representing the analysis of a function defined by
+    a circuit which chosen input variables and output result nodes.
+    """
+
+    var_nodes: Sequence[VarNode]  # specified input var nodes
+    result_nodes: Sequence[CircuitNode]  # specified result nodes
     op_nodes: Sequence[OpNode]  # in-use op nodes, in computation order
     const_nodes: Sequence[ConstNode]  # in_use const nodes, in arbitrary order
     op_to_result: Dict[int, int]  # op nodes in the result, op_node = result[idx]: id(op_node) -> idx
@@ -22,6 +27,13 @@ def analyze_circuit(
     """
     Analyzes a circuit as a function from var_nodes to result_nodes,
     returning a CircuitAnalysis object.
+
+    Args:
+        var_nodes: The chosen input variable nodes of the circuit.
+        result_nodes: The chosen output result nodes of the circuit.
+
+    Returns:
+        A CircuitAnalysis object.
     """
     # What op nodes are in use
     op_nodes: List[OpNode] = (

ck/pgm_compiler/ace/__init__.py

@@ -1 +1 @@
-from .ace import compile_pgm, copy_ace_to_default_location, default_ace_location
+from .ace import compile_pgm, copy_ace_to_default_location, default_ace_location, ace_available

ck/pgm_compiler/support/circuit_table/__init__.py

@@ -1,3 +1,11 @@
+# There are two implementations of the `circuit_table` 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` module.
+# Note that if the Cython implementation is chosen for `circuit_table` then
+# the Cython implementation must be chosen for `circuit`.
+
 # from ._circuit_table_py import (
 from ._circuit_table_cy import (
     CircuitTable,