scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/models/engineering/traffic/_traffic_moments.py

@@ -0,0 +1,57 @@
+"""Density `rho` and flow `w` of Langevin traffic on a road, the first two moments of its speeds."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from sage.all__sagemath_symbolics import oo
+from sage.sets.real_set import RealSet
+
+from ....core.elements import Element
+from ....core.laws import BaseLaw, RateLaw
+from ....core.laws.utils import divergence, laplacian
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+from ._langevin_driving import LangevinDrivingInteraction
+
+
+class TrafficMomentsElement(Element):
+    """Density `rho` and flow `w` of Langevin traffic on a road, the first two moments of its speeds."""
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        rho: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
+        w: Annotated[object, StateSpec()] = 0.25,
+        gamma: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
+        u0: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
+        rho_max: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
+        D1: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.2,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.rho = rho
+        self.w = w
+        self.gamma = gamma
+        self.u0 = u0
+        self.rho_max = rho_max
+        self.D1 = D1
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the closed moment equations of the density and the flow."""
+        return [
+            RateLaw(s.rho, -divergence([s.w]) + laplacian(s.D1 * s.rho**2 / 2)),
+            RateLaw(
+                s.w,
+                -divergence(
+                    [
+                        2 * LangevinDrivingInteraction._target_speed(s.rho, s) * s.w
+                        - s.rho * LangevinDrivingInteraction._target_speed(s.rho, s) ** 2,
+                    ],
+                )
+                - s.gamma * (s.w - s.rho * LangevinDrivingInteraction._target_speed(s.rho, s))
+                + s.D1 * (laplacian(s.rho * s.w) + s.rho * laplacian(s.w) - s.w * laplacian(s.rho)) / 2,
+            ),
+        ]

skcomplex/models/mathematics/__init__.py

@@ -0,0 +1 @@
+"""Mathematics: dynamical systems, fractals, fractional dynamics, stochastic processes, and networks."""

skcomplex/models/mathematics/common/__init__.py

@@ -0,0 +1,3 @@
+"""Realizations shared by several mathematics packages, by family: flows, maps, and walks."""
+
+__all__: list[str] = []

skcomplex/models/mathematics/common/flows/__init__.py

@@ -0,0 +1,7 @@
+"""Flows shared by the mathematics packages: the Lorenz flow."""
+
+from ._lorenz import LorenzElement
+
+__all__: list[str] = [
+    'LorenzElement',
+]

skcomplex/models/mathematics/common/flows/_lorenz.py

