compiled-knowledge 4.0.0a25__cp312-cp312-macosx_11_0_arm64.whl → 4.1.0__cp312-cp312-macosx_11_0_arm64.whl

ck/probability/divergence.py

@@ -0,0 +1,226 @@
+"""
+This module implements several divergences which measure the difference
+between two distributions.
+"""
+import math
+from typing import Sequence
+
+import numpy as np
+
+from ck.pgm import RandomVariable, rv_instances_as_indicators, PGM
+from ck.probability.probability_space import ProbabilitySpace
+
+_NAN: float = np.nan  # Not-a-number (i.e., the result of an invalid calculation).
+
+
+def kl(p: ProbabilitySpace, q: ProbabilitySpace) -> float:
+    """
+    Compute the Kullback-Leibler divergence between p & q,
+    where p is the true distribution.
+
+    This implementation uses logarithms, base 2.
+
+    Args:
+        p: a probability space to compare to.
+        q: the other probability space.
+
+    Returns:
+        the Kullback–Leibler (KL) divergence of p & q, where p is
+        the true distribution.
+
+    Raises:
+        ValueError: if `p` and `q` do not have compatible random variables.specifically:
+            * `len(self.rvs) == len(other.rvs)`
+            * `len(other.rvs[i]) == len(self.rvs[i])` for all `i`
+            * `other.rvs[i].idx == self.rvs[i].idx` for all `i`.
+
+    Warning:
+        this method will enumerate the whole probability space.
+    """
+    if not _compatible_rvs(p.rvs, q.rvs):
+        raise ValueError('incompatible random variables')
+
+    total = 0.0
+    for x in rv_instances_as_indicators(*p.rvs):
+        p_x = p.probability(*x)
+        q_x = q.probability(*x)
+        if p_x <= 0 or q_x <= 0:
+            return _NAN
+        total += p_x * math.log2(p_x / q_x)
+    return total
+
+
+def pseudo_kl(p: ProbabilitySpace, q: ProbabilitySpace) -> float:
+    """
+    A kind of KL divergence, factored by the structure of `p`.
+    This is an experimental measure.
+
+    This implementation uses logarithms, base 2.
+
+    Args:
+        p: a probability space to compare to.
+        q: the other probability space.
+
+    Returns:
+        the factored histogram intersection between the two probability spaces.
+
+    Raises:
+        ValueError: if `p` and `q` do not have compatible random variables.specifically:
+            * `len(self.rvs) == len(other.rvs)`
+            * `len(other.rvs[i]) == len(self.rvs[i])` for all `i`
+            * `other.rvs[i].idx == self.rvs[i].idx` for all `i`.
+        ValueError: if not all random variable of `p` are from a single PGM, which must
+            have a Bayesian network structure.
+    """
+    p_rvs: Sequence[RandomVariable] = p.rvs
+    q_rvs: Sequence[RandomVariable] = q.rvs
+
+    if not _compatible_rvs(p_rvs, q_rvs):
+        raise ValueError('incompatible random variables')
+
+    if len(p_rvs) == 0:
+        return _NAN
+
+    pgm: PGM = p_rvs[0].pgm
+    if any(rv.pgm is not pgm for rv in p_rvs):
+        raise ValueError('p random variables are not from a single PGM.')
+    if not pgm.is_structure_bayesian:
+        raise ValueError('p does not have Bayesian network structure.')
+
+    # Across the two spaces, corresponding random variables are equivalent;
+    # i.e., same number of states and same `idx` values. Therefore,
+    # indicators from either one space can be used in both spaces.
+
+    total: float = 0
+    for factor in pgm.factors:
+        for x in rv_instances_as_indicators(*factor.rvs):  # every possible state of factor rvs
+            p_x = p.probability(*x)
+            q_x = q.probability(*x)
+            if p_x <= 0 or q_x <= 0:
+                return _NAN
+            total += p_x * math.log2(p_x / q_x)
+    return total
+
+
+def hi(p: ProbabilitySpace, q: ProbabilitySpace) -> float:
+    """
+    Compute the histogram intersection between this probability spaces and the given other.
+
+    The histogram intersection between two probability spaces P and Q,
+    with state spaces X, is defined as:
+        HI(P, Q) = sum(min(P(x), Q(x)) for x in X)
+
+    Args:
+        p: a probability space to compare to.
+        q: the other probability space.
+
+    Returns:
+        the histogram intersection between the two probability spaces.
+
+    Raises:
+        ValueError: if `p` and `q` do not have compatible random variables.specifically:
+            * `len(self.rvs) == len(other.rvs)`
+            * `len(other.rvs[i]) == len(self.rvs[i])` for all `i`
+            * `other.rvs[i].idx == self.rvs[i].idx` for all `i`.
+
+    Warning:
+        this method will enumerate the whole probability space.
+
+    """
+    p_rvs: Sequence[RandomVariable] = p.rvs
+    q_rvs: Sequence[RandomVariable] = q.rvs
+
+    if not _compatible_rvs(p_rvs, q_rvs):
+        raise ValueError('incompatible random variables')
+
+    # Across the two spaces, corresponding random variables are equivalent;
+    # i.e., same number of states and same `idx` values. Therefore,
+    # indicators from either one space can be used in both spaces.
+
+    return sum(
+        min(p.probability(*x), q.probability(*x))
+        for x in rv_instances_as_indicators(*p_rvs)
+    )
+
+
+def fhi(p: ProbabilitySpace, q: ProbabilitySpace) -> float:
+    """
+    Compute the factored histogram intersection between this probability spaces and the given other.
+
+    The factored histogram intersection between two probability spaces P and Q,
+    with state spaces X and factorisation F, is defined as:
+        FHI(P, Q) = 1/n sum(P(Y=y) CHI(P, Q, X | Y=y)
+        where:
+            CHI(P, Q, X | Y=y) = HI(P(X | Y=y), Q(X | Y=y))
+            HI(P, Q) = sum(min(P(X=x), Q(X=x)) for x in f)
+
+    The value of _n_ is the sum ofP(Y=y) over all CPT rows. However,
+    this always equals the number of CPTs, i.e., the number of random
+    variables.
+
+    The factorisation F is taken from the `p`.
+
+    For more information about factored histogram intersection, see the publication:
+    Suresh, S., Drake, B. (2025). Sampling of Large Probabilistic Graphical Models
+    Using Arithmetic Circuits. AI 2024: Advances in Artificial Intelligence. AI 2024.
+    Lecture Notes in Computer Science, vol 15443. https://doi.org/10.1007/978-981-96-0351-0_13.
+
+    Args:
+        p: a probability space to compare to.
+        q: the other probability space.
+
+    Returns:
+        the factored histogram intersection between the two probability spaces.
+
+    Raises:
+        ValueError: if `p` and `q` do not have compatible random variables.specifically:
+            * `len(self.rvs) == len(other.rvs)`
+            * `len(other.rvs[i]) == len(self.rvs[i])` for all `i`
+            * `other.rvs[i].idx == self.rvs[i].idx` for all `i`.
+        ValueError: if not all random variable of `p` are from a single PGM, which must
+            have a Bayesian network structure.
+    """
+    p_rvs: Sequence[RandomVariable] = p.rvs
+    q_rvs: Sequence[RandomVariable] = q.rvs
+
+    if not _compatible_rvs(p_rvs, q_rvs):
+        raise ValueError('incompatible random variables')
+
+    if len(p_rvs) == 0:
+        return 0
+
+    pgm: PGM = p_rvs[0].pgm
+    if any(rv.pgm is not pgm for rv in p_rvs):
+        raise ValueError('p random variables are not from a single PGM.')
+    if not pgm.is_structure_bayesian:
+        raise ValueError('p does not have Bayesian network structure.')
+
+    # Across the two spaces, corresponding random variables are equivalent;
+    # i.e., same number of states and same `idx` values. Therefore,
+    # indicators from either one space can be used in both spaces.
+
+    # Loop over all CPTs, accumulating the total
+    total: float = 0
+    for factor in pgm.factors:
+        child: RandomVariable = factor.rvs[0]
+        parents: Sequence[RandomVariable] = factor.rvs[1:]
+        # Loop over all rows of the CPT
+        for parent_indicators in rv_instances_as_indicators(*parents):
+            p_marginal = p.marginal_distribution(child, condition=parent_indicators)
+            q_marginal = q.marginal_distribution(child, condition=parent_indicators)
+            row_hi = np.minimum(p_marginal, q_marginal).sum().item()
+            pr_row = p.probability(*parent_indicators)
+            total += pr_row * row_hi
+
+    return total / len(p_rvs)
+
+
+def _compatible_rvs(rvs1: Sequence[RandomVariable], rvs2: Sequence[RandomVariable]) -> bool:
+    """
+    The rvs are compatible if they have the same number of random variables
+    and the corresponding indicators are equal.
+    """
+    return (
+            len(rvs1) == len(rvs2)
+            and all(len(rv1) == len(rv2) and rv1.idx == rv2.idx for rv1, rv2 in zip(rvs1, rvs2))
+    )

