compiled-knowledge 4.0.0a24__tar.gz → 4.0.0a25__tar.gz

{compiled_knowledge-4.0.0a24/src/compiled_knowledge.egg-info → compiled_knowledge-4.0.0a25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compiled-knowledge
-Version: 4.0.0a24
+Version: 4.0.0a25
 Summary: A Python package for compiling and querying discrete probabilistic graphical models.
 Author-email: Barry Drake <barry@compiledknowledge.org>
 License-Expression: MIT

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "compiled-knowledge"
-version = "4.0.0a24"
+version = "4.0.0a25"
 description = "A Python package for compiling and querying discrete probabilistic graphical models."
 readme = "README.md"
 license = "MIT"
@@ -36,6 +36,7 @@ setuptools = "*"
 build = "*"
 cibuildwheel = "*"
 jupyter-book = "*"
+sphinx = "*"
 twine = "*"
 toml = "*"
 

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/circuit/tmp_const.py

@@ -10,15 +10,16 @@ class TmpConst:
     A TmpConst enables the consistent, temporary setting and clearing
     of circuit variables to constant values.
 
-    Example usage:
+    Example usage::
+
         with TmpConst(my_circuit) as tmp:
             tmp.set_const(0, 123.456)
             tmp.set_const(my_list_of_vars, 110.99)
             program = Program(my_top)
-        # now use 'program'
+        # now use `program`
 
-    Within the 'with' section, circuit variables are set to const values, which
-    the compiler can optimise. When the 'with' section exits, the variables
+    Within the `with` section, circuit variables are set to const values, which
+    the compiler can optimise. When the `with` section exits, the variables
     are restored to their original state.
     """
     __slots__ = ('_circuit', '_undo')

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/circuit_compiler/support/llvm_ir_function.py

@@ -213,10 +213,10 @@ def compile_llvm_program(
     Compile the given LLVM program.
 
     Returns:
-        (engine, function) where
-        engine: is an LLVM execution engine, which must remain
-            in memory for the returned function to be valid.
-        function: is the raw Python callable for the compiled function.
+        `engine` an LLVM execution engine, which must remain
+        in memory for the returned function to be valid,
+
+        `function` the raw Python callable for the compiled function.
     """
     _init_llvm()
 

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/example/diamond_square.py

@@ -8,7 +8,8 @@ class DiamondSquare(PGM):
     This PGM is the 'DiamondSquare' factor graph.
 
     The DiamondSquare is a factor graph with seven random variables (a, b, c, ..., h).
-    Binary factors are between pairs of random variables creating the pattern:
+    Binary factors are between pairs of random variables creating the pattern::
+
                      b
                     / \
                    /   \
@@ -20,6 +21,7 @@ class DiamondSquare(PGM):
                   \   /
                    \ /
                     g
+
     If include_unaries then, also includes one unary factor per random variable.
     """
 

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/example/triangle_square.py

@@ -8,12 +8,14 @@ class TriangleSquare(PGM):
     This PGM is the 'TriangleSquare' factor graph.
 
     The TriangleSquare is a factor graph with six random variables (a, b, c, ..., f).
-    Binary factors are between pairs of random variables crating the pattern:
+    Binary factors are between pairs of random variables crating the pattern::
+
                   b -- d
                 / |    | \
                a  |    |  f
                 \ |    | /
                   c -- e
+
     If include_unaries then, also includes one unary factor per random variable.
     """
 

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/example/truss.py

@@ -7,12 +7,14 @@ class Truss(PGM):
     This PGM is the 'Truss' factor graph.
 
     The Truss is a factor graph with five random variables (a, b, c, d, e).
-    Binary factors are between pairs of random variables creating the pattern:
+    Binary factors are between pairs of random variables creating the pattern::
+
                   b ---- d
                 / |    / |
                a  |  /   |
                 \ | /    |
                   c ---- e
+
     If include_unaries then, also includes one unary factor per random variable.
     """
 

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/in_out/parse_net.py

@@ -16,36 +16,37 @@ def read_network(input_stream, *, name: Optional[str] = None, network_builder: O
     The input can be a string or a stream.
     If the input is empty, then its is treated as an error.
 
-    This input is expected to conform to the following format.
+    This input is expected to conform to the following format::
 
-    <network> ::= <net_block> <node_block>* <potential_block>*
+        <network> ::= <net_block> <node_block>* <potential_block>*
 
-    <net_block> ::= 'net' <block>
+        <net_block> ::= 'net' <block>
 
-    <node_block> ::= 'node' <NAME> <block>
+        <node_block> ::= 'node' <NAME> <block>
 
-    <potential_block> ::= 'potential' <link> <block>
+        <potential_block> ::= 'potential' <link> <block>
 
-    <block> ::= '{' <sentence>* '}'
-    <sentence> ::= <NAME> '=' <value> ';'
+        <block> ::= '{' <sentence>* '}'
+        <sentence> ::= <NAME> '=' <value> ';'
 
-    <link> ::= '(' <NAME> ')'
-             | '(' <NAME> '|' <NAME>+ ')'
+        <link> ::= '(' <NAME> ')'
+                 | '(' <NAME> '|' <NAME>+ ')'
 
-    <value> ::= <STRING> | <NUMBER> | <list>
-    <list> ::='(' <value>* ')'
+        <value> ::= <STRING> | <NUMBER> | <list>
+        <list> ::='(' <value>* ')'
 
     The sentences of a <net_block> are ignored.
 
-    The sentences of a <node_block>
-        <name> of 'states' mandatory, with value that is a list of <STRING>
-        other sentences are ignored.
+    In a <node_block>,
+    <name> of 'states' mandatory, with value that is a list of <STRING>
+    other sentences are ignored.
 
-    The sentences of a <potential_block>
-        <name> of 'data' mandatory, with value that is a list of (list of)* <NUMBER> (shape matching the link)
-        other sentences are ignored.
+    In a <potential_block>,
+    <name> of 'data' is mandatory, with value that is a list of (list of) <NUMBER> (shape matching the link)
+    other sentences are ignored.
+
+    Here is a simple example input::
 
-    Here is a simple example input:
         net{}
         node a
         {
@@ -62,8 +63,9 @@ def read_network(input_stream, *, name: Optional[str] = None, network_builder: O
         }
         potential ( b | a )
         {
-          data = ((0.4 0.4 0.2)(0.4 0.4 0.2)) ;
+          data = ((0.4 0.4 0.2)(0.4 0.4 0.2));
         }
+
     """
     # Decorate the input stream
     input_stream = ParserInput(input_stream)

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/in_out/parser_utils.py

@@ -57,8 +57,10 @@ class ParserInput:
 
     def readline(self) -> str:
         """
+        Read a line of input.
+
         Returns:
-             the next line (including the trailing '\n') or '' if EOF.
+             the next line (including the trailing newline) or empty string if EOF.
         """
         line = ''
         while True:
@@ -69,9 +71,11 @@ class ParserInput:
 
     def read_past_space(self, single_line: bool, comment_char=None) -> str:
         """
+        Read the input up to and including the first non-whitespace character.
+
         Returns:
-            either empty string, '', if end of input, otherwise a single character string that is not whitespace.
-            If single_line is True, then '\n' is treated as eof.
+            either empty string, if end of input, otherwise a single character string that is not whitespace.
+            If single_line is True, then newline is treated as eof.
         """
         c = self.read_one()
         while True:

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/pgm.py

@@ -15,33 +15,32 @@ from ck.utils.iter_extras import (
 from ck.utils.np_extras import NDArrayFloat64, NDArrayUInt8
 
 State: TypeAlias = Union[int, str, bool, float, None]
-State.__doc__ = \
-    """
-    The type for a possible state of a random variable.
-    """
+"""
+The type for a possible state of a random variable.
+"""
 
 Instance: TypeAlias = Sequence[int]
-Instance.__doc__ = \
-    """
-    An instance (of a sequence of random variables) is a sequence of integers
-    that are state indexes, co-indexed with a known sequence of random variables.
-    """
+"""
+An instance (of a sequence of random variables) is a sequence of integers
+that are state indexes, co-indexed with a known sequence of random variables.
+"""
 
 Key: TypeAlias = Union[Instance, int]
-Key.__doc__ = \
-    """
-    A key identifies an instance, either as an instance itself or a
-    single integer, representing an instance with one dimension.
-    """
+"""
+A key identifies an instance, either as an instance itself or a
+single integer, representing an instance with one dimension.
+"""
 
 Shape: TypeAlias = Sequence[int]
-Key.__doc__ = \
-    """
-    The type for the "shape" of a sequence of random variables.
-    That is, the shape of (rv1, rv2, rv3) is (len(rv1), len(rv2), len(rv3)).
-    """
+"""
+The type for the "shape" of a sequence of random variables.
+That is, the shape of (rv1, rv2, rv3) is (len(rv1), len(rv2), len(rv3)).
+"""
 
-DEFAULT_CPT_TOLERANCE: float = 0.000001  # A tolerance when checking CPT distributions sum to one (or zero).
+DEFAULT_CPT_TOLERANCE: float = 0.000001
+"""
+A tolerance when checking CPT distributions sum to one (or zero).
+"""
 
 
 class PGM:
@@ -214,14 +213,17 @@ class PGM:
         The returned random variable will have an `idx` equal to the value of
         `self.number_of_rvs` just prior to adding the new random variable.
 
+        The states of the random variable can be specified either as an integer
+        representing the number of states, or as a sequence of state values. If a
+        single integer, `n`, is provided then the states will be: 0, 1, ..., n-1.
+        If a sequence of states are provided then the states must be unique.
+
         Assumes:
             Provided states contain no duplicates.
 
         Args:
             name: a name for the random variable.
-            states: either an integer number of states or a sequence of state values. If a
-                single integer, `n`, is provided then the states will be 0, 1, ..., n-1.
-                If a sequence of states are provided then the states must be unique.
+            states: either the number of states or a sequence of state values.
 
         Returns:
             a RandomVariable object belonging to this PGM.
@@ -241,10 +243,11 @@ class PGM:
 
         Assumes:
             The given random variables all belong to this PGM.
+
             The random variables contain no duplicates.
 
         Args:
-            *rvs: the random variables.
+            rvs: the random variables.
 
         Returns:
             a Factor object belonging to this PGM.
@@ -336,17 +339,18 @@ class PGM:
             *input_rvs: RandomVariable
     ) -> Factor:
         """
-        Add a sparse 0/1 factor to this PGM representing:
-            result_rv ==  function(*rvs).
-        That is:
+        Add a sparse 0/1 factor to this PGM representing `result_rv == function(*rvs)`.
+        That is::
+
             factor[result_s, *input_s] = 1, if result_s == function(*input_s);
                                        = 0, otherwise.
+
         Args:
             function: a function from state indexes of the input random variables to a state index
                 of the result random variable. The function should take the same number of arguments
                 as `input_rvs` and return a state index for `result_rv`.
             result_rv: the random variable defining result values.
-            *input_rvs: the random variables defining input values.
+            input_rvs: the random variables defining input values.
 
         Returns:
             a Factor object belonging to this PGM, with a configured sparse potential function.
@@ -378,16 +382,17 @@ class PGM:
         """
         Render indicators as a string.
 
-        For example:
+        For example::
             pgm = PGM()
             a = pgm.new_rv('A', ('x', 'y', 'z'))
             b = pgm.new_rv('B', (3, 5))
             print(pgm.indicator_str(a[0], b[1], a[2]))
-        will print:
+
+        will print::
             A=x, B=5, A=z
 
         Args:
-            *indicators: the indicators to render.
+            indicators: the indicators to render.
             sep: the separator to use between the random variable and its state.
             delim: the delimiter to used when rendering multiple indicators.
 
@@ -406,16 +411,17 @@ class PGM:
         """
         Render indicators as a string, grouping indicators by random variable.
 
-        For example:
+        For example::
             pgm = PGM()
             a = pgm.new_rv('A', ('x', 'y', 'z'))
             b = pgm.new_rv('B', (3, 5))
             print(pgm.condition_str(a[0], b[1], a[2]))
-        will print:
+
+        will print::
             A in {x, z}, B=5
 
         Args:
-            *indicators: the indicators to render.
+            indicators: the indicators to render.
         Return:
             a string representation of the given indicators, as a condition.
         """
@@ -930,9 +936,9 @@ class RandomVariable(Sequence[Indicator]):
     in the random variable's PGM list of random variables.
 
     A random variable behaves like a sequence of Indicators, where each indicator represents a random
-    variable being in a particular state. Specifically for a random variable rv, len(rv) is the
+    variable being in a particular state. Specifically for a random variable rv, `len(rv)` is the
     number of states of the random variable and rv[i] is the Indicators representing that
-    rv is in the ith state. When sliced, the result is a tuple, i.e. rv[1:3] = (rv[1], rv[2]).
+    rv is in the ith state. When sliced, the result is a tuple, i.e. `rv[1:3] = (rv[1], rv[2])`.
 
     A RandomVariable has a name. This is for human convenience and has no functional purpose
     within a PGM.
@@ -942,15 +948,18 @@ class RandomVariable(Sequence[Indicator]):
         """
         Create a new random variable, in the given PGM.
 
+        The states of the random variable can be specified either as an integer
+        representing the number of states, or as a sequence of state values. If a
+        single integer, `n`, is provided then the states will be: 0, 1, ..., n-1.
+        If a sequence of states are provided then the states must be unique.
+
         Assumes:
             Provided states contain no duplicates.
 
         Args:
             pgm: the PGM that the random variable will belong to.
             name: a name for the random variable.
-            states: either an integer number of states or a sequence of state values. If a
-                single integer, `n`, is provided then the states will be 0, 1, ..., n-1.
-                If a sequence of states are provided then the states must be unique.
+            states: either the number of states or a sequence of state values.
         """
         self._pgm: PGM = pgm
         self._name: str = name
@@ -1212,15 +1221,14 @@ class RVMap(Sequence[RandomVariable]):
     In addition to accessing a random variable by its index, an RVMap enables
     access to the PGM random variable via the name of each random variable.
 
-    For example, if `pgm.rvs[1]` is a random variable named `xray`, then:
-    ```
-    rvs = RVMap(pgm)
+    For example, if `pgm.rvs[1]` is a random variable named `xray`, then::
+
+        rvs = RVMap(pgm)
 
-    # These all retrieve the same random variable object.
-    xray = rvs[1]
-    xray = rvs('xray')
-    xray = rvs.xray
-    ```
+        # These all retrieve the same random variable object.
+        xray = rvs[1]
+        xray = rvs('xray')
+        xray = rvs.xray
 
     To use an RVMap on a PGM, the random variable names must be unique across the PGM.
     """
@@ -1527,7 +1535,7 @@ class Factor:
         Set to the potential function to a new `ClausePotentialFunction` object.
 
         Args:
-            *key: defines the random variable states of the clause. The key is a sequence of
+            key: defines the random variable states of the clause. The key is a sequence of
                 random variable state indexes, co-indexed with `Factor.rvs`.
 
         Returns:
@@ -1556,7 +1564,7 @@ class Factor:
         return self._potential_function
 
 
-@dataclass(frozen=True, eq=True)
+@dataclass(frozen=True, eq=True, slots=True)
 class ParamId:
     """
     A ParamId identifies a parameter of a potential function.
@@ -2164,7 +2172,7 @@ class DensePotentialFunction(PotentialFunction):
         """
         Set the values of the potential function using the given iterator.
 
-        Mapping instances to *values is as follows:
+        Mapping instances to values is as follows:
             Given Factor(rv1, rv2) where rv1 has 2 states, and rv2 has 3 states:
             values[0] represents instance (0,0)
             values[1] represents instance (0,1)
@@ -2209,7 +2217,7 @@ class DensePotentialFunction(PotentialFunction):
         The order of values is the same as set_iter.
         
         Args:
-            *value: the values to use.
+            value: the values to use.
             
         Returns:
             self
@@ -2414,7 +2422,7 @@ class SparsePotentialFunction(PotentialFunction):
         """
         Set the values of the potential function using the given iterator.
 
-        Mapping instances to *values is as follows:
+        Mapping instances to values is as follows:
             Given Factor(rv1, rv2) where rv1 has 2 states, and rv2 has 3 states:
             values[0] represents instance (0,0)
             values[1] represents instance (0,1)
@@ -2636,7 +2644,7 @@ class CompactPotentialFunction(PotentialFunction):
         """
         Set the values of the potential function using the given iterator.
 
-        Mapping instances to *values is as follows:
+        Mapping instances to `values` is as follows:
             Given Factor(rv1, rv2) where rv1 has 2 states, and rv2 has 3 states:
             values[0] represents instance (0,0)
             values[1] represents instance (0,1)
@@ -2679,7 +2687,7 @@ class CompactPotentialFunction(PotentialFunction):
         The order of values is the same as set_iter.
 
         Args:
-            *value: the values to use.
+            value: the values to use.
 
         Returns:
             self
@@ -3071,7 +3079,8 @@ class CPTPotentialFunction(PotentialFunction):
         Calls self.set_cpd(parent_states, cpd) for each row (parent_states, cpd)
         in rows. Any unmentioned parent states will have zero probabilities.
 
-        Example usage, assuming three Boolean random variables:
+        Example usage, assuming three Boolean random variables::
+
             pgm.Factor(x, y, z).set_cpt().set(
                 # y  z    x[0] x[1]
                 ((0, 0), (0.1, 0.9)),
@@ -3079,9 +3088,9 @@ class CPTPotentialFunction(PotentialFunction):
                 ((1, 0), (0.1, 0.9)),
                 ((1, 1), (0.1, 0.9))
             )
-        
+
         Args:
-            *rows: are tuples (key, cpd) used to set the potential function values.
+            rows: are tuples (key, cpd) used to set the potential function values.
             
         Raises:
             ValueError: if a CPD is not valid.
@@ -3105,7 +3114,7 @@ class CPTPotentialFunction(PotentialFunction):
         Any list entry may be None, indicating 'guaranteed zero' for the associated parent states.
 
         Args:
-            *cpds: are the CPDs used to set the potential function values.
+            cpds: are the CPDs used to set the potential function values.
             
         Raises:
             ValueError: if a CPD is not valid.

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/pgm_circuit/mpe_program.py

@@ -228,10 +228,9 @@ class MPEProgram(ProgramWithSlotmap):
 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
+    """the weighted model count value of the MPE solution."""
+
     mpe: Instance
+    """the MPE solution instance. If there are ties then this will just be once instance."""

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/pgm_circuit/pgm_circuit.py

@@ -16,33 +16,42 @@ class PGMCircuit:
     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]
+    """holds the random variables from the PGM as it was compiled, in order."""
+
     conditions: Sequence[Indicator]
+    """any conditions on `rvs` that were compiled into the circuit."""
+
     circuit_top: CircuitNode
+    """the top circuit node defining the network function."""
+
     number_of_indicators: int
+    """
+    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: int
+    """
+    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: SlotMap
+    """
+    gives the index of the circuit variable corresponding to x,
+    where x is either a random variable indicator (Indicator) or a parameter id (ParamId).
+    """
+
     parameter_values: NDArray
+    """
+    parameter values, co-indexed with the circuit variables, counting beyond `number_of_indicators`.
+    """
 
     def dump(self, *, prefix: str = '', indent: str = '    ') -> None:
         """

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/pgm_circuit/program_with_slotmap.py

@@ -114,7 +114,10 @@ class ProgramWithSlotmap:
 
     def compute_conditioned(self, *condition: Condition) -> NDArrayNumeric:
         """
-        Equivalent to:
+        Compute the program value, after setting the given condition.
+
+        Equivalent to::
+
             self.set_condition(*condition)
             return self.compute()
         """

{compiled_knowledge-4.0.0a24 → compiled_knowledge-4.0.0a25}/src/ck/probability/probability_space.py

@@ -11,17 +11,16 @@ from ck.utils.map_set import MapSet
 from ck.utils.np_extras import dtype_for_number_of_states, NDArrayFloat64, DTypeStates, NDArrayNumeric
 
 Condition: TypeAlias = None | Indicator | Iterable[Indicator]
-Condition.__doc__ = \
-    """
-    Type defining a condition. A condition is logically a set of
-    indicators, each indicator representing a random variable being in some state.
-    
-    If multiple indicators of the same random variable appear in
-    a condition, then they are interpreted as
-    a disjunction, otherwise indicators are interpreted as
-    a conjunction. E.g.,  the condition (X=0, Y=1, Y=3) means
-    X=0 and (Y=1 or Y=3).
-    """
+"""
+Type defining a condition. A condition is logically a set of
+indicators, each indicator representing a random variable being in some state.
+
+If multiple indicators of the same random variable appear in
+a condition, then they are interpreted as
+a disjunction, otherwise indicators are interpreted as
+a conjunction. E.g.,  the condition (X=0, Y=1, Y=3) means
+X=0 and (Y=1 or Y=3).
+"""
 
 _NAN: float = np.nan  # Not-a-number (i.e., the result of an invalid calculation).