Dynamical systems

Dynamical systems: chaotic and driven flows, maps, Koopman embeddings, and normal forms of bifurcations.

BakerMapElement(label, visual=None, *, x=0.2, y=0.3, alpha=1 / 3, lambda_a=1 / 3, lambda_b=2 / 3)

Bases: Element

Coordinates and parameters of the generalized baker map, which stretches the unit square and stacks it.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial stretched coordinate.	0.2
y	Annotated[object, StateSpec()]	The initial squeezed coordinate.	0.3
alpha	Annotated[object, ParameterSpec()]	The position of the cut.	1 / 3
lambda_a	Annotated[object, ParameterSpec()]	The height of the bottom band.	1 / 3
lambda_b	Annotated[object, ParameterSpec()]	The height of the top band.	2 / 3

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import BakerMapElement
>>> BakerMapElement('map', alpha=0.4).alpha
0.4

Source code in src/skcomplex/models/mathematics/dynamical_systems/_baker_map.py

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

BlowUpElement(label, visual=None, *, x=1.0, a=1.0, p=2.0)

Bases: Element

Hyperbolic growth x' = a x^p, which diverges in finite time for p > 1.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial value.	1.0
a	Annotated[object, ParameterSpec()]	The growth coefficient.	1.0
p	Annotated[object, ParameterSpec()]	The growth exponent.	2.0

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import BlowUpElement
>>> BlowUpElement('growth', p=3.0).p
3.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_blow_up.py

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

CatMapElement(label, visual=None, *, x=0.1, y=0.3)

Bases: Element

Coordinates of Arnold's cat map (x, y) -> (2 x + y, x + y) (mod 1) of the unit torus, which maps iterate.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial first coordinate, between 0 and 1.	0.1
y	Annotated[object, StateSpec()]	The initial second coordinate, between 0 and 1.	0.3

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import CatMapElement
>>> CatMapElement('map', x=0.5).x
0.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_cat_map.py

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

CircleMapElement(label, visual=None, *, theta=0.0, Omega=0.25, K=0.9)

Bases: Element

Angle and parameters of the sine circle map theta' = theta + Omega - K / (2 pi) sin(2 pi theta) (mod 1).

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
theta	Annotated[object, StateSpec()]	The initial angle, as a fraction of a turn.	0.0
Omega	Annotated[object, ParameterSpec()]	The bare rotation per step.	0.25
K	Annotated[object, ParameterSpec()]	The nonlinearity.	0.9

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import CircleMapElement
>>> CircleMapElement('map', K=1.0).K
1.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_circle_map.py

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

CubicWalkElement(label, visual=None, *, x=0.3, y=0.0, lam=15.0)

Bases: Element

Walker driven by Bertin's cubic chaotic map x' = lam x (x - 1/2)(x - 1) + x, which steps by 2 x - 1.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial value of the map, between 0 and 1.	0.3
y	Annotated[object, StateSpec(role=position)]	The initial position of the walker.	0.0
lam	Annotated[object, ParameterSpec(domain=open(0, oo))]	The nonlinearity of the map.	15.0

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import CubicWalkElement
>>> CubicWalkElement('walker', lam=8.0).lam
8.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_cubic_walk.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.3,
    y: Annotated[object, StateSpec(role='position')] = 0.0,
    lam: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 15.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.y = y
    self.lam = lam

CuspElement(label, visual=None, *, x=0.5, beta1=0.0, beta2=1.0)

Bases: Element

Normal form x' = beta1 + beta2 x - x^3 of the cusp bifurcation.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial value.	0.5
beta1	Annotated[object, ParameterSpec()]	The first unfolding parameter, the asymmetry.	0.0
beta2	Annotated[object, ParameterSpec()]	The second unfolding parameter, the splitting.	1.0

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import CuspElement
>>> CuspElement('form', beta2=2.0).beta2
2.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_cusp.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.5,
    beta1: Annotated[object, ParameterSpec()] = 0.0,
    beta2: Annotated[object, ParameterSpec()] = 1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.beta1 = beta1
    self.beta2 = beta2

DoublingMapElement(label, visual=None, *, x=0.4, q=DOUBLING_DENOMINATOR)

Bases: Element

Doubling map x' = 2 x (mod 1) on the grid of the fractions of denominator q.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial value, between 0 and 1.	0.4
q	Annotated[object, ParameterSpec(domain=open(0, oo))]	The denominator of the grid.	DOUBLING_DENOMINATOR

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import DoublingMapElement
>>> DoublingMapElement('point', q=1024.0).q
1024.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_doubling_map.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.4,
    q: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = DOUBLING_DENOMINATOR,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.q = q

DrivenRosslerElement(label, visual=None, *, x=1.0, y=1.0, z=1.0, eta=0.0, a=0.2, b=0.4, c=5.743, tau=50.0, rho=0.5)

Bases: RosslerElement

Rössler flow with a control eta, the state that the drive adds to the rate of y and that relaxes to 0.

The element holds the flow and the states and parameters of its control. The interactions of the model add the control to the rate of y and make it an Ornstein-Uhlenbeck process of correlation time tau and noise rho.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	float	The initial first coordinate.	1.0
y	float	The initial second coordinate.	1.0
z	float	The initial third coordinate.	1.0
eta	Annotated[float, StateSpec()]	The initial control.	0.0
a	float	The feedback of the second coordinate on itself.	0.2
b	float	The constant drive of the third coordinate.	0.4
c	float	The threshold of the third coordinate's growth.	5.743
tau	Annotated[float, ParameterSpec(domain=open(0, oo))]	The correlation time of the control.	50.0
rho	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The amplitude of the noise of the control.	0.5

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import DrivenRosslerElement
>>> DrivenRosslerElement('rossler', tau=10.0).tau
10.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_driven_flows.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: float = 1.0,
    y: float = 1.0,
    z: float = 1.0,
    eta: Annotated[float, StateSpec()] = 0.0,
    a: float = 0.2,
    b: float = 0.4,
    c: float = 5.743,
    tau: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 50.0,
    rho: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
) -> None:
    super().__init__(label, visual=visual, x=x, y=y, z=z, a=a, b=b, c=c)
    self.eta = eta
    self.tau = tau
    self.rho = rho

HenonMapElement(label, visual=None, *, x=0.0, y=0.0, a=1.4, b=0.3)

Bases: Element

Coordinates and parameters of the Hénon map x' = 1 - a x^2 + y, y' = b x, which maps iterate.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial first coordinate.	0.0
y	Annotated[object, StateSpec()]	The initial second coordinate.	0.0
a	Annotated[object, ParameterSpec()]	The nonlinearity.	1.4
b	Annotated[object, ParameterSpec()]	The contraction.	0.3

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import HenonMapElement
>>> HenonMapElement('map', a=1.2).a
1.2

Source code in src/skcomplex/models/mathematics/dynamical_systems/_henon_map.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.0,
    y: Annotated[object, StateSpec()] = 0.0,
    a: Annotated[object, ParameterSpec()] = 1.4,
    b: Annotated[object, ParameterSpec()] = 0.3,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.y = y
    self.a = a
    self.b = b

HopfElement(label, visual=None, *, x=0.1, y=0.0, mu=0.25, omega=1.0, a=-1.0)

Bases: Element

Normal form of the Hopf bifurcation in Cartesian coordinates, with the radial law r' = mu r + a r^3.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial real part.	0.1
y	Annotated[object, StateSpec()]	The initial imaginary part.	0.0
mu	Annotated[object, ParameterSpec()]	The bifurcation parameter.	0.25
omega	Annotated[object, ParameterSpec()]	The angular frequency.	1.0
a	Annotated[object, ParameterSpec()]	The cubic coefficient, negative for the supercritical bifurcation.	-1.0

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import HopfElement
>>> HopfElement('form', mu=0.5).mu
0.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_hopf.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.1,
    y: Annotated[object, StateSpec()] = 0.0,
    mu: Annotated[object, ParameterSpec()] = 0.25,
    omega: Annotated[object, ParameterSpec()] = 1.0,
    a: Annotated[object, ParameterSpec()] = -1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.y = y
    self.mu = mu
    self.omega = omega
    self.a = a

