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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solve_nivp
-Version: 0.2.0.dev2
+Version: 0.2.0.dev3
 Summary: A Python toolkit for integrating nonsmooth dynamical systems
 Author: David Riley, Ioannis Stefanou
 License-Expression: MIT

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.alart_curnier_contact.rst

@@ -0,0 +1,12 @@
+solve\_nivp.alart\_curnier\_contact
+===================================
+
+.. automodule:: solve_nivp.alart_curnier_contact
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      build_alart_curnier_contact
+      build_dynamic_alart_curnier_contact

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.block_system.rst

@@ -0,0 +1,7 @@
+solve\_nivp.block\_system
+=========================
+
+.. automodule:: solve_nivp.block_system
+
+Compatibility module. New code should prefer
+``solve_nivp.solvers.block_system``.

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.contact.rst

@@ -0,0 +1,17 @@
+solve\_nivp.contact
+===================
+
+.. automodule:: solve_nivp.contact
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      build_impulse_contact
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      ContactSystem

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.desaxce_contact.rst

@@ -0,0 +1,13 @@
+solve\_nivp.desaxce\_contact
+============================
+
+.. automodule:: solve_nivp.desaxce_contact
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      build_dynamic_desaxce_contact
+      build_dynamic_desaxce_projected_contact
+      build_dynamic_desaxce_residual_contact

{solve_nivp-0.2.0.dev2 → solve_nivp-0.2.0.dev3}/docs/source/api/solve_nivp.integrations.rst

@@ -10,9 +10,13 @@ solve\_nivp.integrations
    
       AlgebraicBackwardEuler
       BackwardEuler
+      BackwardEulerSchur
       CompositeMethod
       EmbeddedBETR
       IntegrationMethod
+      RadauIIA
+      RadauIIASchur
+      SDIRK2
       ThetaMethod
       Trapezoidal
    

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.macklin_contact.rst

@@ -0,0 +1,17 @@
+solve\_nivp.macklin\_contact
+============================
+
+.. automodule:: solve_nivp.macklin_contact
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      build_macklin_contact_blocked
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      MacklinBlockSystem

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.moreau_jean_fremond.rst

@@ -0,0 +1,17 @@
+solve\_nivp.moreau\_jean\_fremond
+=================================
+
+.. automodule:: solve_nivp.moreau_jean_fremond
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      build_moreau_jean_fremond
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      MoreauJeanFremondStepper

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.ncp_contact.rst

@@ -0,0 +1,19 @@
+solve\_nivp.ncp\_contact
+========================
+
+.. automodule:: solve_nivp.ncp_contact
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      build_dynamic_ncp_contact
+      build_ncp_contact
+      build_ncp_contact_blocked
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      NCPBlockSystem

{solve_nivp-0.2.0.dev2 → solve_nivp-0.2.0.dev3}/docs/source/api/solve_nivp.nonlinear_solvers.rst

@@ -3,10 +3,6 @@ solve\_nivp.nonlinear\_solvers
 
 .. automodule:: solve_nivp.nonlinear_solvers
 
+Compatibility module. New code should prefer
+``solve_nivp.solvers.nonlinear_solvers``.
    
-   .. rubric:: Classes
-
-   .. autosummary::
-   
-      ImplicitEquationSolver
-   

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.pcr.rst

@@ -0,0 +1,6 @@
+solve\_nivp.pcr
+===============
+
+.. automodule:: solve_nivp.pcr
+
+Compatibility module. New code should prefer ``solve_nivp.solvers.pcr``.

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.projected_radau_contact.rst

@@ -0,0 +1,21 @@
+solve\_nivp.projected\_radau\_contact
+=====================================
+
+.. automodule:: solve_nivp.projected_radau_contact
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      build_projected_radau_contact
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      DeSaxceProjectedConeLaw
+      NCPNormalConeLaw
+      ProjectedRadauContactLaw
+      ProjectedRadauContactModel
+      SOCFischerBurmeisterLaw

{solve_nivp-0.2.0.dev2 → solve_nivp-0.2.0.dev3}/docs/source/api/solve_nivp.projections.rst

@@ -8,9 +8,13 @@ solve\_nivp.projections
 
    .. autosummary::
    
+      AlgebraicConstraintProjection
+      AnisotropicSOCProjection
+      CompositeContactProjection
       CoulombProjection
       GeneralMoreauVIProjection
       IdentityProjection
+      MoreauSOCProjection
       MuScaledSOCProjection
       Projection
       SignProjection

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.rattle_contact.rst

@@ -0,0 +1,25 @@
+solve\_nivp.rattle\_contact
+===========================
+
+.. automodule:: solve_nivp.rattle_contact
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      build_dynamic_rattle_contact
+      build_rattle_system
+      solve_dynamic_rattle_contact
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      RattleAlgebraicSpec
+      RattleBilateralSpec
+      RattleContactSpec
+      RattleContactSystem
+      RattleMechanicalSystem
+      RattleSolveResult
+      RattleSolver

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.rl.callbacks.rst

@@ -0,0 +1,7 @@
+solve\_nivp.rl.callbacks
+=========================
+
+.. automodule:: solve_nivp.rl.callbacks
+   :members:
+   :undoc-members:
+   :show-inheritance:

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.rl.env.rst

@@ -0,0 +1,7 @@
+solve\_nivp.rl.env
+==================
+
+.. automodule:: solve_nivp.rl.env
+   :members:
+   :undoc-members:
+   :show-inheritance:

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

@@ -0,0 +1,16 @@
+solve\_nivp.rl
+==============
+
+.. automodule:: solve_nivp.rl
+
+The environment and callback modules require optional reinforcement-learning
+dependencies. Install ``solve_nivp[rl]`` to use them at runtime.
+
+.. rubric:: Modules
+
+.. toctree::
+   :maxdepth: 1
+
+   solve_nivp.rl.callbacks
+   solve_nivp.rl.dependency
+   solve_nivp.rl.env

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

@@ -0,0 +1,38 @@
+solve\_nivp API
+===============
+
+.. automodule:: solve_nivp
+   :no-members:
+
+Top-Level Functions
+-------------------
+
+.. autofunction:: solve_nivp.solve_nivp
+
+``solve_ivp_ns`` is kept as a compatibility alias for ``solve_nivp``.
+
+Modules
+-------
+
+.. toctree::
+   :maxdepth: 1
+
+   solve_nivp.ODESolver
+   solve_nivp.ODESystem
+   solve_nivp.adaptive_integrator
+   solve_nivp.alart_curnier_contact
+   solve_nivp.block_system
+   solve_nivp.contact
+   solve_nivp.desaxce_contact
+   solve_nivp.integrations
+   solve_nivp.macklin_contact
+   solve_nivp.moreau_jean_fremond
+   solve_nivp.ncp_contact
+   solve_nivp.nonlinear_solvers
+   solve_nivp.pcr
+   solve_nivp.projected_radau_contact
+   solve_nivp.projections
+   solve_nivp.rattle_contact
+   solve_nivp.rl
+   solve_nivp.solvers
+   solve_nivp.soccp_pgs

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.soccp_pgs.rst

@@ -0,0 +1,19 @@
+solve\_nivp.soccp\_pgs
+======================
+
+.. automodule:: solve_nivp.soccp_pgs
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      desaxce_shift_factory
+      fremond_shift_factory
+      soccp_pgs
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      SocppPgsInfo

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.solvers.block_system.rst

@@ -0,0 +1,11 @@
+solve\_nivp.solvers.block\_system
+=================================
+
+.. automodule:: solve_nivp.solvers.block_system
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      BlockStructuredSystem
+      SchurComplementSolver

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.solvers.nonlinear_solvers.rst

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

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.solvers.pcr.rst

@@ -0,0 +1,10 @@
+solve\_nivp.solvers.pcr
+=======================
+
+.. automodule:: solve_nivp.solvers.pcr
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      pcr_solve

solve_nivp-0.2.0.dev3/docs/source/api/solve_nivp.solvers.rst

@@ -0,0 +1,13 @@
+solve\_nivp.solvers
+===================
+
+.. automodule:: solve_nivp.solvers
+
+.. rubric:: Modules
+
+.. toctree::
+   :maxdepth: 1
+
+   solve_nivp.solvers.block_system
+   solve_nivp.solvers.nonlinear_solvers
+   solve_nivp.solvers.pcr

{solve_nivp-0.2.0.dev2 → solve_nivp-0.2.0.dev3}/docs/source/conf.py

@@ -3,13 +3,18 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / 'src'))
+
 # -- 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'
+release = '0.2.0.dev1'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -23,12 +28,20 @@ extensions = [
     'sphinx.ext.intersphinx',
 ]
 
-# Generate autosummary pages automatically
-autosummary_generate = True
+# API stubs are committed under docs/source/api. Regenerate them explicitly
+# when the public module list changes so normal docs builds do not dirty Git.
+autosummary_generate = False
 
 # Type hints in description for cleaner signatures
 autodoc_typehints = 'description'
 
+# Optional extras are documented without requiring their runtime dependencies.
+autodoc_mock_imports = [
+    'gymnasium',
+    'stable_baselines3',
+    'sb3_contrib',
+]
+
 # Napoleon options
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
@@ -49,10 +62,9 @@ exclude_patterns = []
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'alabaster'
-html_static_path = ['_static']
+html_static_path = []
 
 latex_engine = 'xelatex'
 # latex_elements = {
 #     'preamble': r'\usepackage[utf8]{inputenc}\usepackage[T1]{fontenc}',
 # }
-

{solve_nivp-0.2.0.dev2 → solve_nivp-0.2.0.dev3}/docs/source/index.rst

@@ -14,6 +14,7 @@ This site documents the public API and provides guidance for using the solvers a
    :caption: Contents:
 
    quickstart
+   public_api
    examples
-   modules
+   api/solve_nivp
    development

solve_nivp-0.2.0.dev3/docs/source/public_api.rst

@@ -0,0 +1,93 @@
+Public API Policy
+=================
+
+This page defines the supported surface of ``solve_nivp``.  It is intended to
+keep the package usable as a general library while still allowing active
+research backends to evolve.
+
+Stable API
+----------
+
+The stable API is the recommended import surface for users and downstream
+projects.  These names should be documented, covered by tests, and changed only
+with a compatibility plan.
+
+Top-level convenience API:
+
+* ``solve_nivp.solve_nivp``
+* ``solve_nivp.__version__``
+
+System and driver classes:
+
+* ``solve_nivp.ODESystem``
+* ``solve_nivp.ODESolver``
+
+Nonlinear solver:
+
+* ``solve_nivp.ImplicitEquationSolver``
+
+Integrator classes:
+
+* ``solve_nivp.BackwardEuler``
+* ``solve_nivp.Trapezoidal``
+* ``solve_nivp.ThetaMethod``
+* ``solve_nivp.CompositeMethod``
+* ``solve_nivp.EmbeddedBETR``
+* ``solve_nivp.SDIRK2``
+* ``solve_nivp.RadauIIA``
+
+Projection classes:
+
+* ``solve_nivp.Projection``
+* ``solve_nivp.IdentityProjection``
+* ``solve_nivp.SignProjection``
+* ``solve_nivp.CoulombProjection``
+* ``solve_nivp.GeneralMoreauVIProjection``
+* ``solve_nivp.MuScaledSOCProjection``
+* ``solve_nivp.MoreauSOCProjection``
+* ``solve_nivp.AnisotropicSOCProjection``
+* ``solve_nivp.AlgebraicConstraintProjection``
+* ``solve_nivp.CompositeContactProjection``
+
+Experimental API
+----------------
+
+The experimental API is useful and importable, but it is still allowed to
+change while the package design is being refined.  Where possible, changes
+should still be documented in release notes and tested against the examples
+that use them.
+
+Current experimental areas:
+
+* Contact-system builders and backend-specific helpers.
+* Schur-complement contact solvers.
+* RATTLE contact-system helpers.
+* PETSc-specific large-scale solver paths.
+* ``solve_nivp.rl`` reinforcement-learning wrappers.
+
+Private Internals
+-----------------
+
+Names beginning with ``_`` are private unless explicitly documented here or in
+the API reference.  Internal caches, factorization reuse details, helper
+dispatch functions, notebook utilities, and generated example artifacts are not
+part of the compatibility contract.
+
+Research And Workspace Material
+-------------------------------
+
+The repository currently contains research notebooks, benchmark outputs,
+diagnostic scripts, and generated result files.  Those are valuable for
+reproducibility, but they are not the core package API.  During cleanup they
+should be separated from the installable library path and marked as examples,
+benchmarks, external reproductions, or archived artifacts.
+
+Compatibility Rule
+------------------
+
+Stable API changes should prefer one of these routes:
+
+* preserve the existing import and behavior;
+* add a new explicit option while keeping the old default;
+* deprecate first, remove later;
+* document unavoidable breaking changes with migration notes.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "solve_nivp"
-version = "0.2.0.dev2"
+version = "0.2.0.dev3"
 description = "A Python toolkit for integrating nonsmooth dynamical systems"
 readme = "README.md"
 license = "MIT"

{solve_nivp-0.2.0.dev2 → solve_nivp-0.2.0.dev3}/src/solve_nivp/__init__.py

@@ -50,7 +50,7 @@ See the Sphinx documentation (``docs/``) for extended examples.
 
 import numpy as np
 
-__version__ = "0.2.0.dev2"
+__version__ = "0.2.0.dev3"
 
 from .projections import (
   Projection,
@@ -69,6 +69,7 @@ from .integrations import BackwardEuler, BackwardEulerSchur, RadauIIASchur, Trap
 from .solvers.block_system import SchurComplementSolver, BlockStructuredSystem
 from .ODESystem import ODESystem
 from .ODESolver import ODESolver
+from .mjf_integration import (MJFIntegrationMethod, solve_mjf_fixed_step, MJFContactView)
 from .contact import build_impulse_contact, ContactSystem
 from .alart_curnier_contact import (
   build_alart_curnier_contact,
@@ -211,8 +212,9 @@ def solve_nivp(
   adaptive_opts : dict or None
     Optional controls for the adaptive stepper. Recognized keys include
     ``h_min``, ``h_max``, ``h_up``, ``h_down``, ``safety``, ``use_PI``,
-    ``method_order`` (alias ``p``), ``atol``, ``rtol``, and
-    ``skip_error_indices``. ``h0`` here (if provided) overrides the top-level
+    ``method_order`` (alias ``p``), ``atol``, ``rtol``, ``record_diagnostics``,
+    ``diagnostic_component_names``, and ``skip_error_indices``. ``h0`` here (if
+    provided) overrides the top-level
     ``h0`` for the initial step guess. Unrecognized keys are ignored.
   adaptive : bool, default True
     Enable Richardson extrapolation based adaptive step size control.
@@ -429,6 +431,19 @@ def solve_nivp(
       # Forward active-set filter setting
       stepper.active_set_filter = bool(active_set_filter)
 
+      # Optional diagnostics for blockwise error/residual profiling.
+      _record_diag = bool(adaptive_opts.get('record_diagnostics', False))
+      stepper.record_diagnostics = _record_diag
+      solver_instance.record_diagnostics = _record_diag
+      _diag_names = adaptive_opts.get('diagnostic_component_names', None)
+      if _diag_names is not None:
+        try:
+          _diag_names = list(_diag_names)
+        except TypeError:
+          _diag_names = None
+        stepper.diagnostic_component_names = _diag_names
+        solver_instance.diagnostic_component_names = _diag_names
+
       # Handle auto-h0 from top level
       if h0 is None or (isinstance(h0, str) and str(h0).lower() == 'auto'):
         stepper._auto_h0 = True