compiled-knowledge 4.0.0a24__cp312-cp312-macosx_11_0_arm64.whl → 4.1.0a1__cp312-cp312-macosx_11_0_arm64.whl

ck/dataset/dataset_compute.py

@@ -0,0 +1,140 @@
+"""
+A collection of functions to compute values over datasets using programs.
+"""
+import ctypes as ct
+from typing import Optional, List, Dict
+
+import numpy as np
+
+from ck.dataset import SoftDataset
+from ck.pgm import Indicator, RandomVariable
+from ck.pgm_circuit.slot_map import SlotMap
+from ck.program import RawProgram
+from ck.utils.np_extras import NDArray, NDArrayNumeric
+
+
+def accumulate_compute(
+        program: RawProgram,
+        slot_arrays: NDArray,
+        *,
+        weights: Optional[NDArray] = None,
+        accumulator: Optional[NDArray] = None,
+) -> NDArray:
+    """
+    Apply the given program to every instance in the dataset, summing all results over the instances.
+
+    Args:
+        program: the mathematical transformation to apply to the data.
+        slot_arrays: a 2D numpy array of shape (number_of_instances, number_of_slots). Appropriate
+            slot arrays can be constructed from a soft dataset using `get_slot_arrays`.
+        weights: and optional 1D array of instance weights, of shape (number_of_instances, ), and
+            co-indexed with slot_arrays.
+        accumulator: an optional array to perform the result accumulation, summing with the initial
+            values of the provided accumulator.
+
+    Returns:
+        total_weight, accumulator
+
+    Raises:
+        ValueError: if slot_arrays.shape is not `(..., program.number_of_vars)`.
+        ValueError: if an accumulator is provided, but is not shape `(program.number_of_results, )`.
+        ValueError: if weights provided, but is not shape `(slot_arrays.shape[0],)`.
+    """
+    number_of_results: int = program.number_of_results
+    number_of_vars: int = program.number_of_vars
+
+    if len(slot_arrays.shape) != 2 or slot_arrays.shape[1] != program.number_of_vars:
+        raise ValueError(f'slot arrays expected shape (..., {number_of_vars}) but got {slot_arrays.shape}')
+
+    if accumulator is None:
+        accumulator = np.zeros(number_of_results, dtype=program.dtype)
+    elif accumulator.shape != (number_of_results,):
+        raise ValueError(f'accumulator shape {accumulator.shape} does not match number of results: {number_of_results}')
+
+    if slot_arrays.dtype != program.dtype:
+        raise ValueError(f'slot arrays dtype {slot_arrays.dtype} does not match program.dtype: {program.dtype}')
+    if accumulator.dtype != program.dtype:
+        raise ValueError(f'accumulator dtype {slot_arrays.dtype} does not match program.dtype: {program.dtype}')
+
+    ptr_type = ct.POINTER(np.ctypeslib.as_ctypes_type(program.dtype))
+
+    # Create buffers for program function tmps and outputs
+    # We do not need to create a buffer for program function inputs as that
+    # will be provided by `slot_arrays`.
+    array_outs: NDArrayNumeric = np.zeros(program.number_of_results, dtype=program.dtype)
+    array_tmps: NDArrayNumeric = np.zeros(program.number_of_tmps, dtype=program.dtype)
+    c_array_tmps = array_tmps.ctypes.data_as(ptr_type)
+    c_array_outs = array_outs.ctypes.data_as(ptr_type)
+
+    if weights is None:
+        # This is the unweighed version
+        for instance in slot_arrays:
+            c_array_vars = instance.ctypes.data_as(ptr_type)
+            program.function(c_array_vars, c_array_tmps, c_array_outs)
+            accumulator += array_outs
+
+    else:
+        # This is the weighed version
+        expected_shape = (slot_arrays.shape[0],)
+        if weights.shape != expected_shape:
+            raise ValueError(f'weight shape {weights.shape} is not as expected : {expected_shape}')
+
+        for weight, instance in zip(weights, slot_arrays):
+            c_array_vars = instance.ctypes.data_as(ptr_type)
+            program.function(c_array_vars, c_array_tmps, c_array_outs)
+            accumulator += array_outs * weight
+
+    return accumulator
+
+
+def get_slot_arrays(
+        dataset: SoftDataset,
+        number_of_slots: int,
+        slot_map: SlotMap,
+) -> NDArray:
+    """
+    For each slot from 0 to number_of_slots - 1, get the 1D vector
+    from the dataset that can be used to set each slot.
+
+    This function can be used to prepare slot arrays for `accumulate_compute`.
+
+    Returns:
+        a 2D numpy array of shape (len(dataset), number_of_slots),
+
+    Raises:
+        ValueError: if multiple indicators for a slot in the slot map
+        ValueError: if there are slots with no indicator in slot map
+    """
+
+    # Special case, no slots
+    # We treat this specially to ensure the right shape of the result
+    if number_of_slots == 0:
+        return np.empty(shape=(len(dataset), 0))
+
+    # Use the slot map to work out which indicator corresponds to each slot.
+    indicators: List[Optional[Indicator]] = [None] * number_of_slots
+    for indicator, slot in slot_map.items():
+        if 0 <= slot < number_of_slots and indicator is not None:
+            if indicators[slot] is not None and indicators[slot] != indicator:
+                raise ValueError(f'multiple indicators for slot: {slot}')
+            indicators[slot] = indicator
+    missing_slots = [i for i, indicator in enumerate(indicators) if indicator is None]
+    if len(missing_slots) > 0:
+        missing_slots_str = ', '.join(str(slot) for slot in missing_slots)
+        raise ValueError(f'slots with no indicator in slot map: {missing_slots_str}')
+
+    # Map rv index to state_weights of the dataset
+    rv: RandomVariable
+    state_weights: Dict[int, NDArray] = {
+        rv.idx: dataset.state_weights(rv)
+        for rv in dataset.rvs
+    }
+
+    # Get the columns of the resulting matrix
+    columns = [
+        state_weights[indicator.rv_idx][:, indicator.state_idx]
+        for indicator in indicators
+    ]
+
+    # Concatenate the columns into a matrix
+    return np.column_stack(columns)

