PyCoBi.utility

Module that contains utility functions for results extraction from parameter continuation objects.

pycobi.utility.fractal_dimension(lyapunov_exponents: list) → float[source]

Calculates the fractal or information dimension of an attractor of a dynamical system from its lyapunov epxonents, according to the Kaplan-Yorke formula (Kaplan and Yorke, 1979).

Parameters:

lyapunov_exponents – List containing the lyapunov spectrum of a solution of a dynamical system.

Returns:

Fractal dimension of the attractor of the system.

Return type:

float

pycobi.utility.get_branch_info(branch: Any) → tuple[source]

Extract the branch id and continuation parameter(s) from an auto-07p solution branch object.

Three call shapes are supported, tried in order:

  1. bifDiag (auto’s top-level multi-branch container) — read .BR / .c[‘ICP’] from the first sub-branch.

  2. A single branch object indexed by ‘BR’ with its own .c config.

  3. An IVP-style nested structure where the BR field is buried under an ‘RG’ (regular point) label on the first sub-branch. The previous implementation walked the first 10 label indices and re-raised whichever KeyError happened last; now we iterate the keys explicitly and, on exhaustion, raise a single KeyError naming every key that was tried.

Returns:

(branch_id, icp) where icp is a tuple of one or more PAR indices.

Return type:

tuple

pycobi.utility.get_lyapunov_exponents(eigenvals, period) → list[source]

Calculate Lyapunov exponents from eigenvalues/floquet multipliers.

Parameters:

  • eigenvals – Eigenvalue or floquet multiplier spectrum.

  • period – Period of the periodic solution, if eigenvals is a Floquet multiplier spectrum of a periodic solution.

Returns:

Local Lyapunov exponent spectrum.

Return type:

list

pycobi.utility.get_point_diagnostics(s: Any) → str[source]

Return the Auto-07p string that contains diagnostic data for a particular solution.

Parameters:

s – Solution object on the branch.

Returns:

String with solution diagnostics.

Return type:

str

pycobi.utility.get_point_idx(diag: list, point: int) → int[source]

Extract list idx of correct diagnostics string for continuation point with index point.

Parameters:

  • diag – Diagnostics as stored by auto on solution objects.

  • point – Index of the solution of interest on the branch.

Returns:

Point index for diag.

Return type:

int

pycobi.utility.get_solution_eigenvalues(s: Any, branch: int | None = None, point: int | None = None) → list[source]

Return eigenvalues (or Floquet multipliers, for periodic solutions) of a point.

Thin wrapper around parse_point_diagnostics. The branch and point arguments are kept for backward compatibility but are no longer used — parse_point_diagnostics reads the diagnostic block via s.b.branch / s.b.idx directly.

pycobi.utility.get_solution_keys(branch: Any) → List[str][source]

Extract the names of all solutions on a branch.

Parameters:

branch – Solution branch object as returned by auto.

Returns:

List with solution names.

Return type:

List[str]

pycobi.utility.get_solution_params(s: Any, params: list) → list[source]

Extract parameter values from a solution object.

Parameters:

  • s – Solution object as returned by auto.

  • params – Keys of the parameters to be extracted.

Returns:

List of parameter values.

Return type:

list

pycobi.utility.get_solution_stability(s: Any) → bool[source]

Return stability of a solution.

Thin wrapper around parse_point_diagnostics — when extracting multiple diagnostic fields for the same point, call parse_point_diagnostics once and reuse its dict to avoid re-parsing the text.

pycobi.utility.get_solution_variables(s: Any, variables: list, extract_time: bool = False) → list[source]

Extract state variable values (time series) from a steady-state (periodic) solution object.

Parameters:

  • s – Solution object as returned by auto.

  • variables – Keys of the state variables to be extracted.

  • extract_time – If true, attempt to extract a time vector as well.

Returns:

List of variable values/time series of the provided solution.

Return type:

list

pycobi.utility.parse_point_diagnostics(s: Any, diag: str | None = None) → dict[source]

Parse the auto-07p per-point diagnostic text block into structured fields.

Used as a one-shot parser by get_solution_stability and get_solution_eigenvalues so multi-metric summaries (_create_summary with stability + eigenvalues + lyapunov) only pay the regex cost once per point.

Parameters:

  • s – Solution object as returned by auto-07p.

  • diag – Optional pre-fetched diagnostic text for s (skips the get_point_diagnostics(s) lookup). Pass this when the caller already has the text, e.g. when iterating multiple points and batching the fetch.

Returns:

stable bool or None — True if the solution is stable. None if

no Eigenvalues/Multipliers line is present AND auto’s PT-sign convention can’t be read from s.b.

eigenvalues list[complex] — eigenvalues (equilibrium continuation)

or Floquet multipliers (limit-cycle continuation), in the order auto-07p emits them. Empty if the point did not converge or no spectrum is recorded.

text str — the raw diagnostic block (kept for callers that

still need to grep for things this parser doesn’t surface, e.g. Hopf/Fold/BP function values).

Return type:

dict with keys

pycobi.utility.write_auto_dat(df: DataFrame, path: str | Path, *, columns: Iterable | None = None, n_points: int | None = None, period: float | None = None, normalize_time: bool = True) → Path[source]

Write a time-series DataFrame as an auto-07p .dat file.

Auto-07p reads .dat files via the dat= argument of its python run() command to initialise periodic-orbit continuations from a user-supplied time series (one column of time + one column per state variable, whitespace-separated). This helper writes such a file from a pandas.DataFrame — most commonly the output of pyrates.CircuitTemplate.run(), but any time-indexed numeric DataFrame works.

Parameters:

  • df – Time-indexed DataFrame. The index is interpreted as time; columns hold the state variables. A MultiIndex on columns is fine — every column entry survives into the output file in the order encountered (or the order given by columns).

  • path – Output file path. A .dat suffix is appended if missing.

  • columns – Optional subset of columns to write, in the order they should appear. Defaults to every column of df.

  • n_points – If given, linearly interpolate the time series onto this many evenly-spaced points before writing. Useful when the simulation produced more samples than auto-07p needs, or to ensure a regular mesh from an adaptive solver. Defaults to writing every input row.

  • period – Length (in the same units as the index) of one period of the orbit the file represents. Only consulted when normalize_time=True. Defaults to df.index[-1] - df.index[0] — i.e. assumes the DataFrame already covers exactly one period.

  • normalize_time – When True (default), shift the time column so it starts at 0 and divide by period so it ends at 1. Auto-07p’s default convention is a normalised [0, 1] mesh and the orbit’s actual period lives in PAR(11); turn this off only if the consuming workflow expects raw simulation time.

Returns:

The (possibly suffix-extended) path the file was written to.

Return type:

pathlib.Path

Notes

Recipe for hooking the file into a periodic-orbit continuation:

write_auto_dat(sim_df, 'orbit')                 # → orbit.dat
ode = ODESystem.from_template(template, ..., auto_constants=('lc',))
sols, cont = ode.run(c='lc', ICP=['eta', 11], dat='orbit', name='lc0')

The dat='orbit' argument tells auto-07p to read orbit.dat as the starting time series; ICP=['eta', 11] puts the orbit’s period in PAR(11) so it varies along the continuation.