IntermittencyMapElement(label, visual=None, *, x=0.01, z=2.0)

Bases: Element

Value and exponent of the Pomeau-Manneville map x' = x + x^z (mod 1), which a MapInteraction iterates.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial value, between 0 and 1.	0.01
z	Annotated[object, ParameterSpec()]	The exponent of the tangency at 0, above 1.	2.0

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import IntermittencyMapElement
>>> IntermittencyMapElement('map', z=1.5).z
1.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_intermittency_map.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.01,
    z: Annotated[object, ParameterSpec()] = 2.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.z = z

JerkElement(label, visual=None, *, x=0.0, x_d2=1.0, x_d1=0.0, A=0.6)

Bases: Element

Sprott's jerk flow x''' = -A x'' - x' + |x| - 1 of a state of order 3.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec(order=3, initial=(0.0, 1.0))]	The initial position.	0.0
x_d2	float	The initial second derivative.	1.0
x_d1	float	The initial first derivative.	0.0
A	Annotated[object, ParameterSpec()]	The damping of the second derivative.	0.6

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import JerkElement
>>> JerkElement('jerk', A=0.5).A
0.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_jerk.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec(order=3, initial=(0.0, 1.0))] = 0.0,
    x_d2: float = 1.0,
    x_d1: float = 0.0,
    A: Annotated[object, ParameterSpec()] = 0.6,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.x_d2 = x_d2
    self.x_d1 = x_d1
    self.A = A

LogisticMapElement(label, visual=None, *, x=0.2, r=3.7)

Bases: Element

Value and growth rate of the logistic map x -> r x (1 - x), which a MapInteraction iterates.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial value, between 0 and 1.	0.2
r	Annotated[object, ParameterSpec()]	The growth rate, between 0 and 4.	3.7

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import LogisticMapElement
>>> LogisticMapElement('map', r=3.2).r
3.2

Source code in src/skcomplex/models/mathematics/dynamical_systems/_logistic_map.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.2,
    r: Annotated[object, ParameterSpec()] = 3.7,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.r = r

NewtonMapElement(label, visual=None, *, x=0.5, y=0.5)

Bases: Element

Real and imaginary parts of Newton's method for z^3 = 1, z' = (2 z^3 + 1) / (3 z^2), which maps iterate.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial real part.	0.5
y	Annotated[object, StateSpec()]	The initial imaginary part.	0.5

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import NewtonMapElement
>>> NewtonMapElement('map', x=1.5).x
1.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_newton_map.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.5,
    y: Annotated[object, StateSpec()] = 0.5,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.y = y

RosslerElement(label, visual=None, *, x=1.0, y=1.0, z=1.0, a=0.2, b=0.2, c=5.7)

Bases: Element

Rössler flow x' = -y - z, y' = x + a y, z' = b + z (x - c).

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial first coordinate.	1.0
y	Annotated[object, StateSpec()]	The initial second coordinate.	1.0
z	Annotated[object, StateSpec()]	The initial third coordinate.	1.0
a	Annotated[object, ParameterSpec()]	The feedback of the second coordinate on itself.	0.2
b	Annotated[object, ParameterSpec()]	The constant drive of the third coordinate.	0.2
c	Annotated[object, ParameterSpec()]	The threshold of the third coordinate's growth.	5.7

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import RosslerElement
>>> RosslerElement('rossler', c=4.0).c
4.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_rossler.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 1.0,
    y: Annotated[object, StateSpec()] = 1.0,
    z: Annotated[object, StateSpec()] = 1.0,
    a: Annotated[object, ParameterSpec()] = 0.2,
    b: Annotated[object, ParameterSpec()] = 0.2,
    c: Annotated[object, ParameterSpec()] = 5.7,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.y = y
    self.z = z
    self.a = a
    self.b = b
    self.c = c

SaddleNodeElement(label, visual=None, *, x=0.0, mu=1.0)

Bases: Element

Normal form x' = mu - x^2 of the saddle-node bifurcation.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial value.	0.0
mu	Annotated[object, ParameterSpec()]	The bifurcation parameter.	1.0

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import SaddleNodeElement
>>> SaddleNodeElement('form', mu=-1.0).mu
-1.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_saddle_node.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.0,
    mu: Annotated[object, ParameterSpec()] = 1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.mu = mu

SkewTentMapElement(label, visual=None, *, x=0.4, a=0.3)

Bases: Element

Skew tent map x' = x / a below the peak a and (1 - x) / (1 - a) above it.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial value, between 0 and 1.	0.4
a	Annotated[object, ParameterSpec(domain=open(0, oo))]	The position of the peak, between 0 and 1.	0.3

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import SkewTentMapElement
>>> SkewTentMapElement('point', a=0.5).a
0.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_skew_tent_map.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.4,
    a: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 0.3,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.a = a

SlowManifoldElement(label, visual=None, *, x1=1.0, x2=1.0, mu=-0.05, lam=-1.0)

Bases: Element

Quadratic flow x1' = mu x1, x2' = lam (x2 - x1^2) with the slow manifold x2 = x1^2.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x1	Annotated[object, StateSpec()]	The initial slow coordinate.	1.0
x2	Annotated[object, StateSpec()]	The initial fast coordinate.	1.0
mu	Annotated[object, ParameterSpec()]	The slow eigenvalue.	-0.05
lam	Annotated[object, ParameterSpec()]	The fast eigenvalue.	-1.0

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import SlowManifoldElement
>>> SlowManifoldElement('flow', lam=-2.0).lam
-2.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_koopman.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x1: Annotated[object, StateSpec()] = 1.0,
    x2: Annotated[object, StateSpec()] = 1.0,
    mu: Annotated[object, ParameterSpec()] = -0.05,
    lam: Annotated[object, ParameterSpec()] = -1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x1 = x1
    self.x2 = x2
    self.mu = mu
    self.lam = lam

StandardMapElement(label, visual=None, *, theta=0.0, p=2 * math.pi * GOLDEN_MEAN, K=1.2)

Bases: Element

Angle, momentum, and kick of the standard map p' = p + K sin(theta), theta' = theta + p' (mod 2 pi).

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
theta	Annotated[object, StateSpec()]	The initial angle.	0.0
p	Annotated[object, StateSpec()]	The initial momentum.	2 * pi * GOLDEN_MEAN
K	Annotated[object, ParameterSpec()]	The kick strength.	1.2

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import StandardMapElement
>>> StandardMapElement('map', K=0.5).K
0.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_standard_map.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    theta: Annotated[object, StateSpec()] = 0.0,
    p: Annotated[object, StateSpec()] = 2 * math.pi * GOLDEN_MEAN,
    K: Annotated[object, ParameterSpec()] = 1.2,
) -> None:
    super().__init__(label, visual=visual)
    self.theta = theta
    self.p = p
    self.K = K

SubcriticalHopfElement(label, visual=None, *, x=0.1, y=0.0, alpha=-0.1, omega=1.0, q=0.0, gamma=1.0, s=0.0)

Bases: Element

Subcritical Hopf normal form z' = (alpha + i omega) z + (1 + i q) |z|^2 z - (gamma + i s) |z|^4 z.

The complex amplitude is z = x + i y.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial real part of z.	0.1
y	Annotated[object, StateSpec()]	The initial imaginary part of z.	0.0
alpha	Annotated[object, ParameterSpec()]	The bifurcation parameter, the linear growth rate.	-0.1
omega	Annotated[object, ParameterSpec()]	The angular frequency at small amplitude.	1.0
q	Annotated[object, ParameterSpec()]	The nonlinear frequency shift of the cubic term.	0.0
gamma	Annotated[object, ParameterSpec(domain=open(0, oo))]	The stabilizing quintic coefficient, positive.	1.0
s	Annotated[object, ParameterSpec()]	The nonlinear frequency shift of the quintic term.	0.0

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import SubcriticalHopfElement
>>> SubcriticalHopfElement('form', alpha=0.1).alpha
0.1