ck/probability/empirical_probability_space.py

@@ -11,6 +11,7 @@ class EmpiricalProbabilitySpace(ProbabilitySpace):
         Note that this is not necessarily an efficient approach to calculating probabilities and statistics.
 
         This probability space treats each of the samples as equally weighted.
+        For a probability space over unequally weighted samples, consider using `CrossTableProbabilitySpace`.
 
         Assumes:
             len(sample) == len(rvs), for each sample in samples.

ck/probability/probability_space.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import math
 from abc import ABC, abstractmethod
 from itertools import chain
@@ -203,16 +205,19 @@ class ProbabilitySpace(ABC):
                 loop_rvs.append([rv[i] for i in sorted(states)])
                 reduced_space = True
 
+        best_probability = float('-inf')
+        best_states = None
+
         # If the random variables we are looping over does not have any conditions
         # then it is expected to be faster by using computed marginal probabilities.
         if not reduced_space:
             prs = self.marginal_distribution(*rvs, condition=condition)
-            best_probability = float('-inf')
-            best_states = None
             for probability, inst in zip(prs, rv_instances(*rvs)):
                 if probability > best_probability:
                     best_probability = probability
                     best_states = inst
+            if best_states is None:
+                return _NAN, ()
             return best_probability, best_states
 
         else:
@@ -220,8 +225,6 @@ class ProbabilitySpace(ABC):
             new_conditions = tuple(ind for ind in condition if ind.rv_idx not in rv_indexes)
 
             # Loop over the state space of the 'loop' rvs
-            best_probability = float('-inf')
-            best_states = None
             indicators: Tuple[Indicator, ...]
             for indicators in _combos(loop_rvs):
                 probability = self.wmc(*(indicators + new_conditions))
@@ -229,6 +232,8 @@ class ProbabilitySpace(ABC):
                     best_probability = probability
                     best_states = tuple(ind.state_idx for ind in indicators)
             condition_probability = self.wmc(*condition)
+            if best_states is None:
+                return _NAN, ()
             return best_probability / condition_probability, best_states
 
     def correlation(self, indicator1: Indicator, indicator2: Indicator, condition: Condition = ()) -> float:
@@ -245,6 +250,20 @@ class ProbabilitySpace(ABC):
         """
         condition = check_condition(condition)
 
+        if indicator1.rv_idx == indicator2.rv_idx:
+            # Special case - same random variable
+            condition_groups: MapSet[int, Indicator] = _group_indicators(condition)
+            rv_idx: int = indicator1.rv_idx
+            if indicator1 not in condition_groups.get(rv_idx, (indicator1,)):
+                return _NAN
+            if indicator1 == indicator2:
+                return 1
+            else:
+                if indicator2 not in condition_groups.get(rv_idx, (indicator2,)):
+                    return _NAN
+                else:
+                    return 0
+
         p1 = self.probability(indicator1, condition=condition)
         p2 = self.probability(indicator2, condition=condition)
         p12 = self._joint_probability(indicator1, indicator2, condition=condition)
@@ -267,12 +286,7 @@ class ProbabilitySpace(ABC):
             entropy of the given random variable.
         """
         condition = check_condition(condition)
-        e = 0.0
-        for ind in rv:
-            p = self.probability(ind, condition=condition)
-            if p > 0.0:
-                e -= p * math.log2(p)
-        return e
+        return -sum(plogp(self.probability(ind, condition=condition)) for ind in rv)
 
     def conditional_entropy(self, rv1: RandomVariable, rv2: RandomVariable, condition: Condition = ()) -> float:
         """
@@ -309,13 +323,11 @@ class ProbabilitySpace(ABC):
             joint entropy of the given random variables.
         """
         condition = check_condition(condition)
-        e = 0.0
-        for ind1 in rv1:
-            for ind2 in rv2:
-                p = self._joint_probability(ind1, ind2, condition=condition)
-                if p > 0.0:
-                    e -= p * math.log2(p)
-        return e
+        return -sum(
+            plogp(self._joint_probability(ind1, ind2, condition=condition))
+            for ind1 in rv1
+            for ind2 in rv2
+        )
 
     def mutual_information(self, rv1: RandomVariable, rv2: RandomVariable, condition: Condition = ()) -> float:
         """
@@ -419,8 +431,12 @@ class ProbabilitySpace(ABC):
         denominator = self.joint_entropy(rv1, rv2, condition=condition)
         return self._normalised_mutual_information(rv1, rv2, denominator, condition=condition)
 
-    def covariant_normalised_mutual_information(self, rv1: RandomVariable, rv2: RandomVariable,
-                                                condition: Condition = ()) -> float:
+    def covariant_normalised_mutual_information(
+            self,
+            rv1: RandomVariable,
+            rv2: RandomVariable,
+            condition: Condition = (),
+    ) -> float:
         """
         Calculate the covariant normalised mutual information
         = I(rv1; rv2) / sqrt(H(rv1) * H(rv2)).