ck/dataset/dataset_from_crosstable.py

@@ -0,0 +1,45 @@
+from typing import Sequence
+
+import numpy as np
+
+from ck.dataset import HardDataset
+from ck.dataset.cross_table import CrossTable
+from ck.pgm import RandomVariable
+from ck.utils.np_extras import dtype_for_number_of_states
+
+
+def dataset_from_cross_table(cross_table: CrossTable) -> HardDataset:
+    """
+    Construct a HardDataset from the given cross-table.
+
+    Args:
+        cross_table: A cross-table represented as a dictionary.
+
+    Returns:
+        A dataset where instances and instance weights are those of the
+        given cross-table.
+
+    Ensures:
+        `result.total_weight() == dataset.total_weight()`.
+        Zero weighted instances are not counted.
+    """
+    rvs: Sequence[RandomVariable] = cross_table.rvs
+
+    # Unzip the cross-table dictionary
+    rvs_series = [[] for _ in range(len(rvs))]
+    weights = []
+    for instance, weight in cross_table.items():
+        for series, state in zip(rvs_series, instance):
+            series.append(state)
+        weights.append(weight)
+
+    # Put the hard dataset together
+    return HardDataset(
+        data=(
+            (rv, np.array(series, dtype=dtype_for_number_of_states(len(rv))))
+            for rv, series in zip(rvs, rvs_series)
+        ),
+        weights=np.array(weights, dtype=np.float64),
+    )
+
+

ck/dataset/dataset_from_csv.py

