compiled-knowledge 4.0.0a5__cp313-cp313-macosx_10_13_universal2.whl

ck/utils/np_extras.py

@@ -0,0 +1,51 @@
+# Type used by numpy and ctypes for data type definition
+
+import numpy as np
+
+# A numpy/ctypes data type.
+DType = np.typing.DTypeLike
+
+# A numpy data type for holding state indexes.
+DTypeStates = np.dtypes.UInt8DType | np.dtypes.UInt16DType | np.dtypes.UInt32DType | np.dtypes.UInt64DType
+
+DTypeNumeric = (
+        np.dtypes.Float64DType | np.dtypes.Float32DType
+        | np.dtypes.Int8DType | np.dtypes.Int16DType | np.dtypes.Int32DType | np.dtypes.Int64DType
+        | np.dtypes.UInt8DType | np.dtypes.UInt16DType | np.dtypes.UInt32DType | np.dtypes.UInt64DType
+)
+
+# A numpy array data type.
+NDArray = np.typing.NDArray
+
+NDArrayUInt8 = NDArray[np.dtypes.UInt8DType]
+NDArrayUInt16 = NDArray[np.dtypes.UInt16DType]
+NDArrayUInt32 = NDArray[np.dtypes.UInt32DType]
+NDArrayUInt64 = NDArray[np.dtypes.UInt64DType]
+
+NDArrayFloat64 = NDArray[np.dtypes.Float64DType]
+
+NDArrayStates = NDArray[DTypeStates]
+NDArrayNumeric = NDArray[DTypeNumeric]
+
+
+# Constants for maximum number of states.
+_MAX_STATES_8: int = 2 ** 8 - 1
+_MAX_STATES_16: int = 2 ** 16 - 1
+_MAX_STATES_32: int = 2 ** 32 - 1
+_MAX_STATES_64: int = 2 ** 64 - 1
+
+
+def dtype_for_number_of_states(number_of_states: int) -> DTypeStates:
+    """
+    Infer the numpy dtype required to store any state index of the given PGM.
+    """
+    # Infer the needed size of
+    if number_of_states <= _MAX_STATES_8:
+        return np.uint8
+    if number_of_states <= _MAX_STATES_16:
+        return np.uint16
+    if number_of_states <= _MAX_STATES_32:
+        return np.uint32
+    if number_of_states <= _MAX_STATES_64:
+        return np.uint64
+    raise ValueError(f'cannot determine dtype for the given number of states: {number_of_states!r}')

ck/utils/random_extras.py

@@ -0,0 +1,64 @@
+"""
+A module with extra randomisation functions.
+"""
+import random
+from typing import Protocol, Sequence, Tuple, Any, List
+
+
+class Random(Protocol):
+    """
+    A minimum protocol for a random number generator as used by CK.
+    The usual `random` package implements this protocol.
+    """
+
+    def random(self) -> float:
+        """
+        Returns a random float in the interval [0, 1), includes 0, excludes 1.
+        """
+        ...
+
+    def randrange(self, a: int, b: int) -> int:
+        """
+        Returns a random integer in interval [a, b), includes `a`, excludes `b`.
+        """
+        ...
+
+
+def random_pair(size: int, rand: Random = random) -> Tuple[int, int]:
+    """
+    Return a random pair (i, j) where:
+    0 <= i < size,
+    0 <= j < size,
+    i != j.
+    """
+    i = rand.randrange(0, size)
+    j = (i + rand.randrange(1, size)) % size
+    return i, j
+
+
+def random_permute(items: List[Any], rand: Random = random) -> None:
+    """
+    Randomly permute the given items.
+    For a list of length `n`, this method calls rand.randrange(...) `n - 1` times.
+
+    There is a numpy method to do this, but it uses its own random number generator.
+    """
+    for i in range(len(items) - 1, 0, -1):  # i = n - 1 down to 1
+        j = rand.randrange(0, i + 1)  # 0 <= j <= i
+        items[i], items[j] = items[j], items[i]  # exchange
+
+
+def random_permutation(size: int, rand: Random = random) -> Sequence[int]:
+    """
+    Return a random permutation of the given size.
+
+    The returned list contains each integer 0 to size - 1
+    in a random order.
+
+    This method calls rand.randrange(...) 'size' times.
+
+    There is a numpy method to do this, but it uses its own random number generator.
+    """
+    result = list(range(size))
+    random_permute(result, rand)
+    return result

