solve-nivp 0.2.0.dev1__tar.gz → 0.2.0.dev2__tar.gz

solve_nivp-0.2.0.dev2/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include pytest.ini
+include docs/Makefile
+include docs/make.bat
+
+recursive-include src/solve_nivp *.py
+recursive-include tests *.py
+recursive-include docs/source *.py *.rst

{solve_nivp-0.2.0.dev1/solve_nivp.egg-info → solve_nivp-0.2.0.dev2}/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: solve_nivp
-Version: 0.2.0.dev1
+Version: 0.2.0.dev2
 Summary: A Python toolkit for integrating nonsmooth dynamical systems
 Author: David Riley, Ioannis Stefanou
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/ERC-INJECT/solve_nivp
 Project-URL: Documentation, https://github.com/ERC-INJECT/solve_nivp/tree/main/docs
 Project-URL: Issues, https://github.com/ERC-INJECT/solve_nivp/issues
 Keywords: nonsmooth dynamics,ODE,DAE,variational inequalities,semismooth Newton,projection methods
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Topic :: Scientific/Engineering :: Physics

solve_nivp-0.2.0.dev2/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

solve_nivp-0.2.0.dev2/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

solve_nivp-0.2.0.dev2/docs/source/api/solve_nivp.ODESolver.rst

@@ -0,0 +1,23 @@
+solve\_nivp.ODESolver
+=====================
+
+.. currentmodule:: solve_nivp
+
+.. autoclass:: ODESolver
+
+   
+   .. automethod:: __init__
+
+   
+   .. rubric:: Methods
+
+   .. autosummary::
+   
+      ~ODESolver.__init__
+      ~ODESolver.solve
+   
+   
+
+   
+   
+   

solve_nivp-0.2.0.dev2/docs/source/api/solve_nivp.ODESystem.rst

@@ -0,0 +1,25 @@
+solve\_nivp.ODESystem
+=====================
+
+.. currentmodule:: solve_nivp
+
+.. autoclass:: ODESystem
+
+   
+   .. automethod:: __init__
+
+   
+   .. rubric:: Methods
+
+   .. autosummary::
+   
+      ~ODESystem.__init__
+      ~ODESystem.step
+      ~ODESystem.step_adaptive
+      ~ODESystem.step_fixed
+   
+   
+
+   
+   
+   

solve_nivp-0.2.0.dev2/docs/source/api/solve_nivp.adaptive_integrator.rst

@@ -0,0 +1,12 @@
+solve\_nivp.adaptive\_integrator
+================================
+
+.. automodule:: solve_nivp.adaptive_integrator
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      AdaptiveStepping
+   

solve_nivp-0.2.0.dev2/docs/source/api/solve_nivp.integrations.rst

@@ -0,0 +1,18 @@
+solve\_nivp.integrations
+========================
+
+.. automodule:: solve_nivp.integrations
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      AlgebraicBackwardEuler
+      BackwardEuler
+      CompositeMethod
+      EmbeddedBETR
+      IntegrationMethod
+      ThetaMethod
+      Trapezoidal
+   

solve_nivp-0.2.0.dev2/docs/source/api/solve_nivp.nonlinear_solvers.rst

@@ -0,0 +1,12 @@
+solve\_nivp.nonlinear\_solvers
+==============================
+
+.. automodule:: solve_nivp.nonlinear_solvers
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      ImplicitEquationSolver
+   

solve_nivp-0.2.0.dev2/docs/source/api/solve_nivp.projections.rst

@@ -0,0 +1,17 @@
+solve\_nivp.projections
+=======================
+
+.. automodule:: solve_nivp.projections
+
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      CoulombProjection
+      GeneralMoreauVIProjection
+      IdentityProjection
+      MuScaledSOCProjection
+      Projection
+      SignProjection
+   

solve_nivp-0.2.0.dev2/docs/source/api/solve_nivp.rl.dependency.rst

@@ -0,0 +1,12 @@
+solve\_nivp.rl.dependency
+=========================
+
+.. automodule:: solve_nivp.rl.dependency
+
+   
+   .. rubric:: Functions
+
+   .. autosummary::
+   
+      ensure_rl_dependencies
+   

