compiled-knowledge 4.0.0a20__cp312-cp312-win32.whl

ck/utils/local_config.py

@@ -0,0 +1,270 @@
+"""
+This module provides access to local configuration variables.
+
+Local configuration variables are {variable} = {value} pairs that
+are defined externally to CK for the purposes of adapting
+to the local environment that CK is installed in. Local
+configuration variables are not expected to modify the
+behaviour of algorithms implemented in CK.
+
+The primary method to access local configuration is `get`. Various
+other getter methods wrap `get`.
+
+The `get` method will search for a value for a requested variable
+using the following steps.
+1) Check the `programmatic config` which is a dictionary that
+   can be directly updated.
+2) Check the PYTHONPATH for a module called `config` (i.e., a
+   `config.py` file) for global variables defined in that module.
+3) Check the system environment variables (`os.environ`).
+
+Variable names must be a valid Python identifier. Only valid
+value types are supported, as per the function `valid_value`.
+
+Usage:
+    from ck.utils.local_config import config
+
+    # assume `config.py` is in the PYTHONPATH and contains:
+    #    ABC = 123
+    #    DEF = 456
+
+    val = config.ABC                  # val = 123
+    val = config.XYZ                  # will raise an exception
+    val = config.get('ABC')           # val = 123
+    val = config['DEF']               # val = 456
+    val = config['XYZ']               # will raise an exception
+    val = config.get('XYZ')           # val = None
+    val = config.get('XYZ', 999)      # val = 999
+
+    from ck.utils.local_config import get_params
+
+    val = get_params('ABC')                  # val = ('ABC', 123)
+    val = get_params('ABC', 'DEF')           # val = (('ABC', 123), ('DEF', 456))
+    val = get_params('ABC', 'DEF', sep='=')  # val = ('ABC=123', 'DEF=456')
+    val = get_params('ABC;DEF', delim=';')   # val = 'ABC=123;DEF=456'
+
+"""
+
+import inspect
+import os
+from ast import literal_eval
+from itertools import chain
+from typing import Optional, Dict, Any, Sequence, Iterable
+
+from ck.utils.iter_extras import flatten
+
+try:
+    # Try to import the user's `config.py`
+    import config as _user_config
+except ImportError:
+    _user_config = None
+
+# Sentinel object
+_NIL = object()
+
+
+class Config:
+
+    def __init__(self):
+        self._programmatic_config: Dict[str, Any] = {}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get the value of the given local configuration variable.
+        If the configuration variable is not available, return the given default value.
+        """
+        if not key.isidentifier():
+            raise KeyError(f'invalid local configuration parameter: {key!r}')
+
+        # Check the programmatic config
+        value = self._programmatic_config.get(key, _NIL)
+        if value is not _NIL:
+            return value
+
+        # Check config.py
+        if _user_config is not None:
+            value = vars(_user_config).get(key, _NIL)
+            if value is not _NIL:
+                if not valid_value(value):
+                    raise KeyError(f'user configuration file contains an invalid value for variable: {key!r}')
+                return value
+
+        # Check the OS environment
+        value = os.environ.get(key, _NIL)
+        if value is not _NIL:
+            return value
+
+        # Not found - return the default value
+        return default
+
+    def __contains__(self, key: str) -> bool:
+        return self.get(key, _NIL) is not _NIL
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """
+        Programmatically overwrite a local configuration variable.
+        """
+        if not key.isidentifier():
+            raise KeyError(f'invalid local configuration parameter: {key!r}')
+        if not valid_value(value):
+            raise ValueError(f'invalid local configuration parameter value: {value!r}')
+        self._programmatic_config[key] = value
+
+    def __getitem__(self, key: str):
+        """
+        Get the value of the given configuration variable.
+        If the configuration variable is not available, raise a KeyError.
+        """
+        value = self.get(key, _NIL)
+        if value is _NIL:
+            raise KeyError(f'undefined local configuration parameter: {key}')
+        return value
+
+    def __getattr__(self, key: str):
+        """
+        Get the value of the given configuration variable.
+        If the configuration variable is not available, raise a KeyError.
+        """
+        value = self.get(key, _NIL)
+        if value is _NIL:
+            raise KeyError(f'undefined local configuration parameter: {key}')
+        return value
+
+
+# The global local config object.
+config = Config()
+
+
+def valid_value(value: Any) -> bool:
+    """
+    Does the given value have an acceptable type for
+    a configuration variable?
+    """
+    if isinstance(value, (list, tuple, set)):
+        return all(valid_value(elem) for elem in value)
+    if isinstance(value, dict):
+        return all(valid_value(elem) for elem in chain(value.keys(), value.values()))
+    if callable(value) or inspect.isfunction(value) or inspect.ismodule(value):
+        return False
+    # All tests pass
+    return True
+
+
+# noinspection PyShadowingNames
+def get_params(
+        *keys: str,
+        sep: Optional[str] = None,
+        delim: Optional[str] = None,
+        config: Config = config,
+):
+    """
+    Return one or more configuration parameter as key-value pairs.
+
+    If `sep` is None then each key-value pair is returned as a tuple, otherwise
+    each key-value pair is returned as a string with `sep` as the separator.
+
+    If `delim` is None then each key is treated as is. If one key is provided then
+    its value is returned. If multiple keys are provided, then multiple values
+    are returned in a tuple.
+
+    If `delim` is not None, then keys are split using `delim`, and results
+    are returned as a single string with `delim` as the delimiter. If
+    `delim` is not None then the default value for `sep` is '='.
+
+    For example, assume config.py contains: ABC = 123 and DEF = 456,
+    then:
+        get_params('ABC') -> ('ABC', 123)
+        get_params('ABC', 'DEF') -> ('ABC', 123), ('DEF', 456)
+        get_params('ABC', sep='=') = 'ABC=123'
+        get_params('ABC', 'DEF', sep='=') = 'ABC=123', 'DEF=456'
+        get_params('ABC;DEF', delim=';') = 'ABC=123;DEF=456'
+        get_params('ABC;DEF', sep='==', delim=';') = 'ABC==123;DEF==456'
+
+    :param keys: the names of variables to access.
+    :param sep: the separator character between {variable} and {value}.
+    :param delim: the delimiter character between key-value pairs.
+    :param config: a Config instance to update. Default is the global config.
+    """
+    if delim is not None:
+        keys = flatten(key.split(delim) for key in keys)
+        if sep is None:
+            sep = '='
+
+    if sep is None:
+        items = ((key, config[key]) for key in keys)
+    else:
+        items = (f'{key}{sep}{config[key]!r}' for key in keys)
+
+    if delim is None:
+        result = tuple(items)
+        if len(result) == 1:
+            result = result[0]
+    else:
+        result = delim.join(str(item) for item in items)
+
+    return result
+
+
+# noinspection PyShadowingNames
+def update_config(
+        argv: Sequence[str],
+        valid_keys: Optional[Iterable[str]] = None,
+        *,
+        sep: str = '=',
+        strip_whitespace: bool = True,
+        config: Config = config,
+) -> None:
+    """
+    Programmatically overwrite a local configuration variable from a command line `argv`.
+
+    Variable values are interpreted as per a Python literal.
+
+    Example usage:
+        import sys
+        from ck.utils.local_config import update_config
+
+        def main():
+            ...
+
+        if __name__ == '__main__':
+            update_config(sys.argv, ['in_name', 'out_name'])
+            main()
+
+    :param argv: a collection of strings in the form '{variable}={value}'.
+        Variables not in `valid_keys` will raise a ValueError.
+    :param valid_keys: an optional collection of strings that are valid variables to
+        process from argv, or None to accept all variables.
+    :param sep: the separator character between {variable} and {value}.
+        Defaults is '='.
+    :param strip_whitespace: If True, then whitespace is stripped from
+        the value before updating the config. Whitespace is always stripped
+        from the variable name.
+    :param config: a Config instance to update. Default is the global config.
+    """
+    if valid_keys is not None:
+        valid_keys = set(valid_keys)
+
+    for arg in argv:
+        var_val = str(arg).split(sep, maxsplit=1)
+        if len(var_val) != 2:
+            raise ValueError(f'cannot split argument: {arg!r} using separator {sep!r}')
+
+        var, val = var_val
+        var = var.strip()
+        if strip_whitespace:
+            val = val.strip()
+
+        if valid_keys is not None and var not in valid_keys:
+            raise KeyError(f'invalid key: {arg!r}')
+
+        try:
+            interpreted = literal_eval(val)
+        except (ValueError, SyntaxError) as err:
+            # Some operating systems strip quotes off
+            # strings, so we try to recover.
+            if '"' in val or "'" in val:
+                # Too hard... forget it.
+                raise err
+            interpreted = str(val)
+
+        config[var] = interpreted

ck/utils/map_list.py

@@ -0,0 +1,128 @@
+"""
+This module defines a class "MapList" for mapping keys to lists.
+"""
+from __future__ import annotations
+
+from typing import TypeVar, Generic, List, Dict, MutableMapping, KeysView, ValuesView, ItemsView, Iterable, Iterator
+
+_K = TypeVar('_K')
+_V = TypeVar('_V')
+
+
+class MapList(Generic[_K, _V], MutableMapping[_K, List[_V]]):
+    """
+    A MapList keeps a list for each key, unlike a dict which keeps only
+    a single element for each key.
+    """
+    __slots__ = ('_map', )
+
+    def __init__(self, *args, **kwargs):
+        self._map: Dict[_K, List[_V]] = {}
+        self.update(*args, extend=False, **kwargs)
+
+    def __str__(self) -> str:
+        return str(self._map)
+
+    def __repr__(self) -> str:
+        args = ', '.join(f'{key!r}:{val!r}' for key, val in self.items())
+        class_name = self.__class__.__name__
+        return f'{class_name}({args})'
+
+    def __len__(self) -> int:
+        return len(self._map)
+
+    def __bool__(self) -> bool:
+        return len(self) > 0
+
+    def __getitem__(self, key) -> List[_V]:
+        return self._map[key]
+
+    def __setitem__(self, key: _K, val: List[_V]):
+        if not isinstance(val, list):
+            class_name = self.__class__.__name__
+            raise RuntimeError(f'every {class_name} value must be a list')
+        self._map[key] = val
+
+    def __delitem__(self, key: _K):
+        del self._map[key]
+
+    def __iter__(self) -> Iterator[_K]:
+        return iter(self._map)
+
+    def __contains__(self, key: _K) -> bool:
+        return key in self._map
+
+    def update(self, *args, extend=False, **kwargs):
+        k: _K
+        v: List[_V]
+        if extend:
+            for k, v in dict(*args, **kwargs).items():
+                self.extend(k, v)
+        else:
+            for k, v in dict(*args, **kwargs).items():
+                self[k] = v
+
+    def keys(self) -> KeysView[_K]:
+        return self._map.keys()
+
+    def values(self) -> ValuesView[List[_V]]:
+        return self._map.values()
+
+    def items(self) -> ItemsView[_K, List[_V]]:
+        return self._map.items()
+
+    def get(self, key: _K, default=None):
+        """
+        Get the list corresponding to the given key.
+        If the key is not yet in the MapList then the
+        supplied default will be returned.
+        """
+        return self._map.get(key, default)
+
+    def get_list(self, key: _K) -> List[_V]:
+        """
+        Get the list corresponding to the given key.
+
+        This method will always return a list in the MapList, even if
+        it requires a new list being created.
+
+        Modifying the returned list affects this MapList object.
+        """
+        the_list = self._map.get(key)
+        if the_list is None:
+            the_list = []
+            self._map[key] = the_list
+        return the_list
+
+    def append(self, key: _K, item: _V):
+        """
+        Append the given item to the list identified by the given key.
+        """
+        self.get_list(key).append(item)
+
+    def extend(self, key: _K, items: Iterable[_V]):
+        """
+        Extend the given item to the list identified by the given key.
+        """
+        return self.get_list(key).extend(items)
+
+    def extend_map_list(self, map_list: MapList[_K, _V]):
+        """
+        Add all the keyed given items to the list identified by each key.
+        """
+        for key, items in map_list.items():
+            self.extend(key, items)
+
+    def clear(self):
+        """
+        Remove all items.
+        """
+        return self._map.clear()
+
+    def clear_empty(self):
+        """
+        Remove all empty values.
+        """
+        keys_to_remove = [key for key, value in self._map.items() if len(value) == 0]
+        for key in keys_to_remove:
+            del self._map[key]

ck/utils/map_set.py

@@ -0,0 +1,128 @@
+"""
+This module defines a class "MapSet" for mapping keys to sets.
+"""
+from __future__ import annotations
+
+from typing import TypeVar, Generic, Set, Dict, MutableMapping, Iterator, KeysView, ValuesView, ItemsView, Iterable
+
+_K = TypeVar('_K')
+_V = TypeVar('_V')
+
+
+class MapSet(Generic[_K, _V], MutableMapping[_K, Set[_V]]):
+    """
+    A MapSet keeps a set for each key, unlike a dict which keeps only
+    a single element for each key.
+    """
+    __slots__ = ('_map',)
+
+    def __init__(self, *args, **kwargs):
+        self._map: Dict[_K, Set[_V]] = {}
+        self.update(*args, add_all=False, **kwargs)
+
+    def __str__(self) -> str:
+        return str(self._map)
+
+    def __repr__(self) -> str:
+        args = ', '.join(f'{key!r}:{val!r}' for key, val in self.items())
+        class_name = self.__class__.__name__
+        return f'{class_name}({args})'
+
+    def __len__(self) -> int:
+        return len(self._map)
+
+    def __bool__(self) -> bool:
+        return len(self) > 0
+
+    def __getitem__(self, key: _K) -> Set[_V]:
+        return self._map[key]
+
+    def __setitem__(self, key: _K, val: Set[_V]):
+        if not isinstance(val, set):
+            class_name = self.__class__.__name__
+            raise RuntimeError(f'every {class_name} value must be a set')
+        self._map[key] = val
+
+    def __delitem__(self, key: _K):
+        del self._map[key]
+
+    def __iter__(self) -> Iterator[_K]:
+        return iter(self._map)
+
+    def __contains__(self, key: _K) -> bool:
+        return key in self._map
+
+    def update(self, *args, add_all=True, **kwargs):
+        k: _K
+        v: Set[_V]
+        if add_all:
+            for k, v in dict(*args, **kwargs).items():
+                self.add_all(k, v)
+        else:
+            for k, v in dict(*args, **kwargs).items():
+                self[k] = v
+
+    def keys(self) -> KeysView[_K]:
+        return self._map.keys()
+
+    def values(self) -> ValuesView[Set[_V]]:
+        return self._map.values()
+
+    def items(self) -> ItemsView[_K, Set[_V]]:
+        return self._map.items()
+
+    def get(self, key: _K, default=None):
+        """
+        Get the set corresponding to the given key.
+        If the key is not yet in the MapSet then the
+        supplied default will be returned.
+        """
+        return self._map.get(key, default)
+
+    def get_set(self, key: _K) -> Set[_V]:
+        """
+        Get the set corresponding to the given key.
+
+        This method will always return a set in the MapSet, even if
+        it requires a new set being created.
+
+        Modifying the returned set affects this MapSet object.
+        """
+        the_set = self._map.get(key)
+        if the_set is None:
+            the_set = set()
+            self._map[key] = the_set
+        return the_set
+
+    def add(self, key: _K, item: _V):
+        """
+        Add the given item to the set identified by the given key.
+        """
+        self.get_set(key).add(item)
+
+    def add_all(self, key: _K, items: Iterable[_V]):
+        """
+        Add all the given items to the set identified by the given key.
+        """
+        return self.get_set(key).update(items)
+
+    def add_map_set(self, map_set: MapSet[_K, _V]):
+        """
+        Add all the keyed given items to the set identified by each key.
+        """
+        for key, items in map_set.items():
+            self.add_all(key, items)
+
+    def clear(self):
+        """
+        Remove all items.
+        """
+        return self._map.clear()
+
+    def clear_empty(self):
+        """
+        Remove all empty values.
+        """
+        keys_to_remove = [key for key, value in self._map.items() if len(value) == 0]
+        for key in keys_to_remove:
+            del self._map[key]

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