scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/engine/compile/_compilation.py

@@ -0,0 +1,351 @@
+"""Hold the state of one compilation, the fields its passes produce in order from the system to the problem."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Mapping
+from dataclasses import replace
+
+import numpy as np
+import numpy.typing as npt
+from sage.all__sagemath_symbolics import Expression
+
+from ...core.laws import BaseLaw, CrossingLaw, RuleLaw
+from ...core.specs import CensusSpec, NodeSpec
+from ...core.system import System
+from ...errors import PipelineError
+from ...specs import MatrixLawSpec, TopologyRequestSpec
+from ...specs._plan_spec import _PlanSpec
+from ...types import FormKind
+from ..backends import BaseBackend
+from ..problems import (
+    BlockSpec,
+    DeclarationsSpec,
+    DiffusiveLimitSpec,
+    KernelSpec,
+    LinearTermSpec,
+    LoweredKernelsSpec,
+    OutputSpec,
+    ProblemSpec,
+    ReductionScheduleSpec,
+    SymmetrySpec,
+    TransferNetworkSpec,
+    TransferStateSpec,
+)
+from ..problems._delayed_state_spec import _DelayedStateSpec
+from ..problems._draw_kernel import DrawKernel
+from ..problems._encounter_kernel import EncounterKernel
+from ..problems._finite_volume_kernel import FiniteVolumeKernel
+from ..problems._jacobian_kernel import JacobianKernel
+from ..problems._markov_kernel import MarkovKernel
+from ..problems._problem_functions_spec import _ProblemFunctionsSpec
+from ..problems._topology_kernel import TopologyKernel
+from ..types import ReadKind
+from ._bound_renewal_spec import BoundRenewalSpec
+
+type Laws = list[tuple[KernelSpec, list[BaseLaw]]]
+type BlockLaws = list[tuple[KernelSpec, list[BaseLaw], BlockSpec]]
+
+
+class Compilation:
+    """State of one compilation of a system, whose fields its passes read and write in order.
+
+    The constructor stores the inputs of the compilation, and the passes set every other field, from `nodes` to
+    `problem` in the order they are listed. A field that no pass has set yet is `None`. A pass may also declare hidden
+    states and parameters on the layout, which only grows. Kernel specs are frozen: a pass that adds references to a
+    spec builds a copy, which `_replace_specs` puts in every field that holds the spec.
+
+    Args:
+        system:
+            The system, with the observables of the run.
+
+        backend:
+            The backend instance, or `None` for the backend that suits the size of the system.
+
+        solver:
+            The solver instance, or `None` for the default solver of the system's form.
+
+        owners:
+            The paths of the elements and groups whose laws a partition keeps, or `None` to keep every law.
+
+        held:
+            The paths of the observables that roles bind to and laws read only at synchronisation points.
+
+    Attributes:
+        nodes:
+            The elements, groups, and interactions of the system tree, flattened once.
+
+        census:
+            The laws every component declares, with their owners.
+
+        plan:
+            The partitions of the system.
+
+        layout:
+            The states and parameters of every component, with the blocks of their symbols.
+
+        specs:
+            The kernel spec of every component with its block.
+
+        collected:
+            The laws of every kernel spec as declared, with its block.
+
+        apart:
+            The laws set apart from the kernels of their spec, which a pass of their own compiles.
+
+        lowered:
+            The laws of every kernel spec with complex states split and Markov laws taken out.
+
+        markov:
+            The Markov laws of every kernel spec.
+
+        matrices:
+            The Markov matrices, checked at the initial parameters.
+
+        ordered:
+            The laws with derivatives and lags read through companion states and equations solved.
+
+        delayed:
+            The laws with delayed states read through hidden parameters and events taken out.
+
+        corrected:
+            The laws with the drift correction of every noise law of a convention.
+
+        shifted:
+            The laws with member offset reads lowered to neighbour reads.
+
+        drawn:
+            The laws of the owners of the compilation, masked to the rows present, with draws read from parameters.
+
+        drawn_apart:
+            The laws set apart of the owners of the compilation.
+
+        kinds:
+            The law classes of every owner.
+
+        draws:
+            The kernel of the draws of the laws.
+
+        form:
+            The form of the problem.
+
+        reduced:
+            The laws with every reduction read through its placeholder.
+
+        reduced_apart:
+            The laws set apart, with every reduction read through its placeholder.
+
+        reductions:
+            The reductions the laws read.
+
+        kernels:
+            The kernels of every law kind.
+
+        functions:
+            The numeric functions, the equations, and the backends of the problem.
+
+        jacobian:
+            The exact Jacobian of the drift, or `None`.
+
+        problem:
+            The compiled problem.
+
+        delays:
+            The delayed states with their hidden parameters.
+
+        placeholders:
+            The placeholder of every delayed state read.
+
+        events:
+            The events of every kernel spec.
+
+        renewals:
+            The renewal laws with the hidden states that count them.
+
+        outputs:
+            The outputs of the laws that a pass of a formalism lowers itself, by the identity of the law, which the
+            kernels take in place of the outputs of the law's value.
+
+        written:
+            The operators of fields as written, by state and column, with their stencils.
+
+        limits:
+            The stable steps of explicit field operators.
+
+        volume_limits:
+            The stable steps of finite volumes, as functions of the parameters.
+
+        linear:
+            The linear terms with constant coefficients of the rates of field states.
+
+        volumes:
+            The conservation laws of fields.
+
+        symmetries:
+            The mirror symmetries of the field states.
+
+        constrained:
+            The indices and values of the fixed nodes of meshes.
+
+        encounters:
+            The encounter laws, lowered for their members.
+
+        transfer:
+            The state of the lowering of flows and delays, which one pass creates and a later pass finishes.
+
+        transfer_network:
+            The flows and stocks of the system.
+
+        rules:
+            The rules of every kernel spec, taken out of the reduced laws.
+
+        request_jumps:
+            The jumps that request topology changes, by the identity of the law, with their spec and request.
+
+        topology:
+            The topology changes of the networks, or `None`.
+
+        done:
+            The passes that ran.
+    """
+
+    nodes: list[NodeSpec] | None = None
+    census: CensusSpec | None = None
+    plan: _PlanSpec | None = None
+    layout: DeclarationsSpec | None = None
+    specs: list[tuple[KernelSpec, BlockSpec]] | None = None
+    collected: BlockLaws | None = None
+    apart: Laws | None = None
+    lowered: BlockLaws | None = None
+    markov: list[tuple[KernelSpec, MatrixLawSpec]] | None = None
+    matrices: tuple[MarkovKernel, ...] | None = None
+    ordered: Laws | None = None
+    delayed: Laws | None = None
+    corrected: Laws | None = None
+    shifted: Laws | None = None
+    drawn: Laws | None = None
+    drawn_apart: Laws | None = None
+    kinds: dict[str, set[type]] | None = None
+    draws: DrawKernel | None = None
+    form: FormKind | None = None
+    reduced: Laws | None = None
+    reduced_apart: Laws | None = None
+    reductions: ReductionScheduleSpec | None = None
+    kernels: LoweredKernelsSpec | None = None
+    functions: _ProblemFunctionsSpec | None = None
+    jacobian: JacobianKernel | None = None
+    problem: ProblemSpec | None = None
+    delays: list[_DelayedStateSpec] | None = None
+    placeholders: dict[tuple[str, int, str, int, str, ReadKind], Expression] | None = None
+    events: list[tuple[KernelSpec, CrossingLaw]] | None = None
+    renewals: list[BoundRenewalSpec] | None = None
+    outputs: dict[int, list[OutputSpec]] | None = None
+    written: dict[tuple[str, int], list[tuple[Expression, Expression]]] | None = None
+    limits: list[float] | None = None
+    volume_limits: list[DiffusiveLimitSpec] | None = None
+    linear: list[LinearTermSpec] | None = None
+    volumes: tuple[FiniteVolumeKernel, ...] | None = None
+    symmetries: tuple[SymmetrySpec, ...] | None = None
+    constrained: tuple[npt.NDArray[np.intp], npt.NDArray[np.float64]] | None = None
+    encounters: tuple[EncounterKernel, ...] | None = None
+    transfer: TransferStateSpec | None = None
+    transfer_network: TransferNetworkSpec | None = None
+    rules: list[tuple[KernelSpec, tuple[RuleLaw, ...]]] | None = None
+    request_jumps: dict[int, tuple[KernelSpec, TopologyRequestSpec]] | None = None
+    topology: TopologyKernel | None = None
+    done: set[object] | None = None
+
+    def __init__(
+        self,
+        system: System,
+        backend: BaseBackend | None = None,
+        solver: object = None,
+        owners: frozenset[str] | None = None,
+        held: tuple[str, ...] = (),
+    ) -> None:
+        self.system = system
+        self.backend = backend
+        self.solver = solver
+        self.owners = owners
+        self.held = held
+
+    def _replace_specs(self, replaced: Mapping[int, KernelSpec]) -> None:
+        """Replace kernel specs by their copies in every field that holds them.
+
+        The fields keep their lists, so a pass that loops over a field reads the copies.
+
+        Args:
+            replaced:
+                The copy of every replaced spec, by the identity of the replaced spec.
+        """
+        if not replaced:
+            return
+        self._replace_in(self.specs or [], replaced)
+        self._replace_in(self.markov or [], replaced)
+        self._replace_in(self.events or [], replaced)
+        self._replace_in(self.rules or [], replaced)
+        for block_laws in (self.collected, self.lowered):
+            self._replace_in(block_laws or [], replaced)
+        laws = (
+            self.apart,
+            self.ordered,
+            self.delayed,
+            self.corrected,
+            self.shifted,
+            self.drawn,
+            self.drawn_apart,
+            self.reduced,
+            self.reduced_apart,
+        )
+        for items in laws:
+            self._replace_in(items or [], replaced)
+        if self.delays is not None:
+            self.delays[:] = [replace(delay, spec=replaced.get(id(delay.spec), delay.spec)) for delay in self.delays]
+        if self.renewals is not None:
+            self.renewals[:] = [
+                replace(renewal, spec=replaced.get(id(renewal.spec), renewal.spec)) for renewal in self.renewals
+            ]
+        if self.request_jumps is not None:
+            for key, (spec, request) in self.request_jumps.items():
+                self.request_jumps[key] = (replaced.get(id(spec), spec), request)
+        if self.transfer is not None:
+            self.transfer = self.transfer.replaced(replaced)
+
+    @staticmethod
+    def _replace_in[*Rest](items: list[tuple[KernelSpec, *Rest]], replaced: Mapping[int, KernelSpec]) -> None:
+        """Replace the kernel spec that leads every item of a field by its copy, in place.
+
+        Args:
+            items:
+                The items of the field, each led by a kernel spec.
+
+            replaced:
+                The copy of every replaced spec, by the identity of the replaced spec.
+        """
+        for index, item in enumerate(items):
+            spec = item[0]
+            items[index] = (replaced.get(id(spec), spec), *item[1:])
+
+    @staticmethod
+    def _required[T](value: T | None, name: str) -> T:
+        """Return the value of a field that a pass has set, raising an error for a field no pass has set yet.
+
+        Args:
+            value:
+                The value of the field.
+
+            name:
+                The name of the field.
+
+        Returns:
+            value:
+                The value, which is not `None`.
+
+        Raises:
+            PipelineError:
+                No pass has set the field yet.
+        """
+        if value is None:
+            error_msg = f'No pass has set the field {name!r} of the compilation yet. Run the pass that writes it first.'
+            raise PipelineError(error_msg)
+        return value

skcomplex/engine/compile/_compile.py

@@ -0,0 +1,100 @@
+"""Compile a system into a problem of one mathematical form with a compiler."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Mapping, Sequence
+
+from sklearn.base import clone
+
+from ...core.system import System
+from ...specs import ObservableSpec
+from ..backends import BaseBackend
+from ..problems import BaseProblemSpec
+from ._base import BaseCompiler
+from ._pass_compiler import PassCompiler
+
+
+def compile_system(
+    system: System,
+    backend: BaseBackend | None = None,
+    observables: Sequence[ObservableSpec] = (),
+    *,
+    solver: object = None,
+    initial_state: Mapping[str, object] | None = None,
+    compiler: BaseCompiler | None = None,
+) -> BaseProblemSpec:
+    """Compile a system into a problem of the form its law kinds determine.
+
+    The compiler validates the system in `prepare` and compiles it in `run`. `PassCompiler` compiles every system but
+    operator ones, which `OperatorCompiler` compiles, and a model package can bring the compiler of a form of its own.
+
+    Args:
+        system:
+            The system to compile.
+
+        backend:
+            The backend instance, or `None` for `NumbaBackend` on systems whose groups hold at least 1000 members in
+            total and `NumpyBackend` on the others.
+
+        observables:
+            The observables to compute at every frame, labelled by their path from the root, such as
+            `village/mean_wealth` for an observable of the nested system `village`.
+
+        solver:
+            The solver the problem runs on, or `None` for the default solver of its form, whose limits compiling
+            checks, such as the largest dimension of a Hilbert space.
+
+        initial_state:
+            Initial values that replace those of the components, by the dotted name of the state, such as
+            `{'rabbits.n': 20}`. The state of an operator system is `<system label>.state`, which takes a vector, a
+            density matrix, or `'ground'` for the lowest eigenstate of the generator at the initial parameters.
+
+        compiler:
+            The compiler, whose backend, solver, and observables this function sets, or `None` for `PassCompiler`.
+
+    Returns:
+        problem:
+            The compiled problem.
+
+    Raises:
+        ValidationError:
+            A child has the wrong type, a value is outside its domain or has the wrong shape, or a law is malformed.
+
+        LabelError:
+            A label is not valid, duplicated, or produces a symbol collision.
+
+        RoleError:
+            A role refers to an element that does not exist, or an interaction reads groups of different sizes member
+            by member.
+
+        SpaceError:
+            A vector variable has no enclosing space, or a space is not valid.
+
+        IncompatibleLawsError:
+            The system mixes law kinds that no form supports.
+
+        BackendError:
+            An agent group declares a complex state.
+
+        ValidationError:
+            Validation finds problems of more than one kind, all listed in the message.
+
+    Examples:
+        >>> from skcomplex.engine.compile import compile_system
+        >>> from skcomplex.core.system import System
+        >>> from skcomplex.models.biology.common.populations import ExponentialGrowthInteraction, PopulationElement
+        >>> problem = compile_system(
+        ...     System(
+        ...         elements=[PopulationElement('rabbits', n=10)],
+        ...         interactions=[ExponentialGrowthInteraction('growth', target='rabbits', r=0.5)],
+        ...     ),
+        ... )
+        >>> problem.form.name
+        'ODE'
+        >>> problem.equations
+        {'rabbits.n': n_rabbits*r_growth}
+    """
+    compiler = PassCompiler() if compiler is None else clone(compiler)
+    compiler.set_params(backend=backend, solver=solver, observables=observables)
+    return compiler.check().prepare(system).run(initial_state).problem_

