compiled-knowledge 4.0.0a9__cp312-cp312-win_amd64.whl → 4.0.0a11__cp312-cp312-win_amd64.whl

ck/circuit/circuit.pyx

@@ -1,3 +1,6 @@
+"""
+For more documentation on this module, refer to the Jupyter notebook docs/6_circuits_and_programs.ipynb.
+"""
 from __future__ import annotations
 
 from itertools import chain
@@ -15,12 +18,15 @@ MUL: int = 1
 
 cdef class Circuit:
     """
-    An arithmetic circuit defining computation based on input variables (VarNode objects)
-    and constant values (ConstNode objects). Computation is defined over a mathematical
-    ring, with two operations: addition (AddNode objects) and multiplication (MulNode objects).
+    An arithmetic circuit defines an arithmetic function from input variables (`VarNode` objects)
+    and constant values (`ConstNode` objects) to one or more result values. Computation is defined
+    over a mathematical ring, with two operations: addition and multiplication (represented
+    by `OpNode` objects).
 
-    An arithmetic circuit cam be directly interpreted, using `ck.circuit_compiler.circuit_interpreter`,
-     or may be compiled to an LLVM JIT, using `ck.circuit_compiler.llvm_compiler`.
+    An arithmetic circuit needs to be compiled to a program to execute the function.
+
+    All nodes belong to a circuit. All nodes are immutable, with the exception that a
+    `VarNode` may be temporarily be set to a constant value.
     """
 
     cdef public list[VarNode] vars
@@ -334,6 +340,7 @@ cdef class Circuit:
             prefix: str = '',
             indent: str = '  ',
             var_names: Optional[List[str]] = None,
+            include_consts: bool = False,
     ) -> None:
         """
         Print a dump of the Circuit.
@@ -343,6 +350,7 @@ cdef class Circuit:
             prefix: optional prefix for indenting all lines.
             indent: additional prefix to use for extra indentation.
             var_names: optional variable names to show.
+            include_consts: if true, then constant values are dumped.
         """
 
         next_prefix: str = prefix + indent
@@ -367,10 +375,14 @@ cdef class Circuit:
             elif var.is_const():
                 print(f'{next_prefix}var[{var.idx}]: {var.const.value}')
 
-        print(f'{prefix}const nodes: {self.number_of_consts}')
+        if include_consts:
+            print(f'{prefix}const nodes: {self.number_of_consts}')
+            for const in self._const_map.values():
+                print(f'{next_prefix}{const.value!r}')
+
+        # Add const nodes to the node_name dict
         for const in self._const_map.values():
-            node_name[id(const)] = str(const.value)
-            print(f'{next_prefix}{const.value}')
+            node_name[id(const)] = repr(const.value)
 
         # Add op nodes to the node_name dict
         for i, op in enumerate(self.ops):

ck/circuit/circuit_py.py

@@ -1,3 +1,9 @@
+"""
+This is a pure Python implementation of Circuits (for testing and development)
+
+For more documentation on this module, refer to the Jupyter notebook docs/6_circuits_and_programs.ipynb.
+"""
+
 from __future__ import annotations
 
 from dataclasses import dataclass, field
@@ -14,12 +20,15 @@ MUL: int = 1
 
 class Circuit:
     """
-    An arithmetic circuit defining computation based on input variables (VarNode objects)
-    and constant values (ConstNode objects). Computation is defined over a mathematical
-    ring, with two operations: addition (AddNode objects) and multiplication (MulNode objects).
+    An arithmetic circuit defines an arithmetic function from input variables (`VarNode` objects)
+    and constant values (`ConstNode` objects) to one or more result values. Computation is defined
+    over a mathematical ring, with two operations: addition and multiplication (represented
+    by `OpNode` objects).
 
-    An arithmetic circuit cam be directly interpreted, using `ck.circuit_compiler.circuit_interpreter`,
-     or may be compiled to an LLVM JIT, using `ck.circuit_compiler.llvm_compiler`.
+    An arithmetic circuit needs to be compiled to a program to execute the function.
+
+    All nodes belong to a circuit. All nodes are immutable, with the exception that a
+    `VarNode` may be temporarily be set to a constant value.
     """
 
     def __init__(self, zero: ConstValue = 0, one: ConstValue = 1):
