Metadata-Version: 2.4
Name: bifpy
Version: 0.3.0
Summary: A Python interface to the Auto-07p continuation and bifurcation analysis software
Author-email: Balbir Thomas <balbir.thomas@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/balbirthomas/bifpy
Project-URL: Repository, https://github.com/balbirthomas/bifpy
Project-URL: Bug Tracker, https://github.com/balbirthomas/bifpy/issues
Keywords: auto-07p,bifurcation-analysis,numerical-continuation,dynamical-systems,boundary-value-problem,ordinary-differential-equations
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: sympy
Provides-Extra: views
Requires-Dist: pyvista; extra == "views"
Requires-Dist: imageio-ffmpeg; extra == "views"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pyvista; extra == "test"
Requires-Dist: imageio-ffmpeg; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Dynamic: license-file

# bifpy

![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)
![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)

bifpy is a Python interface to [Auto-07p](https://github.com/auto-07p/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`](examples/auto).
- **A full user manual.** Tutorial and reference documentation under
  [`docs/`](docs), built with Sphinx.

## Installation

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

| Platform | Prerequisites |
| --- | --- |
| Linux | `gfortran` and GNU Make (already the platform's default `make`) from the system package manager, e.g. `apt install gfortran make` on Debian/Ubuntu. |
| macOS | `gfortran` via Homebrew (`brew install gcc`); GNU Make comes with Xcode's Command Line Tools as `/usr/bin/make`. |
| Windows | `gfortran` and GNU Make via a MinGW/MSYS2 install. MSVC cannot compile Fortran, so a MinGW-family toolchain is required regardless. |

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:

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

## Quick start

```python
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](docs/tutorial) for a full walkthrough of this example, and
[`examples/auto`](examples/auto) for one worked example per Auto-07p
demo.

## Documentation

The full Sphinx user manual lives under [`docs/`](docs). Build it
locally with:

```sh
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`](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](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`](auto/README.md) for how); `LICENSE` also reproduces
that engine's own copyright notice.