@@ -549,6 +565,14 @@ class ProbabilitySpace(ABC):
         return wmc
 
 
+def plogp(p: float) -> float:
+    """
+    Returns:
+        p * log2(p)
+    """
+    return p * math.log2(p) if p > 0 else 0
+
+
 def check_condition(condition: Condition) -> Tuple[Indicator, ...]:
     """
     Make the best effort to interpret the given condition.

ck_demos/dataset/demo_dataset_builder.py

@@ -0,0 +1,37 @@
+from ck.dataset import HardDataset, SoftDataset
+from ck.dataset.dataset_builder import DatasetBuilder, soft_dataset_from_builder, hard_dataset_from_builder
+from ck.pgm import PGM
+
+
+def main() -> None:
+    pgm = PGM()
+    x = pgm.new_rv('x', (True, False))
+    y = pgm.new_rv('y', ('yes', 'no', 'maybe'))
+
+    builder = DatasetBuilder([x, y])
+    builder.append()
+    builder.append(1, 2).weight = 3
+    builder.append(None, [0.7, 0.1, 0.2])
+    builder.append().set_states(True, 'maybe')
+
+    print('DatasetBuilder dump')
+    builder.dump()
+    print()
+
+    print('DatasetBuilder dump, showing states and custom missing values')
+    builder.dump(as_states=True, missing='?')
+    print()
+
+    print('HardDataset dump')
+    dataset: HardDataset = hard_dataset_from_builder(builder, missing=99)
+    dataset.dump()
+    print()
+
+    print('SoftDataset dump')
+    dataset: SoftDataset = soft_dataset_from_builder(builder)
+    dataset.dump()
+    print()
+
+
+if __name__ == '__main__':
+    main()

ck_demos/dataset/demo_dataset_from_sampler.py

@@ -0,0 +1,18 @@
+from ck import example
+from ck.dataset.sampled_dataset import dataset_from_sampler
+from ck.pgm import PGM
+from ck.pgm_circuit.wmc_program import WMCProgram
+from ck.pgm_compiler import DEFAULT_PGM_COMPILER
+from ck.sampling.sampler import Sampler
+
+
+def main() -> None:
+    pgm: PGM = example.Student()
+    sampler: Sampler = WMCProgram(DEFAULT_PGM_COMPILER(pgm)).sample_direct()
+    dataset = dataset_from_sampler(sampler, 10)
+
+    dataset.dump()
+
+
+if __name__ == '__main__':
+    main()

ck_demos/learning/demo_bayesian_network_from_cross_tables.py

@@ -0,0 +1,70 @@
+from typing import List, Set
+
+from ck import example
+from ck.dataset import HardDataset
+from ck.dataset.cross_table import CrossTable, cross_table_from_hard_dataset
+from ck.dataset.sampled_dataset import dataset_from_sampler
+from ck.learning.model_from_cross_tables import model_from_cross_tables
+from ck.pgm import PGM, RandomVariable
+from ck.pgm_circuit.wmc_program import WMCProgram
+from ck.pgm_compiler import DEFAULT_PGM_COMPILER
+from ck.probability import divergence
+
+EXCLUDE_UNNECESSARY_CROSS_TABLES = True
+
+
+def main() -> None:
+    # Create a dataset based on model which is an example PGM
+    number_of_samples: int = 10000  # How many instances to make for the model dataset
+    model: PGM = example.Student()
+    model_dataset: HardDataset = dataset_from_sampler(
+        WMCProgram(DEFAULT_PGM_COMPILER(model)).sample_direct(),
+        number_of_samples,
+    )
+
+    # Clone the model, without factors, and transport the dataset to the new PGM
+    pgm = PGM()
+    dataset = HardDataset(weights=model_dataset.weights)
+    for model_rv in model.rvs:
+        rv = pgm.new_rv(model_rv.name, model_rv.states)
+        dataset.add_rv_from_state_idxs(rv, model_dataset.state_idxs(model_rv))
+
+    # What model rvs have a child
+    model_rvs_with_children: Set[RandomVariable] = set()
+    for model_factor in model.factors:
+        for parent_rv in model_factor.rvs[1:]:
+            model_rvs_with_children.add(parent_rv)
+
+    # Construct cross-tables from the dataset
+    cross_tables: List[CrossTable] = []
+    for model_factor in model.factors:
+        if (
+                EXCLUDE_UNNECESSARY_CROSS_TABLES
+                and len(model_factor.rvs) == 1
+                and model_factor.rvs[0] in model_rvs_with_children
+        ):
+            # The factor relates to a single random variable (has
+            # no parents) but it does have children.
+            # No need to include a cross-table as it is inferable from
+            # cross-tables of its children.
+            continue
+
+        rvs = tuple(pgm.rvs[model_rv.idx] for model_rv in model_factor.rvs)
+        cross_tables.append(cross_table_from_hard_dataset(dataset, rvs))
+        print('cross-table:', *rvs)
+
+    # Train the PGM
+    model_from_cross_tables(pgm, cross_tables)
+
+    # Show results
+    print()
+    pgm.dump(show_function_values=True)
+    print()
+    model_space = WMCProgram(DEFAULT_PGM_COMPILER(model))
+    pgm_space = WMCProgram(DEFAULT_PGM_COMPILER(pgm))
+    print('HI', divergence.hi(model_space, pgm_space))
+    print('KL', divergence.kl(model_space, pgm_space))
+
+
+if __name__ == '__main__':
+    main()

ck_demos/learning/demo_simple_learning.py

@@ -0,0 +1,55 @@
+from ck.dataset.dataset_from_csv import hard_dataset_from_csv
+from ck.learning.train_generative_bn import train_generative_bn
+from ck.pgm import PGM
+
+
+def main() -> None:
+    pgm = PGM('Student')
+
+    difficult = pgm.new_rv('difficult', ['y', 'n'])
+    intelligent = pgm.new_rv('intelligent', ['y', 'n'])
+    grade = pgm.new_rv('grade', ['low', 'medium', 'high'])
+    award = pgm.new_rv('award', ['y', 'n'])
+    letter = pgm.new_rv('letter', ['y', 'n'])
+
+    pgm.new_factor(difficult)
+    pgm.new_factor(intelligent)
+    pgm.new_factor(grade, intelligent, difficult)
+    pgm.new_factor(award, intelligent)
+    pgm.new_factor(letter, grade)
+
+    rvs = (difficult, intelligent, grade, award, letter)
+    csv = """
+    0,1,2,0,1
+    1,1,2,0,1
+    1,1,2,0,1
+    0,0,2,0,0
+    0,1,1,1,0
+    1,1,1,1,1
+    1,1,0,0,0
+    1,1,0,0,1
+    1,0,0,0,0
+    """
+
+    dataset = hard_dataset_from_csv(rvs, csv.splitlines())
+
+    # Learn parameters values for `pgm` using the training data `dataset`.
+    # This updates the PGMs potential functions.
+    train_generative_bn(pgm, dataset)
+
+    show_pgm_factors(pgm)
+
+    print('Done.')
+
+
+def show_pgm_factors(pgm: PGM) -> None:
+    for factor in pgm.factors:
+        potential_function = factor.function
+        print(f'Factor: {factor} {type(potential_function)}')
+        for instance, _, param_value in potential_function.keys_with_param:
+            print(f'Factor{instance} = {param_value}')
+        print()
+
+
+if __name__ == '__main__':
+    main()

ck_demos/sampling/demo_wmc_direct_sampler.py

@@ -2,7 +2,7 @@ import random
 
 from ck import example
 from ck.pgm import PGM
-from ck.pgm_compiler import factor_elimination
+from ck.pgm_compiler import DEFAULT_PGM_COMPILER
 from ck.pgm_circuit import PGMCircuit
 from ck.pgm_circuit.wmc_program import WMCProgram
 from ck.probability.empirical_probability_space import EmpiricalProbabilitySpace
@@ -18,7 +18,7 @@ def main():
 
     pgm: PGM = example.Rain()
 
-    pgm_cct: PGMCircuit = factor_elimination.compile_pgm(pgm)
+    pgm_cct: PGMCircuit = DEFAULT_PGM_COMPILER(pgm)
     wmc = WMCProgram(pgm_cct)
     sampler = wmc.sample_direct()
 

{compiled_knowledge-4.0.0a25.dist-info → compiled_knowledge-4.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compiled-knowledge
-Version: 4.0.0a25
+Version: 4.1.0
 Summary: A Python package for compiling and querying discrete probabilistic graphical models.
 Author-email: Barry Drake <barry@compiledknowledge.org>
 License-Expression: MIT
@@ -13,6 +13,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: llvmlite
 Requires-Dist: numpy
+Requires-Dist: scipy
 Dynamic: license-file
 
 Compiled Knowledge