compiled-knowledge 4.0.0a20__cp313-cp313-macosx_10_13_x86_64.whl

ck/pgm_circuit/__init__.py

@@ -0,0 +1 @@
+from .pgm_circuit import PGMCircuit

ck/pgm_circuit/marginals_program.py

@@ -0,0 +1,352 @@
+from __future__ import annotations
+
+import random
+from typing import Sequence, Optional, Tuple, List, Iterable, Dict
+
+import numpy as np
+
+from ck.circuit import CircuitNode, Circuit
+from ck.pgm import RandomVariable, number_of_states, rv_instances_as_indicators
+from ck.pgm_circuit import PGMCircuit
+from ck.pgm_circuit.program_with_slotmap import ProgramWithSlotmap
+from ck.pgm_circuit.slot_map import SlotMap
+from ck.pgm_circuit.support.compile_circuit import compile_results
+from ck.probability.probability_space import ProbabilitySpace, check_condition, Condition
+from ck.program.program_buffer import ProgramBuffer
+from ck.program.raw_program import RawProgram
+from ck.sampling.marginals_direct_sampler import MarginalsDirectSampler
+from ck.sampling.sampler import Sampler
+from ck.sampling.sampler_support import SamplerInfo, get_sampler_info
+from ck.sampling.uniform_sampler import UniformSampler
+from ck.utils.np_extras import NDArray, NDArrayNumeric
+from ck.utils.random_extras import Random
+
+
+class MarginalsProgram(ProgramWithSlotmap, ProbabilitySpace):
+    """
+    A class for computing marginal probability distributions over states of selected output random variables.
+    This class provides, for each indicator, the product of indicator value with the derivative
+    of the network function with respect to the indicator.
+
+    Compile the circuit for computing marginal probability distributions using the
+    so-called 'differential' approach.
+
+    Reference: Darwiche, A. (2003). A differential approach to inference in Bayesian
+    networks. Journal of the ACM (JACM), 50(3), 280-305.
+
+    A note about samplers
+    ---------------------
+
+    When creating a sampler, a client may request that samples are conditioned
+    on provided condition indicators. Also, the WMCProgram may have been
+    produced with compile-in conditions, e.g., using const_conditions with
+    a call to PGM_cct.wmc(...).
+
+    The conditions respected by a sampler are the conjunction of the compiled
+    conditions and the sampler conditions. For example, with compiled condition
+    (A[0], A[1], A[2]) and sampler condition (A[1], A[2], A[3]) the effective
+    condition is (A[1], A[2]), i.e., a sample of A may be 1 or 2.
+
+    Warning:
+        if the sampled random variables include conditions, those conditions
+        must be provided to the sampler. If a sampled random variable is conditioned
+        at compile time, but not passed to the sampler, then the sample will not
+        be aware of the conditions, and unexpected sample values may be produced.
+    """
+
+    def __init__(
+            self,
+            pgm_circuit: PGMCircuit,
+            output_rvs: Optional[Sequence[RandomVariable]] = None,
+            const_parameters: bool = True,
+    ):
+        """
+        Construct a MarginalsProgram object.
+
+        The given program should produce marginal outputs in the order
+        of output_rvs indicators, followed by the wmc output.
+
+        Args:
+            pgm_circuit: The circuit representing a PGM.
+            output_rvs: if None, the output rvs are all rvs, otherwise the given rvs.
+            const_parameters: if True then any circuit variable representing a parameter value will
+                be made 'const' in the resulting program.
+        """
+        top_node: CircuitNode = pgm_circuit.circuit_top
+        circuit: Circuit = top_node.circuit
+        slot_map: SlotMap = pgm_circuit.slot_map
+        input_rvs: Sequence[RandomVariable] = pgm_circuit.rvs
+
+        output_rvs: Sequence[RandomVariable] = tuple(output_rvs) if output_rvs is not None else input_rvs
+
+        output_rvs_slots = [[slot_map[ind] for ind in rv] for rv in output_rvs]
+        flat_out_rv_vars = [circuit.vars[slot] for slots in output_rvs_slots for slot in slots]
+        derivatives = circuit.partial_derivatives(top_node, flat_out_rv_vars, self_multiply=True)
+
+        raw_program: RawProgram = compile_results(
+            pgm_circuit=pgm_circuit,
+            results=derivatives + [top_node],
+            const_parameters=const_parameters,
+        )
+
+        program_buffer = ProgramBuffer(raw_program)
+        ProgramWithSlotmap.__init__(self, program_buffer, slot_map, input_rvs, pgm_circuit.conditions)
+
+        # cache the input slots for the output rvs
+        output_rvs_slots = [[slot_map[ind] for ind in rv] for rv in output_rvs]
+
+        # cache the output offsets for the derivatives.
+        # A map from `RandomVariable.idx` to offset into the result buffer
+        self._rv_idx_to_result_offset: Dict[int, int] = {}
+        prev_offset: int = 0
+        for rv in output_rvs:
+            self._rv_idx_to_result_offset[rv.idx] = prev_offset
+            prev_offset += len(rv)
+
+        # cached a map from output rv to its position in the marginals result
+        self._rv_idx_to_output_index: Dict[int, int] = {rv.idx: i for i, rv in enumerate(output_rvs)}
+
+        self._marginals: List[NDArrayNumeric] = []
+        start = 0
+        for rv_slots in output_rvs_slots:
+            end = start + len(rv_slots)
+            result_part = program_buffer.results[start:end]  # gets a view onto the same data.
+            self._marginals.append(result_part)
+            start = end
+
+        # additional fields
+        self._raw_program: RawProgram = raw_program
+        self._program_buffer: ProgramBuffer = program_buffer
+        self._number_of_indicators: int = pgm_circuit.number_of_indicators
+        self._output_rvs = output_rvs
+        self._output_rvs_slots = output_rvs_slots
+        self._z_cache: Optional[float] = None
+
+        if not const_parameters:
+            # set the parameter slots
+            self.vars[pgm_circuit.number_of_indicators:] = pgm_circuit.parameter_values
+
+    @property
+    def output_rvs(self):
+        """
+        What random variables are included in the marginal probabilities calculations.
+        """
+        return self._output_rvs
+
+    def wmc(self, *condition: Condition) -> float:
+        """
+        What is the weight of the world with the given indicators.
+        If multiple indicators from the same random variable ar mentioned, then it is treated as a disjunction.
+        If a random variable is not mentioned in the indicators, that random variable is marginalised out.
+        """
+        self.set_condition(*condition)
+        self._program_buffer.compute()
+        return self.result_wmc
+
+    @property
+    def z(self):
+        if self._z_cache is None:
+            number_of_indicators: int = self._number_of_indicators
+            slots: NDArray = self.vars
+            old_vals: NDArray = slots[:number_of_indicators].copy()
+            slots[:number_of_indicators] = 1
+            self._program_buffer.compute()
+            self._z_cache = self.result_wmc
+            slots[:number_of_indicators] = old_vals
+        return self._z_cache
+
+    def marginal_distribution(self, *rvs: RandomVariable, condition: Condition = ()):
+        # Check for easy cases.
+        if len(rvs) == 0:
+            if self.wmc(*condition) == 0:
+                return np.array([np.nan])
+            return np.array([1.0])
+        if len(rvs) == 1:
+            return self.marginal_for_rv(rvs[0], condition=condition)
+
+        # We try to eliminate searching combinations of probabilities where marginals are zero.
+        # If there are no marginal probabilities = 0, then this is equivalent to
+        # ProbabilitySpace.marginal_distribution
+
+        condition = check_condition(condition)
+        rvs_marginals = self.marginal_for_rvs(rvs, condition=condition)
+        zero_indicators = set(
+            ind
+            for rv, rv_marginal in zip(rvs, rvs_marginals)
+            for ind, marginal in zip(rv, rv_marginal)
+            if marginal == 0
+        )
+        raw_wmc = self._get_wmc_for_marginals(rvs, condition)
+
+        if len(zero_indicators) == 0:
+            wmc = raw_wmc
+        else:
+            def wmc(indicators):
+                for ind in indicators:
+                    if ind in zero_indicators:
+                        return 0
+                return raw_wmc(indicators)
+
+        result = np.fromiter(
+            (wmc(indicators) for indicators in rv_instances_as_indicators(*rvs)),
+            count=number_of_states(*rvs),
+            dtype=np.float64
+        )
+        _normalise_marginal(result)
+        return result
+
+    def marginal_for_rv(self, rv: RandomVariable, condition: Condition = ()) -> NDArrayNumeric:
+        """
+        Compute and return marginal distribution over the given random variable.
+        The random variable is assumed to be in self.rvs.
+
+        Returns:
+            a numpy array representing the marginal distribution over the states of 'rv'.
+        """
+        self.compute_conditioned(*condition)
+        return self.result_for_rv(rv)
+
+    def marginal_for_rvs(self, rvs: Iterable[RandomVariable], condition: Condition = ()) -> List[NDArrayNumeric]:
+        """
+        Compute and return marginal distribution over the given random variables.
+        Each random variable is assumed to be in self.rvs.
+
+        Returns:
+            a list of numpy arrays representing the marginal distribution over the
+            states of each rv in the given random variables, `rvs`.
+        """
+        self.compute_conditioned(*condition)
+        marginals = self._marginals
+        rv_idx_to_output_index = self._rv_idx_to_output_index
+        return list(marginals[rv_idx_to_output_index[rv.idx]] for rv in rvs)
+
+    def compute(self) -> NDArrayNumeric:
+        self._program_buffer.compute()
+        for part in self._marginals:
+            _normalise_marginal(part)
+        return self._program_buffer.results
+
+    @property
+    def result_wmc(self) -> float:
+        """
+        Assuming the result has been computed,
+        return the WMC value.
+        """
+        return self._program_buffer.results.item(-1)
+
+    @property
+    def result_marginals(self) -> List[NDArrayNumeric]:
+        """
+        Assuming the result has been computed,
+        return the marginal distributions of each random variable, co-indexed with the
+        output random variables, `self.output_rvs`.
+
+        Returns:
+            a list of numpy arrays, the list co-indexed with `self.output_rvs`, each numpy array
+            representing the marginal distribution over the states of the co-indexed random variable.
+        """
+        return self._marginals
+
+    def result_for_rv(self, rv: RandomVariable) -> NDArrayNumeric:
+        """
+        Assuming the result has been computed,
+        return marginal distribution over the given random variable.
+        The random variable is assumed to be in self.output_rvs.
+
+        Returns:
+            a numpy array representing the marginal distribution over the states of 'rv'.
+        """
+        return self._marginals[self._rv_idx_to_output_index[rv.idx]]
+
+    def sample_uniform(
+            self,
+            rvs: Optional[RandomVariable | Sequence[RandomVariable]] = None,
+            *,
+            condition: Condition = (),
+            rand: Random = random,
+    ) -> Sampler:
+        """
+        Create a sampler that performs uniform sampling of
+        the state space of the given random variables, rvs.
+
+        The sampler will yield state lists, where the state
+        values are co-indexed with rvs, or self.rvs if rvs is None.
+
+        This sampler is not affected by and does not affect
+        the state of input slots.
+
+        Args:
+            rvs: the list of random variables to sample; the
+                yielded state vectors are co-indexed with rvs; if None,
+                then the self.rvs are used; if rvs is a single
+                random variable, then single samples are yielded.
+            condition: is a collection of zero or more conditioning indicators.
+            rand: provides the stream of random numbers.
+
+        Returns:
+            a Sampler object (UniformSampler).
+        """
+        return UniformSampler(
+            rvs=(self.rvs if rvs is None else rvs),
+            condition=condition,
+            rand=rand,
+        )
+
+    def sample_direct(
+            self,
+            rvs: Optional[RandomVariable | Sequence[RandomVariable]] = None,
+            *,
+            condition: Condition = (),
+            rand: Random = random,
+            chain_pairs: Sequence[Tuple[RandomVariable, RandomVariable]] = (),
+            initial_chain_condition: Condition = (),
+    ) -> Sampler:
+        """
+        Create an inverse-transform sampler, which uses the fact that marginal
+        probabilities are exactly computable with a single execution of the program.
+
+        The sampler will yield state lists, where the state
+        values are co-indexed with rvs, or self.rvs if rvs is None.
+
+        Args:
+            rvs: the list of random variables to sample; the
+                yielded state vectors are co-indexed with rvs; if None,
+                then the WMC rvs are used; if rvs is a single
+                random variable, then single samples are yielded.
+            condition: is a collection of zero or more conditioning indicators.
+            rand: provides the stream of random numbers.
+            chain_pairs: is a collection of pairs of random variables, each random variable
+                must be in the given rvs. Given a pair (from_rv, to_rv) the state of from_rv is used
+                as a condition for to_rv prior to generating a sample.
+            initial_chain_condition: are condition indicators (just like condition)
+                for the initialisation of the 'to_rv' random variables mentioned in chain_pairs.
+
+        Returns:
+            a Sampler object (MarginalsDirectSampler).
+        """
+        sampler_info: SamplerInfo = get_sampler_info(
+            program_with_slotmap=self,
+            rvs=rvs,
+            condition=condition,
+            chain_pairs=chain_pairs,
+            initial_chain_condition=initial_chain_condition,
+        )
+
+        return MarginalsDirectSampler(
+            sampler_info=sampler_info,
+            raw_program=self._raw_program,
+            rand=rand,
+            rv_idx_to_result_offset=self._rv_idx_to_result_offset,
+        )
+
+
+def _normalise_marginal(distribution: NDArrayNumeric) -> None:
+    """
+    Update the values in the given distribution to
+    properly represent a marginal distribution.
+    """
+    total = np.sum(distribution)
+    if total <= 0:
+        distribution[:] = np.nan
+    elif total != 1:
+        distribution /= total

