dynlib 0.37.4__tar.gz

dynlib-0.37.4/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, İsmail Öztürk
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

dynlib-0.37.4/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: dynlib
+Version: 0.37.4
+Summary: A dynamical systems simulation library.
+Author-email: İsmail Öztürk <ismail.ozturk@amasya.edu.tr>
+License-Expression: BSD-3-Clause
+Keywords: ODE,dynamical-systems,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: jit
+Requires-Dist: numba>=0.57.1; extra == "jit"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: scipy>=1.9; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Requires-Dist: numba>=0.57.1; extra == "dev"
+Dynamic: license-file
+
+# dynlib
+
+Dynlib is a Python library for **modeling, simulating, and analyzing dynamical systems**.  
+Models are described in a TOML-based DSL (Domain-Specific Language) and then executed through a unified runtime—so you can iterate on solvers, parameters, and analyses without rewriting the same Numpy/Matplotlib plumbing for every experiment.
+
+With dynlib, you can define or tweak a model, try different solvers/settings, and visualize behavior quickly. It can be used with notebooks for teaching and demonstration purposes. Created models can be kept in an organized manner and can be shared easily.
+
+## Project status
+
+Dynlib is **alpha-stage** software. APIs may change, and numerical edge cases or bugs can surface. Treat results as exploratory unless you validate them (e.g., alternative steppers, tighter tolerances, smaller step sizes, or analytical checks). If you find suspicious behavior, please open an issue with a minimal reproducer.
+
+## Highlights
+
+### Modeling (TOML DSL)
+- Define **ODEs** and **discrete-time maps** using a declarative TOML spec.
+- Express equations, parameters, state initialization, and metadata in a consistent format.
+- Support for **events**, **auxiliary variables**, **functions/macros**, and **lagging** where applicable.
+- Built-in **model registry** and URI loading (including `builtin://...` models).
+
+### Simulation runtime
+- Multiple stepper families:
+  - ODE: Euler, RK4, RK45, Adams–Bashforth (AB2/AB3), and implicit methods (e.g., SDIRK/TR-BDF2).
+  - Maps: dedicated discrete runner(s) including integer-safe modes.
+- Runner variants and session introspection utilities for iterative workflows.
+- **JIT acceleration** via Numba (optional but highly recommended), plus **disk caching** for compiled runners.
+- **Snapshots and resume** support for long or staged simulations.
+- Selective recording and result APIs designed for downstream analysis.
+
+### Analysis
+Built-in analysis utilities for common dynamical-systems tasks:
+- **Bifurcation** and post-processing utilities
+- **Basins of attraction** (auto/known variants)
+- **Lyapunov exponent** analysis (including runtime observer support)
+- **Fixed point / Equilibria** detection
+- **Manifold** tracing tools (currently limited to 1D manifolds)
+- **Homoclinic/Heteroclinic** orbit tracing and detection
+- **Parameter sweep** helpers and trajectory/post-analysis utilities
+
+### Vector fields & plotting (on top of Matplotlib)
+Dynlib includes plotting helpers tailored for dynamical systems rather than raw Matplotlib boilerplate:
+- Vector field evaluation utilities and **phase-portrait** helpers
+- Plot modules for **basins**, **bifurcation diagrams**, **manifolds**, and general dynamics
+- Higher-level plotting conveniences: **themes**, **facets**, decorations, and export helpers
+- Vector field **animation** support
+
+### CLI
+Dynlib ships a small CLI (Command Line Interface) for convenience tasks such as model validation, listing steppers, and inspecting caches.  
+The CLI is not required for the Python API.
+
+## Prerequisites
+- Python 3.10+
+- Matplotlib for plots.
+- Numpy for numerical calculations.
+- **Numba** is highly recommended for JIT execution:
+  - `python -m pip install numba`
+
+## Installation
+- `pip install dynlib` (when published), or
+- `pip install -e .` for editable installs from source
+
+## Quickstart
+
+Sanity-check the CLI and validate a bundled model:
+
+```bash
+dynlib --version
+dynlib model validate builtin://ode/lorenz.toml
+```
+
+Run a built-in model from Python (Lorenz system):
+
+```python
+from dynlib import setup
+from dynlib.plot import fig, series, export
+
+sim = setup("builtin://ode/lorenz.toml", stepper="rk4")
+
+sim.run(T=15.0, dt=0.01)
+res = sim.results()
+
+print("States:", res.state_names)
+print("Final z:", res["z"][-1])
+
+ax = fig.single()
+series.plot(x=res.t, y=res["x"], ax=ax, label="x")
+series.plot(x=res.t, y=res["z"], ax=ax, label="z", xlabel="time")
+export.show()
+```
+
+Next: see the docs for defining your own TOML models, URI tags (`proj://...`), recording options, and analysis workflows (basins, bifurcation, Lyapunov, fixed points).
+
+## Documentation
+The documentation can be accessed via (#TODO: Add a link ...)

dynlib-0.37.4/README.md

@@ -0,0 +1,93 @@
+# dynlib
+
+Dynlib is a Python library for **modeling, simulating, and analyzing dynamical systems**.  
+Models are described in a TOML-based DSL (Domain-Specific Language) and then executed through a unified runtime—so you can iterate on solvers, parameters, and analyses without rewriting the same Numpy/Matplotlib plumbing for every experiment.
+
+With dynlib, you can define or tweak a model, try different solvers/settings, and visualize behavior quickly. It can be used with notebooks for teaching and demonstration purposes. Created models can be kept in an organized manner and can be shared easily.
+
+## Project status
+
+Dynlib is **alpha-stage** software. APIs may change, and numerical edge cases or bugs can surface. Treat results as exploratory unless you validate them (e.g., alternative steppers, tighter tolerances, smaller step sizes, or analytical checks). If you find suspicious behavior, please open an issue with a minimal reproducer.
+
+## Highlights
+
+### Modeling (TOML DSL)
+- Define **ODEs** and **discrete-time maps** using a declarative TOML spec.
+- Express equations, parameters, state initialization, and metadata in a consistent format.
+- Support for **events**, **auxiliary variables**, **functions/macros**, and **lagging** where applicable.
+- Built-in **model registry** and URI loading (including `builtin://...` models).
+
+### Simulation runtime
+- Multiple stepper families:
+  - ODE: Euler, RK4, RK45, Adams–Bashforth (AB2/AB3), and implicit methods (e.g., SDIRK/TR-BDF2).
+  - Maps: dedicated discrete runner(s) including integer-safe modes.
+- Runner variants and session introspection utilities for iterative workflows.
+- **JIT acceleration** via Numba (optional but highly recommended), plus **disk caching** for compiled runners.
+- **Snapshots and resume** support for long or staged simulations.
+- Selective recording and result APIs designed for downstream analysis.
+
+### Analysis
+Built-in analysis utilities for common dynamical-systems tasks:
+- **Bifurcation** and post-processing utilities
+- **Basins of attraction** (auto/known variants)
+- **Lyapunov exponent** analysis (including runtime observer support)
+- **Fixed point / Equilibria** detection
+- **Manifold** tracing tools (currently limited to 1D manifolds)
+- **Homoclinic/Heteroclinic** orbit tracing and detection
+- **Parameter sweep** helpers and trajectory/post-analysis utilities
+
+### Vector fields & plotting (on top of Matplotlib)
+Dynlib includes plotting helpers tailored for dynamical systems rather than raw Matplotlib boilerplate:
+- Vector field evaluation utilities and **phase-portrait** helpers
+- Plot modules for **basins**, **bifurcation diagrams**, **manifolds**, and general dynamics
+- Higher-level plotting conveniences: **themes**, **facets**, decorations, and export helpers
+- Vector field **animation** support
+
+### CLI
+Dynlib ships a small CLI (Command Line Interface) for convenience tasks such as model validation, listing steppers, and inspecting caches.  
+The CLI is not required for the Python API.
+
+## Prerequisites
+- Python 3.10+
+- Matplotlib for plots.
+- Numpy for numerical calculations.
+- **Numba** is highly recommended for JIT execution:
+  - `python -m pip install numba`
+
+## Installation
+- `pip install dynlib` (when published), or
+- `pip install -e .` for editable installs from source
+
+## Quickstart
+
+Sanity-check the CLI and validate a bundled model:
+
+```bash
+dynlib --version
+dynlib model validate builtin://ode/lorenz.toml
+```
+
+Run a built-in model from Python (Lorenz system):
+
+```python
+from dynlib import setup
+from dynlib.plot import fig, series, export
+
+sim = setup("builtin://ode/lorenz.toml", stepper="rk4")
+
+sim.run(T=15.0, dt=0.01)
+res = sim.results()
+
+print("States:", res.state_names)
+print("Final z:", res["z"][-1])
+
+ax = fig.single()
+series.plot(x=res.t, y=res["x"], ax=ax, label="x")
+series.plot(x=res.t, y=res["z"], ax=ax, label="z", xlabel="time")
+export.show()
+```
+
+Next: see the docs for defining your own TOML models, URI tags (`proj://...`), recording options, and analysis workflows (basins, bifurcation, Lyapunov, fixed points).
+
+## Documentation
+The documentation can be accessed via (#TODO: Add a link ...)

dynlib-0.37.4/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dynlib"
+version = "0.37.4"
+description = "A dynamical systems simulation library."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "İsmail Öztürk", email = "ismail.ozturk@amasya.edu.tr" }]
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+keywords = ["ODE", "dynamical-systems", "simulation"]
+dependencies = [
+  "numpy>=1.24",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3.10",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+
+[project.optional-dependencies]
+jit  = ["numba>=0.57.1"]
+plot = ["matplotlib>=3.7"]
+dev = ["pytest>=7", "scipy>=1.9", "matplotlib>=3.7", "numba>=0.57.1"]
+
+[project.scripts]
+dynlib = "dynlib.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"dynlib.models" = ["**/*.toml"]

dynlib-0.37.4/setup.cfg

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

dynlib-0.37.4/src/dynlib/__init__.py

@@ -0,0 +1,96 @@
+# src/dynlib/__init__.py
+from __future__ import annotations
+
+# Re-export frozen constants/types for stable imports
+from dynlib.runtime.runner_api import (
+    Status, OK, STEPFAIL, NAN_DETECTED, DONE, GROW_REC, GROW_EVT, USER_BREAK,
+)
+
+from .steppers.registry import register, get_stepper, registry, select_steppers, list_steppers
+from .compiler.build import build
+from .runtime.sim import Sim
+
+
+__all__ = [
+    # Core entry points
+    "build", "setup", "Sim", "plot",
+    # Status codes (for advanced use)
+    "Status", "OK", "STEPFAIL", "NAN_DETECTED", "DONE", "GROW_REC", "GROW_EVT", "USER_BREAK",
+    # Results
+    "Results",
+    # Stepper registry
+    "list_steppers", "select_steppers", "get_stepper", "register", "registry",
+]
+
+
+def setup(
+    model, *,
+    stepper=None,
+    mods=None,
+    jit=False,
+    dtype=None,
+    disk_cache=False,
+    config=None,
+    validate_stepper=True,
+) -> Sim:
+    """Compile and setup a simulation in one call.
+
+    This is a convenience function that combines the `build()` and `Sim()`
+    calls into a single step. It compiles the provided model and initializes
+    a simulation instance with the specified stepper and configuration.
+    
+    For most users, this is the recommended entry point. Advanced users who
+    need to inspect or modify the compiled model before simulation should use
+    `build()` and `Sim()` separately.
+    
+    The compiled model remains accessible via the returned `Sim` instance's
+    `model` attribute for advanced use cases.
+
+    Parameters:
+        model: The model to be compiled (ModelSpec or URI string).
+        stepper: The stepper to use for the simulation (e.g., "euler", "rk4", "rk45").
+            If None, uses the model's sim.stepper default.
+        mods: Optional list of mod URIs to apply during compilation.
+        jit: Whether to use JIT compilation (default False).
+        dtype: The data type for computations. If None (default), uses the dtype from the model spec.
+        disk_cache: Whether to use disk caching for compiled models (default False).
+        config: Optional PathConfig for URI resolution.
+        validate_stepper: Whether to validate the stepper against the model (default True).
+
+    Returns:
+        An instance of `Sim` initialized with the compiled model.
+    
+    Example:
+        Simple usage with inline model::
+        
+            from dynlib import setup
+            
+            sim = setup(model_uri, stepper="euler", jit=True)
+            sim.run(T=10.0)
+            results = sim.results()
+        
+        Equivalent manual approach for advanced use::
+        
+            from dynlib import build, Sim
+            
+            model = build(model_uri, stepper="euler", jit=True)
+            # Inspect or modify model here if needed
+            sim = Sim(model)
+            sim.run(T=10.0)
+    
+    See Also:
+        build : Compile a model without creating a Sim instance.
+        Sim : Simulation facade for compiled models.
+    """
+    compiled_model = build(
+        model,
+        stepper=stepper,
+        mods=mods,
+        jit=jit,
+        dtype=dtype,
+        disk_cache=disk_cache,
+        config=config,
+        validate_stepper=validate_stepper,
+    )
+    sim = Sim(compiled_model)
+    return sim

dynlib-0.37.4/src/dynlib/analysis/__init__.py

@@ -0,0 +1,202 @@
+"""Offline analysis namespace for dynlib."""
+
+import importlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dynlib.analysis.basin import (
+        BLOWUP,
+        OUTSIDE,
+        UNRESOLVED,
+        Attractor,
+        BasinResult,
+        FixedPoint,
+        ReferenceRun,
+        KnownAttractorLibrary,
+        build_known_attractors_psc,
+    )
+    from dynlib.analysis.basin_auto import basin_auto
+    from dynlib.analysis.basin_known import basin_known
+    from dynlib.analysis.basin_stats import (
+        BasinStats,
+        AttractorStats,
+        basin_stats,
+        basin_summary,
+        print_basin_summary,
+    )
+    from dynlib.analysis.sweep import (
+        SweepResult,
+        TrajectoryPayload,
+        scalar_sweep,
+        traj_sweep,
+        lyapunov_mle_sweep,
+        lyapunov_spectrum_sweep,
+    )
+    from dynlib.analysis.post import (
+        BifurcationResult,
+        BifurcationExtractor,
+        TrajectoryAnalyzer,
+        MultiVarAnalyzer,
+    )
+    from dynlib.analysis.fixed_points import (
+        FixedPointConfig,
+        FixedPointResult,
+        find_fixed_points,
+    )
+    from dynlib.analysis.manifold import (
+        ManifoldTraceResult,
+        trace_manifold_1d_map,
+        trace_manifold_1d_ode,
+        HeteroclinicRK45Config,
+        HeteroclinicBranchConfig,
+        HeteroclinicFinderConfig2D,
+        HeteroclinicFinderConfigND,
+        HeteroclinicTraceEvent,
+        HeteroclinicMissResult2D,
+        HeteroclinicMissResultND,
+        HeteroclinicFinderResult,
+        HeteroclinicTraceMeta,
+        HeteroclinicTraceResult,
+        HeteroclinicPreset,
+        heteroclinic_finder,
+        heteroclinic_tracer,
+        HomoclinicRK45Config,
+        HomoclinicBranchConfig,
+        HomoclinicFinderConfig,
+        HomoclinicMissResult,
+        HomoclinicFinderResult,
+        HomoclinicTraceEvent,
+        HomoclinicTraceMeta,
+        HomoclinicTraceResult,
+        HomoclinicPreset,
+        homoclinic_finder,
+        homoclinic_tracer,
+    )
+
+_SWEEP_EXPORTS = {
+    "SweepResult",
+    "TrajectoryPayload",
+    "scalar_sweep",
+    "traj_sweep",
+    "lyapunov_mle_sweep",
+    "lyapunov_spectrum_sweep",
+}
+
+_POST_EXPORTS = {
+    "BifurcationResult",
+    "BifurcationExtractor",
+    "TrajectoryAnalyzer",
+    "MultiVarAnalyzer",
+}
+
+_BASIN_EXPORTS = {
+    "BLOWUP",
+    "OUTSIDE",
+    "UNRESOLVED",
+    "Attractor",
+    "BasinResult",
+    "FixedPoint",
+    "ReferenceRun",
+    "KnownAttractorLibrary",
+    "basin_auto",
+    "build_known_attractors_psc",
+    "basin_known",
+}
+
+_BASIN_STATS_EXPORTS = {
+    "BasinStats",
+    "AttractorStats",
+    "basin_stats",
+    "basin_summary",
+    "print_basin_summary",
+}
+
+_FIXED_POINT_EXPORTS = {
+    "FixedPointConfig",
+    "FixedPointResult",
+    "find_fixed_points",
+}
+
+_MANIFOLD_EXPORTS = {
+    "ManifoldTraceResult",
+    "trace_manifold_1d_map",
+    "trace_manifold_1d_ode",
+    "HeteroclinicRK45Config",
+    "HeteroclinicBranchConfig",
+    "HeteroclinicFinderConfig2D",
+    "HeteroclinicFinderConfigND",
+    "HeteroclinicTraceEvent",
+    "HeteroclinicMissResult2D",
+    "HeteroclinicMissResultND",
+    "HeteroclinicFinderResult",
+    "HeteroclinicTraceMeta",
+    "HeteroclinicTraceResult",
+    "HeteroclinicPreset",
+    "heteroclinic_finder",
+    "heteroclinic_tracer",
+    "HomoclinicRK45Config",
+    "HomoclinicBranchConfig",
+    "HomoclinicFinderConfig",
+    "HomoclinicMissResult",
+    "HomoclinicFinderResult",
+    "HomoclinicTraceEvent",
+    "HomoclinicTraceMeta",
+    "HomoclinicTraceResult",
+    "HomoclinicPreset",
+    "homoclinic_finder",
+    "homoclinic_tracer",
+}
+
+__all__ = [
+    # Sweep orchestration
+    *_SWEEP_EXPORTS,
+    # Post-run analysis
+    *_POST_EXPORTS,
+    # Basin analysis
+    *_BASIN_EXPORTS,
+    # Basin statistics
+    *_BASIN_STATS_EXPORTS,
+    # Fixed points
+    *_FIXED_POINT_EXPORTS,
+    # Manifold tracing
+    *_MANIFOLD_EXPORTS,
+]
+
+
+def __getattr__(name):
+    if name in _SWEEP_EXPORTS:
+        module = importlib.import_module("dynlib.analysis.sweep")
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    if name in _POST_EXPORTS:
+        module = importlib.import_module("dynlib.analysis.post")
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    if name in _BASIN_EXPORTS:
+        if name == "basin_auto":
+            module = importlib.import_module("dynlib.analysis.basin_auto")
+        elif name == "basin_known":
+            module = importlib.import_module("dynlib.analysis.basin_known")
+        else:
+            module = importlib.import_module("dynlib.analysis.basin")
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    if name in _BASIN_STATS_EXPORTS:
+        module = importlib.import_module("dynlib.analysis.basin_stats")
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    if name in _FIXED_POINT_EXPORTS:
+        module = importlib.import_module("dynlib.analysis.fixed_points")
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    if name in _MANIFOLD_EXPORTS:
+        module = importlib.import_module("dynlib.analysis.manifold")
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'dynlib.analysis' has no attribute '{name}'")