Source code in src/skcomplex/models/mathematics/dynamical_systems/_subcritical_forms.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.1,
    y: Annotated[object, StateSpec()] = 0.0,
    alpha: Annotated[object, ParameterSpec()] = -0.1,
    omega: Annotated[object, ParameterSpec()] = 1.0,
    q: Annotated[object, ParameterSpec()] = 0.0,
    gamma: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    s: Annotated[object, ParameterSpec()] = 0.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.y = y
    self.alpha = alpha
    self.omega = omega
    self.q = q
    self.gamma = gamma
    self.s = s

TakensBogdanovElement(label, visual=None, *, x=0.2, y=0.0, beta1=0.1, beta2=-1.0, sign=-1.0)

Bases: Element

Normal form x' = y, y' = beta1 + beta2 x + x^2 + sign x y of the Takens-Bogdanov bifurcation.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial first coordinate.	0.2
y	Annotated[object, StateSpec()]	The initial second coordinate.	0.0
beta1	Annotated[object, ParameterSpec()]	The first unfolding parameter.	0.1
beta2	Annotated[object, ParameterSpec()]	The second unfolding parameter.	-1.0
sign	Annotated[object, ParameterSpec()]	The sign of the term x y, 1 or -1.	-1.0

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import TakensBogdanovElement
>>> TakensBogdanovElement('form', beta1=0.0).beta1
0.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_takens_bogdanov.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.2,
    y: Annotated[object, StateSpec()] = 0.0,
    beta1: Annotated[object, ParameterSpec()] = 0.1,
    beta2: Annotated[object, ParameterSpec()] = -1.0,
    sign: Annotated[object, ParameterSpec()] = -1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.y = y
    self.beta1 = beta1
    self.beta2 = beta2
    self.sign = sign

TentMapElement(label, visual=None, *, x=0.3, mu=1.99)

Bases: Element

Value and slope of the tent map x' = mu min(x, 1 - x), which a MapInteraction iterates.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial value, between 0 and 1.	0.3
mu	Annotated[object, ParameterSpec()]	The slope, between 0 and 2.	1.99

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import TentMapElement
>>> TentMapElement('map', mu=1.5).mu
1.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_tent_map.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.3,
    mu: Annotated[object, ParameterSpec()] = 1.99,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.mu = mu

TowelMapElement(label, visual=None, *, x=0.085, y=-0.121, z=0.075, a=3.8, b=3.78)

Bases: Element

Coordinates and growth rates of Rössler's towel map, a three-dimensional map with two positive exponents.

Parameters:

Name	Type	Description	Default
label	str	The label of the element.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[object, StateSpec()]	The initial first coordinate.	0.085
y	Annotated[object, StateSpec()]	The initial second coordinate.	-0.121
z	Annotated[object, StateSpec()]	The initial third coordinate.	0.075
a	Annotated[object, ParameterSpec()]	The growth rate of the first logistic coordinate.	3.8
b	Annotated[object, ParameterSpec()]	The growth rate of the third logistic coordinate.	3.78

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import TowelMapElement
>>> TowelMapElement('map', a=3.7).a
3.7

Source code in src/skcomplex/models/mathematics/dynamical_systems/_towel_map.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[object, StateSpec()] = 0.085,
    y: Annotated[object, StateSpec()] = -0.121,
    z: Annotated[object, StateSpec()] = 0.075,
    a: Annotated[object, ParameterSpec()] = 3.8,
    b: Annotated[object, ParameterSpec()] = 3.78,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.y = y
    self.z = z
    self.a = a
    self.b = b

baker_map(x=0.2, y=0.3, *, alpha=1 / 3, lambda_a=1 / 3, lambda_b=2 / 3)

Return the generalized baker map, which stretches the unit square along x and stacks the two pieces in y.

The strip x < alpha is stretched by 1 / alpha and squeezed into the bottom band of height lambda_a, and the rest is stretched by 1 / (1 - alpha) and squeezed into the top band of height lambda_b. The map preserves area when lambda_a = alpha and lambda_b = 1 - alpha, and it has a fractal attractor when lambda_a + lambda_b < 1.

Parameters:

Name	Type	Description	Default
x	float	The initial stretched coordinate.	0.2
y	float	The initial squeezed coordinate.	0.3
alpha	float	The position of the cut.	1 / 3
lambda_a	float	The height of the bottom band.	1 / 3
lambda_b	float	The height of the top band.	2 / 3

Returns:

Name	Type	Description
system	System	The model, with the states map.x and map.y.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import baker_map
>>> baker_map(lambda_a=0.2).elements[0].lambda_a
0.2

Source code in src/skcomplex/models/mathematics/dynamical_systems/_maps.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'discrete map', 'mixing', 'fractal'),
    references=('Farmer, Ott, and Yorke 1983', 'Datseris and Parlitz 2022', 'Lindgren 2024'),
    defaults={'until': 500, 'dt': 1},
)
def baker_map(
    x: float = 0.2,
    y: float = 0.3,
    *,
    alpha: float = 1 / 3,
    lambda_a: float = 1 / 3,
    lambda_b: float = 2 / 3,
) -> System:
    """Return the generalized baker map, which stretches the unit square along `x` and stacks the two pieces in `y`.

    The strip `x < alpha` is stretched by `1 / alpha` and squeezed into the bottom band of height `lambda_a`, and the
    rest is stretched by `1 / (1 - alpha)` and squeezed into the top band of height `lambda_b`. The map preserves area
    when `lambda_a = alpha` and `lambda_b = 1 - alpha`, and it has a fractal attractor when `lambda_a + lambda_b < 1`.

    Args:
        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.

    Returns:
        system:
            The model, with the states `map.x` and `map.y`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import baker_map
        >>> baker_map(lambda_a=0.2).elements[0].lambda_a
        0.2
    """
    stretch = MapInteraction(
        'x_map',
        target='map',
        state='x',
        function=lambda s: where(
            s.target.x < s.target.alpha,
            s.target.x / s.target.alpha,
            (s.target.x - s.target.alpha) / (1 - s.target.alpha),
        ),
    )
    stack = MapInteraction(
        'y_map',
        target='map',
        state='y',
        function=lambda s: where(
            s.target.x < s.target.alpha,
            s.target.lambda_a * s.target.y,
            1 - s.target.lambda_b + s.target.lambda_b * s.target.y,
        ),
    )
    baker = BakerMapElement('map', x=x, y=y, alpha=alpha, lambda_a=lambda_a, lambda_b=lambda_b)
    return System(elements=[baker], interactions=[stretch, stack])

cat_map(x=0.1, y=0.3)

Return Arnold's cat map (x, y) → (2x + y, x + y) (mod 1), an area-preserving hyperbolic map of the torus.

Parameters:

Name	Type	Description	Default
x	float	The initial first coordinate, between 0 and 1.	0.1
y	float	The initial second coordinate, between 0 and 1.	0.3

Returns:

Name	Type	Description
system	System	The model, with the states map.x and map.y.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import cat_map
>>> cat_map(x=0.5).elements[0].x
0.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_maps.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'discrete map', 'mixing', 'hamiltonian'),
    references=('Arnold and Avez 1968', 'Dilão 2023'),
    defaults={'until': 200, 'dt': 1},
)
def cat_map(x: float = 0.1, y: float = 0.3) -> System:
    """Return Arnold's cat map `(x, y) → (2x + y, x + y) (mod 1)`, an area-preserving hyperbolic map of the torus.

    Args:
        x:
            The initial first coordinate, between 0 and 1.

        y:
            The initial second coordinate, between 0 and 1.

    Returns:
        system:
            The model, with the states `map.x` and `map.y`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import cat_map
        >>> cat_map(x=0.5).elements[0].x
        0.5
    """
    first = MapInteraction('x_map', target='map', state='x', function=lambda s: mod(2 * s.target.x + s.target.y, 1))
    second = MapInteraction('y_map', target='map', state='y', function=lambda s: mod(s.target.x + s.target.y, 1))
    return System(elements=[CatMapElement('map', x=x, y=y)], interactions=[first, second])

circle_map(theta=0.0, *, Omega=0.25, K=0.9)

Return the sine circle map θ' = θ + Ω - K / (2π) sin 2πθ (mod 1), which locks into Arnold tongues.

Parameters:

Name	Type	Description	Default
theta	float	The initial angle, as a fraction of a turn.	0.0
Omega	float	The bare rotation per step.	0.25
K	float	The nonlinearity, invertible below 1.	0.9

Returns:

Name	Type	Description
system	System	The model, with the state map.theta.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import circle_map
>>> circle_map(K=1.0).elements[0].K
1.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_maps.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('discrete map', 'mode locking', 'arnold tongues'),
    references=('Arnold 1965', 'Datseris and Parlitz 2022', 'Dilão 2023'),
    defaults={'until': 500, 'dt': 1},
)
def circle_map(theta: float = 0.0, *, Omega: float = 0.25, K: float = 0.9) -> System:
    """Return the sine circle map `θ' = θ + Ω - K / (2π) sin 2πθ (mod 1)`, which locks into Arnold tongues.

    Args:
        theta:
            The initial angle, as a fraction of a turn.

        Omega:
            The bare rotation per step.

        K:
            The nonlinearity, invertible below 1.

    Returns:
        system:
            The model, with the state `map.theta`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import circle_map
        >>> circle_map(K=1.0).elements[0].K
        1.0
    """
    rotation = MapInteraction(
        'theta_map',
        target='map',
        state='theta',
        function=lambda s: mod(
            s.target.theta + s.target.Omega - s.target.K / (2 * pi) * sin(2 * pi * s.target.theta),
            1,
        ),
    )
    return System(elements=[CircleMapElement('map', theta=theta, Omega=Omega, K=K)], interactions=[rotation])

cubic_chaotic_map(n_walkers=100, *, lam=15.0)

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.

Parameters:

Name	Type	Description	Default
n_walkers	int	The number of walkers of the ensemble.	100
lam	float	The parameter λ of the map, between 0 and 16.	15.0

Returns:

Name	Type	Description
system	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

Source code in src/skcomplex/models/mathematics/dynamical_systems/_chaotic_ensembles.py

@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],
    )

cusp_form(x=0.5, *, beta1=0.0, beta2=1.0)

Return the cusp normal form x' = β1 + β2 x - x³, bistable inside the cusp 27 β1² < 4 β2³.

Parameters:

Name	Type	Description	Default
x	float	The initial value.	0.5
beta1	float	The asymmetry.	0.0
beta2	float	The splitting parameter.	1.0

Returns:

Name	Type	Description
system	System	The model, with the state form.x.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import cusp_form
>>> cusp_form(beta1=0.2).elements[0].beta1
0.2

Source code in src/skcomplex/models/mathematics/dynamical_systems/_normal_forms.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('bifurcation', 'normal form', 'ode', 'bistability', 'hysteresis'),
    references=('Gros 2015', 'Dilão 2023'),
    defaults={'until': 20.0, 'dt': 0.1},
)
def cusp_form(x: float = 0.5, *, beta1: float = 0.0, beta2: float = 1.0) -> System:
    """Return the cusp normal form `x' = β1 + β2 x - x³`, bistable inside the cusp `27 β1² < 4 β2³`.

    Args:
        x:
            The initial value.

        beta1:
            The asymmetry.

        beta2:
            The splitting parameter.

    Returns:
        system:
            The model, with the state `form.x`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import cusp_form
        >>> cusp_form(beta1=0.2).elements[0].beta1
        0.2
    """
    return System(elements=[CuspElement('form', x=x, beta1=beta1, beta2=beta2)])

doubling_map(n_points=100, *, x=0.4, spread=0.01, q=DOUBLING_DENOMINATOR, random_state=0)

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.

Parameters:

Name	Type	Description	Default
n_points	int	The number of points of the ensemble.	100
x	float	The left end of the interval of initial points, which are rounded to the nearest fraction k / q.	0.4
spread	float	The width of the interval of initial points.	0.01
q	float	The odd denominator of the fractions the points stay on, an integer below 2^51.	DOUBLING_DENOMINATOR
random_state	int | Generator | None	The seed or generator of the initial points.	0

Returns:

Name	Type	Description
system	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

Source code in src/skcomplex/models/mathematics/dynamical_systems/_chaotic_ensembles.py

@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})],
    )

finite_time_blow_up(x=1.0, *, a=1.0, p=2.0)

Return hyperbolic growth x' = a x^p, which diverges at the finite time x0^(1 - p) / (a (p - 1)) for p > 1.

Parameters:

Name	Type	Description	Default
x	float	The initial value, positive.	1.0
a	float	The growth coefficient.	1.0
p	float	The growth exponent.	2.0

Returns:

Name	Type	Description
system	System	The model, with the state growth.x.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import finite_time_blow_up
>>> finite_time_blow_up(p=3.0).elements[0].p
3.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_flows.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('ode', 'singularity', 'hyperbolic growth'),
    references=('Forrest 2018',),
    defaults={'until': 0.9, 'dt': 0.01},
)
def finite_time_blow_up(x: float = 1.0, *, a: float = 1.0, p: float = 2.0) -> System:
    """Return hyperbolic growth `x' = a x^p`, which diverges at the finite time `x0^(1 - p) / (a (p - 1))` for p > 1.

    Args:
        x:
            The initial value, positive.

        a:
            The growth coefficient.

        p:
            The growth exponent.

    Returns:
        system:
            The model, with the state `growth.x`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import finite_time_blow_up
        >>> finite_time_blow_up(p=3.0).elements[0].p
        3.0
    """
    return System(elements=[BlowUpElement('growth', x=x, a=a, p=p)])

henon_map(x=0.0, y=0.0, *, a=1.4, b=0.3)

Return the Hénon map x' = 1 - a x² + y, y' = b x, with a fractal strange attractor for its defaults.

Parameters:

Name	Type	Description	Default
x	float	The initial first coordinate.	0.0
y	float	The initial second coordinate.	0.0
a	float	The nonlinearity.	1.4
b	float	The contraction.	0.3

Returns:

Name	Type	Description
system	System	The model, with the states map.x and map.y.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import henon_map
>>> henon_map(a=1.2).elements[0].a
1.2

Source code in src/skcomplex/models/mathematics/dynamical_systems/_maps.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'discrete map', 'strange attractor'),
    references=('Hénon 1976', 'Datseris and Parlitz 2022'),
    defaults={'until': 1000, 'dt': 1},
)
def henon_map(x: float = 0.0, y: float = 0.0, *, a: float = 1.4, b: float = 0.3) -> System:
    """Return the Hénon map `x' = 1 - a x² + y`, `y' = b x`, with a fractal strange attractor for its defaults.

    Args:
        x:
            The initial first coordinate.

        y:
            The initial second coordinate.

        a:
            The nonlinearity.

        b:
            The contraction.

    Returns:
        system:
            The model, with the states `map.x` and `map.y`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import henon_map
        >>> henon_map(a=1.2).elements[0].a
        1.2
    """
    first = MapInteraction(
        'x_map',
        target='map',
        state='x',
        function=lambda s: 1 - s.target.a * s.target.x**2 + s.target.y,
    )
    second = MapInteraction('y_map', target='map', state='y', function=lambda s: s.target.b * s.target.x)
    return System(elements=[HenonMapElement('map', x=x, y=y, a=a, b=b)], interactions=[first, second])

hopf_form(x=0.1, y=0.0, *, mu=0.25, omega=1.0, a=-1.0)

Return the Hopf normal form, whose focus gives birth to a limit cycle of radius √(-μ / a) as μ crosses 0.

x' = μx - ωy + a x (x² + y²) and y' = ωx + μy + a y (x² + y²), supercritical for a < 0.

Parameters:

Name	Type	Description	Default
x	float	The initial first coordinate.	0.1
y	float	The initial second coordinate.	0.0
mu	float	The bifurcation parameter.	0.25
omega	float	The angular frequency.	1.0
a	float	The cubic coefficient, the sign of the first Lyapunov coefficient.	-1.0

Returns:

Name	Type	Description
system	System	The model, with the states form.x and form.y.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import hopf_form
>>> hopf_form(mu=-0.1).elements[0].mu
-0.1