ck/utils/tmp_dir.py

@@ -0,0 +1,94 @@
+"""
+This is a module for creating a temporary directory and making it the working directory.
+
+Usage:
+    from tmp_dir import tmp_dir
+
+    with tmp_dir():
+        # do some stuff
+"""
+import os as _os
+import shutil as _shutil
+import tempfile as _tempfile
+from pathlib import Path
+from typing import Union
+
+
+class tmp_dir:
+    __slots__ = ('_new_dir', '_old_cwd', '_chdir', '_delete_when_done')
+
+    def __init__(
+            self,
+            name: Union[Path, str, None] = None,
+            chdir: bool = True,
+            delete_when_done: bool = True
+    ):
+        """
+        Create a temporary directory, make it the working
+        directory (unless chdir is False), clean up when done
+        (unless delete_when_done is False).
+
+        Args:
+            name: the name of the temporary directory. If name
+                is None, then `tempfile.mkdtemp()` is used.
+            chdir: if True, then chdir to the temporary directory.
+            delete_when_done: if True, then the temporary directory is
+                deleted when done.
+        """
+
+        if name is None:
+            self._new_dir = Path(_tempfile.mkdtemp())
+        else:
+            self._new_dir = Path(name).absolute()
+            self._new_dir.mkdir(exist_ok=True, parents=True)
+
+        self._old_cwd = Path.cwd()
+        self._chdir = chdir
+        if chdir:
+            _os.chdir(self._new_dir)
+        self._delete_when_done = delete_when_done
+
+    def __del__(self):
+        """
+        Calls self.done().
+        """
+        self.done()
+
+    @property
+    def path(self) -> Path:
+        """
+        What is the path to the temporary directory.
+        """
+        return self._new_dir
+
+    def __truediv__(self, arg) -> Path:
+        """
+        Append a path element, just like a Path object.
+        """
+        return self.path / arg
+
+    def done(self) -> None:
+        """
+        Change back to the old working directory and delete the temporary
+        directory, along with all its contents.
+
+        Subsequent calls to done() take no further action.
+        """
+        if self._new_dir is not None:
+            if self._chdir:
+                _os.chdir(self._old_cwd)
+            if self._delete_when_done:
+                _shutil.rmtree(self._new_dir)
+        self._old_cwd = None
+        self._new_dir = None
+
+    def __enter__(self):
+        # nothing to do - already created at __init__
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.done()
+        return exc_val is None
+
+    def __str__(self):
+        return str(self._new_dir)

ck_demos/ace/copy_ace_to_ck.py

@@ -0,0 +1,15 @@
+"""
+This is an example Python script for copying Ace to CK.
+"""
+from ck.pgm_compiler.ace import copy_ace_to_default_location
+
+
+SOURCE_ACE: str = r'C:\Research\Ace\ace_v3.0_windows'
+
+
+def main() -> None:
+    copy_ace_to_default_location(SOURCE_ACE)
+
+
+if __name__ == "__main__":
+    main()

ck_demos/ace/demo_ace.py

@@ -0,0 +1,44 @@
+from ck import example
+from ck.pgm import PGM
+from ck.pgm_compiler import ace
+from ck.pgm_circuit import PGMCircuit
+from ck.pgm_circuit.wmc_program import WMCProgram
+
+
+def main() -> None:
+    pgm: PGM = example.Rain()
+
+    # `ace.compile_pgm` will look for an Ace installation in
+    # a default location. If Ace is not installed in the default
+    # location, then either: (1) pass the location as an argument
+    # to `ace.compile_pgm`, or (2) copy the Ace files to
+    # the default location using `ace.copy_ace_to_default_location`.
+    #
+    # Here is an example showing how to copy Ace to the default
+    # location from a source directory.
+    #
+    # ace.copy_ace_to_default_location(r'E:\Dropbox\Research\Ace\all')
+
+    pgm_cct: PGMCircuit = ace.compile_pgm(pgm, print_output=True)
+
+    print(f'PGM: {pgm.name}')
+    print()
+    print(f'Circuit:')
+    pgm_cct.dump()
+    print()
+
+    wmc = WMCProgram(pgm_cct)
+
+    print('Showing Program results:')
+    for indicators in pgm.instances_as_indicators():
+        instance_as_str = pgm.indicator_str(*indicators)
+        wmc_value = wmc.wmc(*indicators)
+        pgm_value = pgm.value_product_indicators(*indicators)
+        print(f'  {instance_as_str:80} {wmc_value:.6f} {pgm_value:.6f}')
+
+    print()
+    print('Done.')
+
+
+if __name__ == '__main__':
+    main()