ck/pgm_circuit/mpe_program.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import partial
+from typing import Sequence, Optional, Tuple, List, Dict, Set
+
+from ck.circuit import CircuitNode, Circuit, VarNode, OpNode, ADD, MUL
+from ck.circuit_compiler import llvm_vm_compiler, CircuitCompiler
+from ck.pgm import RandomVariable, Instance
+from ck.pgm_circuit import PGMCircuit
+from ck.pgm_circuit.program_with_slotmap import ProgramWithSlotmap
+from ck.pgm_circuit.slot_map import SlotMap
+from ck.pgm_circuit.support.compile_circuit import compile_results
+from ck.probability.probability_space import check_condition
+from ck.program.program_buffer import ProgramBuffer
+from ck.program.raw_program import RawProgram
+from ck.utils.np_extras import NDArray, NDArrayNumeric
+
+_NO_TRACE = (-1, -1)  # used as a sentinel value
+
+_CCT_COMPILER = llvm_vm_compiler  # Python module used for compiling an MPE circuit
+
+
+class MPEProgram(ProgramWithSlotmap):
+    """
+    A class for computing Most Probable Explanation (MPE). This is equivalent to
+    Maximum A Posterior (MAP) inference when there are no latent random variables.
+    """
+
+    def __init__(
+            self,
+            pgm_circuit: PGMCircuit,
+            trace_rvs: Optional[Sequence[RandomVariable]] = None,
+            const_parameters: bool = True,
+            log_parameters: bool = False,
+    ):
+        """
+        Construct a MPEProgram object.
+
+        Compile the circuit for computing Most Probable Explanation (MPE). This is equivalent to
+        Maximum A Posterior (MAP) inference when there are no latent variables.
+
+        This will compile a clone of the given circuit with
+        'add' nodes replaced with 'max' nodes.
+
+        This will augment the given circuit and compile it to make a program for computing MPE states.
+        'trace_vars' is a list random variables, where each random variable is a list of circuit var nodes, each
+        var node representing an indicator (i.e., a state) of a random variable.
+        Assumes that all operator nodes to compute top are either an add or mul node.
+
+        Args:
+            pgm_circuit: The circuit representing a PGM.
+            trace_rvs: the random variables to compute MPE for, default is all random variables of the PGM.
+            const_parameters: if True then any circuit variable representing a parameter value will
+                be made 'const' in the resulting program.
+            log_parameters: if true, then parameters are taken to be logs, i.e., uses addition instead
+                of multiplication.
+        """
+        trace_rvs: Tuple[RandomVariable, ...] = pgm_circuit.rvs if trace_rvs is None else tuple(trace_rvs)
+        if len(trace_rvs) != len(set(trace_rvs)):
+            raise ValueError('duplicated trace random variable detected')
+
+        top: CircuitNode = pgm_circuit.circuit_top
+        circuit: Circuit = top.circuit
+        slot_map: SlotMap = pgm_circuit.slot_map
+
+        cct_compiler: CircuitCompiler
+        if log_parameters:
+            cct_compiler = partial(_CCT_COMPILER.compile_circuit, data_type=_CCT_COMPILER.DataType.MAX_SUM)
+        else:
+            cct_compiler = partial(_CCT_COMPILER.compile_circuit, data_type=_CCT_COMPILER.DataType.MAX_MUL)
+
+        # make inv_trace_blocks
+        #
+        # inv_trace_blocks[slot] = (rv_trace_idx, state_idx)
+        # where
+        #   rv_trace_idx is an index into trace_vars,
+        #   state_idx is an index into trace_vars[rv_trace_idx] indicators,
+        #
+        #   slot = slot_map[ind], where ind = trace_vars[rv_trace_idx][state_idx].
+        #
+        inv_trace_blocks: List[Tuple[int, int]] = [_NO_TRACE] * circuit.number_of_vars
+        rv_trace_idx: int
+        trace_rv: RandomVariable
+        for rv_trace_idx, trace_rv in enumerate(trace_rvs):
+            for state_idx in trace_rv.state_range():
+                slot: int = slot_map[trace_rv[state_idx]]
+                if inv_trace_blocks[slot] is not _NO_TRACE:
+                    raise ValueError('unexpected reused circuit slot')
+                inv_trace_blocks[slot] = (rv_trace_idx, state_idx)
+
+        used_nodes: List[CircuitNode] = list(circuit.reachable_op_nodes(top))
+
+        mpe_idx: Dict[int, int] = {
+            id(used_node): used_node_idx
+            for used_node_idx, used_node in enumerate(used_nodes)
+        }
+
+        # create a dummy MPE result until compute is called
+        dummy_result = MPEResult(float('nan'), tuple(0 for _ in trace_rvs))
+
+        self._trace_rvs: Tuple[RandomVariable, ...] = trace_rvs
+        self._inv_trace_blocks = inv_trace_blocks
+        self._top: CircuitNode = top
+        self._mpe_result: MPEResult = dummy_result
+
+        self._top_idx: Optional[int] = mpe_idx.get(id(top))  # it may be possible that top is not an op node.
+        self._used_nodes: List[CircuitNode] = used_nodes
+        self._mpe_idx: Dict[int, int] = mpe_idx
+
+        raw_program: RawProgram = compile_results(
+            pgm_circuit=pgm_circuit,
+            results=used_nodes,
+            const_parameters=const_parameters,
+            compiler=cct_compiler,
+        )
+        ProgramWithSlotmap.__init__(self, ProgramBuffer(raw_program), slot_map, pgm_circuit.rvs, pgm_circuit.conditions)
+
+        if not const_parameters:
+            # set the parameter slots
+            self.vars[pgm_circuit.number_of_indicators:] = pgm_circuit.parameter_values
+
+    def mpe(self, *condition) -> MPEResult:
+        """
+        What is the MPE, given any conditioning indicators.
+
+        The mpe array may contain None in an element corresponding to a traced random variable where
+        all states of that random variable lead to the same wmc value. I.e., the solution is indifferent
+        to the state of that random variable. In this case, a caller is at liberty to use any state for that
+        random variable as an MPE solution. For example, all 'None' values could be replaced with zero
+        and the solution is still a valid MPE solution.
+
+        Returns:
+            an MPEResult with field `wmc` and `mpe`.
+            wmc: is the value of the weighted model count.
+            mpe: is an Instance, co-indexed with trace vars, where mpe[rv_idx] = state_idx.
+        """
+        condition = check_condition(condition)
+        self.compute_conditioned(*condition)
+        return self._mpe_result
+
+    @property
+    def trace_rvs(self) -> Sequence[RandomVariable]:
+        """
+        What are the random variables used in an MPE trace.
+        """
+        return self._trace_rvs
+
+    def compute(self) -> NDArrayNumeric:
+        """
+        Execute the program to compute and return the result. As per `ProgramBuffer.compute`.
+
+        Warning:
+            when returning an array, the array is backed by the program buffer memory, not a copy.
+        """
+        program_result: NDArray = self._program_buffer.compute()
+        self._trace()
+        return program_result
+
+    @property
+    def mpe_result(self) -> MPEResult:
+        """
+        Get the MPEResult of the last program computation.
+
+        Returns:
+            an MPEResult object.
+        """
+        return self._mpe_result
+
+    def _trace(self) -> None:
+        """
+        Trace the last program computation to determine the wmc and the mpe states.
+        """
+        if self._top_idx is not None:
+            wmc: float = self.results.item(self._top_idx)
+            states: List[Optional[int]] = [None for _ in self._trace_rvs]
+            seen: Set[int] = set()
+            self._trace_r(self._top, wmc, states, seen)
+            mpe = tuple(
+                0 if state_idx is None else state_idx
+                for state_idx in states
+            )
+            self._mpe_result = MPEResult(wmc, mpe)
+
+    def _trace_r(self, node: CircuitNode, node_value: float, states: List[Optional[int]], seen: Set[int]) -> None:
+
+        # A circuit is a DAG, not necessarily a tree.
+        # No need to revisit nodes.
+        if id(node) in seen:
+            return
+        seen.add(id(node))
+
+        if isinstance(node, VarNode):
+            self._trace_var(node, states)
+        elif isinstance(node, OpNode):
+            if node.symbol == ADD:
+                # Find which child node led to the max result, then recurse though it only.
+                for child in node.args:
+                    if isinstance(child, OpNode):
+                        child_value: float = self.results.item(self._mpe_idx[id(child)])
+                        if child_value == node_value:
+                            self._trace_r(child, child_value, states, seen)
+                            return
+                    elif isinstance(child, VarNode):
+                        child_value: float = self.vars.item(child.idx)
+                        if child_value == node_value:
+                            self._trace_var(child, states)
+                            return
+                # No child value equaled the value for node! We should never get here
+                assert False, 'not reached'
+            elif node.symbol == MUL:
+                # Recurse though each child node
+                for child in node.args:
+                    if isinstance(child, OpNode):
+                        child_value: float = self.results.item(self._mpe_idx[id(child)])
+                        self._trace_r(child, child_value, states, seen)
+                    elif isinstance(child, VarNode):
+                        self._trace_var(child, states)
+
+    def _trace_var(self, node: VarNode, states: List[Optional[int]]) -> None:
+        trace = self._inv_trace_blocks[node.idx]
+        if trace is not _NO_TRACE:
+            rv_trace_idx, state_idx = trace
+            states[rv_trace_idx] = state_idx
+
+
+@dataclass
+class MPEResult:
+    """
+    An MPE result is the result of MPE inference.
+
+    Fields:
+        wmc: the weighted model count value of the MPE solution.
+        mpe: The MPE solution instance. If there are ties then this will just be once instance.
+    """
+    wmc: float
+    mpe: Instance