solve_nivp-0.2.0.dev2/docs/source/api/solve_nivp.rl.rst

@@ -0,0 +1,15 @@
+solve\_nivp.rl
+==============
+
+.. automodule:: solve_nivp.rl
+
+   
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   callbacks
+   dependency
+   env

solve_nivp-0.2.0.dev2/docs/source/api/solve_nivp.rst

@@ -0,0 +1,25 @@
+solve\_nivp
+===========
+
+.. automodule:: solve_nivp
+
+   
+   .. rubric:: Functions
+
+   .. autosummary::
+   
+      solve_nivp
+   
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   ODESolver
+   ODESystem
+   adaptive_integrator
+   integrations
+   nonlinear_solvers
+   projections
+   rl

solve_nivp-0.2.0.dev2/docs/source/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'solve_nivp'
+copyright = '2025, David Riley'
+author = 'David Riley'
+release = 'March 26, 2025'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',  # NumPy/Google-style docstrings
+    'sphinx.ext.viewcode',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.intersphinx',
+]
+
+# Generate autosummary pages automatically
+autosummary_generate = True
+
+# Type hints in description for cleaner signatures
+autodoc_typehints = 'description'
+
+# Napoleon options
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+
+# Intersphinx mappings for cross-references
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
+}
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']
+
+latex_engine = 'xelatex'
+# latex_elements = {
+#     'preamble': r'\usepackage[utf8]{inputenc}\usepackage[T1]{fontenc}',
+# }
+

solve_nivp-0.2.0.dev2/docs/source/development.rst

@@ -0,0 +1,30 @@
+Development
+===========
+
+Testing
+-------
+Run the unit tests from the project root in a fresh virtual environment:
+
+.. code-block:: bash
+
+   python3 -m venv .venv && source .venv/bin/activate
+   pip install -U pip
+   pip install -e .[test]
+   pytest -q
+
+Documentation
+-------------
+Build the docs locally:
+
+.. code-block:: bash
+
+   cd docs
+   make clean html
+
+Then open ``_build/html/index.html`` in your browser.
+
+Style and contributions
+-----------------------
+- Use NumPy-style docstrings (processed by ``napoleon``).
+- Keep public APIs documented and covered by tests.
+- Submit PRs with focused changes and include updates to docs/examples.

solve_nivp-0.2.0.dev2/docs/source/examples.rst

@@ -0,0 +1,62 @@
+Examples
+========
+
+Sign projection (scalar)
+------------------------
+
+.. code-block:: python
+
+    import numpy as np
+    from solve_nivp import solve_nivp, SignProjection
+
+    # trivial rhs, demonstrate projection behavior
+    rhs = lambda t, y: -y
+    t_span = (0.0, 0.2)
+    y0 = np.array([0.5, 0.0])  # y, w
+
+    proj = SignProjection(y_indices=0, w_indices=1)
+
+    t, y, h, fk, info = solve_nivp(
+        fun=lambda t, s: np.array([-s[0], 0.0]),
+        t_span=t_span,
+        y0=y0,
+        method='backward_euler',
+        projection='sign',
+        solver='semismooth_newton',
+        projection_opts={'y_indices': 0, 'w_indices': 1},
+        solver_opts={'globalization': 'linesearch'}
+    )
+
+    # y[:,0] is state y, y[:,1] is projected w in sign(y)
+
+Coulomb projection (toy)
+------------------------
+
+.. code-block:: python
+
+    import numpy as np
+    from solve_nivp import solve_nivp, CoulombProjection
+
+    # toy constraint force: f_conf(y) = K y (diagonal)
+    K = np.array([2.0, 3.0, 0.0])
+    def con_force(y, t=None, Fk_val=None):
+        return K * y
+
+    y0 = np.zeros(6)  # pairs (v_i, z_i)
+    t_span = (0.0, 0.1)
+
+    t, y, h, fk, info = solve_nivp(
+        fun=lambda t, s: -s,
+        t_span=t_span,
+        y0=y0,
+        method='composite',
+        projection='coulomb',
+        solver='VI',
+        projection_opts={
+            'con_force_func': con_force,
+            'rhok': np.ones_like(y0),
+            'constraint_indices': np.array([0, 2, 4]),
+            'conf_jacobian_mode': 'full',
+        },
+    )
+

