scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/engine/problems/_linear_term_spec.py

@@ -0,0 +1,50 @@
+"""Define the linear term spec."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from sage.all__sagemath_symbolics import Expression
+
+from ...core.elements import FieldElement
+from ...specs._base_spec import BaseSpec
+from ..types import Chain
+from ._reference_spec import ReferenceSpec
+
+OPERATORS = ('laplacian', 'partial', 'inverse_helmholtz')
+
+
+@dataclass(frozen=True, eq=False)
+class LinearTermSpec(BaseSpec):
+    """Term of the rate of a field state that applies a chain of operators to a state, times a constant coefficient.
+
+    Args:
+        target:
+            The component whose rate holds the term.
+
+        source:
+            The component the operators act on.
+
+        place:
+            The field of the source.
+
+        chain:
+            The operators from outermost to innermost, with their axes.
+
+        coefficient:
+            The coefficient, an expression of parameters.
+
+        references:
+            The references of the coefficient's symbols.
+    """
+
+    target: ReferenceSpec
+    source: ReferenceSpec
+    place: FieldElement
+    chain: Chain
+    coefficient: Expression
+    references: Mapping[Expression, ReferenceSpec]

skcomplex/engine/problems/_loop_term_spec.py

@@ -0,0 +1,44 @@
+"""Define the loop term spec."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from sage.all__sagemath_symbolics import Expression
+
+from ...specs._base_spec import BaseSpec
+from ._reference_spec import ReferenceSpec
+
+
+@dataclass(frozen=True)
+class LoopTermSpec(BaseSpec):
+    """Node of the feedback graph of a system with the expression its value or its rate is computed from.
+
+    Args:
+        kind:
+            `'flow'`, or `'rate'` for a rate law outside flows.
+
+        path:
+            The node of a flow, or the state a rate law targets.
+
+        expression:
+            The expression.
+
+        references:
+            The references of the expression's symbols.
+
+        source:
+            The state a flow drains, or `None`.
+
+        sink:
+            The state a flow fills, or `None`.
+    """
+
+    kind: str
+    path: str
+    expression: Expression
+    references: Mapping[Expression, ReferenceSpec]
+    source: str | None = None
+    sink: str | None = None

skcomplex/engine/problems/_lowered_kernels_spec.py

