API reference

MappyDS

Poincaré maps, periodic points and bifurcations of hybrid (smooth / non-smooth) dynamical systems: the Julia counterpart of the Python package mappy-ds.

MappyDS implements the mode concept (Miino, NOLTA, IEICE 15(2), 2024): a dynamical system is split into smooth primitive pieces, modes, connected by transition rules. From the modes the package builds the Poincaré map of the system as a composite diffeomorphism together with its Jacobian matrix and Hessian tensor, which in turn feed periodic-point search, local bifurcation analysis and parameter continuation.

Example

The Izhikevich neuron model with a firing threshold at v = 30:

using MappyDS, StaticArrays

izhikevich = VectorField(2) do y, p
    v, u = y
    return SVector(0.04 * v^2 + 5 * v + 140 - u + p.I, p.a * (p.b * v - u))
end
fire = Border((y, p) -> y[1] - 30, 2)
firing = Mapping((y, p) -> y + SVector(p.c - 30, p.d), 2)
reduce = Mapping((y, p) -> y[2], 2, 1)
revert = Mapping((u, p) -> SVector(30.0, u[1]), 1, 2)

pmap = PoincareMap(
    [
        ContinuousMode(:A, izhikevich; borders = (fire,)),
        DiscreteMode(:B, firing),
        DiscreteMode(:P, reduce),
        DiscreteMode(:Pinv, revert),
    ],
    Dict(:A => [:P], :B => :A, :P => :Pinv, :Pinv => :B),
    :Pinv,
)
params = (a = 0.2, b = 0.2, c = -50.0, d = 2.0, I = 10.0)
res = image_detail(pmap, -3.0, params; hessian = true)
res.y, res.jac, res.hes   # ≈ [-3.47838], [0.27080;;], [-0.19326;;;]
res.mode_history          # [:Pinv, :B, :A, :P, :Pinv]

The implementation plan and the API mapping from the Python package are in docs/JULIA_RELEASE_PLAN.md of the mappy repository.

Border(q, dim; direction = 1, name = nameof(q))

Declare a border (section) $q(y, p) = 0$ of a continuous mode on $\mathbb{R}^{dim}$ (Python: @border(dim, direction, name)). direction is the zero crossing that terminates the mode: 1 for negative to positive, -1 for positive to negative and 0 for both. name identifies the border in transition rules written as Dict(:mode => Dict(:border => :next)).

Mapping(f, dom_dim, cod_dim = dom_dim; name = nameof(f))

Declare a discrete map $y \mapsto f(y, p)$ from $\mathbb{R}^{dom\_dim}$ to $\mathbb{R}^{cod\_dim}$ (Python: @mapping(dom_dim, cod_dim)).

Examples

henon = Mapping(2) do y, p
    x, u = y
    return SVector(1 - p.a * x^2 + u, p.b * x)
end
henon([0.0, 0.0], (a = 1.4, b = 0.3))  # [1.0, 0.0]

(f::SystemFunction)(y, p = nothing) -> Vector{Float64}

Evaluate the function numerically.

SystemFunction

Abstract supertype of VectorField, Mapping and Border: a user function f(y, p) of a state vector y and parameters p together with the dimensions of its domain and codomain.

The function is evaluated on SVectors (StaticArrays) and differentiated with ForwardDiff, so it must be written generically: build the result with SVector(...), [...] or a tuple, do not fix element types to Float64, and read parameters as p.a (a NamedTuple) or any other container you pass. Branches on the values of y are allowed (unlike the SymPy tracing of the Python package), but the function must be differentiable where it is evaluated.

See also jacobian, hessian, dom_dim, cod_dim.

VectorField(f, dim; name = nameof(f))

Declare the right-hand side of an autonomous ODE $\dot y = f(y, p)$ on $\mathbb{R}^{dim}$ (Python: @vector_field(dim)).

Examples

izhikevich = VectorField(2) do y, p
    v, u = y
    return SVector(0.04 * v^2 + 5 * v + 140 - u + p.I, p.a * (p.b * v - u))
end
jacobian(izhikevich, [0.0, 0.0], (a = 0.2, b = 0.2, I = 10.0))

as_state(y) -> Vector{Float64}

Convert y (a number, tuple or vector) to a one-dimensional Float64 vector; array inputs are copied.

cod_dim(f)

Dimension of the codomain of a system function or mode.

direction(b::Border)

Direction of the zero crossing that triggers the border (1, -1 or 0).

dom_dim(f)

Dimension of the domain of a system function, mode or map.

hessian(f::SystemFunction, y, p = nothing) -> Array{Float64, 3}

Hessian tensor hes[i, j, k] = ∂²f_i/(∂y_j ∂y_k) at y, computed with nested ForwardDiff Jacobians.

jacobian(f::SystemFunction, y, p = nothing) -> Matrix{Float64}

Jacobian matrix jac[i, j] = ∂f_i/∂y_j at y, computed with ForwardDiff.

mixed_hessian(f::SystemFunction, y, p) -> Array{Float64, 3}

Mixed second derivative hes_p[i, j, m] = ∂²f_i/(∂y_j ∂p_m) at y, the last axis in the order of the keys of the NamedTuple p.

parameter_jacobian(f::SystemFunction, y, p) -> Matrix{Float64}

Derivative jac_p[i, m] = ∂f_i/∂p_m at y with respect to the parameters, one column per key of the NamedTuple p in its order (a cod_dim × 0 matrix when p is nothing or empty). Parameters the function does not read give zero columns.

ContinuousMode(name, fun::VectorField; borders = (), max_interval = 20.0,
               in_trajectory = true, trajectory_dt = 1.0e-2,
               alg = Tsit5(), reltol = 1.0e-6, abstol = 1.0e-9, solver_kwargs...)