@@ -352,6 +361,7 @@ class Circuit:
             prefix: str = '',
             indent: str = '  ',
             var_names: Optional[List[str]] = None,
+            include_consts: bool = False,
     ) -> None:
         """
         Print a dump of the Circuit.
@@ -361,6 +371,7 @@ class Circuit:
             prefix: optional prefix for indenting all lines.
             indent: additional prefix to use for extra indentation.
             var_names: optional variable names to show.
+            include_consts: if true, then constant values are dumped.
         """
 
         next_prefix: str = prefix + indent
@@ -374,34 +385,38 @@ class Circuit:
         print(f'{prefix}number of arcs: {self.number_of_arcs:,}')
 
         print(f'{prefix}var nodes: {self.number_of_vars}')
-        for var in self._vars:
+        for var in self.vars:
             node_name[id(var)] = f'var[{var.idx}]'
             var_name: str = '' if var_names is None or var.idx >= len(var_names) else var_names[var.idx]
             if var_name != '':
                 if var.is_const():
-                    print(f'{next_prefix}var[{var.idx}]: {var_name}, const({var.const.value})')
+                    print(f'{next_prefix}var[{var.idx}]: {var_name}, {var.const.value}')
                 else:
                     print(f'{next_prefix}var[{var.idx}]: {var_name}')
             elif var.is_const():
-                print(f'{next_prefix}var[{var.idx}]: const({var.const.value})')
+                print(f'{next_prefix}var[{var.idx}]: {var.const.value}')
+
+        if include_consts:
+            print(f'{prefix}const nodes: {self.number_of_consts}')
+            for const in self._const_map.values():
+                print(f'{next_prefix}{const.value!r}')
 
-        print(f'{prefix}const nodes: {self.number_of_consts}')
+        # Add const nodes to the node_name dict
         for const in self._const_map.values():
-            node_name[id(const)] = str(const.value)
-            print(f'{next_prefix}const({const.value})')
+            node_name[id(const)] = repr(const.value)
 
         # Add op nodes to the node_name dict
-        for i, op in enumerate(self._ops):
-            node_name[id(op)] = f'{op.symbol}<{i}>'
+        for i, op in enumerate(self.ops):
+            node_name[id(op)] = f'{op.op_str()}<{i}>'
 
         print(
             f'{prefix}op nodes: {self.number_of_op_nodes} '
             f'(arcs: {self.number_of_arcs}, ops: {self.number_of_operations})'
         )
-        for op in reversed(self._ops):
+        for op in reversed(self.ops):
             op_name = node_name[id(op)]
             args_str = ' '.join(node_name[id(arg)] for arg in op.args)
-            print(f'{next_prefix}{op_name}\\{len(op.args)}: {args_str}')
+            print(f'{next_prefix}{op_name}: {args_str}')
 
     def _check_nodes(self, nodes: Iterable[Args]) -> Tuple[CircuitNode, ...]:
         """
@@ -585,12 +600,18 @@ class OpNode(CircuitNode):
         self.symbol: int = symbol
 
     def __str__(self) -> str:
+        return f'{self.op_str()}\\{len(self.args)}'
+
+    def op_str(self) -> str:
+        """
+        Returns the op node operation as a string.
+        """
         if self.symbol == MUL:
-            return f'mul\\{len(self.args)}'
+            return 'mul'
         elif self.symbol == ADD:
-            return f'add\\{len(self.args)}'
+            return 'add'
         else:
-            return f'?{self.symbol}\\{len(self.args)}'
+            return '?' + str(self.symbol)
 
 
 @dataclass
@@ -688,7 +709,7 @@ class _DerivativeHelper:
             for value in (self._derivative_prod(prods) for prods in d_node.sum_prod)
             if not value.is_zero()
         )
-        # we can release the temporary memory at this DNode now
+        # We can release the temporary memory at this DNode now
         d_node.sum_prod = None
 
         # Construct the addition operation

ck/pgm.py

@@ -1,80 +1,5 @@
 """