ck/pgm_circuit/pgm_circuit.py

@@ -0,0 +1,79 @@
+from dataclasses import dataclass
+from typing import Sequence, List, Dict
+
+from ck.circuit import CircuitNode, Circuit
+from ck.pgm import RandomVariable, Indicator
+from ck.pgm_circuit.slot_map import SlotMap, SlotKey
+from ck.utils.np_extras import NDArray
+
+
+@dataclass
+class PGMCircuit:
+    """
+    A data structure representing the results of compiling a PGM to a circuit.
+
+    If the circuit contains variables to represent parameter values, then `parameter_values`
+    holds the values of the parameters. Specifically, given parameter id `param_id`, then
+    `parameter_values[slot_map[param_id] - number_of_indicators]` is the value of the
+    identified parameter as it was in the PGM.
+
+    Fields:
+        rvs: holds the random variables from the PGM as it was compiled, in order.
+
+        conditions: any conditions on `rvs` that were compiled into the circuit.
+
+        number_of_indicators: is the number of indicators in `rvs` which is
+            `sum(len(rv) for rv in rvs`. Specifically, `circuit.vars[i]` is the circuit variable
+            corresponding to the ith indicator, where `circuit` is `circuit_top.circuit` and
+            indicators are ordered as per `rvs`.
+
+        number_of_parameters: is the number of parameters from the PGM that are
+            represented as circuit variables. This may be zero if parameters from the PGM
+            were compiled as constants.
+
+        slot_map[x]: gives the index of the circuit variable corresponding to x,
+            where x is either a random variable indicator (Indicator) or a parameter id (ParamId).
+
+    """
+
+    rvs: Sequence[RandomVariable]
+    conditions: Sequence[Indicator]
+    circuit_top: CircuitNode
+    number_of_indicators: int
+    number_of_parameters: int
+    slot_map: SlotMap
+    parameter_values: NDArray
+
+    def dump(self, *, prefix: str = '', indent: str = '    ') -> None:
+        """
+        Print a dump of the circuit.
+        This is intended for debugging and demonstration purposes.
+
+        Args:
+            prefix: optional prefix for indenting all lines.
+            indent: additional prefix to use for extra indentation.
+        """
+
+        # We infer names for the circuit variables, either as an indicator or as a parameter.
+        # The `var_names` will be passed to `circuit.dump`.
+
+        circuit: Circuit = self.circuit_top.circuit
+        var_names: List[str] = [''] * circuit.number_of_vars
+
+        # Name the circuit variables that are indicators
+        rvs_by_idx: Dict[int, RandomVariable] = {rv.idx: rv for rv in self.rvs}
+        slot_key: SlotKey
+        slot: int
+        for slot_key, slot in self.slot_map.items():
+            if isinstance(slot_key, Indicator):
+                rv = rvs_by_idx[slot_key.rv_idx]
+                state_idx = slot_key.state_idx
+                var_names[slot] = f'{rv.name!r}[{state_idx}] {rv.states[state_idx]!r}'
+
+        # Name the circuit variables that are parameters
+        for i, param_value in enumerate(self.parameter_values):
+            slot = i + self.number_of_indicators
+            var_names[slot] = f'param[{i}] = {param_value}'
+
+        # Dump the circuit
+        circuit.dump(prefix=prefix, indent=indent, var_names=var_names)