bifpy

bifpy is a Python interface to Auto-07p, continuation and bifurcation software for ordinary differential equations. Given an algebraic system f(u, p) = 0, or a system of ordinary differential equations u'(t) = f(u(t), p), subject to one or more free parameters p, Auto-07p follows ("continues") families of solutions as a parameter is varied, and locates and classifies the bifurcation points encountered along the way (folds, branch points, Hopf bifurcations, period doublings, and so on). The same boundary value algorithms used for ODEs also let Auto-07p analyse periodic and connecting (homoclinic/heteroclinic) orbits, and certain stationary and travelling wave solutions of parabolic partial differential equations.

Auto-07p itself is implemented in Fortran and normally expects models to be written in Fortran or C. bifpy instead lets a model be written as ordinary Python functions, using the same argument conventions as SciPy, and visualised with Matplotlib or PyVista.

Features

• Full problem-type coverage. Every one of Auto-07p's own problem types - equilibria, periodic orbits, general boundary value problems, homoclinic/heteroclinic connections, parabolic PDEs, optimization, and more - is available through bifpy.auto.
• A direct, thin binding. bifpy talks to Auto-07p's Fortran routines straight through Python's built-in ctypes module - no generated wrapper code, no third-party binding tool.
• A fast, native-execution path. Passing transpile=True compiles a model straight to a standalone Auto-07p executable via symbolic tracing, instead of interpreting it through Python callbacks - typically far faster for models whose own residual evaluation dominates run time, and able to derive exact analytic Jacobians automatically.
• Built-in visualization. Static 2D/3D bifurcation and solution diagrams (bifpy.diagrams, Matplotlib-based), and an interactive 3D viewer for dense solution families (bifpy.views, PyVista-based).
• 72 worked examples. Every demo shipped with Auto-07p itself, ported to bifpy one-for-one - see examples/auto.
• A full user manual. Tutorial and reference documentation under docs/, built with Sphinx.

Installation

pip install bifpy

bifpy has no prebuilt wheels yet: installing it compiles the vendored Auto-07p Fortran engine from source, so gfortran (GNU Fortran) and GNU Make must already be available on the system.

A POSIX/BSD make will not work: auto/Makefile relies on several GNU-only extensions.

For local development, install from a source checkout in editable mode instead:

git clone https://github.com/balbirthomas/bifpy
cd bifpy
pip install -e .

Quick start

from bifpy import auto

def equation(state, parameters):
    return [state[0] ** 2 - parameters[0]]

def starting_point(state, parameters, normalized_time):
    state[0] = 1.0
    parameters[0] = 1.0

settings = dict(
    ips=auto.IPS_ALGEBRAIC_SYSTEM,
    ndim=1, npar=1, nmx=100,
    ntst=20, ncol=4, iad=3,
    ilp=1, isp=2, iads=1, itmx=9, itnw=5, nwtn=3, jac=0,
    ds=0.1, dsmin=0.001, dsmax=0.5,
    rl0=0.0, rl1=10.0, a0=-1e300, a1=1e300,
    epsl=1e-7, epsu=1e-7, epss=1e-5,
)
result = auto.run(equation, starting_point, settings, icu=[1])
for point in result.branches[0].points:
    print(point.parameters[0], point.state[0])

This continues the family of solutions of f(u, p) = u² − p = 0 as p varies, starting from (u, p) = (1, 1). See the tutorial for a full walkthrough of this example, and examples/auto for one worked example per Auto-07p demo.

Documentation

The full Sphinx user manual lives under docs/. Build it locally with:

pip install bifpy[docs]
sphinx-build docs docs/_build/html

Repository layout

• src/bifpy/ - the Python package.
• auto/ - the vendored Auto-07p Fortran engine (src/, include/, depends/), plus capi/, the bind(c) shim written for this project that gives bifpy's ctypes layer a C-ABI-safe entry point into it. auto/update refreshes the vendored code from an upstream Auto-07p clone; see auto/README.md.
• tests/ - the regression test suite.
• examples/auto/ - one runnable example per Auto-07p demo.
• docs/ - the Sphinx user manual's sources.

Platform support

bifpy runs every Auto-07p continuation in a dedicated subprocess (see bifpy.auto._process's own module docstring for why, and for the full platform rationale summarised here). How that subprocess is started differs by platform:

• Linux (bifpy's primary development platform): a model's callbacks (func, stpnt, pvls, bcnd, icnd, fopt) may be any Python callable - a plain function, a lambda, a closure, or a function defined directly in a Jupyter notebook cell.
• macOS and Windows: each callback must instead be a plain, top-level function defined in an importable module - not a lambda, not a closure, and not a function defined directly in a notebook cell (define it in a separate .py module and import it instead). Windows has no alternative here (there is no fork() on Windows at all); macOS could use fork() too, but doesn't, matching Python's own default start method there since 3.8.

The macOS and Windows code paths have not yet been exercised on real macOS/Windows machines - only on Linux, by forcing the same "spawn"-based mechanism those platforms use (see tests/test_multiprocessing_context.py). Testing on those platforms directly is deferred.

License

bifpy is distributed under the BSD 3-Clause License - see LICENSE. This is the same license as Auto-07p's own Fortran engine, a portion of which bifpy vendors under auto/ (see auto/README.md for how); LICENSE also reproduces that engine's own copyright notice.