@@ -0,0 +1,147 @@
+from typing import Iterable, List, Sequence, Optional
+
+from ck.dataset import HardDataset
+from ck.pgm import RandomVariable
+
+
+def hard_dataset_from_csv(
+        rvs: Iterable[RandomVariable],
+        lines: Iterable[str],
+        *,
+        weights: Optional[int | str] = None,
+        sep: str = ',',
+        comment: str = '#',
+) -> HardDataset:
+    """
+    Interpret the given sequence of lines as CSV for a HardDataset.
+
+    Each line is a list of state indexes (ints) separated by `sep`.
+
+    Every line should have the same number of values.
+
+    If the first line contains a non-integer value, then the first
+    line will be interpreted as a header line.
+
+    If there is no header line, then the values will be interpreted in the
+    same order as `rvs` and the number of values on each line should be
+    the same as the number of random variables in `rvs`.
+
+    If there is a header line, then it will be interpreted as the order
+    of random variables. There must be a column name in the header to match
+    each name of the given random variables. Additional columns will be ignored.
+
+    As text file (and StringIO) objects are iterable over lines, here is how to read a csv file:
+    ```
+        with open(csv_filename, 'r') as file:
+            hard_dataset_from_csv(rvs, file)
+    ```
+    Here is an example to read from a csv string:
+    ```
+        hard_dataset_from_csv(rvs, csv_string.splitlines())
+    ```
+
+    Args:
+        rvs: the random variables for the returned dataset.
+        lines: the sequence of lines to interpret, each line is an instance in the dataset.
+        weights: the column in the csv file holding instance weights. Can be either the
+            column number (counting from zero) or a column name (requires a header line).
+        sep: the string to use to separate values in a line, default is a comma.
+        comment: text starting with this will be treated as a comment. Set to '' to disallow comments.
+
+    Returns:
+        a HardDataset.
+
+    Raises:
+        ValueError: if the lines do not conform to a CSV format.
+    """
+    rvs: Sequence[RandomVariable] = tuple(rvs)
+
+    # Define `clean_line` being sensitive to comments.
+    if len(comment) > 0:
+        def clean_line(l: str) -> str:
+            i = l.find(comment)
+            if i >= 0:
+                l = l[:i]
+            return l.strip()
+    else:
+        def clean_line(l: str) -> str:
+            return l.strip()
+
+    # Get the first line which may be a header line or data line
+    it = iter(lines)
+    try:
+        while True:
+            line = clean_line(next(it))
+            if len(line) > 0:
+                break
+    except StopIteration:
+        # Empty dataset with the given random variables
+        return HardDataset((rv, []) for rv in rvs)
+
+    values: List[str] = [value.strip() for value in line.split(sep)]
+    number_of_columns: int = len(values)
+    series: List[List[int]]  # series[dataset-column] = list of values
+    weight_series: Optional[List[float]] = None
+    column_map: List[int]  # column_map[dataset-column] = input-column
+    if all(_is_number(value) for value in values):
+        # First line is not a header line
+        if weights is None:
+            if number_of_columns != len(rvs):
+                raise ValueError('number of columns does not match number of random variables')
+            column_map = list(range(len(rvs)))
+        else:
+            if number_of_columns != len(rvs) + 1:
+                raise ValueError('number of columns does not match number of random variables and weight column')
+            if not isinstance(weights, int):
+                raise ValueError('no header detected - `weights` must be a column number')
+            if not (-number_of_columns <= weights < number_of_columns):
+                raise ValueError('`weights` column number out of range')
+            column_map = list(range(len(rvs) + 1))
+            column_map.pop(weights)
+
+        # Initialise series with the first line of data
+        series = [[int(values[i])] for i in column_map]
+        if weights is not None:
+            weight_series = [float(values[weights])]
+
+    else:
+        # First line is a header line
+        # Lookup each random variable to find its column
+        column_map = [
+            values.index(rv.name)  # will raise ValueError if not found
+            for rv in rvs
+        ]
+        if isinstance(weights, str):
+            # Convert weights column name to column number
+            weights: int = values.index(weights)  # will raise ValueError if not found
+        elif isinstance(weights, int) and not (number_of_columns <= weights < number_of_columns):
+            raise ValueError('`weights` column number out of range')
+
+        # Initialise each series as empty
+        series = [[] for _ in rvs]
+        if weights is not None:
+            weight_series = []
+
+    # Read remaining data lines
+    for line in it:
+        line = clean_line(line)
+        if len(line) == 0:
+            continue
+        if len(values) != number_of_columns:
+            raise ValueError('number of values does not match number of columns')
+        values = line.split(sep)
+        for series_i, i in zip(series, column_map):
+            series_i.append(int(values[i]))
+        if weights is not None:
+            weight_series.append(float(values[weights]))
+
+    # Construct the dataset
+    return HardDataset(zip(rvs, series), weights=weight_series)
+
+
+def _is_number(s: str) -> bool:
+    try:
+        float(s)
+        return True
+    except ValueError:
+        return False