Source code in src/skcomplex/models/mathematics/dynamical_systems/_normal_forms.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('bifurcation', 'normal form', 'ode', 'limit cycle'),
    references=('Gros 2015', 'Dilão 2023'),
    defaults={'until': 50.0, 'dt': 0.1},
)
def hopf_form(x: float = 0.1, y: float = 0.0, *, mu: float = 0.25, omega: float = 1.0, a: float = -1.0) -> System:
    """Return the Hopf normal form, whose focus gives birth to a limit cycle of radius `√(-μ / a)` as μ crosses 0.

    `x' = μx - ωy + a x (x² + y²)` and `y' = ωx + μy + a y (x² + y²)`, supercritical for `a < 0`.

    Args:
        x:
            The initial first coordinate.

        y:
            The initial second coordinate.

        mu:
            The bifurcation parameter.

        omega:
            The angular frequency.

        a:
            The cubic coefficient, the sign of the first Lyapunov coefficient.

    Returns:
        system:
            The model, with the states `form.x` and `form.y`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import hopf_form
        >>> hopf_form(mu=-0.1).elements[0].mu
        -0.1
    """
    return System(elements=[HopfElement('form', x=x, y=y, mu=mu, omega=omega, a=a)])

intermittency_map(x=0.01, *, z=2.0)

Return the Pomeau-Manneville map x' = x + x^z (mod 1), whose long laminar phases near 0 end in chaotic bursts.

Parameters:

Name	Type	Description	Default
x	float	The initial value, between 0 and 1.	0.01
z	float	The exponent of the tangency at 0, above 1.	2.0

Returns:

Name	Type	Description
system	System	The model, with the state map.x.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import intermittency_map
>>> intermittency_map(z=1.5).elements[0].z
1.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_maps.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'discrete map', 'intermittency'),
    references=('Pomeau and Manneville 1980', 'Dilão 2023', 'Jensen 2023'),
    defaults={'until': 1000, 'dt': 1},
)
def intermittency_map(x: float = 0.01, *, z: float = 2.0) -> System:
    """Return the Pomeau-Manneville map `x' = x + x^z (mod 1)`, whose long laminar phases near 0 end in chaotic bursts.

    Args:
        x:
            The initial value, between 0 and 1.

        z:
            The exponent of the tangency at 0, above 1.

    Returns:
        system:
            The model, with the state `map.x`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import intermittency_map
        >>> intermittency_map(z=1.5).elements[0].z
        1.5
    """
    burst = MapInteraction(
        'x_map',
        target='map',
        state='x',
        function=lambda s: mod(s.target.x + s.target.x**s.target.z, 1),
    )
    return System(elements=[IntermittencyMapElement('map', x=x, z=z)], interactions=[burst])

koopman_slow_manifold(x1=1.0, x2=-1.0, *, mu=-0.05, lam=-1.0)

Return the quadratic flow x1' = mu x1, x2' = lam (x2 - x1^2), with a slow manifold and a linear embedding.

For lam < mu < 0 the fast direction contracts onto the slow manifold x2 = x1^2, and the state then slides along it to the origin. With the observable x1^2, the coordinates (x1, x2, x1^2) span a Koopman-invariant subspace in which the flow is linear, with the eigenvalues mu, lam, and 2 mu. The Koopman eigenfunctions phi_mu = x1 and phi_lam = x2 - b x1^2 with b = lam / (lam - 2 mu) decay exactly as exp(mu t) and exp(lam t), so trajectories follow the parabolas x2 = b x1^2 + C |x1|^(lam / mu).

Parameters:

Name	Type	Description	Default
x1	float	The initial slow coordinate.	1.0
x2	float	The initial fast coordinate.	-1.0
mu	float	The slow eigenvalue.	-0.05
lam	float	The fast eigenvalue.	-1.0

Returns:

Name	Type	Description
system	System	The model, with the states flow.x1 and flow.x2.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import koopman_slow_manifold
>>> koopman_slow_manifold(lam=-2.0).elements[0].lam
-2.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_koopman.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('Koopman operator', 'slow manifold', 'eigenfunctions', 'ode'),
    references=('Brunton, Budišić, Kaiser, and Kutz 2022', 'Tu et al. 2014', 'Brunton et al. 2016'),
    defaults={'until': 40.0, 'dt': 0.1},
)
def koopman_slow_manifold(
    x1: float = 1.0,
    x2: float = -1.0,
    *,
    mu: float = -0.05,
    lam: float = -1.0,
) -> System:
    """Return the quadratic flow `x1' = mu x1`, `x2' = lam (x2 - x1^2)`, with a slow manifold and a linear embedding.

    For `lam < mu < 0` the fast direction contracts onto the slow manifold `x2 = x1^2`, and the state then slides
    along it to the origin. With the observable `x1^2`, the coordinates `(x1, x2, x1^2)` span a Koopman-invariant
    subspace in which the flow is linear, with the eigenvalues `mu`, `lam`, and `2 mu`. The Koopman eigenfunctions
    `phi_mu = x1` and `phi_lam = x2 - b x1^2` with `b = lam / (lam - 2 mu)` decay exactly as `exp(mu t)` and
    `exp(lam t)`, so trajectories follow the parabolas `x2 = b x1^2 + C |x1|^(lam / mu)`.

    Args:
        x1:
            The initial slow coordinate.

        x2:
            The initial fast coordinate.

        mu:
            The slow eigenvalue.

        lam:
            The fast eigenvalue.

    Returns:
        system:
            The model, with the states `flow.x1` and `flow.x2`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import koopman_slow_manifold
        >>> koopman_slow_manifold(lam=-2.0).elements[0].lam
        -2.0
    """
    return System(elements=[SlowManifoldElement('flow', x1=x1, x2=x2, mu=mu, lam=lam)])

logistic_map(x=0.2, *, r=3.7)

Return the logistic map x_{t+1} = r x_t (1 - x_t), which reaches chaos through period doubling as r grows.

Parameters:

Name	Type	Description	Default
x	float	The initial value, between 0 and 1.	0.2
r	float	The growth rate, between 0 and 4.	3.7

Returns:

Name	Type	Description
system	System	The model, with the state map.x.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import logistic_map
>>> logistic_map(r=3.2).elements[0].r
3.2

Source code in src/skcomplex/models/mathematics/dynamical_systems/_maps.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'discrete map', 'period doubling'),
    references=('May 1976', 'Satz 2022'),
    defaults={'until': 200, 'dt': 1},
)
def logistic_map(x: float = 0.2, *, r: float = 3.7) -> System:
    """Return the logistic map `x_{t+1} = r x_t (1 - x_t)`, which reaches chaos through period doubling as `r` grows.

    Args:
        x:
            The initial value, between 0 and 1.

        r:
            The growth rate, between 0 and 4.

    Returns:
        system:
            The model, with the state `map.x`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import logistic_map
        >>> logistic_map(r=3.2).elements[0].r
        3.2
    """
    logistic = MapInteraction(
        'x_map',
        target='map',
        state='x',
        function=lambda s: s.target.r * s.target.x * (1 - s.target.x),
    )
    return System(elements=[LogisticMapElement('map', x=x, r=r)], interactions=[logistic])

lorenz(x=1.0, y=1.0, z=1.0, *, sigma=10.0, rho=28.0, beta=8 / 3)

Return the Lorenz-63 model of convection, chaotic on a butterfly-shaped attractor for its standard parameters.

Parameters:

Name	Type	Description	Default
x	float	The initial convection intensity.	1.0
y	float	The initial temperature difference between rising and falling currents.	1.0
z	float	The initial deviation of the vertical temperature profile.	1.0
sigma	float	The Prandtl number.	10.0
rho	float	The Rayleigh number relative to its critical value.	28.0
beta	float	The geometric factor.	8 / 3

Returns:

Name	Type	Description
system	System	The model, with the states lorenz.x, lorenz.y, and lorenz.z.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import lorenz
>>> lorenz(rho=20.0).elements[0].rho
20.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_flows.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'ode', 'strange attractor'),
    references=('Lorenz 1963', 'Datseris and Parlitz 2022'),
    defaults={'until': 50.0, 'dt': 0.01},
)
def lorenz(
    x: float = 1.0,
    y: float = 1.0,
    z: float = 1.0,
    *,
    sigma: float = 10.0,
    rho: float = 28.0,
    beta: float = 8 / 3,
) -> System:
    """Return the Lorenz-63 model of convection, chaotic on a butterfly-shaped attractor for its standard parameters.

    Args:
        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.

    Returns:
        system:
            The model, with the states `lorenz.x`, `lorenz.y`, and `lorenz.z`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import lorenz
        >>> lorenz(rho=20.0).elements[0].rho
        20.0
    """
    return System(elements=[LorenzElement('lorenz', x=x, y=y, z=z, sigma=sigma, rho=rho, beta=beta)])

newton_raphson_map(x=0.5, y=0.5)

Return Newton's method for z³ = 1 in the complex plane, z' = (2z³ + 1) / (3z²), in real coordinates.

Every start except a set of measure zero converges to one of the three cube roots of unity, and the boundaries of their basins are fractal.

Parameters:

Name	Type	Description	Default
x	float	The initial real part.	0.5
y	float	The initial imaginary part.	0.5

Returns:

Name	Type	Description
system	System	The model, with the states map.x and map.y.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import newton_raphson_map
>>> newton_raphson_map(x=1.5).elements[0].x
1.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_maps.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('discrete map', 'basins', 'fractal'),
    references=('Dilão 2023',),
    defaults={'until': 50, 'dt': 1},
)
def newton_raphson_map(x: float = 0.5, y: float = 0.5) -> System:
    """Return Newton's method for `z³ = 1` in the complex plane, `z' = (2z³ + 1) / (3z²)`, in real coordinates.

    Every start except a set of measure zero converges to one of the three cube roots of unity, and the boundaries of
    their basins are fractal.

    Args:
        x:
            The initial real part.

        y:
            The initial imaginary part.

    Returns:
        system:
            The model, with the states `map.x` and `map.y`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import newton_raphson_map
        >>> newton_raphson_map(x=1.5).elements[0].x
        1.5
    """
    real = MapInteraction(
        'x_map',
        target='map',
        state='x',
        function=lambda s: (
            2 * s.target.x / 3 + (s.target.x**2 - s.target.y**2) / (3 * (s.target.x**2 + s.target.y**2) ** 2)
        ),
    )
    imaginary = MapInteraction(
        'y_map',
        target='map',
        state='y',
        function=lambda s: (
            2 * s.target.y / 3 - 2 * s.target.x * s.target.y / (3 * (s.target.x**2 + s.target.y**2) ** 2)
        ),
    )
    return System(elements=[NewtonMapElement('map', x=x, y=y)], interactions=[real, imaginary])

ou_driven_rossler(x=1.0, y=1.0, z=1.0, *, a=0.2, b=0.4, c=5.743, tau=50.0, rho=0.5, eta=0.0)

Return the Rössler flow driven through its bifurcations by a slow Ornstein-Uhlenbeck control parameter.

The flow is x' = -y - z, y' = x + a y + eta, z' = b + z (x - c), Eq. 13 of Cestnik and Martens, and the control follows eta' = (-eta + rho xi) / tau with white noise xi. The control is an Ornstein-Uhlenbeck process with the correlation time tau and the stationary variance rho^2 / (2 tau). A control that varies slowly against the period of the flow sweeps it through the period doublings and chaotic bands of its bifurcation diagram.

Parameters:

Name	Type	Description	Default
x	float	The initial first coordinate.	1.0
y	float	The initial second coordinate.	1.0
z	float	The initial third coordinate.	1.0
a	float	The feedback of the second coordinate on itself.	0.2
b	float	The constant drive of the third coordinate.	0.4
c	float	The threshold of the third coordinate's growth.	5.743
tau	float	The correlation time of the control.	50.0
rho	float	The amplitude of the noise of the control.	0.5
eta	float	The initial control.	0.0

Returns:

Name	Type	Description
system	System	The model, with the states rossler.x, rossler.y, rossler.z, and the control rossler.eta.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import ou_driven_rossler
>>> ou_driven_rossler(tau=10.0).elements[0].tau
10.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_driven_flows.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('Rössler', 'Ornstein-Uhlenbeck', 'sde', 'bifurcation diagram', 'chaos', 'nonstationary'),
    references=('Cestnik and Martens 2025', 'Rössler 1976', 'Uhlenbeck and Ornstein 1930'),
    defaults={'until': 500.0, 'dt': 0.1, 'solver': EulerMaruyamaSolver(dt=0.01)},
)
def ou_driven_rossler(
    x: float = 1.0,
    y: float = 1.0,
    z: float = 1.0,
    *,
    a: float = 0.2,
    b: float = 0.4,
    c: float = 5.743,
    tau: float = 50.0,
    rho: float = 0.5,
    eta: float = 0.0,
) -> System:
    """Return the Rössler flow driven through its bifurcations by a slow Ornstein-Uhlenbeck control parameter.

    The flow is `x' = -y - z`, `y' = x + a y + eta`, `z' = b + z (x - c)`, Eq. 13 of Cestnik and Martens, and the
    control follows `eta' = (-eta + rho xi) / tau` with white noise `xi`. The control is an Ornstein-Uhlenbeck
    process with the correlation time `tau` and the stationary variance `rho^2 / (2 tau)`. A control that varies
    slowly against the period of the flow sweeps it through the period doublings and chaotic bands of its
    bifurcation diagram.

    Args:
        x:
            The initial first coordinate.

        y:
            The initial second coordinate.

        z:
            The initial third coordinate.

        a:
            The feedback of the second coordinate on itself.

        b:
            The constant drive of the third coordinate.

        c:
            The threshold of the third coordinate's growth.

        tau:
            The correlation time of the control.

        rho:
            The amplitude of the noise of the control.

        eta:
            The initial control.

    Returns:
        system:
            The model, with the states `rossler.x`, `rossler.y`, `rossler.z`, and the control `rossler.eta`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import ou_driven_rossler
        >>> ou_driven_rossler(tau=10.0).elements[0].tau
        10.0
    """
    rossler = DrivenRosslerElement('rossler', x=x, y=y, z=z, eta=eta, a=a, b=b, c=c, tau=tau, rho=rho)
    drive = RateInteraction('drive', target='rossler', state='y', rate=lambda s: s.target.eta)
    control = RelaxationInteraction(
        'control',
        target='rossler',
        state='eta',
        time=lambda s: s.target.tau,
        noise=lambda s: s.target.rho / s.target.tau,
    )
    return System(elements=[rossler], interactions=[drive, control])

rossler(x=1.0, y=1.0, z=1.0, *, a=0.2, b=0.2, c=5.7)

Return the Rössler model, a chaotic flow with one folded band for its standard parameters.

Parameters:

Name	Type	Description	Default
x	float	The initial first coordinate.	1.0
y	float	The initial second coordinate.	1.0
z	float	The initial third coordinate.	1.0
a	float	The feedback of the second coordinate on itself.	0.2
b	float	The constant drive of the third coordinate.	0.2
c	float	The threshold of the third coordinate's growth.	5.7

Returns:

Name	Type	Description
system	System	The model, with the states rossler.x, rossler.y, and rossler.z.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import rossler
>>> rossler(c=4.0).elements[0].c
4.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_flows.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'ode', 'strange attractor'),
    references=('Rössler 1976',),
    defaults={'until': 200.0, 'dt': 0.05},
)
def rossler(
    x: float = 1.0,
    y: float = 1.0,
    z: float = 1.0,
    *,
    a: float = 0.2,
    b: float = 0.2,
    c: float = 5.7,
) -> System:
    """Return the Rössler model, a chaotic flow with one folded band for its standard parameters.

    Args:
        x:
            The initial first coordinate.

        y:
            The initial second coordinate.

        z:
            The initial third coordinate.

        a:
            The feedback of the second coordinate on itself.

        b:
            The constant drive of the third coordinate.

        c:
            The threshold of the third coordinate's growth.

    Returns:
        system:
            The model, with the states `rossler.x`, `rossler.y`, and `rossler.z`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import rossler
        >>> rossler(c=4.0).elements[0].c
        4.0
    """
    return System(elements=[RosslerElement('rossler', x=x, y=y, z=z, a=a, b=b, c=c)])