A mode whose evolution follows the autonomous ODE fun until one of the borders (Borders of the same dimension, with distinct names) is crossed in the direction it declares. Without borders the mode is the time-max_interval flow map. alg is any OrdinaryDiffEq algorithm (the default Tsit5() corresponds to SciPy's RK45); reltol, abstol and the remaining keyword arguments are forwarded to solve.

When derivatives are requested the first and second variational equations are integrated together with the state and the result is corrected for the dependence of the hitting time on the initial state (Miino, NOLTA, IEICE 15(2), 2024). The image then differs from the one obtained without derivatives by an amount of the order of the solver tolerance, because the adaptive step sizes change.

DiscreteMode(name, fun::Mapping; in_trajectory = false)

A mode whose evolution is a single application of the map fun. in_trajectory decides whether the jump contributes a two-point TrajectorySegment to recorded trajectories.

Mode

Abstract supertype of ContinuousMode and DiscreteMode: a primitive, smooth piece of a hybrid system together with the rule that terminates it. Both kinds expose evolve.

StepResult

Result of evolve. Fields: y (state at the end of the mode), jac (jac[i, j] = ∂y_i/∂y0_j), hes (hes[i, j, k] = ∂²y_i/(∂y0_j ∂y0_k)), jac_p and hes_p (parameter derivatives, from MappyDS 0.2 / 0.3), border (1-based index of the border that terminated a continuous mode, nothing otherwise), t (time spent in a continuous mode) and segment (the recorded TrajectorySegment). Derivatives that were not requested are nothing.

border_names(mode::ContinuousMode) -> Tuple

Names of the borders of the mode, in the order of borders.

evolve(mode, y0, p = nothing; jacobian = false, hessian = false,
       parameter_jacobian = false, parameter_hessian = false, trajectory = false) -> StepResult

Evolve the state y0 through the mode (Python: Mode.step). jacobian and hessian request the Jacobian matrix and the Hessian tensor of the mode map (hessian implies jacobian); parameter_jacobian requests the derivative with respect to the parameters (p must then be a NamedTuple; one column per key, in order) and parameter_hessian the mixed second derivative hes_p (implies parameter_jacobian); trajectory records the trajectory within the mode if the mode is in_trajectory.

AbstractMap

Abstract supertype of maps built from modes (PoincareMap and Diffeomorphism). Subtypes implement image_detail; image and trajectory are convenience wrappers.

Diffeomorphism(fun::Mapping; name = :map)

A discrete map $y \mapsto f(y, p)$ on $\mathbb{R}^n$ as a map with a single mode named name; fun must have equal domain and codomain dimensions. The underlying Mapping is d.fun.

MapResult

Image of a point under a map with derivatives (Python: MapResult). Fields: y, jac (jac[i, j] = ∂y_i/∂y0_j), hes (hes[i, j, k] = ∂²y_i/(∂y0_j ∂y0_k)), jac_p, hes_p (parameter derivatives, from MappyDS 0.2 / 0.3), param_keys (keys of the parameter NamedTuple), mode_history (names of the modes visited, from the initial to the final one) and trajectory. Derivatives that were not requested are nothing.

The characteristic multipliers are available through LinearAlgebra.eigvals(res) and the eigenvectors through LinearAlgebra.eigvecs(res); see also end_mode.

PoincareMap(modes, transitions, initial_mode, end_modes = nothing; max_transitions = 1000)

Poincaré map of a hybrid system described by modes and transition rules.

Starting in initial_mode, the state is evolved mode by mode following transitions until one of the end_modes (by default initial_mode) is reached; that is one iteration of the map. The Jacobian and Hessian are composed with the chain rule along the way.

transitions maps each mode name (a Symbol) to its successor:

• a mode name for a discrete mode, a borderless continuous mode or, as a shorthand, a continuous mode with a single border;
• a vector or tuple of mode names, one per border in the order of borders;
• a Dict(:border_name => :mode_name) covering every border of the mode.

Only modes reachable from initial_mode need a rule. The map is validated at construction: unknown names raise UnknownModeError; rules that do not fit their mode, missing rules for reachable modes, dimension mismatches between a mode and its successor and unreachable end modes raise TransitionError. max_transitions bounds the number of mode transitions per iteration.

end_mode(res::MapResult) -> Symbol

Name of the mode the image belongs to.

image(map, y0, p = nothing; n = 1, kwargs...) -> Vector{Float64}

Compute the n-th image of y0 under the map.

image_detail(map, y0, p = nothing; n = 1, jacobian = true, hessian = false,
             parameter_jacobian = false, parameter_hessian = false,
             trajectory = false, mode = nothing) -> MapResult

Compute the n-th image of y0 under the map with derivatives. jacobian (default true) and hessian request the Jacobian matrix and the Hessian tensor; parameter_jacobian requests the derivative with respect to every parameter of the NamedTuple p (MapResult.jac_p, columns in the order of MapResult.param_keys; implies jacobian); parameter_hessian requests the mixed second derivative MapResult.hes_p (implies hessian and parameter_jacobian); trajectory records the trajectory. For a PoincareMap, mode starts the iteration in another mode than initial_mode (useful when a previous image ended in a different end mode).

Requesting derivatives integrates the variational equations together with the state, which changes the adaptive step sizes of the ODE solver; the image therefore differs slightly (on the order of the solver tolerance) from the one obtained with jacobian = false.

trajectory(map, y0, p = nothing; n = 1, kwargs...) -> Trajectory

Compute the trajectory from y0 over n iterations of the map.

Trajectory(segments = TrajectorySegment[])

A trajectory as a sequence of TrajectorySegments in chronological order. Modes with in_trajectory = false do not contribute a segment.

traj.y concatenates the states of all segments (dim × n_points); it throws an ArgumentError if the segments have different dimensions.

TrajectorySegment(mode, kind, y, t = nothing)

The part of a trajectory spent in a single mode. kind is :continuous or :discrete, y holds the sampled states as columns (dim × n_points; a discrete segment holds the two points before and after the map) and t the sampling times relative to the start of the segment (nothing for discrete segments).

dim(x)

Dimension of the state space of a trajectory segment or of a map.

states(traj::Trajectory) -> Matrix{Float64}

All sampled states of the trajectory concatenated, dim × n_points (also available as traj.y).

CycleResult

Result of find_cycle. Fields: success, retcode (SciMLBase.ReturnCode of the nonlinear solver), y (the periodic point, nothing on failure), eigvals and eigvecs (characteristic multipliers and eigenvectors of the Jacobian of the period-th iterate at y, nothing on failure), nfev (number of evaluations of the map) and residual (Tⁿ(y) - y at the last iterate).

find_cycle(map, y0, p = nothing; period = 1, alg = SimpleTrustRegion(),
           abstol = 1.0e-10, reltol = 1.0e-10, maxiters = 100, kwargs...) -> CycleResult

Find a periodic point of a map by solving $T^n(y) - y = 0$ with the analytic Jacobian $DT^n(y) - I$ provided by the map, where $T$ is map and $n$ is period. The system is a SciMLBase.NonlinearProblem; alg is any algorithm of SimpleNonlinearSolve or NonlinearSolve, and the remaining keyword arguments are forwarded to solve.

Examples

henon = Mapping(2) do y, p
    x, u = y
    return SVector(1 - p.a * x^2 + u, p.b * x)
end
res = find_cycle(Diffeomorphism(henon), [0.6, 0.2], (a = 1.4, b = 0.3))
res.y        # ≈ [0.631354, 0.189406]
res.eigvals  # ≈ [-1.923739, 0.155946]

trace_cycle(map, y0, params::NamedTuple, param_key::Symbol, end_value;
            period = 1, resolution = 100, show_progress = false, callback = nothing,
            kwargs...) -> Vector{ContinuationStep}

Continue a periodic point along a parameter: calls find_cycle at each point of a continuation of params[param_key] from its current value to end_value, starting each search from the previous periodic point. The info of each step holds :eigvals, :eigvecs, :nfev and :residual as in CycleResult. The remaining keyword arguments are forwarded to find_cycle.

trace_cycle_arclength(map, y0, params::NamedTuple, param_key::Symbol;
                      period = 1, direction = 1, bounds = nothing,
                      step = 0.01, step_min = 1e-6, step_max = 0.1, max_steps = 1000,
                      newton_tol = 1e-10, newton_max_iter = 10,
                      show_progress = false, callback = nothing) -> Vector{ContinuationStep}

Follow a branch of periodic points by pseudo-arclength continuation.

Unlike trace_cycle, which prescribes the parameter values, this continuation treats the periodic point and the parameter together as a point $u = (y, λ)$ on the curve $T^n(y, λ) - y = 0$ and advances along the curve itself, so folds (saddle-node bifurcations), where the branch turns back in $λ$, are passed and the continuation carries on along the other side. The tangent of the curve is the null vector of $[DT^n - I \mid ∂T^n/∂λ]$, available analytically from MapResult.jac and MapResult.jac_p.

Bifurcations along the branch are detected from sign changes between consecutive points and recorded in info[:events] of the later point:

• :fold: the tangent's parameter component changes sign;
• :branch_point: $\det(DT^n - I)$ changes sign without a fold (transcritical or pitchfork; the continuation follows one branch);
• :period_doubling: $\det(DT^n + I)$ changes sign;
• :neimark_sacker: a complex pair of multipliers crosses the unit circle.

direction (+1: $λ$ increasing first) and bounds ((lo, hi) on $λ$) work as in arclength_continuation, as do step, step_min, step_max, max_steps, newton_tol and newton_max_iter. Each step's info holds :eigvals, :eigvecs, :tangent (unit vector in the $(y, λ)$ space), :step, :newton_iterations and :events.

Examples

The fixed point of y ↦ y + p - y² exists for p ≥ 0 only; both fixed points ±√p lie on one curve that folds at p = 0:

f = Mapping((y, p) -> y[1] + p.p - y[1]^2, 1)
steps = trace_cycle_arclength(Diffeomorphism(f), [0.5], (p = 0.25,), :p;
    direction = -1, step = 0.05, step_max = 0.1, bounds = (-1.0, 0.25))
any(:fold in s.info[:events] for s in steps)         # true
steps[end].y[1] < 0 && steps[end].params.p > 0       # true: the lower branch

LocalBfResult

Result of find_local_bf. Fields: success, retcode, y (periodic point at the bifurcation), eigvals, eigvecs, nfev, residual ($T^n(y) - y$ followed by the real and imaginary parts of $\det(DT^n(y) - e^{iθ} I)$ at the last iterate), params (the parameters with the bifurcation parameter at its solved value) and theta (argument of the critical multiplier). y, eigvals, eigvecs, params and theta are nothing on failure.

find_local_bf(map, y0, params::NamedTuple, param_key::Symbol, theta;
              period = 1, alg = SimpleTrustRegion(), abstol = 1e-10, reltol = 1e-10,
              maxiters = 100, kwargs...) -> LocalBfResult

Find a local bifurcation point of a periodic point.

A periodic point $y$ of period $n$ undergoes a local bifurcation when one of its characteristic multipliers crosses the unit circle at $μ = e^{iθ}$. The unknowns $(y, λ, θ)$, with $λ$ = params[param_key], are solved from

\[T^n(y) - y = 0, \qquad \det(DT^n(y) - e^{iθ} I) = 0,\]

the determinant being split into its real and imaginary parts. The initial theta selects the kind of bifurcation: 0 ($μ = 1$) a tangent (saddle-node) bifurcation, pi ($μ = -1$) a period-doubling bifurcation, any other value a Neimark–Sacker bifurcation (a complex pair $e^{±iθ}$ on the unit circle). The Jacobian of the system is supplied analytically from the map's jac, hes, jac_p and hes_p. The nonlinear solver and its options are as in find_cycle.

trace_local_bf(map, y0, params::NamedTuple, bf_param_key::Symbol, theta,
               cnt_param_key::Symbol, end_value; period = 1, resolution = 100,
               show_progress = false, callback = nothing, kwargs...) -> Vector{ContinuationStep}

Continue a local bifurcation along a second parameter: params[cnt_param_key] is swept from its current value to end_value, and at each point find_local_bf solves for the periodic point, params[bf_param_key] and θ, starting from the previous solution. The result traces a bifurcation curve in the (cnt_param_key, bf_param_key) plane. Each step's y is the periodic point, params holds both parameters and info holds :theta, :eigvals, :eigvecs, :nfev and :residual. The two keys must differ.

trace_local_bf_arclength(map, y0, params::NamedTuple, bf_param_key::Symbol, theta,
                         cnt_param_key::Symbol; period = 1, direction = 1, bounds = nothing,
                         step = 0.01, step_min = 1e-6, step_max = 0.1, max_steps = 1000,
                         newton_tol = 1e-10, newton_max_iter = 10,
                         show_progress = false, callback = nothing) -> Vector{ContinuationStep}

Follow a local-bifurcation curve by pseudo-arclength continuation.

The bifurcation conditions of find_local_bf are $d + 2$ equations in the $d + 3$ unknowns $u = (y, λ_{bf}, θ, λ_{cnt})$, so their solutions form a curve: the bifurcation curve in the $(λ_{cnt}, λ_{bf})$ plane together with the periodic point and the argument of the critical multiplier. The curve is followed with arclength_continuation, so it may turn back in $λ_{cnt}$ (as a fold curve does at a cusp) without stopping. The Jacobian of the system is fully analytic.

Events between consecutive points are recorded in info[:events] of the later point: :fold (the curve turns back in $λ_{cnt}$; for a fold curve this happens at a cusp), :resonance_1_1, :resonance_1_2, :resonance_1_3, :resonance_1_4 (on a Neimark–Sacker curve, $θ$ passes $0$, $π$, $2π/3$ or $π/2$) and :second_multiplier_crossing (the number of multipliers outside the unit circle changes, i.e. another bifurcation curve is crossed). Each step's info also holds :theta, :eigvals, :eigvecs, :tangent (unit vector in the $u$ space), :step and :newton_iterations. direction and bounds refer to $λ_{cnt}$.

Examples

The cusp normal form x ↦ x + l1 + l2 x - x³ has the fold curve l2 = 3x², l1 = -2x³, which turns back in l2 at the cusp (0, 0):

cusp = Mapping((x, p) -> x[1] + p.l1 + p.l2 * x[1] - x[1]^3, 1)
steps = trace_local_bf_arclength(Diffeomorphism(cusp), [0.5], (l1 = -0.25, l2 = 0.75), :l1, 0.0, :l2;
    direction = -1, step = 0.1, step_max = 0.2, bounds = (-1.0, 0.75))
any(:fold in s.info[:events] for s in steps)           # true
steps[end].y[1] < 0 && steps[end].params.l1 > 0        # true: the lower branch

ArclengthPoint

One accepted point of arclength_continuation: the point u on the solution curve (length m + 1), the unit tangent of the curve at u in the direction of travel, the arclength step that led to this point (0 for the first point) and the newton_iterations the corrector needed.

ContinuationStep(y, params, info)

One successful step of a parameter continuation: the continued variable y, the parameters params (a NamedTuple) at this step and extra data info (a Dict{Symbol, Any}, empty if none) returned by the step function.

StepFunctionResult(success, y = nothing, params = nothing, info = nothing)

Return value of a step function passed to continuation. The continuation stops at the first step with success == false or y === nothing. params replaces the parameters for the following steps (e.g. with a solved parameter updated); info is stored in ContinuationStep.

arclength_continuation(fun, u0; step = 0.01, step_min = 1e-6, step_max = 0.1,
                       max_steps = 1000, direction = 1, bounds = nothing,
                       newton_tol = 1e-10, newton_max_iter = 10, callback = nothing)

Follow a solution curve of $F(u) = 0$ by pseudo-arclength continuation.

fun(u) returns the residual $F(u)$ (length m) and its Jacobian (m × (m + 1)); $F : \mathbb{R}^{m+1} \to \mathbb{R}^m$ has a one-dimensional zero set. Starting from u0 (first corrected onto the curve with its last component held fixed), each step predicts $u = u_k + h t_k$ along the unit tangent $t_k$ and corrects it with Newton's method on the bordered system $F(u) = 0$, $t_k \cdot (u - u_k) = h$, whose Jacobian $[J; t_k^T]$ is regular even where $J$ loses rank in the parameter direction, so folds are passed without special treatment (Keller, 1977). The step grows by 1.5 when Newton converges in at most three iterations, is halved when six or more are needed or when it fails, and the orientation is kept by requiring $t_k \cdot t_{k+1} > 0$.

The last component of u is the parameter-like coordinate used by direction (+1 to start with it increasing, -1 decreasing) and bounds ((lo, hi): stop when it would leave the interval; the last step is shortened so that the final point lies close to the boundary). fun may throw a MappyError, a SingularException or a DomainError to signal that u is not evaluable; the step is then retried with a smaller h. The continuation stops when bounds are left, max_steps is reached, the step cannot be reduced below step_min, or the curve closes on itself; it throws an ErrorException if u0 cannot be corrected onto the curve.

The arclength is measured in the Euclidean metric of u; if the state and the parameter have very different scales, rescale the parameter in fun. For maps built on ODE solves, the noise floor of the map limits the accuracy the corrector can reach: use solver tolerances well below newton_tol (e.g. reltol = 1e-8, abstol = 1e-10) or raise newton_tol.

Examples

circle(u) = ([dot(u, u) - 1.0], permutedims(2u))
pts = arclength_continuation(circle, [1.0, 0.0]; step = 0.3, step_max = 0.3)
all(abs(dot(p.u, p.u) - 1) < 1e-9 for p in pts)  # true; stops after one turn

continuation(fun, y0, params::NamedTuple, param_key::Symbol, end_value;
             resolution = 100, show_progress = false, callback = nothing)

Continue the solution of a step function along a parameter.

params[param_key] is swept linearly from its current value to end_value in resolution points, both ends included. At each point fun(y, p) is called, where y and p are those of the previous successful step (y0 and params at the first point) with p[param_key] set to the current value; it must return a StepFunctionResult. The sweep stops at the first unsuccessful step. callback is called with each successful ContinuationStep; show_progress prints one status line per step to stderr.

Examples

step(y, p) = StepFunctionResult(true, sqrt(p.p))
steps = continuation(step, 1.0, (p = 1.0,), :p, 4.0; resolution = 4)
[(s.params.p, s.y) for s in steps]  # (1.0, 1.0), (2.0, 1.414…), (3.0, 1.732…), (4.0, 2.0)

LineStyle(; color = :black, alpha = 0.3)

Color (any Makie color) and opacity of plotted lines or markers.

PlotConfig(; kwargs...)

Configuration of plot2d. Keyword arguments and defaults:

• only_map = false: draw only the image points, not the trajectories;
• figsize = (600, 600): figure size in pixels;
• xlabel = "x", ylabel = "y": axis labels;
• xlim = (-3.0, 3.0), ylim = (-3.0, 3.0): axis limits;
• xkey = 1, ykey = 2: indices of the state components on the axes;
• linewidth = 1.0, markersize = 4.0: trajectory line width and marker size;
• param_keys = Symbol[], param_index = 1, param_step = 0.1: parameters that can be changed with the up/down keys, the one selected first and the increment of one key press;
• scalar_axis = :x: for one-dimensional maps, the axis whose coordinate becomes the state when the figure is clicked;
• trajectory_style, point_style, click_style: a LineStyle, or for the first two a Dict{Symbol, LineStyle} with one style per mode name (the key :_default is used for modes not listed).

plot2d(map, y0, p = nothing, config = PlotConfig(); mode = nothing,
       frames = nothing, show = true) -> Figure

Iterate a map and draw its orbit (Python: mappy_ds.plot.plot2d). Requires a Makie backend. Each frame computes one iteration of map from the current state and draws the trajectory segments (unless config.only_map) and the image point.

With frames = n the figure is built non-interactively from n iterations and returned (use it with CairoMakie to save a picture). Otherwise the figure keeps iterating (one iteration per rendered frame, GLMakie) and reacts to the user:

• mouse click: restart from the clicked coordinates (for a one-dimensional state the coordinate on config.scalar_axis);
• space or e: clear the axis;
• f: toggle drawing the trajectories;
• p: select the next parameter of config.param_keys;
• up/down: change the selected parameter by config.param_step.

mode starts a PoincareMap in another mode than its initial_mode; later iterations continue from the mode each image ends in. show = false skips display(fig).

plot_trajectory(trajectory; ax = nothing, xkey = 1, ykey = 2,
                styles = LineStyle(; color = :black, alpha = 1.0), linewidth = 1.0) -> Axis

Draw a Trajectory onto a Makie Axis (a new figure is created if ax is omitted; Python: mappy_ds.plot.plot_trajectory). Segments whose dimension is too small to contain xkey and ykey are skipped. styles is a LineStyle or a Dict{Symbol, LineStyle} with one style per mode name (:_default for the others). Requires a Makie backend.

DerivativeError(fun, msg)

A system function could not be differentiated with ForwardDiff (Python: SymbolicEvaluationError). Typical causes are element types fixed to Float64 in the user function or operations that are not differentiable.

MappyError <: Exception

Base type of all errors raised deliberately by MappyDS, so callers can catch the whole family at once (Python: mappy_ds.MappyError).

ModeNotTerminatedError(mode, max_interval)

A continuous mode reached max_interval without hitting a border.

TransitionError(mode; border=nothing, reason=nothing)

The transition rules of a Poincaré map are inconsistent (missing rule, wrong number of entries, unknown border name, mismatched dimensions, no reachable end mode), or a mode ended through a border that has no successor.

UnknownModeError(name)

A mode name does not appear in the mode set of a Poincaré map.