jaxcont 0.1.0__tar.gz

jaxcont-0.1.0/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use JaxCont in your research, please cite the archived release."
+title: "JaxCont: Differentiable Continuation and Bifurcation Analysis in JAX"
+type: software
+authors:
+  - family-names: Ziaeemehr
+    given-names: Abolfazl
+repository-code: "https://github.com/Ziaeemehr/JaxCont"
+url: "https://jaxcont.readthedocs.io"
+license: MIT
+version: 0.1.0

jaxcont-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JaxCont Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jaxcont-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CITATION.cff
+include examples/GALLERY_HEADER.rst

jaxcont-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: jaxcont
+Version: 0.1.0
+Summary: High-performance continuation and bifurcation analysis in JAX
+Author-email: Abolfazl Ziaeemehr <a.ziaeemehr@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Ziaeemehr/JaxCont
+Project-URL: Documentation, https://jaxcont.readthedocs.io
+Project-URL: Repository, https://github.com/Ziaeemehr/JaxCont
+Project-URL: Bug Tracker, https://github.com/Ziaeemehr/JaxCont/issues
+Project-URL: Changelog, https://jaxcont.readthedocs.io/en/latest/changelog.html
+Keywords: bifurcation,continuation,dynamical-systems,jax,numerical-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jax>=0.3.0
+Requires-Dist: jaxlib>=0.3.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: matplotlib>=3.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: sphinx>=7.0.0; extra == "dev"
+Requires-Dist: sphinx-book-theme>=1.1.0; extra == "dev"
+Requires-Dist: sphinx-gallery>=0.19.0; extra == "dev"
+Requires-Dist: jupyter>=1.0.0; extra == "dev"
+Requires-Dist: ipython>=8.12.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0.0; extra == "docs"
+Requires-Dist: sphinx-book-theme>=1.1.0; extra == "docs"
+Requires-Dist: sphinx-gallery>=0.19.0; extra == "docs"
+Requires-Dist: myst-parser>=2.0.0; extra == "docs"
+Dynamic: license-file
+
+# JaxCont
+
+**Vectorize whole continuation sweeps with `jax.vmap`, and differentiate
+bifurcation locations with `jax.grad`.**
+
+[![Test](https://github.com/Ziaeemehr/JaxCont/actions/workflows/tests.yml/badge.svg)](https://github.com/Ziaeemehr/JaxCont/actions/workflows/tests.yml)
+[![Documentation Status](https://readthedocs.org/projects/jaxcont/badge/?version=latest)](https://jaxcont.readthedocs.io/latest/)
+[![PyPI version](https://img.shields.io/pypi/v/jaxcont.svg)](https://pypi.org/project/jaxcont/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+JaxCont is an equilibrium continuation and bifurcation-analysis library built
+around JAX transformations. Its whole-loop pseudo-arclength engine is a pure,
+compiled computation: use `vmap` to compute ensembles of branches in one
+batched kernel, `jacfwd` to differentiate through a sweep, or the implicit
+`fold_parameter` solver for reverse-mode gradients of a fold location.
+
+```python
+# One compiled kernel computes a branch for every design value.
+branches = jax.vmap(run_branch)(design_values)
+
+# A fold location can participate in gradient-based inverse design.
+dp_dtheta = jax.grad(
+    lambda theta: jc.fold_parameter(f, u_guess, p_guess, theta)
+)(theta)
+```
+
+The v0.1 series deliberately focuses on equilibria: natural and
+pseudo-arclength continuation, fold and Hopf detection with refinement,
+linear stability, and bifurcation diagrams. Periodic orbits, Floquet
+multipliers, boundary-value problems, branch switching, and two-parameter
+continuation are not part of the supported v0.1 API.
+
+## Installation
+
+JaxCont requires Python 3.9 or newer.
+
+```bash
+pip install jaxcont
+```
+
+For a development checkout:
+
+```bash
+git clone https://github.com/Ziaeemehr/JaxCont.git
+cd JaxCont
+python -m pip install -e ".[dev]"
+```
+
+JAX's platform-specific accelerator installation is documented in the
+[JAX installation guide](https://docs.jax.dev/en/latest/installation.html).
+
+## Quick start
+
+Continue the positive branch of `u² + p = 0` through its fold at `p = 0`:
+
+```python
+import jax.numpy as jnp
+import jaxcont as jc
+
+def saddle_node(u, p, args):
+    return u**2 + p
+
+problem = jc.bif_problem(saddle_node, u0=jnp.array([1.0]), p0=-1.0)
+result = jc.continuation(
+    problem,
+    p_span=(-1.0, 0.2),
+    settings=jc.ContinuationPar(ds=0.03, max_steps=200),
+    events=[jc.Fold()],
+)
+
+print(result.branch.params)
+print([(event.kind, event.p) for event in result.events])
+```
+
+`PseudoArclength(engine="scan")` is the default algorithm. It uses the
+whole-loop compiled engine, computes stability in a vectorized post-pass, and
+refines requested fold/Hopf events. Use `jc.Natural()` for natural-parameter
+continuation or `jc.PseudoArclength(engine="legacy")` only when comparing with
+the compatibility implementation.
+
+See the [quickstart](https://jaxcont.readthedocs.io/en/latest/quickstart.html),
+[Sphinx-Gallery examples](https://jaxcont.readthedocs.io/en/latest/auto_examples/index.html),
+[`example_06_vmap_sweep.py`](examples/example_06_vmap_sweep.py), and
+[`example_07_differentiable.py`](examples/example_07_differentiable.py) for the
+full `vmap`, `jacfwd`, and inverse-design stories.
+
+## Development
+
+```bash
+python -m pytest
+make docs
+python -m build
+python -m twine check dist/*
+```
+
+Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). The project
+roadmap and supported scope live in [notes/ROADMAP.md](notes/ROADMAP.md).
+
+## Citation
+
+If JaxCont supports your research, cite the archived release using the DOI in
+the GitHub/Zenodo release record. Citation metadata is also provided in
+[`CITATION.cff`](CITATION.cff). Until the first archive is minted:
+
+```bibtex
+@software{ziaeemehr_jaxcont_2026,
+  author  = {Ziaeemehr, Abolfazl},
+  title   = {JaxCont: Differentiable Continuation and Bifurcation Analysis in JAX},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/Ziaeemehr/JaxCont}
+}
+```
+
+JaxCont is distributed under the [MIT License](LICENSE).

jaxcont-0.1.0/README.md

@@ -0,0 +1,115 @@
+# JaxCont
+
+**Vectorize whole continuation sweeps with `jax.vmap`, and differentiate
+bifurcation locations with `jax.grad`.**
+
+[![Test](https://github.com/Ziaeemehr/JaxCont/actions/workflows/tests.yml/badge.svg)](https://github.com/Ziaeemehr/JaxCont/actions/workflows/tests.yml)
+[![Documentation Status](https://readthedocs.org/projects/jaxcont/badge/?version=latest)](https://jaxcont.readthedocs.io/latest/)
+[![PyPI version](https://img.shields.io/pypi/v/jaxcont.svg)](https://pypi.org/project/jaxcont/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+JaxCont is an equilibrium continuation and bifurcation-analysis library built
+around JAX transformations. Its whole-loop pseudo-arclength engine is a pure,
+compiled computation: use `vmap` to compute ensembles of branches in one
+batched kernel, `jacfwd` to differentiate through a sweep, or the implicit
+`fold_parameter` solver for reverse-mode gradients of a fold location.
+
+```python
+# One compiled kernel computes a branch for every design value.
+branches = jax.vmap(run_branch)(design_values)
+
+# A fold location can participate in gradient-based inverse design.
+dp_dtheta = jax.grad(
+    lambda theta: jc.fold_parameter(f, u_guess, p_guess, theta)
+)(theta)
+```
+
+The v0.1 series deliberately focuses on equilibria: natural and
+pseudo-arclength continuation, fold and Hopf detection with refinement,
+linear stability, and bifurcation diagrams. Periodic orbits, Floquet
+multipliers, boundary-value problems, branch switching, and two-parameter
+continuation are not part of the supported v0.1 API.
+
+## Installation
+
+JaxCont requires Python 3.9 or newer.
+
+```bash
+pip install jaxcont
+```
+
+For a development checkout:
+
+```bash
+git clone https://github.com/Ziaeemehr/JaxCont.git
+cd JaxCont
+python -m pip install -e ".[dev]"
+```
+
+JAX's platform-specific accelerator installation is documented in the
+[JAX installation guide](https://docs.jax.dev/en/latest/installation.html).
+
+## Quick start
+
+Continue the positive branch of `u² + p = 0` through its fold at `p = 0`:
+
+```python
+import jax.numpy as jnp
+import jaxcont as jc
+
+def saddle_node(u, p, args):
+    return u**2 + p
+
+problem = jc.bif_problem(saddle_node, u0=jnp.array([1.0]), p0=-1.0)
+result = jc.continuation(
+    problem,
+    p_span=(-1.0, 0.2),
+    settings=jc.ContinuationPar(ds=0.03, max_steps=200),
+    events=[jc.Fold()],
+)
+
+print(result.branch.params)
+print([(event.kind, event.p) for event in result.events])
+```
+
+`PseudoArclength(engine="scan")` is the default algorithm. It uses the
+whole-loop compiled engine, computes stability in a vectorized post-pass, and
+refines requested fold/Hopf events. Use `jc.Natural()` for natural-parameter
+continuation or `jc.PseudoArclength(engine="legacy")` only when comparing with
+the compatibility implementation.
+
+See the [quickstart](https://jaxcont.readthedocs.io/en/latest/quickstart.html),
+[Sphinx-Gallery examples](https://jaxcont.readthedocs.io/en/latest/auto_examples/index.html),
+[`example_06_vmap_sweep.py`](examples/example_06_vmap_sweep.py), and
+[`example_07_differentiable.py`](examples/example_07_differentiable.py) for the
+full `vmap`, `jacfwd`, and inverse-design stories.
+
+## Development
+
+```bash
+python -m pytest
+make docs
+python -m build
+python -m twine check dist/*
+```
+
+Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). The project
+roadmap and supported scope live in [notes/ROADMAP.md](notes/ROADMAP.md).
+
+## Citation
+
+If JaxCont supports your research, cite the archived release using the DOI in
+the GitHub/Zenodo release record. Citation metadata is also provided in
+[`CITATION.cff`](CITATION.cff). Until the first archive is minted:
+
+```bibtex
+@software{ziaeemehr_jaxcont_2026,
+  author  = {Ziaeemehr, Abolfazl},
+  title   = {JaxCont: Differentiable Continuation and Bifurcation Analysis in JAX},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/Ziaeemehr/JaxCont}
+}
+```
+
+JaxCont is distributed under the [MIT License](LICENSE).

jaxcont-0.1.0/examples/GALLERY_HEADER.rst

@@ -0,0 +1,9 @@
+JaxCont example gallery
+=======================
+
+These executable examples progress from classical equilibrium continuation to
+the capabilities that distinguish JaxCont: batched whole-branch computation
+with :func:`jax.vmap` and differentiable bifurcation locations.
+
+The documentation build generates a downloadable Python script and Jupyter
+notebook for every example. Output execution is opt-in; see ``docs/README.md``.

jaxcont-0.1.0/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jaxcont"
+dynamic = ["version"]
+description = "High-performance continuation and bifurcation analysis in JAX"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Abolfazl Ziaeemehr", email = "a.ziaeemehr@gmail.com"}
+]
+keywords = ["bifurcation", "continuation", "dynamical-systems", "jax", "numerical-analysis"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+dependencies = [
+    "jax>=0.3.0",
+    "jaxlib>=0.3.0",
+    "numpy>=1.21.0",
+    "scipy>=1.7.0",
+    "matplotlib>=3.5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "black>=23.0.0",
+    "flake8>=6.0.0",
+    "mypy>=1.5.0",
+    "isort>=5.12.0",
+    "sphinx>=7.0.0",
+    "sphinx-book-theme>=1.1.0",
+    "sphinx-gallery>=0.19.0",
+    "jupyter>=1.0.0",
+    "ipython>=8.12.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+]
+docs = [
+    "sphinx>=7.0.0",
+    "sphinx-book-theme>=1.1.0",
+    "sphinx-gallery>=0.19.0",
+    "myst-parser>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Ziaeemehr/JaxCont"
+Documentation = "https://jaxcont.readthedocs.io"
+Repository = "https://github.com/Ziaeemehr/JaxCont"
+"Bug Tracker" = "https://github.com/Ziaeemehr/JaxCont/issues"
+Changelog = "https://jaxcont.readthedocs.io/en/latest/changelog.html"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "jaxcont._version.__version__"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+# Fast by default: no coverage instrumentation, slow tests excluded, and GPU
+# tests excluded (they self-skip on CPU-only runners anyway, but excluding
+# them here keeps `pytest` quiet-by-default on GPU dev machines too -- see
+# tests/test_gpu_smoke.py). Run everything with `make test-all`; coverage
+# with `make test-cov`; GPU smoke tests explicitly with `pytest -m gpu`.
+addopts = "-q -m 'not slow and not gpu'"
+
+[tool.black]
+line-length = 100
+target-version = ['py39', 'py310', 'py311']
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"
+line_length = 100
+multi_line_output = 3
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true

jaxcont-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jaxcont-0.1.0/setup.py

@@ -0,0 +1,6 @@
+"""Setup script for JaxCont package."""
+
+from setuptools import setup, find_packages
+
+# This file is kept for compatibility but pyproject.toml is the main configuration
+setup()

jaxcont-0.1.0/src/jaxcont/__init__.py

@@ -0,0 +1,111 @@
+"""
+JaxCont: High-Performance Continuation and Bifurcation Analysis in JAX
+
+A modern Python package for numerical continuation and bifurcation analysis
+of dynamical systems, leveraging JAX's automatic differentiation and JIT
+compilation for exceptional performance.
+"""
+
+from jaxcont._version import __version__
+
+__author__ = "Abolfazl Ziaeemehr"
+__license__ = "MIT"
+
+# Functional API -- the blessed public surface: bif_problem() + continuation()
+from jaxcont.api import (
+    BifProblem,
+    bif_problem,
+    continuation,
+    ContinuationPar,
+    ContinuationAlgorithm,
+    PseudoArclength,
+    Natural,
+    Event,
+    Fold,
+    Hopf,
+    EventHit,
+    Branch,
+    ContinuationResult,
+)
+
+# Core imports
+from jaxcont.core.continuation import (
+    ContinuationProblem,
+    ContinuationSolution,
+    equilibrium_continuation,
+)
+from jaxcont.core.predictor_corrector import PredictorCorrector
+from jaxcont.core.natural_continuation import NaturalContinuation
+from jaxcont.core.pseudo_arclength import PseudoArclengthContinuation
+
+# Problem definitions
+from jaxcont.problems.equilibrium import EquilibriumProblem
+
+# Differentiable fold solver (reverse-mode grad of a fold location via the
+# implicit function theorem -- see examples/example_07_differentiable.py)
+from jaxcont.bifurcations.fold_solve import fold_point, fold_parameter
+
+# Bifurcation detection
+from jaxcont.bifurcations.detector import BifurcationDetector
+from jaxcont.bifurcations.fold import FoldBifurcation
+from jaxcont.bifurcations.hopf import HopfBifurcation
+
+# Solvers
+from jaxcont.solvers.newton import NewtonSolver
+from jaxcont.solvers.corrector import Corrector
+
+# Stability analysis
+from jaxcont.stability.eigenvalue import compute_eigenvalues, analyze_stability
+
+# NOTE: v0.1.0 ships equilibria only. Periodic-orbit / Floquet / BVP / period-
+# doubling APIs are experimental stubs and are intentionally NOT exported at
+# the top level (see the project roadmap). They remain importable from their
+# submodules for development, e.g.:
+#     from jaxcont.problems.periodic import PeriodicOrbitProblem
+#     from jaxcont.stability.floquet import compute_floquet_multipliers
+
+# Utilities
+from jaxcont.utils.config import Config
+from jaxcont.utils.plotting import plot_bifurcation_diagram, plot_continuation
+
+__all__ = [
+    # Functional API (blessed surface)
+    "BifProblem",
+    "bif_problem",
+    "continuation",
+    "ContinuationPar",
+    "ContinuationAlgorithm",
+    "PseudoArclength",
+    "Natural",
+    "Event",
+    "Fold",
+    "Hopf",
+    "EventHit",
+    "Branch",
+    "ContinuationResult",
+    "fold_point",
+    "fold_parameter",
+    # Core
+    "ContinuationProblem",
+    "ContinuationSolution",
+    "equilibrium_continuation",
+    "PredictorCorrector",
+    "NaturalContinuation",
+    "PseudoArclengthContinuation",
+    # Problems
+    "EquilibriumProblem",
+    # Bifurcations
+    "BifurcationDetector",
+    "FoldBifurcation",
+    "HopfBifurcation",
+    # Solvers
+    "NewtonSolver",
+    "Corrector",
+    # Stability
+    "compute_eigenvalues",
+    "analyze_stability",
+    # Utilities
+    "Config",
+    "plot_bifurcation_diagram",
+    "plot_continuation",
+]

jaxcont-0.1.0/src/jaxcont/_version.py

@@ -0,0 +1,3 @@
+"""Version information for JaxCont."""
+
+__version__ = "0.1.0"