scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/engine/problems/_renewal_kernel.py

@@ -0,0 +1,250 @@
+"""Renewal law compiled into the draws, resets, and waiting times of every member of its component."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Callable, Mapping
+
+import numpy as np
+import numpy.typing as npt
+
+from ...errors import SolverError, ValidationError
+from ...specs import DrawSpec, RenewalRecordSpec, RunStateSpec
+from ...types import Array, Indices
+from ..types import Drawn, ReadKind
+from ._base import BaseKernel
+from ._draw_kernel import DrawKernel
+from ._expression_printer import ExpressionPrinter
+from ._reference_spec import ReferenceSpec
+
+type MemberFunction = tuple[Callable[..., object], tuple[ReferenceSpec | str, ...]]
+"""Function of the states and parameters of renewing members and of the values drawn for them, with its readers."""
+
+type Sampler = tuple[DrawSpec, MemberFunction]
+"""DrawSpec of a renewal law with the function of its arguments."""
+
+_READ_SOURCES = frozenset({ReadKind.SINGLE, ReadKind.MEMBER})
+
+
+class RenewalKernel(BaseKernel):
+    """Renewal law compiled into the draws, resets, and waiting times of every member of its component.
+
+    `run(state)` keeps in `values_` the next renewal time of every member, drawn from the state at its time, and the
+    solver that keeps the renewal times renews the members that are due, at their own times.
+
+    Args:
+        label:
+            The name of the renewal law.
+
+        members:
+            The number of members that renew on their own clocks.
+
+        counts:
+            The flat index of the hidden state that counts the renewals of every member.
+
+        states:
+            The flat indices of the states of every member that records keep, one row per member.
+
+        names:
+            The dotted state name and the component of every column of `states`.
+
+        targets:
+            The flat indices the reset writes, one row per reset component and one column per member.
+
+        reset:
+            The function of the renewing members that returns the value of every reset component, or `None`.
+
+        waiting:
+            The function of the renewing members that returns their next waiting times.
+
+        before:
+            The draws of the reset, taken before it.
+
+        after:
+            The draws of the waiting time alone, taken after the reset.
+
+        sampler:
+            A function `f(rng, size=, t=, **values)` that returns the waiting times, or `None` for a symbolic one. It
+            receives the random stream, the number of renewing members, their times, and their values by name.
+
+        reads:
+            The states and parameters of the renewing members that a sampler receives, by name.
+
+    Attributes:
+        values_:
+            The next renewal time of every member of the last run.
+    """
+
+    values_: Array
+
+    def __init__(
+        self,
+        label: str,
+        members: int,
+        counts: Indices,
+        states: Indices,
+        names: tuple[str, ...],
+        *,
+        targets: Indices,
+        reset: MemberFunction | None,
+        waiting: MemberFunction,
+        before: tuple[Sampler, ...],
+        after: tuple[Sampler, ...],
+        sampler: Callable[..., npt.ArrayLike] | None = None,
+        reads: Mapping[str, ReferenceSpec] | None = None,
+    ) -> None:
+        self.label = label
+        self.members = members
+        self.counts = counts
+        self.states = states
+        self.names = names
+        self.targets = targets
+        self.reset = reset
+        self.waiting = waiting
+        self.before = before
+        self.after = after
+        self.sampler = sampler
+        self.reads = reads
+
+    @staticmethod
+    def _evaluate(
+        function: MemberFunction,
+        times: Array,
+        x: Array,
+        p: Array,
+        fired: Indices,
+        *,
+        drawn: Drawn,
+    ) -> list[Array]:
+        """Return the value of every expression of a member function for every renewing member."""
+        compiled, readers = function
+        arguments = []
+        for reader in readers:
+            if isinstance(reader, str):
+                arguments.append(drawn[reader])
+                continue
+            column = reader.column_of(x, p)
+            arguments.append(column[fired] if reader.source is ReadKind.MEMBER else column)
+        values = ExpressionPrinter._values_of(compiled(times, *arguments))
+        return [np.broadcast_to(np.asarray(value, dtype=float), fired.shape).copy() for value in values]
+
+    def _sample(
+        self,
+        samplers: tuple[Sampler, ...],
+        times: Array,
+        x: Array,
+        p: Array,
+        fired: Indices,
+        *,
+        drawn: Drawn,
+        rng: np.random.Generator,
+    ) -> None:
+        """DrawSpec a value of every sampler for every renewing member into the drawn values, in order."""
+        for draw, arguments in samplers:
+            values = self._evaluate(arguments, times, x, p, fired, drawn=drawn) if draw.arguments else []
+            drawn[draw.name] = DrawKernel._sample_draw(draw, values, fired.size, rng)
+
+    def _sampled(self, times: Array, x: Array, p: Array, fired: Indices, *, rng: np.random.Generator) -> Array:
+        """Return the waiting times a function draws for the renewing members."""
+        if self.sampler is None:
+            error_msg = f'The renewal law {self.label} has no function of its waiting time.'
+            raise ValidationError(error_msg)
+        values = {
+            name: reader.column_of(x, p)[fired] if reader.source is ReadKind.MEMBER else reader.column_of(x, p)
+            for name, reader in (self.reads or {}).items()
+        }
+        found = self.sampler(rng, size=fired.size, t=times, **values)
+        return np.broadcast_to(np.asarray(found, dtype=float), fired.shape).copy()
+
+    def _wait(
+        self,
+        times: Array,
+        x: Array,
+        p: Array,
+        fired: Indices,
+        *,
+        drawn: Drawn,
+        rng: np.random.Generator,
+    ) -> Array:
+        """Return the next renewal times of members from their states, after drawing the waiting time's draws."""
+        self._sample(self.after, times, x, p, fired, drawn=drawn, rng=rng)
+        waiting = (
+            self._evaluate(self.waiting, times, x, p, fired, drawn=drawn)[0]
+            if self.sampler is None
+            else self._sampled(times, x, p, fired, rng=rng)
+        )
+        if not np.all(waiting >= 0):
+            error_msg = (
+                f'The renewal law {self.label} drew the waiting time {waiting[~(waiting >= 0)][0]}, but waiting '
+                'times must be nonnegative. DrawSpec them from a distribution with nonnegative support.'
+            )
+            raise SolverError(error_msg)
+        return times + waiting
+
+    def _run(self, inputs: RunStateSpec | None) -> None:
+        """Set the next renewal time of every member, drawn from the state as if every member renewed at its time."""
+        state = self._state_of(inputs)
+        x, p, rng = state.x, state.p, self._generator_of(state)
+        fired = np.arange(self.members, dtype=np.intp)
+        times = np.full(self.members, state.t)
+        drawn: Drawn = {}
+        self._sample(self.before, times, x, p, fired, drawn=drawn, rng=rng)
+        self.values_ = self._wait(times, x, p, fired, drawn=drawn, rng=rng)
+
+    def _fire(
+        self,
+        times: Array,
+        fired: Indices,
+        x: Array,
+        p: Array,
+        rng: np.random.Generator,
+    ) -> tuple[Array, Array, RenewalRecordSpec]:
+        """Renew members at their times: draw, reset their states, count the renewal, and draw the next times.
+
+        Args:
+            times:
+                The renewal time of every renewing member.
+
+            fired:
+                The renewing members.
+
+            x:
+                The state vector.
+
+            p:
+                The parameter vector.
+
+            rng:
+                The random number generator.
+
+        Returns:
+            state:
+                The state vector after the resets.
+
+            following:
+                The next renewal time of every renewing member.
+
+            record:
+                The record of the renewals.
+        """
+        drawn: Drawn = {}
+        self._sample(self.before, times, x, p, fired, drawn=drawn, rng=rng)
+        state = x.copy()
+        if self.reset is not None:
+            for place, value in zip(
+                self.targets,
+                self._evaluate(self.reset, times, x, p, fired, drawn=drawn),
+                strict=True,
+            ):
+                state[place[fired]] = value
+        state[self.counts[fired]] += 1
+        following = self._wait(times, state, p, fired, drawn=drawn, rng=rng)
+        record = RenewalRecordSpec(
+            self.label,
+            times.copy(),
+            fired.copy(),
+            x[self.states[fired]],
+            state[self.states[fired]],
+            self.names,
+        )
+        return state, following, record

skcomplex/engine/problems/_request_spec.py

@@ -0,0 +1,27 @@
+"""Define the request spec."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from sage.all__sagemath_symbolics import Expression
+
+from ...specs._base_spec import BaseSpec
+from ...specs._draw_spec import DrawSpec
+from ._kernel_spec import KernelSpec
+
+
+@dataclass(frozen=True)
+class _RequestSpec(BaseSpec):
+    """DrawSpec of a component that needs a value per evaluation row at every step."""
+
+    owner: str
+    name: str
+    normal: bool
+    rows: int
+    slot: Expression
+    spec: KernelSpec
+    draw: DrawSpec | None = None
+    slots: Mapping[str, Expression] = field(default_factory=dict)

skcomplex/engine/problems/_rule_kernel.py

@@ -0,0 +1,227 @@
+"""Local rule compiled for a lattice, with its neighbour table and its evaluation."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import functools
+from collections.abc import Callable, Iterable
+
+import numba
+import numpy as np
+import numpy.typing as npt
+import scipy.sparse
+
+from ...core.spaces import BaseSpace
+from ...core.specs import LatticeStateSpec
+from ...errors import SolverError, ValidationError
+from ...specs import ArgumentsSpec, LookupSpec, RunStateSpec
+from ...types import Array, Indices
+from ._base import BaseKernel
+
+_LOOKUP_KINDS = {'table': 0, 'totalistic': 1, 'outer': 2}
+
+
+@numba.njit(cache=True)
+def _fused_lookup(
+    values: Array,
+    centers: Array,
+    fill: float,
+    table: Indices,
+    kind: int,
+    *,
+    base: int,
+    lookup: Array,
+    columns: int,
+) -> Array:
+    """Return the next values of a lookup rule at every site in one compiled loop."""
+    n_sites, n_offsets = table.shape
+    following = np.empty(n_sites)
+    for site in range(n_sites):
+        code = 0
+        total = 0.0
+        for offset in range(n_offsets):
+            neighbour = table[site, offset]
+            value = values[neighbour] if neighbour < n_sites else fill
+            code = code * base + int(value)
+            total += value
+        if kind == 0:
+            following[site] = lookup[code]
+        elif kind == 1:
+            following[site] = lookup[int(total)]
+        else:
+            following[site] = lookup[int(centers[site]) * columns + int(total)]
+    return following
+
+
+_NO_ARGUMENTS = ArgumentsSpec()
+
+
+class RuleKernel(BaseKernel):
+    """Local rule compiled for a lattice, with its neighbour table and its evaluation.
+
+    Args:
+        owner:
+            The path of the component that declares the rule.
+
+        targets:
+            The lattice states the rule updates.
+
+        reads:
+            The lattice states whose neighbourhoods the rule reads.
+
+        table:
+            The member index of every neighbour of every site, with the number of sites for the fill value.
+
+        rule:
+            The function rule, or `None` for a lookup rule.
+
+        lookup:
+            The lookup array of a table or totalistic rule, or `None` for a function rule.
+
+        schedule:
+            The update schedule.
+
+        stochastic:
+            Whether the rule receives uniform random numbers.
+
+        arguments:
+            The parameters a function rule receives by keyword.
+
+        fused:
+            Whether a synchronous lookup rule runs as one compiled loop.
+
+        degrees:
+            The number of real neighbours of every site, for a function rule that reads them, or `None`.
+
+        classes:
+            The sites of every class of the colored or checkerboard schedule.
+    """
+
+    values_: None
+
+    def __init__(
+        self,
+        owner: str,
+        targets: tuple[LatticeStateSpec, ...],
+        reads: tuple[LatticeStateSpec, ...],
+        table: Indices,
+        rule: Callable[..., object] | None,
+        *,
+        lookup: LookupSpec | None,
+        schedule: str,
+        stochastic: bool,
+        arguments: ArgumentsSpec = _NO_ARGUMENTS,
+        fused: bool = False,
+        degrees: Array | None = None,
+        classes: tuple[Indices, ...] = (),
+    ) -> None:
+        self.owner = owner
+        self.targets = targets
+        self.reads = reads
+        self.table = table
+        self.rule = rule
+        self.lookup = lookup
+        self.schedule = schedule
+        self.stochastic = stochastic
+        self.arguments = arguments
+        self.fused = fused
+        self.degrees = degrees
+        self.classes = classes
+
+    @property
+    def space(self) -> BaseSpace:
+        """Lattice or network of the rule."""
+        return self.targets[0].space
+
+    @functools.cached_property
+    def reading(self) -> scipy.sparse.csr_matrix:
+        """Sparse matrix whose entry `(i, j)` is 1 when site `i` reads site `j`."""
+        size = self.table.shape[0]
+        rows = np.repeat(np.arange(size), self.table.shape[1])
+        columns = self.table.ravel()
+        real = columns < size
+        ones = np.ones(int(real.sum()))
+        return scipy.sparse.csr_matrix((ones, (rows[real], columns[real])), shape=(size, size))
+
+    def _next(self, x: Array, p: Array, sites: Indices | None, rng: np.random.Generator) -> list[Array]:
+        """Return the next values of the targets at some sites, read from the current state."""
+        space = self.space
+        table = self.table if sites is None else self.table[sites]
+        if self.lookup is not None:
+            values = x[self.reads[0].sites]
+            if self.fused and sites is None:
+                centers = x[self.targets[0].sites]
+                lookup = self.lookup
+                following = _fused_lookup(
+                    np.ascontiguousarray(values),
+                    np.ascontiguousarray(centers),
+                    float(space.fill),
+                    table,
+                    _LOOKUP_KINDS[lookup.kind],
+                    base=lookup.base,
+                    lookup=lookup.values,
+                    columns=lookup.columns,
+                )
+                return [following]
+            gathered = np.append(values, space.fill)[table].astype(np.intp)
+            lookup = self.lookup
+            if lookup.kind == 'table':
+                codes = np.ravel_multi_index(tuple(gathered.T), (lookup.base,) * gathered.shape[1])
+                return [lookup.values[codes]]
+            totals = gathered.sum(axis=1)
+            if lookup.kind == 'totalistic':
+                return [lookup.values[totals]]
+            centers = x[self.targets[0].sites].astype(np.intp)
+            return [lookup.values[(centers if sites is None else centers[sites]) * lookup.columns + totals]]
+        columns = [column for state in self.reads for column in np.append(x[state.sites], space.fill)[table].T]
+        keywords = self.arguments.values(x, p, sites)
+        if self.degrees is not None:
+            keywords['degree'] = self.degrees if sites is None else self.degrees[sites]
+        if self.stochastic:
+            keywords['random'] = rng.random(table.shape[0])
+        if self.rule is None:
+            error_msg = f'The local rule of {self.owner} has neither a function nor a lookup.'
+            raise ValidationError(error_msg)
+        result = self.rule(*columns, **keywords)
+        several = len(self.targets) > 1
+        results = list(result) if several and isinstance(result, Iterable) else [result]
+        if len(results) != len(self.targets):
+            error_msg = (
+                f'The local rule of {self.owner} returned {len(results)} arrays for {len(self.targets)} targets.'
+            )
+            raise SolverError(error_msg)
+        return [np.broadcast_to(np.asarray(item, dtype=float), (table.shape[0],)) for item in results]
+
+    def _assign(self, x: Array, values: list[Array], sites: Indices | None) -> None:
+        """Write the next values of the targets at some sites."""
+        for state, value in zip(self.targets, values, strict=True):
+            if sites is None:
+                x[state.sites] = value
+            else:
+                x[state.start + sites] = value
+
+    def _run_near(self, inputs: RunStateSpec, active: npt.NDArray[np.bool_]) -> None:
+        """Update the state in place, synchronously, at the active sites and the sites that read one of them."""
+        x, p, rng = inputs.x, inputs.p, self._generator_of(inputs)
+        readers = active | (self.reading @ active.astype(np.float64) > 0)
+        sites = np.flatnonzero(readers)
+        if sites.size:
+            self._assign(x, self._next(x, p, sites, rng), sites)
+
+    def _run(self, inputs: RunStateSpec | None) -> None:
+        """Update the state vector of the state in place by one application of the rule on its schedule."""
+        self.values_ = None
+        state = self._state_of(inputs)
+        x, p, rng = state.x, state.p, self._generator_of(state)
+        size = self.targets[0].size
+        if self.schedule == 'synchronous':
+            self._assign(x, self._next(x, p, None, rng), None)
+            return
+        if self.schedule in {'checkerboard', 'colored'}:
+            for sites in self.classes:
+                self._assign(x, self._next(x, p, sites, rng), sites)
+            return
+        order = rng.permutation(size) if self.schedule == 'random-sequential' else rng.integers(size, size=size)
+        for site in order:
+            sites = np.asarray([site])
+            self._assign(x, self._next(x, p, sites, rng), sites)

skcomplex/engine/problems/_set_symbol_spec.py

@@ -0,0 +1,28 @@
+"""Define the set symbol spec."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from sage.all__sagemath_symbolics import Expression
+
+from ...specs._base_spec import BaseSpec
+from ._reference_spec import ReferenceSpec
+
+_MEMBER_REFERENCE = re.compile(r'^(?P<path>.+)\[(?P<index>-?\d+)\]$')
+
+
+_EDGE_NAMES = ('source', 'target', 'edge')
+
+
+@dataclass(frozen=True)
+class SetSymbolSpec(BaseSpec):
+    """Symbol of one element of an element set, with the same symbol of every element of the set."""
+
+    canonical: Expression
+    references: tuple[ReferenceSpec, ...]
+    label: str

skcomplex/engine/problems/_source_loader.py

@@ -0,0 +1,113 @@
+"""Define the source loader."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import hashlib
+import importlib.util
+import os
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from types import ModuleType
+
+from ...base import BaseConfig
+from ...errors import ValidationError
+
+CACHE_DIR = Path.home() / '.cache' / 'skcomplex' / 'kernels'
+"""The default directory of the generated sources and of Numba's cache."""
+
+
+class SourceLoader(BaseConfig[str | Path | None, str]):
+    """Loader of generated source, imported from a file of the cache directory named by its digest.
+
+    `prepare(cache_dir)` sets the directory of the generated files, `~/.cache/skcomplex/kernels` by default, and
+    `run(source)` writes the source there once and imports it into `module_`. Source without injected functions is
+    kept in `sys.modules`, so the same source is imported once. Source with injected functions is imported afresh,
+    with the functions set on the module before its code runs.
+
+    Args:
+        prefix:
+            The start of the name of the module, a Python identifier.
+
+        functions:
+            The functions the source reads by name, injected into its module, or `None` for none.
+
+    Attributes:
+        directory_:
+            The directory of the generated files.
+
+        module_:
+            The module of the last source run.
+
+    Examples:
+        >>> from skcomplex.engine.problems import SourceLoader
+        >>> loader = SourceLoader('skcomplex_example').check().prepare()
+        >>> loader.run('def double(x): return 2 * x').module_.double(3)
+        6
+    """
+
+    directory_: Path
+    module_: ModuleType
+
+    def __init__(self, prefix: str, functions: Mapping[str, object] | None = None) -> None:
+        self.prefix = prefix
+        self.functions = functions
+
+    def _check(self) -> None:
+        """Raise an error for a prefix that is not a Python identifier.
+
+        Raises:
+            ValidationError:
+                The prefix is not a Python identifier.
+        """
+        if not self.prefix.isidentifier():
+            error_msg = f'The prefix of a source loader is a Python identifier, not {self.prefix!r}.'
+            raise ValidationError(error_msg)
+
+    def _prepare(self, context: str | Path | None) -> None:
+        """Set the directory of the generated files, the default cache directory when none is given.
+
+        Args:
+            context:
+                The directory of the generated files, or `None` for `~/.cache/skcomplex/kernels`.
+        """
+        self.directory_ = Path(context) if context is not None else CACHE_DIR
+
+    def _run(self, inputs: str | None) -> None:
+        """Write the source to the cache directory once and import it into `module_`.
+
+        Args:
+            inputs:
+                The generated source.
+
+        Raises:
+            ValidationError:
+                No source was given.
+            ImportError:
+                The generated file cannot be imported.
+        """
+        if inputs is None:
+            error_msg = 'A source loader runs on generated source, not None.'
+            raise ValidationError(error_msg)
+        functions = dict(self.functions or {})
+        name = f'{self.prefix}_{hashlib.sha256(inputs.encode()).hexdigest()[:24]}'
+        if not functions and name in sys.modules:
+            self.module_ = sys.modules[name]
+            return
+        self.directory_.mkdir(parents=True, exist_ok=True)
+        path = self.directory_ / f'{name}.py'
+        if not path.exists():
+            temporary = path.with_suffix(f'.{os.getpid()}.tmp')
+            temporary.write_text(inputs)
+            temporary.replace(path)
+        specification = importlib.util.spec_from_file_location(name, path)
+        if specification is None or specification.loader is None:
+            error_msg = f'The generated source at {path} cannot be imported.'
+            raise ImportError(error_msg)
+        module = importlib.util.module_from_spec(specification)
+        module.__dict__.update(functions)
+        if not functions:
+            sys.modules[name] = module
+        specification.loader.exec_module(module)
+        self.module_ = module

skcomplex/engine/problems/_static_search.py

@@ -0,0 +1,42 @@
+"""Neighbours that do not change during a run, the edges of a network or the offsets of a lattice."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+
+from ...specs import RunStateSpec
+from ...types import Indices
+from ..types import EdgesFound
+from ._base import BaseSearch
+
+
+class StaticSearch(BaseSearch):
+    """Neighbours that do not change during a run, the edges of a network or the offsets of a lattice.
+
+    Args:
+        indptr:
+            The start of the neighbours of every member, and the number of pairs last.
+
+        indices:
+            The neighbours of every member in turn.
+
+        edges:
+            The edge of a network layer that joins every member to every neighbour, or `None` on a lattice.
+
+    Attributes:
+        pairs_:
+            The row starts, the neighbours, and the edges of the last run.
+    """
+
+    pairs_: EdgesFound
+
+    def __init__(self, indptr: Indices, indices: Indices, edges: Indices | None = None) -> None:
+        self.indptr = indptr
+        self.indices = indices
+        self.edges = edges
+
+    def _run(self, inputs: RunStateSpec | None) -> None:
+        """Set the neighbours of every member."""
+        state = self._state_of(inputs)
+        del state
+        self.pairs_ = self.indptr, self.indices, self.edges