@@ -0,0 +1,59 @@
+"""Define the lowered kernels spec."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+
+from ...core.laws import BaseLaw
+from ...specs._base_spec import BaseSpec
+from ...types import FormKind
+from ._draw_kernel import DrawKernel
+from ._law_kernel import LawKernel
+from ._random_stream import RandomStream
+from ._reduction_schedule_spec import ReductionScheduleSpec
+from ._reference_spec import ReferenceSpec
+
+
+@dataclass(frozen=True)
+class LoweredKernelsSpec(BaseSpec):
+    """Kernels of every law kind, with the changes of every jump output and the law of every output.
+
+    Args:
+        kernels:
+            The kernels of every law kind, in evaluation order.
+
+        jump_changes:
+            The state changes of every jump output, keyed by the output's identity.
+
+        laws:
+            The kernel spec and the law every output was lowered from, keyed by the output's identity.
+
+        form:
+            The form of the problem, which a backend writes the numeric functions of, or `None` before it is known.
+
+        size:
+            The size of the state vector.
+
+        reductions:
+            The reductions the kernels read, evaluated before them at every evaluation, or `None`.
+
+        draws:
+            The random values a stochastic map draws at every step into the parameter vector extended after its
+            parameters, or `None` for a deterministic problem.
+
+        stream:
+            The random stream the functions of the laws receive, or `None`.
+    """
+
+    kernels: defaultdict[type, list[LawKernel]]
+    jump_changes: dict[int, list[tuple[ReferenceSpec, object]]]
+    laws: dict[int, tuple[object, BaseLaw]]
+    form: FormKind | None = None
+    size: int = 0
+    reductions: ReductionScheduleSpec | None = None
+    draws: DrawKernel | None = None
+    stream: RandomStream | None = None

skcomplex/engine/problems/_markov_kernel.py

@@ -0,0 +1,68 @@
+"""Transition or emission matrix of a Markov law, evaluated from the parameters to check its rows."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Callable
+
+import numpy as np
+import numpy.typing as npt
+
+from ...specs import RunStateSpec
+from ...types import Array
+from ._base import BaseKernel
+
+_ROW_TOLERANCE = 1e-9
+
+
+class MarkovKernel(BaseKernel):
+    """Transition or emission matrix of a Markov law, evaluated from the parameters to check its rows.
+
+    `run(state)` keeps in `values_` the description of the first negative entry or row that does not sum to one at the
+    parameters of the state, or `None` when every matrix is stochastic.
+
+    Args:
+        law:
+            The description of the law, used in messages.
+
+        function:
+            The function `M(p)` that returns the matrix of every member from the parameter vector.
+
+        reads:
+            The indices of the parameter vector the matrix reads.
+
+    Attributes:
+        values_:
+            The description of what is wrong with the matrix at the last run, or `None`.
+    """
+
+    values_: str | None
+
+    def __init__(
+        self,
+        law: str,
+        function: Callable[[Array], npt.NDArray[np.float64]],
+        reads: frozenset[int],
+    ) -> None:
+        self.law = law
+        self.function = function
+        self.reads = reads
+
+    def _run(self, inputs: RunStateSpec | None) -> None:
+        """Set the description of what is wrong with the matrix at the parameters, or `None`."""
+        self.values_ = self._problem(self._state_of(inputs))
+
+    def _problem(self, state: RunStateSpec) -> str | None:
+        """Return the description of what is wrong with the matrix at the parameters of a state, or `None`."""
+        values = self.function(state.p)
+        for member, matrix in enumerate(values):
+            where = f' of member {member}' if values.shape[0] > 1 else ''
+            negative = np.argwhere(~(matrix >= 0))
+            if negative.size:
+                row, column = negative[0]
+                return f'the entry ({row}, {column}){where} of the {self.law} is {matrix[row, column]}, below 0'
+            sums = matrix.sum(axis=1)
+            wrong = np.flatnonzero(np.abs(sums - 1) > _ROW_TOLERANCE)
+            if wrong.size:
+                return f'the row {wrong[0]}{where} of the {self.law} sums to {sums[wrong[0]]}, not 1'
+        return None

skcomplex/engine/problems/_metric_search.py