ck/dataset/sampled_dataset.py

@@ -0,0 +1,96 @@
+import random
+from dataclasses import dataclass
+from typing import Sequence, List, Iterator, Tuple, Dict
+
+import numpy as np
+
+from ck.dataset import HardDataset
+from ck.dataset.cross_table import CrossTable
+from ck.pgm import RandomVariable, Instance
+from ck.sampling.sampler import Sampler
+from ck.utils.np_extras import dtype_for_number_of_states, NDArray
+from ck.utils.random_extras import Random
+
+
+def dataset_from_sampler(sampler: Sampler, length: int) -> HardDataset:
+    """
+    Create a hard dataset using samples from a sampler.
+
+    Args:
+        sampler: A sampler which defined the random variables and provides samples.
+        length: The length of the dataset to create.
+
+    Returns:
+        A HardDataset of the given length.
+    """
+    rvs: Sequence[RandomVariable] = sampler.rvs
+    columns: List[NDArray] = [
+        np.zeros(length, dtype=dtype_for_number_of_states(len(rv)))
+        for rv in rvs
+    ]
+    for i, instance in enumerate(sampler.take(length)):
+        for column, state in zip(columns, instance):
+            column[i] = state
+    return HardDataset(zip(rvs, columns))
+
+
+class CrossTableSampler(Sampler):
+    def __init__(self, crosstab: CrossTable, rand: Random = random):
+        """
+        Adapt a cross table to a sampler.
+
+        Instances will be drawn from the sampler according to their
+        weight in the given cross-table. If the given cross-table is
+        modified after constructing the sampler, the sampler will not
+        be affected.
+        """
+        if len(crosstab) == 0:
+            raise ValueError('no instances to sample')
+
+        super().__init__(rvs=crosstab.rvs, condition=())
+
+        # Group instances by weight.
+        # We do this in anticipation that it makes sampling more efficient.
+        weight_groups: Dict[float, _WeightGroup] = {}
+        for instance, weight in crosstab.items():
+            weight_group = weight_groups.get(weight)
+            if weight_group is None:
+                weight_groups[weight] = _WeightGroup(weight, weight, [instance])
+            else:
+                weight_group.append(instance)
+
+        self._weight_groups: List[_WeightGroup] = list(weight_groups.values())
+        self._total_weight = sum(group.total for group in weight_groups.values())
+        self._rand = rand
+
+    def __iter__(self) -> Iterator[Instance]:
+        while True:
+            # This code performs inverse transform sampling
+            r: float = self._rand.random() * self._total_weight
+
+            # This does a serial search to find the weight group.
+            # This is efficient for small numbers of groups, but this may be
+            # improved for large numbers of groups.
+            it = iter(self._weight_groups)
+            group = next(it)
+            while r >= group.total:
+                r -= group.total
+                group = next(it)
+
+            # Pick an instance in the group
+            i = int(r / group.weight)
+            yield group.instances[i]
+
+
+@dataclass
+class _WeightGroup:
+    """
+    Support for CrossTableSampler.
+    """
+    weight: float
+    total: float
+    instances: List[Tuple[int, ...]]
+
+    def append(self, instance: Tuple[int, ...]) -> None:
+        self.total += self.weight
+        self.instances.append(instance)

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.
     """
 

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.
     """
 

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.
     """
 

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)

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: