PyCoBi.automated_continuation

Module that contains functions for automated parameter continuation / bifurcation analysis routines.

Automated multi-step continuations and codimension-2 searches.

These helpers wrap ODESystem.run with bookkeeping for two common patterns:

  • continue_period_doubling_bf: chase a period-doubling cascade in two parameters, recursing on every new PD point encountered.

  • codim2_search: 2-parameter continuation of a codim-1 starting point with optional recursion into codim-2 points (ZH / GH / BT).

Stability note

These are convenience wrappers around the lower-level ODESystem.run API. Recursive codim-2 searches depend on the underlying auto-07p run producing the expected branch structure; on unfamiliar models you should validate the results against a manual run before trusting them. The implementations follow standard auto-07p conventions for switching between equilibrium / limit-cycle / fold continuations, but they cannot guarantee numerical stability across all model families. Sub-runs that fail with an exception inside ODESystem.run will be reported via UserWarning rather than abort the whole search.

Continue codim-1 bifurcation points in 2 parameters with recursive handling of codim-2 points along each curve.

For every entry in starting_points (typically auto-07p labels like 'LP1', 'HB1', 'PD1'), run a 2-parameter continuation in params. Then walk the resulting curve for codim-2 points and, for each new one, perform the appropriate switch-and-continue:

  • ZH (zero-Hopf): 1D equilibrium continuation in params[0] stopping at the nearest fold or Hopf, then recursive 2D continuation of that codim-1 point.

  • GH (generalized Hopf / Bautin): switch to LC continuation in params[0] and PAR(11) (period), looking for a fold-of-cycles (LP) that, if found, is recursively continued in 2 parameters via the LC route.

  • BT (Bogdanov-Takens): 1D equilibrium continuation from BT stopping at the nearest Hopf, then 2D continuation of the resulting Hopf curve. Does not follow the homoclinic curve emerging from BT (that requires HomCont params with IPS=9; see auto-07p docs).

The list of recognised codim-2 types can be narrowed via codim2_types — e.g. pass ('ZH',) to suppress GH/BT recursion entirely.

Failures during sub-continuations are surfaced as UserWarning rather than propagated, on the assumption that a search across many points should tolerate individual misfires.

Parameters:

  • params – Two-element list of continuation parameter identifiers (int PAR indices or string names; see _resolve_param_for_extract).

  • starting_points – Codim-1 auto-07p labels (e.g. ['LP1', 'HB1']) to start from.

  • origin – Origin continuation key on which the starting points live.

  • pyauto_instance – The active ODESystem.

  • max_recursion_depth – Maximum codim-2 recursion depth. Default 3.

  • recursion – Internal recursion counter; do not set directly.

  • periodic – If true, the initial continuation is run with IPS=2, ISW=2 (limit-cycle 2-parameter continuation); use this when the starting point sits on a limit-cycle branch (e.g. a PD or fold-of-cycle).

  • kwargs_2D_lc_cont – Extra kwargs merged into the 2D LC continuation (periodic=True).

  • kwargs_2D_cont – Extra kwargs merged into the 2D equilibrium continuation (periodic=False).

  • kwargs_1D_lc_cont – Extra kwargs merged into the 1D LC continuation triggered by a GH point.

  • precision – Decimal places used to dedupe codim-2 points along the curve.

  • codim2_types – Tuple of codim-2 bifurcation types to recurse on. Default ('ZH', 'GH', 'BT').

  • kwargs – Remaining keyword arguments forwarded to pyauto_instance.run.

Returns:

Mapping of continuation name to ODESystem continuation key for every run performed (the initial continuations plus every successful recursive sub-run).

Return type:

dict

pycobi.automated_continuation.continue_period_doubling_bf(solution, continuation: str | int | Any, pyauto_instance: ODESystem, icp, max_iter: int = 1000, _depth: int = 0, **run_kwargs) → tuple[source]

Chase a cascade of period-doubling bifurcations on a limit cycle.

Given a limit-cycle continuation with at least one PD (or BP as a fallback when no PD exists), branch-switch onto the new limit cycle at each PD/BP point and recurse on the resulting branch — the classic auto-07p PD-cascade workflow (see e.g. the lor demo, where successive runs of c.lor.2 / c.lor.3 branch-switch at PD1, PD2, … to track the period-doubling route to chaos).

The continuation parameters and switches are fixed by the PD-cascade semantics: IPS=2 (LC), ISW=-1 (branch switch onto the new limit cycle), ICP=[icp, 11] (the user-supplied 1D parameter plus PAR(11) for the period). Anything else (NMX, NPR, NTST, DS, DSMIN/DSMAX, UZSTOP, …) is forwarded via **run_kwargs.

Branching rules:

  • If the input LC has at least one PD label, branch-switch at every PD on the input.

  • If the input has no PD but at least one BP, branch-switch at the first BP only. The cascade is then continued only as long as a subsequent LC carries a PD (a BP-only continuation doesn’t extend, to avoid infinite BP→BP recursion).

  • If neither PD nor BP is present, return an empty list.

Recursion termination (per PyCoBi 1.0.x spec):

  • Branch-switched at a PD: recurse if the new LC has a new PD or a new BP.

  • Branch-switched at a BP: recurse only if the new LC has a new PD (a new BP alone is not enough).

Parameters:

  • solution – Summary of the LC continuation to inspect — either the pandas.DataFrame returned by ode.results[cont_key] or a literal {point_id: {'bifurcation': str}} dict (tests).

  • continuation – The LC continuation key used as origin for the branch-switch.

  • pyauto_instance – Active ODESystem.

  • icp – The single 1D continuation parameter (int PAR index or string name). Auto-07p needs ICP=[icp, 11] for LC continuation; the period (PAR 11) is appended automatically.

  • max_iter – Maximum recursion depth. Default 1000 (effectively unbounded).

  • run_kwargs – Forwarded to ODESystem.run() for each LC continuation step. Common keys: NMX, NPR, NTST, DS, DSMIN, DSMAX, UZSTOP.

Returns:

(continuation_names, pyauto_instance). continuation_names lists every LC continuation registered along the cascade, in depth-first execution order. Each step’s continuation is named pd_d{depth}_{label} (e.g. pd_d0_PD1, pd_d1_PD1, …).

Return type:

tuple