solve_nivp-0.2.0.dev2/docs/source/index.rst

@@ -0,0 +1,19 @@
+.. solve_nivp documentation master file, created by
+   sphinx-quickstart on Wed Mar 26 11:17:18 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+solve_nivp documentation
+========================
+
+This site documents the public API and provides guidance for using the solvers and projections.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   quickstart
+   examples
+   modules
+   development

solve_nivp-0.2.0.dev2/docs/source/modules.rst

@@ -0,0 +1,17 @@
+
+solve_nivp API
+==============
+
+.. autosummary::
+   :toctree: api
+   :recursive:
+   :caption: Public modules
+
+   solve_nivp
+   solve_nivp.ODESystem
+   solve_nivp.ODESolver
+   solve_nivp.integrations
+   solve_nivp.adaptive_integrator
+   solve_nivp.nonlinear_solvers
+   solve_nivp.projections
+   solve_nivp.rl

solve_nivp-0.2.0.dev2/docs/source/quickstart.rst

@@ -0,0 +1,42 @@
+Quickstart
+==========
+
+Install
+-------
+
+- Stable: ``pip install solve_nivp``
+- From source (editable): ``pip install -e .[test]``
+
+Minimal example
+---------------
+
+.. code-block:: python
+
+    import numpy as np
+    from solve_nivp import solve_nivp
+
+    # y' = -y with identity projection
+    rhs = lambda t, y: -y
+    t_span = (0.0, 1.0)
+    y0 = np.array([1.0])
+
+    t, y, h, fk, info = solve_nivp(
+        fun=rhs,
+        t_span=t_span,
+        y0=y0,
+        method='composite',
+        projection='identity',
+        solver='VI',
+    )
+
+    print(t[:5], y[:5])
+
+Options
+-------
+- Projections: ``'identity'``, ``'sign'``, ``'coulomb'`` (see API docs for arguments like ``y_indices``, ``w_indices``, ``con_force_func``, ``conf_jacobian_mode``)
+- Solvers: ``'VI'`` and ``'semismooth_newton'`` (globalization ``'none'`` or ``'linesearch'``)
+- Integrators: BackwardEuler, Trapezoidal, ThetaMethod, CompositeMethod, EmbeddedBETR, SDIRK2
+
+Numba acceleration
+------------------
+Some projector internals can use numba if available. To disable, pass ``use_numba=False`` to the relevant projection. To install: ``pip install numba``.

solve_nivp-0.2.0.dev2/docs/source/solve_nivp.rst

@@ -0,0 +1,58 @@
+solve\_nivp package
+===================
+
+.. automodule:: solve_nivp
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+solve\_nivp.ODESolver module
+----------------------------
+
+.. automodule:: solve_nivp.ODESolver
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+solve\_nivp.ODESystem module
+----------------------------
+
+.. automodule:: solve_nivp.ODESystem
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+solve\_nivp.adaptive\_integrator module
+---------------------------------------
+
+.. automodule:: solve_nivp.adaptive_integrator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+solve\_nivp.integrations module
+--------------------------------
+
+.. automodule:: solve_nivp.integrations
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+solve\_nivp.nonlinear\_solvers module
+-------------------------------------
+
+.. automodule:: solve_nivp.nonlinear_solvers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+solve\_nivp.projections module
+------------------------------
+
+.. automodule:: solve_nivp.projections
+   :members:
+   :undoc-members:
+   :show-inheritance:

{solve_nivp-0.2.0.dev1 → solve_nivp-0.2.0.dev2}/pyproject.toml

@@ -1,13 +1,14 @@
 [build-system]