ck_demos/all_demos.py

@@ -0,0 +1,88 @@
+"""
+Run all the demo scripts (except nominated exclusions).
+This may be used as a 'smoke test'.
+"""
+import sys
+from pathlib import Path
+from subprocess import call
+
+from ck_demos.utils.stop_watch import StopWatch
+
+DEMO_TOP_DIR = '.'  # relative to the directory this script is in
+
+# These are scripts and directories we explicitly will not include
+EXCEPTIONS = [
+    'utils',  # package of utilities
+    'ace',  # 3rd party, optional dependency
+]
+
+# These are what are printed as a separator lines
+LINE = '-' * 80
+LINE_2 = '=' * 80
+
+
+def main() -> int:
+    python_exe = sys.executable
+    print('Python executable:', python_exe)
+    print()
+
+    errors = []
+    script_count = 0
+    python_env = None
+    total_time = StopWatch()
+
+    # Start search of demo directories in the script directory.
+    script_path = Path(__file__)
+    script_name = script_path.stem
+    demos_top_dir_path = (script_path.parent / DEMO_TOP_DIR)
+    dirs = find_demo_dirs(demos_top_dir_path)
+
+    # Always exclude self if we happen to find our own script.
+    exceptions = set(EXCEPTIONS + [Path(__file__).name])
+
+    for demo_dir in dirs:
+        for script in demo_dir.iterdir():
+            if (
+                    script.is_file() and
+                    script.name.endswith('.py') and
+                    (not script.name.startswith('_')) and
+                    script.name not in exceptions
+            ):
+                print(LINE)
+                print(script.name)
+                print(LINE)
+                script_count += 1
+
+                time = StopWatch()
+                return_code = call([python_exe, script.as_posix()], env=python_env)
+                time.stop()
+
+                if return_code != 0:
+                    errors.append(f'Error code {return_code}: {script.name}')
+                print(LINE)
+                print(f'exited with code {return_code}, time = {time}, file = {script.name}')
+
+    print(LINE_2)
+    print(f'Done running {script_name}, {script_count} scripts in {total_time}s')
+    print(f'Number of errors: {len(errors)}')
+    for error in errors:
+        print(error)
+
+    # Provide a useful exit code.
+    if len(errors) > 0:
+        return -1
+    else:
+        return 0
+
+
+def find_demo_dirs(demos_top_dir_path: Path):
+    return [demos_top_dir_path] + [
+        d
+        for d in demos_top_dir_path.iterdir()
+        if d.is_dir() and d.name not in EXCEPTIONS
+    ]
+
+
+if __name__ == '__main__':
+    ret_code = main()
+    exit(ret_code)

ck_demos/circuit/demo_circuit_dump.py

@@ -0,0 +1,22 @@
+"""
+This demo shows how to dump a Circuit.
+"""
+from ck.circuit import Circuit
+
+
+def main() -> None:
+    cct = Circuit()
+    x0 = cct.new_var()  # this var will have index 0
+    x1 = cct.new_var()  # this var will have index 1
+    c123 = cct.const(123)
+    m = cct.mul(x0, x1)
+    _ = cct.add(c123, m)
+
+    cct.dump()
+
+    # with open('demo_cct_dump.txt', 'w') as out:
+    #     circuit.dump(out)
+
+
+if __name__ == '__main__':
+    main()

ck_demos/circuit/demo_derivatives.py