saddle_node_form(x=0.0, *, mu=1.0)

Return the saddle-node normal form x' = μ - x², whose two equilibria ±√μ meet and vanish at μ = 0.

Parameters:

Name	Type	Description	Default
x	float	The initial value.	0.0
mu	float	The bifurcation parameter.	1.0

Returns:

Name	Type	Description
system	System	The model, with the state form.x.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import saddle_node_form
>>> saddle_node_form(mu=0.5).elements[0].mu
0.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_normal_forms.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('bifurcation', 'normal form', 'ode'),
    references=('Gros 2015', 'Dilão 2023'),
    defaults={'until': 10.0, 'dt': 0.05},
)
def saddle_node_form(x: float = 0.0, *, mu: float = 1.0) -> System:
    """Return the saddle-node normal form `x' = μ - x²`, whose two equilibria `±√μ` meet and vanish at μ = 0.

    Args:
        x:
            The initial value.

        mu:
            The bifurcation parameter.

    Returns:
        system:
            The model, with the state `form.x`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import saddle_node_form
        >>> saddle_node_form(mu=0.5).elements[0].mu
        0.5
    """
    return System(elements=[SaddleNodeElement('form', x=x, mu=mu)])

skew_tent_map(n_points=100, *, a=0.3, x=0.4, spread=0.01, random_state=0)

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.

Parameters:

Name	Type	Description	Default
n_points	int	The number of points of the ensemble.	100
a	float	The position of the top of the tent, between 0 and 1.	0.3
x	float	The left end of the interval of initial points.	0.4
spread	float	The width of the interval of initial points.	0.01
random_state	int | Generator | None	The seed or generator of the initial points.	0

Returns:

Name	Type	Description
system	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

Source code in src/skcomplex/models/mathematics/dynamical_systems/_chaotic_ensembles.py

@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})],
    )

sprott_jerk(x=0.0, velocity=0.0, acceleration=1.0, *, A=0.6)

Return Sprott's jerk equation x''' = -A x'' - x' + |x| - 1, chaotic near A = 0.6.

Parameters:

Name	Type	Description	Default
x	float	The initial position.	0.0
velocity	float	The initial first derivative.	0.0
acceleration	float	The initial second derivative.	1.0
A	float	The damping of the second derivative.	0.6

Returns:

Name	Type	Description
system	System	The model, with the state jerk.x of order 3 and its derivatives jerk.x_d1 and jerk.x_d2.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import sprott_jerk
>>> sprott_jerk(A=0.5).elements[0].A
0.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_flows.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'ode', 'third order'),
    references=('Sprott 1997', 'Datseris and Parlitz 2022'),
    defaults={'until': 200.0, 'dt': 0.1},
)
def sprott_jerk(
    x: float = 0.0,
    velocity: float = 0.0,
    acceleration: float = 1.0,
    *,
    A: float = 0.6,
) -> System:
    """Return Sprott's jerk equation `x''' = -A x'' - x' + |x| - 1`, chaotic near A = 0.6.

    Args:
        x:
            The initial position.

        velocity:
            The initial first derivative.

        acceleration:
            The initial second derivative.

        A:
            The damping of the second derivative.

    Returns:
        system:
            The model, with the state `jerk.x` of order 3 and its derivatives `jerk.x_d1` and `jerk.x_d2`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import sprott_jerk
        >>> sprott_jerk(A=0.5).elements[0].A
        0.5
    """
    return System(elements=[JerkElement('jerk', x=x, x_d1=velocity, x_d2=acceleration, A=A)])

standard_map(theta=0.0, p=2 * math.pi * GOLDEN_MEAN, *, K=1.2)

Return the Chirikov standard map p' = p + K sin θ, θ' = θ + p', with global chaos above K ≈ 0.9716.

The last invariant circle that spans the angle, the golden-mean torus, breaks at K ≈ 0.971635. The angle is taken modulo 2π and the momentum is kept on the real line, so its spread measures diffusion.

Parameters:

Name	Type	Description	Default
theta	float	The initial angle.	0.0
p	float	The initial momentum, by default on the golden-mean torus of the unkicked rotor.	2 * pi * GOLDEN_MEAN
K	float	The kick strength.	1.2

Returns:

Name	Type	Description
system	System	The model, with the states map.theta and map.p.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import standard_map
>>> standard_map(K=0.5).elements[0].K
0.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_maps.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'discrete map', 'hamiltonian', 'kam'),
    references=('Chirikov 1979', 'Datseris and Parlitz 2022', 'Dilão 2023', 'Lindgren 2024'),
    defaults={'until': 1000, 'dt': 1},
)
def standard_map(theta: float = 0.0, p: float = 2 * math.pi * GOLDEN_MEAN, *, K: float = 1.2) -> System:
    """Return the Chirikov standard map `p' = p + K sin θ`, `θ' = θ + p'`, with global chaos above K ≈ 0.9716.

    The last invariant circle that spans the angle, the golden-mean torus, breaks at K ≈ 0.971635.
    The angle is taken modulo 2π and the momentum is kept on the real line, so its spread measures diffusion.

    Args:
        theta:
            The initial angle.

        p:
            The initial momentum, by default on the golden-mean torus of the unkicked rotor.

        K:
            The kick strength.

    Returns:
        system:
            The model, with the states `map.theta` and `map.p`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import standard_map
        >>> standard_map(K=0.5).elements[0].K
        0.5
    """
    kick = MapInteraction(
        'p_map',
        target='map',
        state='p',
        function=lambda s: s.target.p + s.target.K * sin(s.target.theta),
    )
    rotation = MapInteraction(
        'theta_map',
        target='map',
        state='theta',
        function=lambda s: mod(s.target.theta + s.target.p + s.target.K * sin(s.target.theta), 2 * pi),
    )
    return System(elements=[StandardMapElement('map', theta=theta, p=p, K=K)], interactions=[kick, rotation])

subcritical_hopf_form(x=0.1, y=0.0, *, alpha=-0.1, omega=1.0, q=0.0, gamma=1.0, s=0.0)

Return the subcritical Hopf normal form, where a stable focus coexists with a stable limit cycle.

The complex amplitude z = x + iy follows z' = (alpha + iω) z + (1 + iq) |z|² z - (gamma + is) |z|⁴ z, so its modulus follows r' = alpha r + r³ - gamma r⁵. The focus z = 0 is stable for alpha < 0. The stable limit cycle of radius r² = (1 + √(1 + 4 alpha gamma)) / (2 gamma) exists for alpha > -1 / (4 gamma), and an unstable cycle separates the two attractors while alpha < 0. A slow sweep of alpha up and down therefore jumps to the cycle at alpha = 0 and falls back to the focus at alpha = -1 / (4 gamma), a hysteresis loop.

Parameters:

Name	Type	Description	Default
x	float	The initial real part of z.	0.1
y	float	The initial imaginary part of z.	0.0
alpha	float	The bifurcation parameter alpha, the linear growth rate.	-0.1
omega	float	The angular frequency ω at small amplitude.	1.0
q	float	The nonlinear frequency shift q of the cubic term.	0.0
gamma	float	The stabilizing quintic coefficient gamma, positive.	1.0
s	float	The nonlinear frequency shift s of the quintic term.	0.0

Returns:

Name	Type	Description
system	System	The model, with the states form.x and form.y.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import subcritical_hopf_form
>>> subcritical_hopf_form(alpha=0.1).elements[0].alpha
0.1