-requires = ["setuptools", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "solve_nivp"
-version = "0.2.0.dev1"
+version = "0.2.0.dev2"
 description = "A Python toolkit for integrating nonsmooth dynamical systems"
 readme = "README.md"
-license = {text = "MIT"}
+license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.9"
 authors = [
   { name = "David Riley" },
@@ -24,7 +25,6 @@ keywords = [
 classifiers = [
   "Development Status :: 4 - Beta",
   "Intended Audience :: Science/Research",
-  "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",
   "Topic :: Scientific/Engineering :: Mathematics",
   "Topic :: Scientific/Engineering :: Physics",
@@ -66,3 +66,8 @@ solve_nivp-selftest = "solve_nivp._selftest:main"
 Homepage = "https://github.com/ERC-INJECT/solve_nivp"
 Documentation = "https://github.com/ERC-INJECT/solve_nivp/tree/main/docs"
 Issues = "https://github.com/ERC-INJECT/solve_nivp/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["solve_nivp*"]
+exclude = ["tests*"]

solve_nivp-0.2.0.dev2/pytest.ini

@@ -0,0 +1,10 @@
+[pytest]
+addopts = -q -m "not slow and not external and not examples"
+testpaths = tests
+markers =
+    unit: fast package-level unit tests.
+    slow: long-running numerical or benchmark-style tests.
+    examples: tests that depend on example notebooks/scripts or generated example helpers.
+    external: tests that require optional external projects or data outside the core package.
+    petsc: tests that require petsc4py/PETSc.
+    rl: tests that require reinforcement-learning optional dependencies.

{solve_nivp-0.2.0.dev1 → solve_nivp-0.2.0.dev2/src}/solve_nivp/ODESolver.py

@@ -42,30 +42,35 @@ class ODESolver:
         abort_on_fixed_failure: bool = True,
         t_eval: Optional[np.ndarray] = None,
     ):
-        """
-        Initialize the ODESolver.
+        """Initialize the time integration driver.
 
-        Parameters:
-            system: The ODE system to be integrated.
-            t_span: A tuple (t0, tf) specifying the start and end times.
-            h: The initial time step size.
-            thin_output: Store every *N*-th accepted step (1 = store all).
-                First and last steps are always stored.
-            store_fk: Whether to store per-step residual vectors.
-                Setting to False saves ~1× state-vector memory per step.
-            gc_interval: Call ``gc.collect()`` every *N* accepted steps
-                (0 = disabled). Useful for large problems where stale
-                solver factorisations may linger.
-            abort_on_fixed_failure: Stop fixed-step integration at the first
-                nonlinear failure instead of marching forward with the failed
-                state. The failed attempt is still recorded in
-                ``error_estimates``.
-            t_eval: Strictly increasing array of times in ``[t0, tf]`` that
-                must be evaluated.  When provided, the time loop clips the
-                step so it lands exactly on each ``t_eval`` entry, and the
-                returned histories contain only those entries (matches the
-                scipy ``solve_ivp`` convention).  Pass ``None`` to keep the
-                adaptive/fixed grid as the output.
+        Parameters
+        ----------
+        system : object
+            ODE system to integrate.
+        t_span : tuple of float
+            ``(t0, tf)`` start and end times.
+        h : float, default 1e-2
+            Initial time step size.
+        thin_output : int, default 1
+            Store every *N*-th accepted step. First and last steps are always
+            stored.
+        store_fk : bool, default True
+            Whether to store per-step residual vectors. Setting this to
+            ``False`` saves about one state-vector of memory per step.
+        gc_interval : int, default 0
+            Call ``gc.collect()`` every *N* accepted steps. ``0`` disables
+            explicit garbage collection.
+        abort_on_fixed_failure : bool, default True
+            Stop fixed-step integration at the first nonlinear failure instead
+            of marching forward with the failed state. The failed attempt is
+            still recorded in ``error_estimates``.
+        t_eval : ndarray or None, optional
+            Strictly increasing array of times in ``[t0, tf]`` that must be
+            evaluated. When provided, the time loop clips each step so it lands
+            exactly on each requested entry, and the returned histories contain
+            only those entries. Pass ``None`` to keep the adaptive or fixed
+            integration grid as the output.
         """
         self.system = system
         self.t0, self.tf = t_span

{solve_nivp-0.2.0.dev1 → solve_nivp-0.2.0.dev2/src}/solve_nivp/ODESystem.py

@@ -124,7 +124,7 @@ class ODESystem:
         Returns:
             An instance of the selected integration method.
         """
-        from .nonlinear_solvers import ImplicitEquationSolver
+        from .solvers.nonlinear_solvers import ImplicitEquationSolver
         from .projections import IdentityProjection
 
         default_solver = ImplicitEquationSolver(