xpplab 0.1.1__py3-none-win_amd64.whl

xpplab/__init__.py

@@ -0,0 +1,23 @@
+"""XPP Lab: XPPAUT's simulation and AUTO bifurcation engine for Python.
+
+    import xpplab as xs
+    m = xs.load("lecar.ode")
+    sol = m.run(total=100)
+    d = m.auto.equilibria("iapp")
+    d.special()
+
+The numerics are XPPAUT 8.0's own code, compiled into a native
+library. No Fortran or C compiler and no X11 server are needed.
+"""
+
+from ._engine import EngineError, find_engine_library
+from .analysis import Table
+from .animation import Animation
+from .auto import Diagram, Point
+from .model import METHODS, Equilibrium, Model, Trajectory, load
+
+__all__ = ["Model", "Trajectory", "Equilibrium", "Diagram", "Point", "Table", "Animation",
+           "EngineError", "METHODS", "load", "find_engine_library",
+           "__version__"]
+
+__version__ = "0.1.1"

xpplab/_docs/auto.md

@@ -0,0 +1,102 @@
+# Bifurcation analysis with AUTO
+
+A **bifurcation diagram** shows how the long-term behaviour of a system
+changes as one parameter varies: where equilibria appear, vanish or lose
+stability, and where oscillations are born. XPP Lab computes these
+diagrams with **AUTO** (E. Doedel), the same continuation code that XPPAUT
+embeds.
+
+## The idea in brief
+
+Pick a parameter, say a current `I`. AUTO starts from an equilibrium and
+follows it step by step as `I` changes. At each step it solves for the
+equilibrium and checks its stability. When something qualitative happens it
+marks a **special point**:
+
+| Label | Name | What happens |
+|---|---|---|
+| LP | limit point (fold, saddle-node) | Two equilibria meet and vanish; the branch turns back. |
+| HB | Hopf bifurcation | A pair of eigenvalues crosses the imaginary axis; periodic orbits are born. |
+| BP | branch point | Two branches cross (common with symmetry). |
+| PD | period doubling | An orbit loses stability to one of twice the period. |
+| TR | torus (Neimark-Sacker) | An orbit loses stability to quasi-periodic motion. |
+| LP (on orbits) | fold of limit cycles | Two periodic orbits meet and vanish. |
+| EP | end point | Where the computation stopped. |
+
+Stable parts are drawn solid, unstable parts dashed. The colours follow
+XPPAUT: steady states are red (stable) and black (unstable); periodic orbits
+are green (stable) and blue (unstable).
+
+## A typical session
+
+1. **Start at an equilibrium.** Run the model until it settles, or press
+   **Equilibrium**. **Follow steady states** also polishes the start point
+   with Newton's method, but AUTO needs to begin close to an equilibrium.
+2. **Choose the parameter** and its range (**Par min** and **Par max**).
+3. **Follow steady states.** The special points appear in the table and on
+   the plot.
+4. **Select a special point** (click it in the table or the plot) and choose
+   what to do from there:
+   - from **HB**: *Periodic orbits from this Hopf point*, or a two-parameter
+     curve of Hopf points;
+   - from **LP**: a two-parameter curve of folds;
+   - from **BP**: *Switch to the other branch*;
+   - from **PD**: the period-doubled branch.
+5. For two-parameter curves, choose the **2nd param.** first. The result
+   appears in the **Two parameters** tab.
+
+Try it: [open the Morris-Lecar model](example:lecar.ode), apply the `hopf`
+set (Workspace > Sets), then [follow the steady states in iapp](cmd:auto steady iapp).
+
+## Check the diagram with simulations
+
+**Workspace > Range** (XPPAUT's *Initial conds > Range*) runs the model
+once for each value of a parameter, and in *Max / min* mode records the
+maximum and minimum of a variable after a transient. When the parameter and
+the plotted variable match the Bifurcation window's, the results appear as
+grey dots on AUTO's diagram. They should sit on the stable branches: the
+solid red lines and the solid green ones. Where the system is bistable,
+different initial values land on different branches; tick *Start each run
+where the last ended* to follow one branch as the parameter moves.
+
+## The numerical settings
+
+| Setting | Meaning | Advice |
+|---|---|---|
+| Step DS | Size of the first step. **Its sign is the direction.** | Use a negative DS to explore towards smaller parameter values. |
+| DS min, DS max | Bounds on the adaptive step. | A smaller DS max gives smoother curves and fewer missed points. |
+| Par min, Par max | The parameter range. | AUTO stops at the edges. |
+| Max steps (NMAX) | Most steps per run. | A closed loop of orbits runs until NMAX: lower it to stop sooner. |
+| Label every (NPR) | Also label a point every N steps. | Labelled points can be continued from. |
+| Mesh NTST | Mesh intervals for periodic orbits. | Increase it (to 50 or 100) for spiky orbits such as action potentials. |
+
+## When things go wrong
+
+- **"AUTO computed no points"**: the start point is probably not an
+  equilibrium. Run the model to steady state first, or press Equilibrium.
+- **The branch stops early**: check Par min and Par max, and Norm max.
+  Then try a smaller DS max.
+- **Periodic orbits fail from a Hopf point**: increase NTST, or reduce DS.
+- **Points come out jagged**: reduce DS max.
+
+## Scripting the same analysis
+
+Every step is also available from the command window:
+
+```
+use hopf
+auto set ds=0.02 dsmax=0.05 parmax=0.6
+auto steady iapp
+auto from 2 periodic
+```
+
+and from Python:
+
+```
+import xpplab as xs
+m = xs.load("lecar.ode")
+m.apply_set("hopf")
+d = m.auto.equilibria("iapp")
+orbits = m.auto.continue_from(d.first("HB"), "periodic")
+m.auto.diagram.plot()
+```

xpplab/_docs/odefile.md

@@ -0,0 +1,88 @@
+# The .ode file format
+
+A model is a plain text file, usually ending in `.ode`. XPP Lab reads
+exactly the format of XPPAUT 8.0, so files written for XPPAUT work
+unchanged. Each statement goes on its own line, and the file ends with
+`done`. Upper and lower case are the same in names.
+
+## A complete example
+
+```
+# Lotka-Volterra predator-prey model
+x' = a*x - b*x*y
+y' = -c*y + d*x*y
+par a=1, b=0.5, c=0.75, d=0.25
+init x=2, y=1
+aux total = x + y
+@ total=50, dt=0.02, xp=x, yp=y, xlo=0, xhi=8, ylo=0, yhi=6
+done
+```
+
+## Equations
+
+| Form | Meaning |
+|---|---|
+| `x' = f` or `dx/dt = f` | A differential equation. |
+| `x(t+1) = f` | A map (difference equation); use method `discrete`. |
+| `x(t) = f` | A Volterra integral equation (`f` may contain `int{...}`). |
+| `0 = f` | An algebraic constraint (with `solv` variables: a DAE). |
+| `s = expression` | A fixed (intermediate) quantity, computed at each step. |
+| `aux name = expression` | An auxiliary output: plotted and saved, but not integrated. |
+
+## Declarations
+
+| Statement | Meaning |
+|---|---|
+| `par a=1, b=2` | Parameters. |
+| `init x=0.1, y=0` | Initial values (`x(0)=0.1` also works). |
+| `number pi2=6.2832` | A constant that cannot be changed while running. |
+| `f(u,v) = u^2 - v` | A user function, with up to 9 arguments. |
+| `!d = 2*a` | A derived parameter, recomputed when parameters change. |
+| `table g g.tab` | A function tabulated in a file. |
+| `wiener w` | A Wiener process for noise; use `euler` or `backeul`. |
+| `markov z 2` | A Markov chain variable with 2 states (transition table follows). |
+| `global 1 x-1 {x=0}` | An event: when `x-1` crosses zero upwards, reset `x=0`. |
+| `bdry x-1` | A boundary condition for boundary-value problems. |
+| `set name {a=2, total=50}` | A named parameter set. |
+| `#include file.inc` | Insert another file. |
+
+Arrays save typing: `x[1..10]' = -x[j] + x[j-1]` defines ten equations,
+with `j` running from 1 to 10.
+
+## Expressions
+
+Arithmetic: `+ - * / ^` and parentheses. Comparisons and logic
+(`< > <= >= == != & |`) give 1 or 0, so `(x>0)*x` is max(x, 0).
+
+Functions: `sin cos tan asin acos atan atan2 sinh cosh tanh exp ln log
+log10 sqrt abs heav sign mod max min flr ran normal besselj bessely erf erfc
+hom_bcs`, and `if(cond)then(a)else(b)`.
+
+Special terms: `t` is time. `delay(x, tau)` or `x(t-tau)` is a delayed
+value. `pi` is 3.14159...
+
+## Options (@ lines)
+
+Options set how the model runs. They can be combined on one line:
+`@ total=100, dt=0.05, meth=stiff`.
+
+| Option | Meaning |
+|---|---|
+| `total`, `dt`, `t0`, `trans` | Integration time, step, start time, transient to discard. |
+| `meth` | Method: `rungekutta`, `euler`, `modeuler`, `adams`, `gear`, `stiff`, `cvode`, `5dp`, `83dp`, `2rb`, `backeul`, `qualrk`, `volterra`, `ymp`, `discrete`. |
+| `tol`, `atol` | Relative and absolute tolerances of adaptive methods. |
+| `dtmin`, `dtmax` | Limits on the adaptive step. |
+| `bound` | Stop if a variable exceeds this size. |
+| `nout` | Store every n-th step. |
+| `maxstor` | Maximum number of stored points. |
+| `delay` | Maximum delay, for delay equations. |
+| `xp`, `yp`, `xlo`, `xhi`, `ylo`, `yhi` | The phase-plane variables and window. |
+| `nmesh` | Grid for nullclines. |
+| `poimap`, `poivar`, `poipln`, `poisgn` | Poincare sections. |
+| `ds`, `dsmin`, `dsmax`, `parmin`, `parmax`, `nmax`, `npr`, `ntst` | AUTO settings. |
+
+## Comments
+
+Lines starting with `#` are comments. The first comment lines of a file are
+shown as its description in the Models window, so describe your model there.
+Lines starting with `"` are XPPAUT's interactive tutorial text.

xpplab/_engine.py

@@ -0,0 +1,331 @@
+"""Low-level access to the XPPAUT engine library (engine/api/xppe.h).
+
+XPPAUT keeps its state in global variables, so one loaded copy of the
+engine library holds one model. Each Engine therefore loads its own private
+copy of the library file. The copies are independent: several models can
+be open at once, and closing one frees its memory.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import shutil
+import sys
+import tempfile
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+
+__all__ = ["Engine", "EngineError", "find_engine_library"]
+
+API_VERSION = 2
+
+OK = 0
+ERR_STATE = -1
+ERR_LOAD = -2
+ERR_FATAL = -3
+ERR_NAME = -4
+ERR_RANGE = -5
+ERR_NUMERIC = -6
+
+VARIABLES = 0
+PARAMETERS = 1
+COLUMNS = 2
+SETS = 3
+
+AUTO_U0 = 0
+AUTO_UMAX = 1
+AUTO_UMIN = 2
+AUTO_UMEAN = 3
+AUTO_EIG_RE = 4
+AUTO_EIG_IM = 5
+AUTO_PARAMS = 6
+
+_ERROR_NAMES = {
+    ERR_STATE: "state",
+    ERR_LOAD: "load",
+    ERR_FATAL: "fatal",
+    ERR_NAME: "name",
+    ERR_RANGE: "range",
+    ERR_NUMERIC: "numeric",
+}
+
+
+class EngineError(RuntimeError):
+    """An error reported by the XPPAUT engine.
+
+    ``log`` holds everything the engine printed during the failing call,
+    which usually explains the problem (for example a syntax error in the
+    model file).
+    """
+
+    def __init__(self, message: str, code: int = 0, log: str = ""):
+        super().__init__(message)
+        self.code = code
+        self.kind = _ERROR_NAMES.get(code, "error")
+        self.log = log
+
+    def __str__(self) -> str:
+        text = super().__str__()
+        if self.log.strip():
+            tail = "\n".join(self.log.strip().splitlines()[-12:])
+            text += "\n\nEngine output (last lines):\n" + tail
+        return text
+
+
+class AutoPointInfo(ctypes.Structure):
+    _fields_ = [
+        ("branch", ctypes.c_int),
+        ("point", ctypes.c_int),
+        ("type", ctypes.c_int),
+        ("label", ctypes.c_int),
+        ("stable", ctypes.c_int),
+        ("periodic", ctypes.c_int),
+        ("two_parameter", ctypes.c_int),
+        ("par1_slot", ctypes.c_int),
+        ("par2_slot", ctypes.c_int),
+        ("par1", ctypes.c_double),
+        ("par2", ctypes.c_double),
+        ("norm", ctypes.c_double),
+        ("period", ctypes.c_double),
+        ("type_name", ctypes.c_char * 4),
+    ]
+
+
+class AniItem(ctypes.Structure):
+    """One shape of an animation frame (xppe_ani_item in xppe.h)."""
+    _fields_ = [
+        ("shape", ctypes.c_int),
+        ("command", ctypes.c_int),
+        ("filled", ctypes.c_int),
+        ("x1", ctypes.c_double),
+        ("y1", ctypes.c_double),
+        ("x2", ctypes.c_double),
+        ("y2", ctypes.c_double),
+        ("color", ctypes.c_int),
+        ("level", ctypes.c_double),
+        ("thickness", ctypes.c_int),
+        ("trail", ctypes.c_int),
+        ("font_size", ctypes.c_int),
+        ("serif", ctypes.c_int),
+        ("text", ctypes.c_char * 128),
+    ]
+
+
+def _library_name() -> str:
+    if sys.platform == "win32":
+        return "libxppe.dll"
+    if sys.platform == "darwin":
+        return "libxppe.dylib"
+    return "libxppe.so"
+
+
+def find_engine_library() -> Path:
+    """Locate the engine library.
+
+    The XPPLAB_ENGINE environment variable wins. Otherwise use the copy
+    installed inside the package, then a development build in the
+    repository's build/ directory.
+    """
+    env = os.environ.get("XPPLAB_ENGINE")
+    if env:
+        return Path(env)
+    here = Path(__file__).resolve().parent
+    candidates = [here / "_lib" / _library_name()]
+    repo = here.parents[2]
+    candidates += [repo / d / "engine" / _library_name()
+                   for d in ("build", "build-release", "build-debug")]
+    for c in candidates:
+        if c.exists():
+            return c
+    raise EngineError(
+        "the XPP Lab engine library was not found; set XPPLAB_ENGINE "
+        "to the path of " + _library_name())
+
+
+_SIGNATURES = {
+    "xppe_api_version": ([], ctypes.c_int),
+    "xppe_version": ([], ctypes.c_char_p),
+    "xppe_load": ([ctypes.c_char_p, ctypes.c_int,
+                   ctypes.POINTER(ctypes.c_char_p)], ctypes.c_int),
+    "xppe_log": ([], ctypes.c_char_p),
+    "xppe_error": ([], ctypes.c_char_p),
+    "xppe_count": ([ctypes.c_int], ctypes.c_int),
+    "xppe_name": ([ctypes.c_int, ctypes.c_int], ctypes.c_char_p),
+    "xppe_get": ([ctypes.c_char_p, ctypes.POINTER(ctypes.c_double)],
+                 ctypes.c_int),
+    "xppe_set": ([ctypes.c_char_p, ctypes.c_char_p], ctypes.c_int),
+    "xppe_set_number": ([ctypes.c_char_p, ctypes.c_double], ctypes.c_int),
+    "xppe_apply_set": ([ctypes.c_char_p], ctypes.c_int),
+    "xppe_run": ([], ctypes.c_int),
+    "xppe_rows": ([], ctypes.c_int),
+    "xppe_column": ([ctypes.c_int, ctypes.POINTER(ctypes.c_double),
+                     ctypes.c_int], ctypes.c_int),
+    "xppe_equilibrium": ([ctypes.POINTER(ctypes.c_double)] * 3, ctypes.c_int),
+    "xppe_rhs": ([ctypes.c_double, ctypes.POINTER(ctypes.c_double),
+                  ctypes.POINTER(ctypes.c_double)], ctypes.c_int),
+    "xppe_manifold_count": ([], ctypes.c_int),
+    "xppe_manifold": ([ctypes.c_int, ctypes.POINTER(ctypes.c_int)], ctypes.c_int),
+    "xppe_fourier": ([ctypes.c_char_p], ctypes.c_int),
+    "xppe_power": ([ctypes.c_char_p], ctypes.c_int),
+    "xppe_spectrum": ([ctypes.c_int, ctypes.c_char_p, ctypes.c_char_p,
+                       ctypes.c_int, ctypes.c_int], ctypes.c_int),
+    "xppe_histogram": ([ctypes.c_char_p, ctypes.c_int, ctypes.c_double,
+                        ctypes.c_double, ctypes.c_char_p], ctypes.c_int),
+    "xppe_histogram2d": ([ctypes.c_char_p, ctypes.c_int, ctypes.c_double,
+                          ctypes.c_double, ctypes.c_char_p, ctypes.c_int,
+                          ctypes.c_double, ctypes.c_double], ctypes.c_int),
+    "xppe_autocorrelation": ([ctypes.c_char_p, ctypes.c_int, ctypes.c_double,
+                              ctypes.c_double], ctypes.c_int),
+    "xppe_correlation": ([ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int,
+                          ctypes.c_int], ctypes.c_int),
+    "xppe_mean": ([ctypes.c_char_p, ctypes.POINTER(ctypes.c_double),
+                   ctypes.POINTER(ctypes.c_double)], ctypes.c_int),
+    "xppe_lyapunov": ([ctypes.POINTER(ctypes.c_double)], ctypes.c_int),
+    "xppe_adjoint": ([ctypes.c_int, ctypes.c_double], ctypes.c_int),
+    "xppe_hfunction": ([ctypes.c_int, ctypes.POINTER(ctypes.c_char_p)],
+                       ctypes.c_int),
+    "xppe_fit": ([ctypes.c_char_p, ctypes.c_int, ctypes.c_int, ctypes.c_char_p,
+                  ctypes.c_char_p, ctypes.c_char_p, ctypes.c_double,
+                  ctypes.c_double, ctypes.c_int], ctypes.c_int),
+    "xppe_result_rows": ([], ctypes.c_int),
+    "xppe_result_count": ([], ctypes.c_int),
+    "xppe_result_name": ([ctypes.c_int], ctypes.c_char_p),
+    "xppe_result_column": ([ctypes.c_int, ctypes.POINTER(ctypes.c_double),
+                            ctypes.c_int], ctypes.c_int),
+    "xppe_ic_last": ([], ctypes.c_int),
+    "xppe_bvp_count": ([], ctypes.c_int),
+    "xppe_bvp": ([ctypes.c_int, ctypes.c_double, ctypes.c_double], ctypes.c_int),
+    "xppe_ani_load": ([ctypes.c_char_p], ctypes.c_int),
+    "xppe_ani_window": ([ctypes.POINTER(ctypes.c_double)] * 4, ctypes.c_int),
+    "xppe_ani_frame": ([ctypes.c_int], ctypes.c_int),
+    "xppe_ani_get": ([ctypes.c_int, ctypes.POINTER(AniItem)], ctypes.c_int),
+    "xppe_nullcline": ([ctypes.c_int, ctypes.c_int, ctypes.c_int,
+                        ctypes.c_double, ctypes.c_double, ctypes.c_double,
+                        ctypes.c_double, ctypes.c_int,
+                        ctypes.POINTER(ctypes.c_float), ctypes.c_int],
+                       ctypes.c_int),
+    "xppe_auto_get": ([ctypes.c_char_p, ctypes.POINTER(ctypes.c_double)],
+                      ctypes.c_int),
+    "xppe_auto_set": ([ctypes.c_char_p, ctypes.c_double], ctypes.c_int),
+    "xppe_auto_parameters": ([ctypes.c_char_p, ctypes.c_char_p], ctypes.c_int),
+    "xppe_auto_set_workdir": ([ctypes.c_char_p], ctypes.c_int),
+    "xppe_auto_reset": ([], ctypes.c_int),
+    "xppe_auto_run": ([ctypes.c_char_p], ctypes.c_int),
+    "xppe_auto_grab": ([ctypes.c_int], ctypes.c_int),
+    "xppe_auto_ungrab": ([], ctypes.c_int),
+    "xppe_auto_parameter_count": ([], ctypes.c_int),
+    "xppe_auto_parameter_name": ([ctypes.c_int], ctypes.c_char_p),
+    "xppe_auto_main_slot": ([ctypes.c_int], ctypes.c_int),
+    "xppe_auto_count": ([], ctypes.c_int),
+    "xppe_auto_point": ([ctypes.c_int, ctypes.POINTER(AutoPointInfo)],
+                        ctypes.c_int),
+    "xppe_auto_point_data": ([ctypes.c_int, ctypes.c_int,
+                              ctypes.POINTER(ctypes.c_double), ctypes.c_int],
+                             ctypes.c_int),
+}
+
+# The engine reads and writes files relative to the working directory, and
+# AUTO uses the HOME environment variable. Both are process-wide, so engine
+# calls are serialised.
+_process_lock = threading.RLock()
+
+
+def _text(b: bytes | None) -> str:
+    return b.decode("latin-1") if b else ""
+
+
+class Engine:
+    """One private copy of the engine library, holding at most one model."""
+
+    def __init__(self, library: str | os.PathLike | None = None):
+        source = Path(library) if library else find_engine_library()
+        self._tmpdir = Path(tempfile.mkdtemp(prefix="xpplab-"))
+        self._path = self._tmpdir / source.name
+        shutil.copy2(source, self._path)
+        self.workdir = self._tmpdir / "work"
+        self.workdir.mkdir()
+        self._lib = ctypes.CDLL(str(self._path))
+        for name, (args, res) in _SIGNATURES.items():
+            fn = getattr(self._lib, name)
+            fn.argtypes = args
+            fn.restype = res
+        if self._lib.xppe_api_version() != API_VERSION:
+            raise EngineError("engine library has an incompatible API version")
+        self.cwd: Path | None = None
+        self._closed = False
+        self._batch = 0
+
+    # -- plumbing ---------------------------------------------------------
+
+    @contextmanager
+    def batch(self):
+        """Hold the engine for many calls in a row (reading a diagram point by
+        point): one change of directory instead of two per call."""
+        with _process_lock:
+            old = os.getcwd()
+            if self.cwd is not None:
+                os.chdir(self.cwd)
+            self._batch += 1
+            try:
+                yield self
+            finally:
+                self._batch -= 1
+                os.chdir(old)
+
+    def call(self, name: str, *args, check: bool = True):
+        """Call an xppe_* function inside the model's working directory and
+        raise EngineError on failure."""
+        if self._closed:
+            raise EngineError("this model has been closed")
+        fn = getattr(self._lib, name)
+        with _process_lock:
+            if self._batch:
+                rc = fn(*args)
+            else:
+                old = os.getcwd()
+                if self.cwd is not None:
+                    os.chdir(self.cwd)
+                try:
+                    rc = fn(*args)
+                finally:
+                    os.chdir(old)
+        if check and isinstance(rc, int) and rc < 0:
+            raise EngineError(_text(self._lib.xppe_error()) or name + " failed",
+                              rc, self.log)
+        return rc
+
+    @property
+    def log(self) -> str:
+        return _text(self._lib.xppe_log())
+
+    @property
+    def version(self) -> str:
+        return _text(self._lib.xppe_version())
+
+    def names(self, kind: int) -> list[str]:
+        n = self._lib.xppe_count(kind)
+        return [_text(self._lib.xppe_name(kind, i)) for i in range(n)]
+
+    def close(self) -> None:
+        """Unload this copy of the engine and delete its files."""
+        if self._closed:
+            return
+        self._closed = True
+        handle = self._lib._handle
+        del self._lib
+        try:
+            if sys.platform == "win32":
+                ctypes.windll.kernel32.FreeLibrary(ctypes.c_void_p(handle))
+            else:
+                ctypes.CDLL(None).dlclose(ctypes.c_void_p(handle))
+        except Exception:
+            pass
+        shutil.rmtree(self._tmpdir, ignore_errors=True)
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception:
+            pass