@@ -0,0 +1,43 @@
+"""
+This is a script for exploring partial derivatives.
+"""
+from ck.circuit_compiler.llvm_compiler import compile_circuit
+from ck.circuit import Circuit
+from ck.program import Program
+
+
+def main() -> None:
+    cct = Circuit()
+    x = cct.new_vars(2)  # indicators x[0] and x[1]
+    y = cct.new_vars(2)  # indicators y[0] and y[1]
+    f = cct.new_vars(2)  # factor between x and y
+    q = cct.add(
+        cct.mul(x[0], y[0], f[0]),
+        cct.mul(x[0], y[1], f[1]),
+        cct.mul(x[1], y[0], f[1]),
+        cct.mul(x[1], y[1], f[0]),
+    )
+
+    derivatives = cct.partial_derivatives(q, f)  # returns a list: [f0', f1']
+
+    # prog is a function from [x0, x1, y0, y1, f0, f1] to [f0', f1', q]
+    prog = Program(compile_circuit(*derivatives + [q]))
+
+    # Make a dataset.
+    dataset = [
+        # x    y     f
+        [1, 0, 1, 0, 0.4, 0.6],
+        [0, 1, 1, 0, 0.4, 0.6],
+        [1, 0, 0, 1, 0.4, 0.6],
+        [0, 1, 0, 1, 0.4, 0.6],
+        [1, 1, 1, 1, 0.4, 0.6],
+    ]
+
+    for instance in dataset:
+        result = prog(*instance)
+        print(instance, result[:-1], result[-1])
+    print()
+
+
+if __name__ == '__main__':
+    main()

ck_demos/circuit_compiler/compare_circuit_compilers.py

@@ -0,0 +1,32 @@
+from typing import Sequence
+
+from ck import example
+from ck.circuit_compiler import NamedCircuitCompiler
+from ck.pgm import PGM
+from ck.pgm_compiler.named_pgm_compilers import NamedPGMCompiler
+from ck_demos.utils.compare import compare
+
+PGMS: Sequence[PGM] = [
+    example.Rain(),
+    # example.Insurance(),
+    # example.Pathfinder(),
+    # example.Mildew(),
+]
+
+PGM_COMPILERS: Sequence[NamedPGMCompiler] = [NamedPGMCompiler.FE_BEST_JOINTREE]
+
+CCT_COMPILERS: Sequence[NamedCircuitCompiler] = list(NamedCircuitCompiler)
+
+
+def main() -> None:
+    compare(
+        pgms=PGMS,
+        pgm_compilers=PGM_COMPILERS,
+        cct_compilers=CCT_COMPILERS,
+    )
+    print()
+    print('Done.')
+
+
+if __name__ == '__main__':
+    main()

ck_demos/circuit_compiler/show_llvm_program.py

@@ -0,0 +1,26 @@
+from ck import example
+from ck.circuit import CircuitNode
+from ck.circuit_compiler import llvm_vm_compiler
+from ck.circuit_compiler.support.llvm_ir_function import LLVMRawProgram
+from ck.pgm import PGM
+from ck.pgm_circuit import PGMCircuit
+from ck.pgm_compiler import NamedPGMCompiler, PGMCompiler
+
+EXAMPLE_PGM: PGM = example.Rain()
+PGM_COMPILER: PGMCompiler = NamedPGMCompiler.FE_BEST_JOINTREE
+
+
+def main() -> None:
+    pgm_cct: PGMCircuit = PGM_COMPILER(EXAMPLE_PGM)
+    top: CircuitNode = pgm_cct.circuit_top
+
+    program: LLVMRawProgram = llvm_vm_compiler.compile_circuit(top)
+
+    print(program.llvm_program)
+
+    print()
+    print('Done.')
+
+
+if __name__ == '__main__':
+    main()

ck_demos/pgm/demo_pgm_dump.py

@@ -0,0 +1,18 @@
+from ck import example
+
+
+def main() -> None:
+    """
+    Demonstrate dumping a PGM
+    """
+    pgm = example.Alarm()
+
+    print('Dumping PGM')
+    pgm.dump()
+
+    print()
+    print('Done.')
+
+
+if __name__ == '__main__':
+    main()

ck_demos/pgm/demo_pgm_dump_stress.py

@@ -0,0 +1,18 @@
+"""
+Demonstrate dumping a PGM - stressing the method
+"""
+from ck import example
+
+
+def main() -> None:
+    pgm = example.Stress()
+
+    print('Dumping PGM')
+    pgm.dump(show_function_values=True)
+
+    print()
+    print('Done.')
+
+
+if __name__ == '__main__':
+    main()

ck_demos/pgm/demo_pgm_string_rendering.py

