dynlib 0.37.4__py3-none-any.whl

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/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}'")