-This module support the in-memory creation of probabilistic graphical models.
-
-A probabilistic graphical model (PGM) represents a joint probability distribution over
-a set of random variables. Specifically, a PGM is a factor graph with discrete random variables.
-
-A random variable is represented by a RandomVariable object. Each random variable has a
-fixed, finite number of states. Many algorithms will assume at least two states.
-Every RandomVariable object belongs to exactly one PGM object. A RandomVariable
-has a name (for human convenience) and its states are indexed by integers, counting
-from zero.
-
-A PGM also has factors. Each Factor of a PGM connects a set of RandomVariable objects
-of the PGM. In general, the order of the random variables of a factor is functionally
-irrelevant, but is practically relevant for operating with Factor objects. The "shape"
-of a factor is the list of the numbers of states of the factor's random variables (co-indexed
-with the list of random variables of the factor).
-
-If a PGM is representing a Bayesian network, then each factor represents a conditional
-probability table (CPT) and the first random variable of the factor is taken to be the child
-random variable, with the remaining random variables being the parents.
-
-Every factor has associated with it a potential function. A potential function maps
-each combination of states of the factor's random variables to a value (of type float).
-A combination of states of random variables is represented as a Key. A Key is essentially
-a list of state indexes, co-indexed with the factor's random variables.
-
-A potential function is a map from all possible keys (according to the potential function's
-shape) to a float value. Each potential function has zero or more "parameters" which may be
-adjusted to change the potential function's mapping. The parameters of a potential function
-are indexed sequentially from zero.
-
-Each parameter of a potential function is associated with one or more keys. The value of the
-parameter is the value of the potential function for it's associated keys. Conversely, each
-key of a potential function is associate with zero or one parameters. That is, it is possible
-that a potential function maps multiple keys to the same parameter, in which case keys that map
-to the same parameter will have the same value.
-
-If a key of a potential function is associated with a parameter, then the value of
-the potential function for that key is the value of the parameter.
-
-If a key of a potential function is associated with zero parameters then the value of
-the potential function for that key is zero. Furthermore, the key is referred to as
-"guaranteed-zero", meaning that no change in the parameter values of the potential function
-will change the value for that key away from zero.
-
-RandomVariable objects are immutable and hashable, including their states.
-
-Factor objects cannot change the random variables they are a factor of. However,
-the PotentialFunction associated with a Factor may be updated.
-
-Factors may share a potential function, so long as they have the same shape.
-
-PotentialFunction objects cannot change their shape, but may be otherwise mutable and
-are generally not hashable. A particular class of potential function may allow its mapping
-to change and even its available parameters to change.
-
-There are many kinds of potential function. A DensePotentialFunction has exactly
-one parameter for each possible key (no 'guaranteed-zero' keys) and there are no
-shared parameters. A SparsePotentialFunction only has parameters for explicitly
-mentioned keys.
-
-There is a special class of potential function called a ZeroPotentialFunction which
-(like DensePotentialFunction) has a parameter for each possible key (and thus no
-key is guaranteed-zero). However, the value of each parameter is zero and there
-is no mechanism to update these values.
-
-A ZeroPotentialFunction is the default PotentialFunction for a Factor. It may be seen
-as a light-weight placeholder until replaced by some other potential function.
-It may also be used as a light-weight surrogate for a DensePotentialFunction when
-performing PGM parameter learning.
-
-Each RandomVariable has an index (`idx`) which is a sequence number, starting from zero,
-indicating when that RandomVariable was added to its PGM.
-
-Each Factor has an  index (`idx`) which is a sequence number, starting from zero,
-indicating when that Factor was added to its PGM.
+For more documentation on this module, refer to the Jupyter notebook docs/4_PGM_advanced.ipynb.
 """
 from __future__ import annotations
 
@@ -82,8 +7,8 @@ import math
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from itertools import repeat as _repeat
-from typing import Sequence, Tuple, Dict, Optional, overload, Iterator, Set, Iterable, List, Union, Callable, \
-    Collection, Any
+from typing import Sequence, Tuple, Dict, Optional, overload, Set, Iterable, List, Union, Callable, \
+    Collection, Any, Iterator
 
 import numpy as np
 
@@ -462,7 +387,7 @@ class PGM:
             a string representation of the given indicators.
         """
         return delim.join(
-            f'{rv}{sep}{state}'
+            f'{_clean_str(rv)}{sep}{_clean_str(state)}'
             for rv, state in (
                 self.indicator_pair(indicator)
                 for indicator in indicators
@@ -559,7 +484,7 @@ class PGM:
         assert len(instance) == len(rvs)
         return delim.join(str(rv.states[i]) for rv, i in zip(rvs, instance))
 
-    def instances(self, flip: bool = False) -> Iterator[Instance]:
+    def instances(self, flip: bool = False) -> Iterable[Instance]:
         """
         Iterate over all possible instances of this PGM, in natural index
         order (i.e., last random variable changing most quickly).
@@ -573,7 +498,7 @@ class PGM:
         """
         return _combos_ranges(tuple(len(rv) for rv in self._rvs), flip=not flip)
 
-    def instances_as_indicators(self, flip: bool = False) -> Iterator[Sequence[Indicator]]:
+    def instances_as_indicators(self, flip: bool = False) -> Iterable[Sequence[Indicator]]:
         """
         Iterate over all possible instances of this PGM, in natural index
         order (i.e., last random variable changing most quickly).
@@ -605,7 +530,7 @@ class PGM:
         """
         return tuple(rv[state] for rv, state in zip(self._rvs, instance))
 
-    def factor_values(self, key: Key) -> Iterator[float]:
+    def factor_values(self, key: Key) -> Iterable[float]:
         """
         For a given instance key, each factor defines a single value. This method
         returns those values.
@@ -717,6 +642,11 @@ class PGM:
         If no indicators are provided, then the value of the partition function (z)
         is returned.
 
+        If multiple indicators are provided for the same random variable, then all matching
+        instances are summed.
+
+        This method has the same semantics as `ProbabilitySpace.wmc` without conditioning.
+
         Warning:
             this is potentially computationally expensive as it marginalised random
             variables not mentioned in the given indicators.
@@ -727,29 +657,51 @@ class PGM:
         Returns:
             the product of factors, conditioned on the given instance. This is the
             computed value of the PGM, conditioned on the given instance.
-
-        Raises:
-            RuntimeError: if a random variable is referenced multiple times in the given indicators.
         """
-        # Create an instance from the indicators
-        inst: List[int] = [-1] * self.number_of_rvs
+        # # Create a filter from the indicators
+        # inst_filter: List[Set[int]] = [set() for _ in range(self.number_of_rvs)]
+        # for indicator in indicators:
+        #     rv_idx: int = indicator.rv_idx
+        #     inst_filter[rv_idx].add(indicator.state_idx)
+        # # Collect rvs not mentioned - to marginalise
+        # for rv, rv_filter in zip(self.rvs, inst_filter):
+        #     if len(rv_filter) == 0:
+        #         rv_filter.update(rv.state_range())
+        #
+        # def _sum_inst(_instance: Instance) -> bool:
+        #     return all(
+        #         (_state in _rv_filter)
+        #         for _state, _rv_filter in zip(_instance, inst_filter)
+        #     )
+        #
+        # # Accumulate the result
+        # sum_value = 0
+        # for instance in self.instances():
+        #     if _sum_inst(instance):
+        #         sum_value += self.value_product(instance)
+        #
+        # return sum_value
+
+        # Work out the space to sum over
+        sum_space_set: List[Optional[Set[int]]] = [None] * self.number_of_rvs
         for indicator in indicators:
             rv_idx: int = indicator.rv_idx
-            if inst[rv_idx] >= 0:
-                raise RuntimeError(f'random variable mentioned multiple times: {self.rvs[rv_idx]}')
-            inst[rv_idx] = indicator.state_idx
+            cur_set = sum_space_set[rv_idx]
+            if cur_set is None:
+                sum_space_set[rv_idx] = cur_set = set()
+            cur_set.add(indicator.state_idx)
 
-        # Collect rvs not mentioned - to marginalise
-        rvs = [rv for rv in self.rvs if inst[rv.idx] < 0]
+        # Convert to a list of states that we need to sum over.
+        sum_space_list: List[List[int]] = [
+            list(cur_set if cur_set is not None else rv.state_range())
+            for cur_set, rv in zip(sum_space_set, self.rvs)
+        ]
 
         # Accumulate the result
-        sum_value = 0
-        for instance in rv_instances_as_indicators(*rvs):
-            for indicator in instance:
-                inst[indicator.rv_idx] = indicator.state_idx
-            sum_value += self.value_product(inst)
-
-        return sum_value
+        return sum(
+            self.value_product(instance)
+            for instance in _combos(sum_space_list)
+        )
 
     def dump_synopsis(
             self,
@@ -937,8 +889,8 @@ class PGM:
         else:
             _cur_rv = sorted(cur_rv)
             rv = self._rvs[_cur_rv[0].rv_idx]
-            states_str = sep.join(str(rv.states[ind.state_idx]) for ind in _cur_rv)
-            cur_str += f'{rv}{elem}{{{states_str}}}'
+            states_str: str = sep.join(_clean_str(rv.states[ind.state_idx]) for ind in _cur_rv)
+            cur_str += f'{_clean_str(rv)}{elem}{{{states_str}}}'
         return cur_str
 
 
@@ -1095,7 +1047,7 @@ class RandomVariable(Sequence[Indicator]):
         """
         return range(len(self._states))
 
-    def factors(self) -> Iterator[Factor]:
+    def factors(self) -> Iterable[Factor]:
         """
         Iterate over factors that this random variable participates in.
         This method performs a search through all `self.pgm.factors`.
@@ -1194,8 +1146,8 @@ class RandomVariable(Sequence[Indicator]):
             return self.idx == other.idx and len(self) == len(other)
         else:
             return (
-                len(indicators) == len(other) and
-                all(indicators[i] == other[i] for i in range(len(indicators)))
+                    len(indicators) == len(other) and
+                    all(indicators[i] == other[i] for i in range(len(indicators)))
             )
 
     def __len__(self) -> int:
@@ -1467,7 +1419,7 @@ class Factor:
     def __getitem__(self, index):
         return self._rvs[index]
 
-    def instances(self, flip: bool = False) -> Iterator[Instance]:
+    def instances(self, flip: bool = False) -> Iterable[Instance]:
         """
         Iterate over all possible instances, in natural index order (i.e.,
         last random variable changing most quickly).
@@ -1481,7 +1433,7 @@ class Factor:
         """
         return self.function.instances(flip)
 
-    def parent_instances(self, flip: bool = False) -> Iterator[Instance]:
+    def parent_instances(self, flip: bool = False) -> Iterable[Instance]:
         """
         Iterate over all possible instances of parent random variable, in
         natural index order (i.e., last random variable changing most quickly).
@@ -1935,7 +1887,7 @@ class PotentialFunction(ABC):
             raise ValueError(f'invalid parameter index: {param_idx}')
         return ParamId(id(self), param_idx)
 
-    def items(self) -> Iterator[Tuple[Instance, float]]:
+    def items(self) -> Iterable[Tuple[Instance, float]]:
         """
         Iterate over all keys and values of this potential function.
 
@@ -1946,7 +1898,7 @@ class PotentialFunction(ABC):
         for key in _combos_ranges(self._shape, flip=True):
             yield key, self[key]
 
-    def instances(self, flip: bool = False) -> Iterator[Instance]:
+    def instances(self, flip: bool = False) -> Iterable[Instance]:
         """
         Iterate over all possible instances, in natural index order (i.e.,
         last random variable changing most quickly).
@@ -1960,7 +1912,7 @@ class PotentialFunction(ABC):
         """
         return _combos_ranges(self._shape, flip=not flip)
 
-    def parent_instances(self, flip: bool = False) -> Iterator[Instance]:
+    def parent_instances(self, flip: bool = False) -> Iterable[Instance]:
         """
         Iterate over all possible instances of parent random variable, in
         natural index order (i.e., last random variable changing most quickly).
@@ -2055,7 +2007,7 @@ class ZeroPotentialFunction(PotentialFunction):
         return self.number_of_states
 
     @property
-    def params(self) -> Iterator[Tuple[int, float]]:
+    def params(self) -> Iterable[Tuple[int, float]]:
         for param_idx in range(self.number_of_parameters):
             yield param_idx, 0
 
@@ -2121,6 +2073,8 @@ class DensePotentialFunction(PotentialFunction):
 
     @property
     def params(self) -> Iterable[Tuple[int, float]]:
+        # Type warning due to numpy type erasure
+        # noinspection PyTypeChecker
         return enumerate(self._values)
 
     @property
@@ -2297,9 +2251,12 @@ class DensePotentialFunction(PotentialFunction):
 class SparsePotentialFunction(PotentialFunction):
     """
     A sparse potential function.
-    The default value for each parameter is zero.
-    The user may set the value of any key.
-    Setting the value of a key back to zero does not remove its parameter.
+
+    There is one parameter for each non-zero key value.
+    The user may set the value for any key and parameters will
+    be automatically reconfigured as needed. Setting the value for
+    a key to zero disassociates the key from its parameter and
+    thus makes that key "guaranteed zero".
     """
 
     def __init__(self, factor: Factor):
@@ -2354,7 +2311,7 @@ class SparsePotentialFunction(PotentialFunction):
         """
         Set the potential function value, for a given key.
         
-       If value is zero, then the key will become "guaranteed zero".
+        If value is zero, then the key will become "guaranteed zero".
 
         Arg:
             key: defines an instance in the state space of the potential function.
@@ -2368,7 +2325,7 @@ class SparsePotentialFunction(PotentialFunction):
 
         if param_idx is None:
             if value == 0:
-                # nothing to do
+                # Nothing to do
                 return
             param_idx = len(self._values)
             self._values.append(value)
@@ -2376,11 +2333,16 @@ class SparsePotentialFunction(PotentialFunction):
             return
 
         if value != 0:
-            # simple case
+            # Simple case
             self._values[param_idx] = value
             return
 
-        # Need to clear an existing non-zero parameter.
+        # This is the case where the key was associated with a parameter
+        # but the value is being set to zero, so we
+        # need to clear an existing non-zero parameter.
+        # This code operates by first ensuring the parameter is the last one,
+        # then popping the last parameter.
+
         end: int = len(self._values) - 1
         if param_idx != end:
             # need to swap the parameter with the end.
@@ -2392,7 +2354,7 @@ class SparsePotentialFunction(PotentialFunction):
                     # There will only be one, so we can break now
                     break
 
-        # remove the parameter
+        # Remove the parameter
         self._values.pop()
         self._params.pop(instance)
 
@@ -2541,10 +2503,14 @@ class SparsePotentialFunction(PotentialFunction):
 
 class CompactPotentialFunction(PotentialFunction):
     """
-    A sparse potential function.
-    There is one parameter for each unique, non-zero parameter value.
-    The default value for each parameter is zero.
-    The user may set the value of any key.
+    A compact potential function is sparse, where values for keys of
+    the same value are represented by a single parameter.
+
+    There is one parameter for each unique, non-zero key value.
+    The user may set the value for any key and parameters will
+    be automatically reconfigured as needed. Setting the value for
+    a key to zero disassociates the key from its parameter and
+    thus makes that key "guaranteed zero".
     """
 
     def __init__(self, factor: Factor):
@@ -2772,9 +2738,9 @@ class CompactPotentialFunction(PotentialFunction):
 
     def _remove_param(self, param_idx: int) -> None:
         """
-        Remove the index parameter from self._params and self._counts.
+        Remove the indexed parameter from self._params and self._counts.
         If the parameter is not at the end of the list of parameters
-        then it will be swapped with the end parameter.
+        then it will be swapped with the last parameter in the list.
         """
 
         # ensure the parameter is at the end of the list
@@ -2796,10 +2762,10 @@ class CompactPotentialFunction(PotentialFunction):
 
 class ClausePotentialFunction(PotentialFunction):
     """
-    A clause potential function represents a clause (from a CNF formula) i.e. a disjunction.
-    A clause over variables X, Y, Z, is of the form: 'X=x or Y=y or Z=z'.
+    A clause potential function represents a clause From a CNF formula.
+    I.e. a clause over variables X, Y, Z, is a disjunction of the form: 'X=x or Y=y or Z=z'.
 
-    A clause potential function guaranteed zero for the key where the clause is false,
+    A clause potential function is guaranteed zero for a key where the clause is false,
     i.e., when 'X != x and Y != y and Z != z'.
 
     For keys where the clause is true, the value of the potential function
@@ -3047,7 +3013,7 @@ class CPTPotentialFunction(PotentialFunction):
         else:
             return self._values[offset:offset + child_size]
 
-    def cpds(self) -> Iterator[Tuple[Instance, Sequence[float]]]:
+    def cpds(self) -> Iterable[Tuple[Instance, Sequence[float]]]:
         """
         Iterate over (parent_states, cpd) tuples.
         This will exclude zero CPDs.
@@ -3358,7 +3324,7 @@ def number_of_states(*rvs: RandomVariable) -> int:
     return _multiply(len(rv) for rv in rvs)
 
 
-def rv_instances(*rvs: RandomVariable, flip: bool = False) -> Iterator[Instance]:
+def rv_instances(*rvs: RandomVariable, flip: bool = False) -> Iterable[Instance]:
     """
     Enumerate instances of the given random variables.
 
@@ -3377,7 +3343,7 @@ def rv_instances(*rvs: RandomVariable, flip: bool = False) -> Iterator[Instance]
     return _combos_ranges(shape, flip=not flip)
 
 
-def rv_instances_as_indicators(*rvs: RandomVariable, flip: bool = False) -> Iterator[Sequence[Indicator]]:
+def rv_instances_as_indicators(*rvs: RandomVariable, flip: bool = False) -> Iterable[Sequence[Indicator]]:
     """
     Enumerate instances of the given random variables.
 
@@ -3492,3 +3458,18 @@ def _normalise_potential_function(
             total = group_sum[group]
             if total > 0:
                 function.set_param_value(param_idx, param_value / total)
+
+
+_CLEAN_CHARS: Set[str] = set('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-+~?.')
+
+
+def _clean_str(s) -> str:
+    """
+    Quote a string if empty or not all characters are in _CLEAN_CHARS.
+    This is used when rendering indicators.
+    """
+    s = str(s)
+    if len(s) == 0 or not all(c in _CLEAN_CHARS for c in s):
+        return repr(s)
+    else:
+        return s