@@ -0,0 +1,155 @@
+"""Neighbours in a continuous space found from the positions at every evaluation with a k-d tree."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+
+import numpy as np
+import numpy.typing as npt
+from scipy.spatial import cKDTree
+
+from ...core.spaces import (
+    ConeNeighborhood,
+    NearestNeighborhood,
+    RadiusNeighborhood,
+)
+from ...specs import DirectionSpec, EntrySpec, RunStateSpec
+from ...types import Array, Indices
+from ..types import EdgesFound, Pairs
+from ._base import BaseSearch
+
+
+class MetricSearch(BaseSearch):
+    """Neighbours in a continuous space found from the positions at every evaluation with a k-d tree.
+
+    Args:
+        neighbourhood:
+            The radius, nearest, or cone neighbourhood.
+
+        positions:
+            The entry of the position state of the members.
+
+        periods:
+            The sides of a periodic box, or `None` for distances without minimum images.
+
+        direction:
+            The state with the direction of a cone, or `None`.
+
+    Attributes:
+        pairs_:
+            The row starts and the neighbours of every member of the last run, with no edges.
+    """
+
+    pairs_: EdgesFound
+
+    def __init__(
+        self,
+        neighbourhood: RadiusNeighborhood | NearestNeighborhood | ConeNeighborhood,
+        positions: EntrySpec,
+        periods: tuple[float, ...] | None = None,
+        direction: DirectionSpec | None = None,
+    ) -> None:
+        self.neighbourhood = neighbourhood
+        self.positions = positions
+        self.periods = periods
+        self.direction = direction
+
+    def wrapped(self, x: Array) -> Array:
+        """Return the positions of the members, wrapped into a periodic box.
+
+        Args:
+            x:
+                The state vector.
+
+        Returns:
+            positions:
+                One row of position components per member.
+        """
+        positions = self.positions.view(x)
+        if self.periods is None:
+            return positions
+        periods = np.asarray(self.periods)
+        wrapped = np.mod(positions, periods)
+        return np.where(wrapped >= periods, wrapped - periods, wrapped)
+
+    def differences(self, x: Array, readers: Indices, others: Indices) -> Array:
+        """Return the displacement from every reader to its neighbour, the minimum image in a periodic box.
+
+        Args:
+            x:
+                The state vector.
+
+            readers:
+                The reader of every pair.
+
+            others:
+                The neighbour of every pair.
+
+        Returns:
+            differences:
+                One row of components per pair, `x_reader - x_other` wrapped.
+        """
+        positions = self.positions.view(x)
+        difference = positions[readers] - positions[others]
+        if self.periods is None:
+            return difference
+        periods = np.asarray(self.periods)
+        return difference - periods * np.rint(difference / periods)
+
+    def _run(self, inputs: RunStateSpec | None) -> None:
+        """Set the neighbours of every member at the current positions."""
+        state = self._state_of(inputs)
+        x, q = state.x, state.p
+        del q
+        positions = self.wrapped(x)
+        size = positions.shape[0]
+        tree = cKDTree(positions, boxsize=np.asarray(self.periods) if self.periods is not None else None)
+        neighbourhood = self.neighbourhood
+        if isinstance(neighbourhood, NearestNeighborhood):
+            readers, others = self._nearest(tree, positions, neighbourhood.k)
+        else:
+            pairs = tree.query_pairs(neighbourhood.radius, output_type='ndarray').astype(np.intp)
+            readers = np.concatenate([pairs[:, 0], pairs[:, 1]])
+            others = np.concatenate([pairs[:, 1], pairs[:, 0]])
+            if isinstance(neighbourhood, ConeNeighborhood):
+                keep = self._inside(x, readers, others, neighbourhood)
+                readers, others = readers[keep], others[keep]
+        if neighbourhood.center:
+            readers, others = self._with_center(readers, others, size)
+        self.pairs_ = (*self._rows(readers, others, size), None)
+
+    @staticmethod
+    def _nearest(tree: cKDTree, positions: Array, k: int) -> tuple[Indices, Indices]:
+        """Return the pairs of every member with its `k` nearest other members."""
+        size = positions.shape[0]
+        k = min(k, size - 1)
+        if k < 1:
+            return np.zeros(0, dtype=np.intp), np.zeros(0, dtype=np.intp)
+        _, found = tree.query(positions, k=k + 1)
+        found = np.asarray(found, dtype=np.intp).reshape(size, k + 1)
+        own = found == np.arange(size)[:, None]
+        own[~own.any(axis=1), -1] = True
+        return np.repeat(np.arange(size, dtype=np.intp), k), found[~own].astype(np.intp)
+
+    def _inside(self, x: Array, readers: Indices, others: Indices, cone: ConeNeighborhood) -> npt.NDArray[np.bool_]:
+        """Return whether every pair has its neighbour inside the reader's cone."""
+        assert self.direction is not None
+        separation = -self.differences(x, readers, others)
+        direction = self.direction.vectors(x)[readers]
+        dot = np.sum(direction * separation, axis=1)
+        norms = np.sqrt(np.sum(direction * direction, axis=1)) * np.sqrt(np.sum(separation * separation, axis=1))
+        return dot >= np.cos(cone.angle) * norms
+
+    @staticmethod
+    def _rows(readers: Indices, others: Indices, size: int) -> Pairs:
+        """Return the row starts and the neighbours, sorted by reader and then by neighbour, of a list of pairs."""
+        order = np.lexsort((others, readers))
+        counts = np.bincount(readers, minlength=size)
+        indptr = np.concatenate([np.zeros(1, dtype=np.intp), np.cumsum(counts)]).astype(np.intp)
+        return indptr, others[order].astype(np.intp)
+
+    @staticmethod
+    def _with_center(readers: Indices, others: Indices, size: int) -> tuple[Indices, Indices]:
+        """Return pairs with every member paired with itself."""
+        own = np.arange(size, dtype=np.intp)
+        return np.concatenate([readers, own]), np.concatenate([others, own])

skcomplex/engine/problems/_monte_carlo_kernel.py