@@ -0,0 +1,90 @@
+"""Define the Lorenz flow, the three-mode truncation of Rayleigh-Bénard convection."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from .....core.elements import Element
+from .....core.laws import BaseLaw, RateLaw
+from .....specs import ParameterSpec, StateSpec, VisualSpec
+
+
+class LorenzElement(Element):
+    """Lorenz flow `x' = sigma (y - x)`, `y' = x (rho - z) - y`, `z' = x y - beta z`.
+
+    A subclass that declares the states with a fractional `StateSpec(order=q)` gives the fractional Lorenz flow with
+    Caputo derivatives of order `q`.
+
+    Args:
+        label:
+            The label of the element.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        x:
+            The initial convection intensity.
+
+        y:
+            The initial temperature difference between rising and falling currents.
+
+        z:
+            The initial deviation of the vertical temperature profile.
+
+        sigma:
+            The Prandtl number.
+
+        rho:
+            The Rayleigh number relative to its critical value.
+
+        beta:
+            The geometric factor.
+
+    Examples:
+        >>> from skcomplex.core.system import System
+        >>> from skcomplex.engine.runtime import Simulation
+        >>> from skcomplex.models.mathematics.common.flows import LorenzElement
+        >>> system = System(elements=[LorenzElement('lorenz', x=0.0, y=0.0, z=2.0, beta=0.5)])
+        >>> trajectory = Simulation(system, dt=0.5).check().prepare().run(until=1.0).trajectory_
+        >>> [round(float(value), 4) for value in trajectory.values('lorenz.z')]
+        [2.0, 1.5576, 1.2131]
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        x: Annotated[float, StateSpec()] = 1.0,
+        y: Annotated[float, StateSpec()] = 1.0,
+        z: Annotated[float, StateSpec()] = 1.0,
+        sigma: Annotated[float, ParameterSpec()] = 10.0,
+        rho: Annotated[float, ParameterSpec()] = 28.0,
+        beta: Annotated[float, ParameterSpec()] = 8 / 3,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.x = x
+        self.y = y
+        self.z = z
+        self.sigma = sigma
+        self.rho = rho
+        self.beta = beta
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the rates of the three modes.
+
+        Args:
+            s:
+                The namespace of the symbols the laws can use.
+
+        Returns:
+            laws:
+                The rates of `x`, `y`, and `z`.
+        """
+        return [
+            RateLaw(s.x, s.sigma * (s.y - s.x)),
+            RateLaw(s.y, s.x * (s.rho - s.z) - s.y),
+            RateLaw(s.z, s.x * s.y - s.beta * s.z),
+        ]

skcomplex/models/mathematics/dynamical_systems/__init__.py

@@ -0,0 +1,90 @@
+"""Dynamical systems: chaotic and driven flows, maps, Koopman embeddings, and normal forms of bifurcations."""
+
+from ._baker_map import BakerMapElement
+from ._blow_up import BlowUpElement
+from ._cat_map import CatMapElement
+from ._chaotic_ensembles import cubic_chaotic_map, doubling_map, skew_tent_map
+from ._circle_map import CircleMapElement
+from ._cubic_walk import CubicWalkElement
+from ._cusp import CuspElement
+from ._doubling_map import DoublingMapElement
+from ._driven_flows import DrivenRosslerElement, ou_driven_rossler
+from ._flows import finite_time_blow_up, lorenz, rossler, sprott_jerk
+from ._henon_map import HenonMapElement
+from ._hopf import HopfElement
+from ._intermittency_map import IntermittencyMapElement
+from ._jerk import JerkElement
+from ._koopman import SlowManifoldElement, koopman_slow_manifold
+from ._logistic_map import LogisticMapElement
+from ._maps import (
+    baker_map,
+    cat_map,
+    circle_map,
+    henon_map,
+    intermittency_map,
+    logistic_map,
+    newton_raphson_map,
+    standard_map,
+    tent_map,
+    towel_map,
+)
+from ._newton_map import NewtonMapElement
+from ._normal_forms import cusp_form, hopf_form, saddle_node_form, takens_bogdanov_form
+from ._rossler import RosslerElement
+from ._saddle_node import SaddleNodeElement
+from ._skew_tent_map import SkewTentMapElement
+from ._standard_map import StandardMapElement
+from ._subcritical_forms import SubcriticalHopfElement, subcritical_hopf_form
+from ._takens_bogdanov import TakensBogdanovElement
+from ._tent_map import TentMapElement
+from ._towel_map import TowelMapElement
+
+__all__: list[str] = [
+    'BakerMapElement',
+    'BlowUpElement',
+    'CatMapElement',
+    'CircleMapElement',
+    'CubicWalkElement',
+    'CuspElement',
+    'DoublingMapElement',
+    'DrivenRosslerElement',
+    'HenonMapElement',
+    'HopfElement',
+    'IntermittencyMapElement',
+    'JerkElement',
+    'LogisticMapElement',
+    'NewtonMapElement',
+    'RosslerElement',
+    'SaddleNodeElement',
+    'SkewTentMapElement',
+    'SlowManifoldElement',
+    'StandardMapElement',
+    'SubcriticalHopfElement',
+    'TakensBogdanovElement',
+    'TentMapElement',
+    'TowelMapElement',
+    'baker_map',
+    'cat_map',
+    'circle_map',
+    'cubic_chaotic_map',
+    'cusp_form',
+    'doubling_map',
+    'finite_time_blow_up',
+    'henon_map',
+    'hopf_form',
+    'intermittency_map',
+    'koopman_slow_manifold',
+    'logistic_map',
+    'lorenz',
+    'newton_raphson_map',
+    'ou_driven_rossler',
+    'rossler',
+    'saddle_node_form',
+    'skew_tent_map',
+    'sprott_jerk',
+    'standard_map',
+    'subcritical_hopf_form',
+    'takens_bogdanov_form',
+    'tent_map',
+    'towel_map',
+]

skcomplex/models/mathematics/dynamical_systems/_baker_map.py

@@ -0,0 +1,59 @@
+"""Coordinates and parameters of the generalized baker map, which stretches the unit square and stacks it."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from ....core.elements import Element
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+
+
+class BakerMapElement(Element):
+    """Coordinates and parameters of the generalized baker map, which stretches the unit square and stacks it.
+
+    Args:
+        label:
+            The label of the element.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        x:
+            The initial stretched coordinate.
+
+        y:
+            The initial squeezed coordinate.
+
+        alpha:
+            The position of the cut.
+
+        lambda_a:
+            The height of the bottom band.
+
+        lambda_b:
+            The height of the top band.
+
+    Examples:
+        >>> from skcomplex.models.mathematics.dynamical_systems import BakerMapElement
+        >>> BakerMapElement('map', alpha=0.4).alpha
+        0.4
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        x: Annotated[object, StateSpec()] = 0.2,
+        y: Annotated[object, StateSpec()] = 0.3,
+        alpha: Annotated[object, ParameterSpec()] = 1 / 3,
+        lambda_a: Annotated[object, ParameterSpec()] = 1 / 3,
+        lambda_b: Annotated[object, ParameterSpec()] = 2 / 3,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.x = x
+        self.y = y
+        self.alpha = alpha
+        self.lambda_a = lambda_a
+        self.lambda_b = lambda_b

skcomplex/models/mathematics/dynamical_systems/_blow_up.py

@@ -0,0 +1,64 @@
+"""Hyperbolic growth `x' = a x^p`, which diverges in finite time for `p > 1`."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+from typing import Annotated
+
+from ....core.elements import Element
+from ....core.laws import BaseLaw, RateLaw
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+
+
+class BlowUpElement(Element):
+    """Hyperbolic growth `x' = a x^p`, which diverges in finite time for `p > 1`.
+
+    Args:
+        label:
+            The label of the element.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        x:
+            The initial value.
+
+        a:
+            The growth coefficient.
+
+        p:
+            The growth exponent.
+
+    Examples:
+        >>> from skcomplex.models.mathematics.dynamical_systems import BlowUpElement
+        >>> BlowUpElement('growth', p=3.0).p
+        3.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        x: Annotated[object, StateSpec()] = 1.0,
+        a: Annotated[object, ParameterSpec()] = 1.0,
+        p: Annotated[object, ParameterSpec()] = 2.0,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.x = x
+        self.a = a
+        self.p = p
+
+    def _get_laws(self, s: SimpleNamespace) -> list[BaseLaw]:
+        """Return the rate of the value.
+
+        Args:
+            s:
+                The namespace of the symbols the laws can use.
+
+        Returns:
+            laws:
+                The laws of the element.
+        """
+        return [RateLaw(s.x, s.a * s.x**s.p)]

skcomplex/models/mathematics/dynamical_systems/_cat_map.py

@@ -0,0 +1,44 @@
+"""Coordinates of Arnold's cat map `(x, y) -> (2 x + y, x + y) (mod 1)` of the unit torus, which maps iterate."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from ....core.elements import Element
+from ....specs import StateSpec, VisualSpec
+
+
+class CatMapElement(Element):
+    """Coordinates of Arnold's cat map `(x, y) -> (2 x + y, x + y) (mod 1)` of the unit torus, which maps iterate.
+
+    Args:
+        label:
+            The label of the element.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        x:
+            The initial first coordinate, between 0 and 1.
+
+        y:
+            The initial second coordinate, between 0 and 1.
+
+    Examples:
+        >>> from skcomplex.models.mathematics.dynamical_systems import CatMapElement
+        >>> CatMapElement('map', x=0.5).x
+        0.5
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        x: Annotated[object, StateSpec()] = 0.1,
+        y: Annotated[object, StateSpec()] = 0.3,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.x = x
+        self.y = y

skcomplex/models/mathematics/dynamical_systems/_chaotic_ensembles.py

@@ -0,0 +1,186 @@
+"""Dynamical systems models: ensembles of chaotic maps, their invariant densities, and chaotic walks."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from types import SimpleNamespace
+
+import numpy as np
+from sage.all__sagemath_symbolics import Expression
+
+from ....core.elements import GroupElement
+from ....core.system import System
+from ....specs import ObservableSpec
+from ..._catalog import register_model
+from ._cubic_walk import CubicWalkElement
+from ._doubling_map import DOUBLING_DENOMINATOR, DoublingMapElement
+from ._skew_tent_map import SkewTentMapElement
+
+
+def _square_displacement(member: SimpleNamespace) -> Expression:
+    """Return the squared position of a walker."""
+    return member.y**2
+
+
+def _draw_cloud(
+    size: int,
+    start: float,
+    spread: float,
+    random_state: int | np.random.Generator | None,
+) -> np.ndarray:
+    """Return points drawn uniformly from the interval `[start, start + spread]`."""
+    return np.random.default_rng(random_state).uniform(start, start + spread, size)
+
+
+@register_model(
+    field='mathematics/dynamical_systems',
+    tags=('chaos', 'discrete map', 'random walk', 'diffusion'),
+    references=('Bertin 2021',),
+    defaults={'until': 200, 'dt': 1},
+    observables=lambda system: [
+        ObservableSpec('displacement', group='walkers', variable='y'),
+        ObservableSpec('square_displacement', _square_displacement, group='walkers'),
+    ],
+)
+def cubic_chaotic_map(n_walkers: int = 100, *, lam: float = 15.0) -> System:
+    """Return Bertin's cubic chaotic map and the chaotic walk it drives, which spreads like a random walk.
+
+    Every walker follows the map `x' = λ x (x - 1/2)(x - 1) + x` on the unit interval and moves by the step
+    `y' = y + 2x - 1`. The fixed point `x = 1/2` is stable for `λ < 8`, a period-two cycle follows, and the map is
+    chaotic at `λ = 15`. The walkers start at `y = 0` with values of `x` spread regularly over the unit interval, so
+    the mean position stays near 0 while the mean square position grows linearly in time, and the invariant density of
+    `x` is not uniform.
+
+    Args:
+        n_walkers:
+            The number of walkers of the ensemble.
+
+        lam:
+            The parameter `λ` of the map, between 0 and 16.
+
+    Returns:
+        system:
+            The model, with the states `walkers.x` and `walkers.y` and the observables `displacement`, the mean
+            position, and `square_displacement`, the mean square position.
+
+    Examples:
+        >>> from skcomplex.models.mathematics.dynamical_systems import cubic_chaotic_map
+        >>> cubic_chaotic_map(4, lam=10.0).elements[0].check().prepare().size_
+        4
+    """
+    start = (np.arange(n_walkers) + 1 / 4) / n_walkers
+    walkers = GroupElement(
+        'walkers',
+        element=CubicWalkElement,
+        size=n_walkers,
+        values={'x': start, 'y': 0.0, 'lam': lam},
+    )
+    return System(
+        elements=[walkers],
+    )
+
+
+@register_model(
+    field='mathematics/dynamical_systems',
+    tags=('chaos', 'discrete map', 'piecewise linear', 'invariant density'),
+    references=('Bertin 2021',),
+    defaults={'until': 50, 'dt': 1},
+)
+def skew_tent_map(
+    n_points: int = 100,
+    *,
+    a: float = 0.3,
+    x: float = 0.4,
+    spread: float = 0.01,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return an ensemble of the skew tent map, whose density relaxes to the uniform invariant density for any `a`.
+
+    The map is `x' = x / a` for `x < a` and `x' = (1 - x) / (1 - a)` otherwise. Every value has one preimage on each
+    branch, with slopes `1 / a` and `1 / (1 - a)`, so the uniform density is invariant. The points start in a narrow
+    interval and spread over the unit interval until their histogram is flat. For `a = 1/2` both slopes are 2, and in
+    floating point every orbit reaches 0 within about 55 steps, so `a` should differ from 1/2.
+
+    Args:
+        n_points:
+            The number of points of the ensemble.
+
+        a:
+            The position of the top of the tent, between 0 and 1.
+
+        x:
+            The left end of the interval of initial points.
+
+        spread:
+            The width of the interval of initial points.
+
+        random_state:
+            The seed or generator of the initial points.
+
+    Returns:
+        system:
+            The model, with the states `points.x`.
+
+    Examples:
+        >>> from skcomplex.models.mathematics.dynamical_systems import skew_tent_map
+        >>> skew_tent_map(10, a=0.7).elements[0].values['a']
+        0.7
+    """
+    start = _draw_cloud(n_points, x, spread, random_state)
+    return System(
+        elements=[GroupElement('points', element=SkewTentMapElement, size=n_points, values={'x': start, 'a': a})],
+    )
+
+
+@register_model(
+    field='mathematics/dynamical_systems',
+    tags=('chaos', 'discrete map', 'bernoulli shift', 'invariant density'),
+    references=('Bertin 2021',),
+    defaults={'until': 50, 'dt': 1},
+)
+def doubling_map(
+    n_points: int = 100,
+    *,
+    x: float = 0.4,
+    spread: float = 0.01,
+    q: float = DOUBLING_DENOMINATOR,
+    random_state: int | np.random.Generator | None = 0,
+) -> System:
+    """Return an ensemble of the doubling map `x' = 2x (mod 1)`, iterated exactly on fractions with an odd denominator.
+
+    In floating point `2x (mod 1)` shifts out one binary digit per step, and every orbit reaches 0 within 53 steps.
+    The model keeps every point on the fractions `k / q` of an odd denominator `q` and applies the map to them exactly,
+    `k' = 2k (mod q)`, through the update `x' = (2 round(q x) mod q) / q`. The orbits are the exact orbits of these
+    fractions. The default `q` is a prime below `2^50` of which 2 is a primitive root, so every orbit except that of 0
+    has the period `q - 1`, about `10^15`. The points start in a narrow interval and spread until their histogram
+    matches the uniform invariant density.
+
+    Args:
+        n_points:
+            The number of points of the ensemble.
+
+        x:
+            The left end of the interval of initial points, which are rounded to the nearest fraction `k / q`.
+
+        spread:
+            The width of the interval of initial points.
+
+        q:
+            The odd denominator of the fractions the points stay on, an integer below `2^51`.
+
+        random_state:
+            The seed or generator of the initial points.
+
+    Returns:
+        system:
+            The model, with the states `points.x`.
+
+    Examples:
+        >>> from skcomplex.models.mathematics.dynamical_systems import doubling_map
+        >>> float(doubling_map(10, q=101.0).elements[0].values['x'][0] * 101)
+        41.0
+    """
+    start = np.floor(q * _draw_cloud(n_points, x, spread, random_state) + 1 / 2) / q
+    return System(
+        elements=[GroupElement('points', element=DoublingMapElement, size=n_points, values={'x': start, 'q': q})],
+    )

skcomplex/models/mathematics/dynamical_systems/_circle_map.py

@@ -0,0 +1,49 @@
+"""Angle and parameters of the sine circle map `theta' = theta + Omega - K / (2 pi) sin(2 pi theta) (mod 1)`."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from typing import Annotated
+
+from ....core.elements import Element
+from ....specs import ParameterSpec, StateSpec, VisualSpec
+
+
+class CircleMapElement(Element):
+    """Angle and parameters of the sine circle map `theta' = theta + Omega - K / (2 pi) sin(2 pi theta) (mod 1)`.
+
+    Args:
+        label:
+            The label of the element.
+
+        visual:
+            How the element is drawn, or `None` for `default_visual_`.
+
+        theta:
+            The initial angle, as a fraction of a turn.
+
+        Omega:
+            The bare rotation per step.
+
+        K:
+            The nonlinearity.
+
+    Examples:
+        >>> from skcomplex.models.mathematics.dynamical_systems import CircleMapElement
+        >>> CircleMapElement('map', K=1.0).K
+        1.0
+    """
+
+    def __init__(
+        self,
+        label: str,
+        visual: VisualSpec | None = None,
+        *,
+        theta: Annotated[object, StateSpec()] = 0.0,
+        Omega: Annotated[object, ParameterSpec()] = 0.25,
+        K: Annotated[object, ParameterSpec()] = 0.9,
+    ) -> None:
+        super().__init__(label, visual=visual)
+        self.theta = theta
+        self.Omega = Omega
+        self.K = K