Source code in src/skcomplex/models/mathematics/dynamical_systems/_subcritical_forms.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('bifurcation', 'normal form', 'ode', 'limit cycle', 'bistability', 'hysteresis'),
    references=('Bertin 2021',),
    defaults={'until': 50.0, 'dt': 0.1},
)
def subcritical_hopf_form(
    x: float = 0.1,
    y: float = 0.0,
    *,
    alpha: float = -0.1,
    omega: float = 1.0,
    q: float = 0.0,
    gamma: float = 1.0,
    s: float = 0.0,
) -> System:
    """Return the subcritical Hopf normal form, where a stable focus coexists with a stable limit cycle.

    The complex amplitude `z = x + iy` follows `z' = (alpha + iω) z + (1 + iq) |z|² z - (gamma + is) |z|⁴ z`, so its
    modulus follows `r' = alpha r + r³ - gamma r⁵`. The focus `z = 0` is stable for `alpha < 0`. The stable limit cycle
    of radius `r² = (1 + √(1 + 4 alpha gamma)) / (2 gamma)` exists for `alpha > -1 / (4 gamma)`, and an unstable cycle
    separates the two attractors while `alpha < 0`. A slow sweep of `alpha` up and down therefore jumps to the cycle at
    `alpha = 0` and falls back to the focus at `alpha = -1 / (4 gamma)`, a hysteresis loop.

    Args:
        x:
            The initial real part of `z`.

        y:
            The initial imaginary part of `z`.

        alpha:
            The bifurcation parameter `alpha`, the linear growth rate.

        omega:
            The angular frequency `ω` at small amplitude.

        q:
            The nonlinear frequency shift `q` of the cubic term.

        gamma:
            The stabilizing quintic coefficient `gamma`, positive.

        s:
            The nonlinear frequency shift `s` of the quintic term.

    Returns:
        system:
            The model, with the states `form.x` and `form.y`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import subcritical_hopf_form
        >>> subcritical_hopf_form(alpha=0.1).elements[0].alpha
        0.1
    """
    return System(
        elements=[SubcriticalHopfElement('form', x=x, y=y, alpha=alpha, omega=omega, q=q, gamma=gamma, s=s)],
    )

takens_bogdanov_form(x=0.2, y=0.0, *, beta1=0.1, beta2=-1.0, sign=-1.0)

Return the Takens-Bogdanov normal form x' = y, y' = β1 + β2 x + x² + s x y, where a saddle-node meets a Hopf.

Parameters:

Name	Type	Description	Default
x	float	The initial position.	0.2
y	float	The initial velocity.	0.0
beta1	float	The first unfolding parameter.	0.1
beta2	float	The second unfolding parameter.	-1.0
sign	float	The sign s of the mixed term, -1 or 1.	-1.0

Returns:

Name	Type	Description
system	System	The model, with the states form.x and form.y.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import takens_bogdanov_form
>>> takens_bogdanov_form(beta1=0.0).elements[0].beta1
0.0

Source code in src/skcomplex/models/mathematics/dynamical_systems/_normal_forms.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('bifurcation', 'normal form', 'ode', 'codimension two'),
    references=('Gros 2015', 'Dilão 2023'),
    defaults={'until': 50.0, 'dt': 0.1},
)
def takens_bogdanov_form(
    x: float = 0.2,
    y: float = 0.0,
    *,
    beta1: float = 0.1,
    beta2: float = -1.0,
    sign: float = -1.0,
) -> System:
    """Return the Takens-Bogdanov normal form `x' = y`, `y' = β1 + β2 x + x² + s x y`, where a saddle-node meets a Hopf.

    Args:
        x:
            The initial position.

        y:
            The initial velocity.

        beta1:
            The first unfolding parameter.

        beta2:
            The second unfolding parameter.

        sign:
            The sign `s` of the mixed term, `-1` or `1`.

    Returns:
        system:
            The model, with the states `form.x` and `form.y`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import takens_bogdanov_form
        >>> takens_bogdanov_form(beta1=0.0).elements[0].beta1
        0.0
    """
    return System(elements=[TakensBogdanovElement('form', x=x, y=y, beta1=beta1, beta2=beta2, sign=sign)])

tent_map(x=0.3, *, mu=1.99)

Return the tent map x' = μ min(x, 1 - x), chaotic with Lyapunov exponent ln μ for μ above 1.

Parameters:

Name	Type	Description	Default
x	float	The initial value, between 0 and 1.	0.3
mu	float	The slope, between 0 and 2.	1.99

Returns:

Name	Type	Description
system	System	The model, with the state map.x.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import tent_map
>>> tent_map(mu=1.5).elements[0].mu
1.5

Source code in src/skcomplex/models/mathematics/dynamical_systems/_maps.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'discrete map', 'piecewise linear'),
    references=('Datseris and Parlitz 2022', 'Dilão 2023'),
    defaults={'until': 200, 'dt': 1},
)
def tent_map(x: float = 0.3, *, mu: float = 1.99) -> System:
    """Return the tent map `x' = μ min(x, 1 - x)`, chaotic with Lyapunov exponent `ln μ` for μ above 1.

    Args:
        x:
            The initial value, between 0 and 1.

        mu:
            The slope, between 0 and 2.

    Returns:
        system:
            The model, with the state `map.x`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import tent_map
        >>> tent_map(mu=1.5).elements[0].mu
        1.5
    """
    tent = MapInteraction(
        'x_map',
        target='map',
        state='x',
        function=lambda s: s.target.mu * where(s.target.x < 1 / 2, s.target.x, 1 - s.target.x),
    )
    return System(elements=[TentMapElement('map', x=x, mu=mu)], interactions=[tent])

towel_map(x=0.085, y=-0.121, z=0.075, *, a=3.8, b=3.78)

Return Rössler's towel map, a three-dimensional map with two positive Lyapunov exponents.

x' = a x (1 - x) - 0.05 (y + 0.35)(1 - 2z), y' = 0.1 ((y + 0.35)(1 - 2z) - 1)(1 - 1.9 x), and z' = b z (1 - z) + 0.2 y.

Parameters:

Name	Type	Description	Default
x	float	The initial first coordinate.	0.085
y	float	The initial second coordinate.	-0.121
z	float	The initial third coordinate.	0.075
a	float	The growth rate of the first logistic coordinate.	3.8
b	float	The growth rate of the third logistic coordinate.	3.78

Returns:

Name	Type	Description
system	System	The model, with the states map.x, map.y, and map.z.

Examples:

>>> from skcomplex.models.mathematics.dynamical_systems import towel_map
>>> towel_map(a=3.7).elements[0].a
3.7

Source code in src/skcomplex/models/mathematics/dynamical_systems/_maps.py

@register_model(
    field='mathematics/dynamical_systems',
    tags=('chaos', 'discrete map', 'hyperchaos'),
    references=('Rössler 1979', 'Datseris and Parlitz 2022'),
    defaults={'until': 1000, 'dt': 1},
)
def towel_map(
    x: float = 0.085,
    y: float = -0.121,
    z: float = 0.075,
    *,
    a: float = 3.8,
    b: float = 3.78,
) -> System:
    """Return Rössler's towel map, a three-dimensional map with two positive Lyapunov exponents.

    `x' = a x (1 - x) - 0.05 (y + 0.35)(1 - 2z)`, `y' = 0.1 ((y + 0.35)(1 - 2z) - 1)(1 - 1.9 x)`, and
    `z' = b z (1 - z) + 0.2 y`.

    Args:
        x:
            The initial first coordinate.

        y:
            The initial second coordinate.

        z:
            The initial third coordinate.

        a:
            The growth rate of the first logistic coordinate.

        b:
            The growth rate of the third logistic coordinate.

    Returns:
        system:
            The model, with the states `map.x`, `map.y`, and `map.z`.

    Examples:
        >>> from skcomplex.models.mathematics.dynamical_systems import towel_map
        >>> towel_map(a=3.7).elements[0].a
        3.7
    """
    first = MapInteraction(
        'x_map',
        target='map',
        state='x',
        function=lambda s: (
            s.target.a * s.target.x * (1 - s.target.x) - 0.05 * (s.target.y + 0.35) * (1 - 2 * s.target.z)
        ),
    )
    second = MapInteraction(
        'y_map',
        target='map',
        state='y',
        function=lambda s: 0.1 * ((s.target.y + 0.35) * (1 - 2 * s.target.z) - 1) * (1 - 1.9 * s.target.x),
    )
    third = MapInteraction(
        'z_map',
        target='map',
        state='z',
        function=lambda s: s.target.b * s.target.z * (1 - s.target.z) + 0.2 * s.target.y,
    )
    return System(elements=[TowelMapElement('map', x=x, y=y, z=z, a=a, b=b)], interactions=[first, second, third])