@@ -0,0 +1,213 @@
+"""Monte Carlo sampling of a lattice state compiled from its local objective, move, and sampler."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Callable, Mapping
+
+import numpy as np
+
+from ...core.specs import LatticeStateSpec
+from ...errors import SolverError
+from ...specs import ArgumentsSpec, MoveSpec, RunStateSpec, SamplerSpec
+from ...types import Array, Indices
+from ._base import BaseKernel
+from ._expression_printer import ExpressionPrinter
+
+
+class MonteCarloKernel(BaseKernel):
+    """Monte Carlo sampling of a lattice state compiled from its local objective, move, and sampler.
+
+    Args:
+        owner:
+            The path of the component that declares the objective.
+
+        target:
+            The lattice state the move changes.
+
+        table:
+            The member index of every neighbour of every site.
+
+        delta:
+            The objective change `delta(value, *neighbours, proposal, **arguments)` over arrays of sites.
+
+        arguments:
+            The parameters and states the objective and the intensity read.
+
+        intensity:
+            The intensity of the acceptance as a function of the arguments.
+
+        move:
+            The move.
+
+        sampler:
+            The acceptance rule and the schedule.
+
+        classes:
+            The sites of every class of the colored or checkerboard schedule.
+
+        masked:
+            Whether the objective change reads the mask of the real neighbours of a neighbour sum.
+
+        bond:
+            For cluster moves, the half change `bond(value, neighbour, **arguments)` of the objective of a site with one
+            neighbour when the value of the site flips and then the value of the neighbour flips, or `None`.
+    """
+
+    values_: None
+
+    def __init__(
+        self,
+        owner: str,
+        target: LatticeStateSpec,
+        table: Indices,
+        delta: Callable[..., object],
+        arguments: ArgumentsSpec,
+        *,
+        intensity: Callable[..., object],
+        move: MoveSpec,
+        sampler: SamplerSpec,
+        classes: tuple[Indices, ...] = (),
+        masked: bool = False,
+        bond: Callable[..., object] | None = None,
+    ) -> None:
+        self.owner = owner
+        self.target = target
+        self.table = table
+        self.delta = delta
+        self.arguments = arguments
+        self.intensity = intensity
+        self.move = move
+        self.sampler = sampler
+        self.classes = classes
+        self.masked = masked
+        self.bond = bond
+
+    def _objective_change(
+        self,
+        x: Array,
+        values: Array,
+        sites: Indices,
+        proposal: Array,
+        keywords: Mapping[str, object],
+    ) -> Array:
+        """Return the objective change of moving some sites to proposed values."""
+        rows = self.table[sites]
+        neighbours = np.append(x[self.target.sites], self.target.space.fill)[rows]
+        masks = (rows != self.target.size).astype(float).T if self.masked else ()
+        change = ExpressionPrinter._values_of(
+            self.delta(0.0, values, *neighbours.T, proposal, *masks, *keywords.values()),
+        )[0]
+        return np.broadcast_to(np.asarray(change, dtype=float), values.shape)
+
+    def _propose(self, values: Array, rng: np.random.Generator) -> Array:
+        """Return proposed values for some sites."""
+        if self.move.kind == 'flip':
+            return -values
+        if self.move.kind == 'random-value':
+            return np.asarray(self.move.values)[rng.integers(len(self.move.values), size=values.size)]
+        if self.move.kind == 'gaussian':
+            return values + rng.normal(0.0, self.move.width, size=values.size)
+        if self.move.kind == 'function' and self.move.function is not None:
+            return np.broadcast_to(np.asarray(self.move.function(values.copy(), rng), dtype=float), values.shape)
+        return values + rng.uniform(-self.move.width, self.move.width, size=values.size)
+
+    def _intensity_of(self, keywords: Mapping[str, object]) -> Array:
+        """Return the intensity at some sites, after checking that it is positive."""
+        intensity = np.asarray(
+            ExpressionPrinter._values_of(self.intensity(self.time_, *keywords.values()))[0],
+            dtype=float,
+        )
+        if np.any(intensity <= 0):
+            error_msg = f'The intensity of {self.owner} is {intensity}, but it must be positive.'
+            raise SolverError(error_msg)
+        return intensity
+
+    def _grow(self, x: Array, p: Array, values: Array, sites: Indices, rng: np.random.Generator) -> Indices:
+        """Return the neighbours that bonds add to a cluster from its newest sites."""
+        rows = self.table[sites]
+        keywords = {
+            name: value[:, None] if isinstance(value, np.ndarray) else value
+            for name, value in self.arguments.values(x, p, sites).items()
+        }
+        intensity = self._intensity_of(keywords)
+        neighbours = np.append(values, self.target.space.fill)[rows]
+        if self.bond is None:
+            error_msg = f'The Monte Carlo laws of {self.owner} make cluster moves without the objective of a bond.'
+            raise SolverError(error_msg)
+        bond = ExpressionPrinter._values_of(self.bond(0.0, values[sites][:, None], neighbours, *keywords.values()))[0]
+        bonds = np.broadcast_to(np.asarray(bond, dtype=float), rows.shape)
+        with np.errstate(over='ignore'):
+            probability = 1.0 - np.exp(np.minimum(bonds * intensity, 0.0))
+        added = (rows != self.target.size) & (rng.random(rows.shape) < probability)
+        return np.unique(rows[added])
+
+    def _flip_cluster(self, x: Array, p: Array, rng: np.random.Generator) -> int:
+        """Flip the values of a cluster grown by Wolff bonds from a random site, and return its size."""
+        start, size = self.target.start, self.target.size
+        values = x[start : start + size].copy()
+        inside = np.zeros(size, dtype=bool)
+        newest = rng.integers(size, size=1)
+        inside[newest] = True
+        while newest.size:
+            found = self._grow(x, p, values, newest, rng)
+            newest = found[~inside[found]]
+            inside[newest] = True
+        x[start + np.flatnonzero(inside)] = -values[inside]
+        return int(inside.sum())
+
+    def _update(self, x: Array, p: Array, sites: Indices, rng: np.random.Generator) -> None:
+        """Propose and accept moves at sites that do not neighbour each other."""
+        keywords = self.arguments.values(x, p, sites)
+        intensity = self._intensity_of(keywords)
+        values = x[self.target.start + sites]
+        if self.sampler.kind == 'heat-bath':
+            candidates = (
+                np.unique(np.concatenate([values, -values]))
+                if self.move.kind == 'flip'
+                else np.asarray(self.move.values)
+            )
+            objectives = np.stack(
+                [
+                    self._objective_change(x, values, sites, np.full(values.shape, value), keywords)
+                    for value in candidates
+                ],
+            )
+            weights = np.exp(-(objectives - objectives.min(axis=0)) * intensity)
+            cumulative = np.cumsum(weights / weights.sum(axis=0), axis=0)
+            chosen = (rng.random(values.size) > cumulative).sum(axis=0)
+            x[self.target.start + sites] = candidates[np.minimum(chosen, candidates.size - 1)]
+            return
+        proposal = self._propose(values, rng)
+        change = self._objective_change(x, values, sites, proposal, keywords)
+        with np.errstate(over='ignore'):
+            if self.sampler.kind == 'metropolis':
+                probability = np.exp(-np.maximum(change, 0.0) * intensity)
+            else:
+                probability = 1.0 / (1.0 + np.exp(change * intensity))
+        accepted = rng.random(values.size) < probability
+        x[self.target.start + sites[accepted]] = proposal[accepted]
+
+    @property
+    def targets(self) -> tuple[LatticeStateSpec, ...]:
+        """Lattice state the move changes, as the one target of the step."""
+        return (self.target,)
+
+    def _run(self, inputs: RunStateSpec | None) -> None:
+        """Update the state vector of the state in place by one sweep of the lattice."""
+        self.values_ = None
+        state = self._state_of(inputs)
+        x, p, rng = state.x, state.p, self._generator_of(state)
+        self.time_ = state.t
+        size = self.target.size
+        if self.move.kind == 'cluster':
+            flipped = 0
+            while flipped < size:
+                flipped += self._flip_cluster(x, p, rng)
+            return
+        if self.sampler.schedule in {'checkerboard', 'colored'}:
+            for sites in self.classes:
+                self._update(x, p, sites, rng)
+            return
+        for site in rng.permutation(size):
+            self._update(x, p, np.asarray([site]), rng)