skcomplex/engine/compile/_complex.py

@@ -0,0 +1,216 @@
+"""Split complex expressions and laws into real expressions of their real and imaginary parts."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Callable
+
+from sage.all__sagemath_symbolics import SR, Expression, I, arctan2, sqrt
+
+from ...errors import ValidationError
+from ..types import Parts
+from ._members import _SHIFT
+
+_LINEAR = frozenset({'laplacian', 'inverse_helmholtz', 'partial', 'upwind', 'derivative', 'lag', 'delayed'})
+_SUMS = frozenset({'total', 'mean'})
+_REAL_OPERANDS = frozenset(
+    {
+        'mod',
+        'either',
+        'both',
+        'maximum',
+        'minimum',
+        'variance',
+        'count',
+        'floor',
+        'ceil',
+        'sgn',
+        'sign',
+        'heaviside',
+        'unit_step',
+        'min_symbolic',
+        'max_symbolic',
+    },
+)
+_WHERE = 'where'
+_UNSPLIT = frozenset({'real_part', 'imag_part', 'conjugate', 'arg', 'abs'})
+_LEFTOVER = _UNSPLIT - {'abs'}
+_STAND_IN = '_split_part_'
+
+
+def _name_of(expression: Expression) -> str:
+    """Return the name of the function at the top of an expression, or an empty string."""
+    return str(getattr(expression.operator(), 'name', lambda: '')())
+
+
+def _names_in(expression: Expression) -> set[str]:
+    """Return the names of the functions applied anywhere in an expression."""
+    names, stack = set(), [expression]
+    while stack:
+        item = stack.pop()
+        if item.operator() is None:
+            continue
+        names.add(_name_of(item))
+        stack.extend(item.operands())
+    return names
+
+
+def _is_zero(expression: Expression) -> bool:
+    """Check whether a real expression is zero as written, without asking Maxima."""
+    return bool(SR(expression).is_trivial_zero())
+
+
+def _checked(part: Expression, expression: Expression, owner: str) -> Expression:
+    """Return a real or imaginary part with every modulus written out, after checking that no complex value is left."""
+    part = _modulus_form(part)
+    left = sorted(_names_in(part) & _LEFTOVER)
+    if not part.has(I) and not left:
+        return part
+    error_msg = (
+        f'The {owner} applies a function to a complex value in {expression} that the compiler cannot write with real '
+        'and imaginary parts. Use arithmetic, the elementary functions, real_part, imag_part, conjugate, abs, and '
+        'arg on complex values.'
+    )
+    raise ValidationError(error_msg)
+
+
+def _stand_in(part: Expression, stand_ins: dict[Expression, Expression]) -> Expression:
+    """Return a real symbol that stands for a real part while Sage splits the function applied to it."""
+    if part.operator() is None:
+        return part
+    item = SR.symbol(f'{_STAND_IN}{len(stand_ins)}')
+    item.decl_assume('real')
+    stand_ins[item] = part
+    return item
+
+
+def _real(parts: Parts, expression: Expression, owner: str) -> Expression:
+    """Return the real part of a value whose imaginary part must be zero, as an operand that only takes real values."""
+    real, imaginary = parts
+    if _is_zero(imaginary):
+        return real
+    error_msg = (
+        f'The {owner} gives the complex value {expression} where only real values have a meaning. Take its modulus '
+        '`abs(...)`, its real part `real_part(...)`, or its imaginary part `imag_part(...)` first.'
+    )
+    raise ValidationError(error_msg)
+
+
+def _split_relation(expression: Expression, owner: str) -> Expression:
+    """Return a relation of real operands, rejecting the order of complex values."""
+    sides = []
+    for side in (expression.lhs(), expression.rhs()):
+        real, imaginary = _split_complex(side, owner)
+        if not _is_zero(imaginary):
+            error_msg = (
+                f'The {owner} compares the complex value {side} in {expression}, and complex values have no order. '
+                'Compare its modulus `abs(...)` or its real part `real_part(...)`.'
+            )
+            raise ValidationError(error_msg)
+        sides.append(real)
+    return expression.operator()(*sides)
+
+
+def _split_part(name: str, operand: Expression, owner: str) -> Parts:
+    """Return the parts of the modulus, argument, real part, imaginary part, or conjugate of a value."""
+    real, imaginary = _split_complex(operand, owner)
+    if name == 'abs':
+        return (abs(real) if _is_zero(imaginary) else sqrt(real**2 + imaginary**2)), SR(0)
+    values = {
+        'real_part': (real, SR(0)),
+        'imag_part': (imaginary, SR(0)),
+        'conjugate': (real, -imaginary),
+        'arg': (arctan2(imaginary, real), SR(0)),
+    }
+    return values[name]
+
+
+def _split_where(function: Callable[..., Expression], operands: list[Expression], owner: str) -> Parts:
+    """Return the parts of a choice between two values, whose condition takes real values."""
+    condition = _real(_split_complex(operands[0], owner), operands[0], owner)
+    (real, imaginary), (other_real, other_imaginary) = (_split_complex(item, owner) for item in operands[1:])
+    return function(condition, real, other_real), function(condition, imaginary, other_imaginary)
+
+
+def _split_function(expression: Expression, owner: str) -> Parts | None:
+    """Return the parts of a call of a modulus, argument, part, linear operator, or reduction, or `None` otherwise."""
+    name, operands, function = _name_of(expression), list(expression.operands()), expression.operator()
+    if name in _UNSPLIT:
+        return _split_part(name, operands[0], owner)
+    if name in _LINEAR or name in _SUMS:
+        real, imaginary = _split_complex(operands[0], owner)
+        rest = [_real(_split_complex(item, owner), item, owner) for item in operands[1:]]
+        return function(real, *rest), function(imaginary, *rest)
+    if name == _SHIFT:
+        real, imaginary = _split_complex(operands[0], owner)
+        return function(real, *operands[1:]), function(imaginary, *operands[1:3], 0.0)
+    if name == _WHERE:
+        return _split_where(function, operands, owner)
+    if name in _REAL_OPERANDS:
+        return function(*(_real(_split_complex(item, owner), item, owner) for item in operands)), SR(0)
+    return None
+
+
+def _modulus_form(expression: Expression) -> Expression:
+    """Return an expression with every modulus of a complex value written with its real and imaginary parts.
+
+    Args:
+        expression:
+            The expression.
+
+    Returns:
+        expression:
+            The expression with `abs(a + I*b)` written as `sqrt(a^2 + b^2)`.
+    """
+    if expression.operator() is None or not expression.has(I):
+        return expression
+    operands = [_modulus_form(operand) for operand in expression.operands()]
+    if _name_of(expression) == 'abs':
+        return sqrt(operands[0].real_part() ** 2 + operands[0].imag_part() ** 2)
+    return expression.operator()(*operands)
+
+
+def _split_complex(expression: object, owner: str) -> Parts:
+    """Return the real and imaginary parts of an expression of real symbols as real expressions.
+
+    Sage writes the parts of arithmetic and of the elementary functions. The modulus, argument, parts, and conjugate,
+    the linear operators of fields and companions, sums and means over groups, and member offset reads are split
+    term by term, and relations and the other functions take real operands.
+
+    Args:
+        expression:
+            The expression, whose symbols are all real.
+
+        owner:
+            The law and the path of the component that holds the expression, used in error messages.
+
+    Returns:
+        parts:
+            The real part and the imaginary part.
+
+    Raises:
+        ValidationError:
+            The expression orders complex values, gives a complex value to a function that takes real values, or applies
+            a function whose parts Sage cannot write.
+    """
+    parsed: Expression = SR(expression)
+    if not parsed.has(I):
+        return parsed, SR(0)
+    if parsed.is_relational():
+        return _split_relation(parsed, owner), SR(0)
+    if parsed.operator() is None:
+        number = parsed.pyobject()
+        if isinstance(number, complex):
+            return SR(number.real), SR(number.imag)
+        return parsed.real_part(), parsed.imag_part()
+    parts = _split_function(parsed, owner)
+    if parts is not None:
+        return parts
+    stand_ins: dict[Expression, Expression] = {}
+    operands = [
+        _stand_in(real, stand_ins) + I * _stand_in(imaginary, stand_ins)
+        for real, imaginary in (_split_complex(item, owner) for item in parsed.operands())
+    ]
+    rebuilt = parsed.operator()(*operands)
+    real, imaginary = _checked(rebuilt.real_part(), parsed, owner), _checked(rebuilt.imag_part(), parsed, owner)
+    return real.subs(stand_ins), imaginary.subs(stand_ins)