@@ -0,0 +1,15 @@
+from ck.pgm import PGM
+
+
+def main() -> None:
+    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]))
+    print(pgm.condition_str(a[0], b[1], a[2]))
+
+
+if __name__ == '__main__':
+    main()

ck_demos/pgm/show_examples.py

@@ -0,0 +1,25 @@
+from ck import example
+from ck.pgm import PGM
+
+INDENT: str = '    '
+PRECISION: int = 3
+MAX_STATE_DIGITS = 21
+
+
+def main() -> None:
+    """
+    Show all standard PGM examples
+    """
+    for example_name, pgm_class in example.ALL_EXAMPLES.items():
+        pgm: PGM = pgm_class()
+
+        print(example_name)
+        pgm.dump_synopsis(prefix=INDENT)
+        print()
+
+    print()
+    print('Done.')
+
+
+if __name__ == '__main__':
+    main()

ck_demos/pgm_compiler/compare_pgm_compilers.py

@@ -0,0 +1,50 @@
+from typing import Sequence
+
+from ck import example
+from ck.circuit_compiler import NamedCircuitCompiler
+from ck.pgm import PGM
+from ck.pgm_circuit.support.compile_circuit import DEFAULT_CIRCUIT_COMPILER
+from ck.pgm_compiler.named_pgm_compilers import NamedPGMCompiler
+from ck_demos.utils.compare import compare
+
+# @formatter:off
+
+PGMS: Sequence[PGM] = [
+    example.Rain(),
+    example.Cancer(),
+    example.Earthquake(),
+    example.Asia(),
+    example.Survey(),
+    example.Sachs(),
+    example.Child(),
+    example.Alarm(),
+
+    # example.Hailfinder(),
+    # example.Insurance(),
+    # example.Pathfinder(),
+    # example.Mildew(),
+]
+
+CCT_COMPILERS: Sequence[NamedCircuitCompiler] = [DEFAULT_CIRCUIT_COMPILER]
+
+PGM_COMPILERS: Sequence[NamedPGMCompiler] = [
+    named_compiler
+    for named_compiler in NamedPGMCompiler
+    if named_compiler.name.startswith('FE_') and 'WEIGHTED' not in named_compiler.name
+] + [NamedPGMCompiler.ACE]
+
+# @formatter:on
+
+
+def main() -> None:
+    compare(
+        pgms=PGMS,
+        pgm_compilers=PGM_COMPILERS,
+        cct_compilers=CCT_COMPILERS,
+    )
+    print()
+    print('Done.')
+
+
+if __name__ == '__main__':
+    main()

ck_demos/pgm_compiler/demo_compiler_dump.py

@@ -0,0 +1,50 @@
+from ck import example
+from ck.circuit import Circuit
+from ck.pgm import PGM
+from ck.pgm_circuit import PGMCircuit
+from ck.pgm_circuit.wmc_program import WMCProgram
+from ck.pgm_compiler.factor_elimination import join_tree_to_circuit
+from ck.pgm_compiler.support.clusters import min_degree, Clusters
+from ck.pgm_compiler.support.join_tree import JoinTree, clusters_to_join_tree
+
+
+def main() -> None:
+    pgm: PGM = example.Rain()
+
+    print(f'PGM {pgm.name!r}')
+    print()
+
+    clusters: Clusters = min_degree(pgm)
+
+    clusters.dump()
+
+    join_tree: JoinTree = clusters_to_join_tree(clusters)
+
+    print('Join Tree:')
+    join_tree.dump()
+    print()
+
+    pgm_circuit: PGMCircuit = join_tree_to_circuit(join_tree)
+    circuit: Circuit = pgm_circuit.circuit_top.circuit
+
+    print('Circuit:')
+    circuit.dump()
+    print()
+
+    wmc = WMCProgram(pgm_circuit)
+
+    print()
+    print('Showing Program Results:')
+    print(f'  {"State":80} {"WMC":8} {"PGM":8}')
+    for indicators in pgm.instances_as_indicators():
+        instance_as_str = pgm.indicator_str(*indicators)
+        wmc_value = wmc.wmc(*indicators)
+        pgm_value = pgm.value_product_indicators(*indicators)
+        print(f'  {instance_as_str:80} {wmc_value:8.6f} {pgm_value:8.6f}')
+
+    print()
+    print('Done.')
+
+
+if __name__ == '__main__':
+    main()