mappy_ds.root.trace_cycle_arclength#

mappy_ds.root.trace_cycle_arclength(diffeo, y0, params, param_key, *, period=1, direction=1, bounds=None, step=0.01, step_min=1e-06, step_max=0.1, max_steps=1000, show_progress=False, callback=None)#

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 = (\bm y, \lambda)\) on the curve \(T^n(\bm y, \lambda) - \bm y = 0\) and advances along the curve itself, so folds (saddle-node bifurcations), where the branch turns back in \(\lambda\), 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 \partial T^n/\partial\lambda]\), 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ⁿ - I) changes sign without a fold (transcritical or pitchfork; the continuation follows one branch);

  • "period_doubling" — det(DTⁿ + I) changes sign;

  • "neimark_sacker" — a complex pair of multipliers crosses the unit circle.

Refine an event with find_local_bf(), starting from either of the two points and theta = 0 (fold), pi (period doubling) or the argument of the critical pair (Neimark–Sacker).

Parameters:
diffeoMap

The map.

y0array_like

Initial guess of the periodic point at params.

paramsmapping

Initial parameters; not modified.

param_keystr

Key of the continuation parameter \(\lambda\).

periodint, optional

Period of the cycle, by default 1.

directionint, optional

+1 to start with \(\lambda\) increasing, -1 decreasing; by default 1.

boundstuple of float, optional

Stop when \(\lambda\) leaves [lo, hi].

step, step_min, step_maxfloat, optional

Initial, minimum and maximum arclength step in the \((\bm y, \lambda)\) space; see arclength_continuation().

max_stepsint, optional

Maximum number of points after the first, by default 1000.

show_progressbool, optional

Print one line per accepted point to standard error.

callbackcallable, optional

Called with each accepted ContinuationStep.

Returns:
list of ContinuationStep

One step per accepted point, in order along the curve. y is the periodic point, params holds the parameter value, and info holds eigvals, eigvecs, tangent (unit vector in the \((\bm y, \lambda)\) space), step, newton_iterations and events.

Raises:
ValueError

If the map does not depend on param_key.

See also

trace_cycle

Natural-parameter continuation at prescribed values.

mappy_ds.continuation.arclength_continuation

The underlying algorithm.

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. Starting on the upper branch with p decreasing, the continuation passes the fold and comes back along the lower branch:

>>> import numpy as np
>>> from mappy_ds import Diffeomorphism, mapping
>>> from mappy_ds.root import trace_cycle_arclength
>>> @mapping(1)
... def f(y, p):
...     return y + p["p"] - y**2
>>> 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[-1].y[0] < 0 and steps[-1].params["p"] > 0
True