Metadata-Version: 2.4
Name: bifpack
Version: 0.1.0
Summary: A Python interface to BIFPACK, R. Seydel's Fortran package for continuation, bifurcation, and stability analysis.
Author: Dr. Rüdiger Seydel
Author-email: Balbir Thomas <balbir.thomas@gmail.com>
Maintainer-email: Balbir Thomas <balbir.thomas@gmail.com>
License-Expression: GPL-2.0-or-later
Project-URL: Homepage, https://github.com/balbirthomas/bifpack
Project-URL: Repository, https://github.com/balbirthomas/bifpack
Project-URL: Issues, https://github.com/balbirthomas/bifpack/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Fortran
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# 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.

```python
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.
