BIFPACK

BIFPACK is a Fortran 77 package for continuation, bifurcation, and stability analysis, written by Rüdiger Seydel. It is the companion software to his textbook Practical Bifurcation and Stability Analysis (3rd edition, Interdisciplinary Applied Mathematics vol. 5, Springer) — anyone working through that book can use the software in this repository exactly as the book and BIFPACK's own manual describe.

This repository provides two ways to use BIFPACK, side by side:

1. The original Fortran interface — build BIFPACK's libraries and example programs directly with the included Makefile, and write your own models as Fortran source compiled and linked against them. Start with examples/README.md; src/README.md, solvers/README.md and bin/README.md describe the rest of the Fortran source tree.
2. A Python interface — the same underlying BIFPACK Fortran engine, driven from ordinary Python model functions, with results as plain Python data. bifpack.algebraic (continuation and stability analysis of systems of algebraic equations), bifpack.periodic_orbits (periodic solutions of autonomous ODEs), and bifpack.boundary_value (two-point ODE boundary-value problems) are all complete and tested, along with bifpack.diagrams for plotting a result with Matplotlib — see docs/TODO.md for current status.

Both interfaces are built from, and drive, the same unmodified BIFPACK Fortran source under src//solvers/ — see AGENTS.md for the standing rule that this source is never edited, and docs/TODO.md for the Python interface's current status and design record.

Getting started (Fortran)

make static     # lib/libbifpack.a, lib/libbifsolv.a
make shared     # lib/libbifpack_a.so / _b.so / _d.so
make bin        # bin/bifpack-* post-processing utilities
make examples   # all ten documented example programs
make all        # all of the above

Requires gfortran and GNU Make. See examples/README.md for how to run an example once built, and how to write and build your own model.

Getting started (Python)

pip install bifpack

compiles BIFPACK's own Fortran source as part of the install (needs gfortran and GNU Make on your own machine - the only two requirements beyond Python itself and Matplotlib, both installed automatically) - no separate make capi step needed.

import bifpack.algebraic as algebraic

def f(y, par):
    return [y[0] ** 2 - par]  # y**2 - par = 0

result = algebraic.run(f, y0=[1.0], par0=1.0, step=0.1, max_steps=20)
branch = result.branches[0]
for point in branch.points:
    print(point.parameters[0], point.state[0], point.point_type)

Working from a checkout instead (contributing, or wanting the example Fortran programs too) - pip install . from the repository root does the same thing; or skip packaging entirely with make capi followed by PYTHONPATH=src.

Full documentation - a tutorial, a complete user guide, the API reference, and a developer's guide - lives under docs/ (Sphinx source) and builds with make docs (needs make capi first) into docs/_build/html/.

Repository layout

• src/ — BIFPACK's own core Fortran source (continuation and bifurcation analysis: algebraic equations, boundary-value problems, periodic solutions). See src/README.md.
• solvers/ — the generic numerical building blocks BIFPACK's core relies on (a Newton-type solver, a linear-equation solver, EISPACK eigenvalue routines, an ODE integrator and two alternative boundary-value solvers). See solvers/README.md.
• bin/ — standalone utilities for post-processing BIFPACK's own output-record files. See bin/README.md.
• examples/ — ten worked example models from the book, each showing how to write and build a BIFPACK model. See examples/README.md.
• docs/ — BIFPACK's own manual (manual.asc, plain text — the authoritative reference for every calling convention, option, and output-file format mentioned in this repository's own READMEs) and bifpack.ps; TODO.md records this repository's own reorganization and Python-interface design decisions, and current status.
• capi/ — a small Fortran bind(c) shim giving the Python interface a C-ABI-safe entry point into BIFPACK's own calling convention, without editing any upstream file (AGENTS.md's "Never Edit Upstream BIFPACK Source").
• src/bifpack/ — the Python package: results.py (backend-agnostic result data structures), algebraic//boundary_value// periodic_orbits/ (one sub-package per BIFPACK problem class, see docs/guide/problem-classes.rst), diagrams.py (plotting a result with Matplotlib).
• tests/ — the Python interface's own regression suite.
• pyproject.toml/setup.py/MANIFEST.in — the Python package's own packaging metadata and build step (setup.py's own custom build_py command compiles BIFPACK's own Fortran source as part of pip install - see its own module docstring).
• Makefile — builds everything above; see "Getting started" above and AGENTS.md for how it is organized (one shared library per documented file grouping, to avoid combining BIFPACK routines that were never meant to coexist in one binary).
• LICENSE — the license (GPL-2.0-or-later) covering both BIFPACK itself and bifpack; see also the disclaimer of warranty in docs/manual.asc.
• AGENTS.md — standing conventions for anyone (human or agent) working in this repository.

License

BIFPACK and bifpack are both distributed under the GNU General Public License; see the enclosed file LICENSE. Before first use, read docs/manual.asc, in particular its disclaimer of warranty.