Metadata-Version: 2.4
Name: solve_nivp
Version: 0.1.2
Summary: A Python toolkit for integrating nonsmooth dynamical systems
Author: David Riley, Ioannis Stefanou
License: 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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.8
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: rl
Requires-Dist: gymnasium>=0.29; extra == "rl"
Requires-Dist: stable-baselines3>=2.2; extra == "rl"
Requires-Dist: sb3-contrib>=2.2; extra == "rl"
Requires-Dist: matplotlib>=3.5; extra == "rl"
Provides-Extra: docs
Requires-Dist: sphinx>=6; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2; extra == "docs"
Dynamic: license-file

# solve_nivp

A Python library for time integration of **nonsmooth** ODE/DAE systems—models
with abrupt changes such as impacts, switching, or inequality constraints.
Such models arise in frictional contact mechanics, piecewise and switching
behaviour in circuits, sliding-mode control, and discontinuous rules in
finance and energy markets. Classical solvers, which assume smoothness, often
require regularisation or very small steps due to the inherent stiffness
of these models. **solve_nivp** builds nonsmooth rules directly into the
implicit time-stepping scheme, enabling users to encode constraints and advance
the state robustly.

## Key features

- **Projection-based constraint encoding.** Users express set-valued or
  nonsmooth relations as projections onto convex sets (Coulomb friction cone,
  sign / normal cone, second-order cone, algebraic constraints). Custom
  projections need only implement `project()` and an optional `tangent_cone()`.

- **Nonlinear solvers for nonsmooth problems.** A semismooth Newton method with
  Armijo line search and a variational-inequality (VI) fixed-point iteration,
  both with standard tolerances, safeguards, and iteration diagnostics.

- **Implicit integrators.** Backward Euler, Trapezoidal, θ-method, a composite
  TR–BE scheme (Bathe-type, second-order), and an embedded BE–TR error estimator.

- **Adaptive step-size control** with Richardson extrapolation.

- **Optional RL add-on.** Exposes the time integrator as a Gym-style
  environment for learning adaptive step-size policies (TD3 / TQC via Stable
  Baselines 3).

The library is organised around three interchangeable components—projection,
nonlinear solver, and integrator—so that swapping algorithms during
experimentation is straightforward. Linear-algebra routines operate on dense or
sparse arrays in the SciPy ecosystem.

## Installation

Recommended developer install:

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -U pip
pip install -e .[test]
```

Optional extras:

```bash
# RL experiments
pip install -e .[rl]
```

## Quickstart

```python
import numpy as np
from solve_nivp import solve_ivp_ns

# simple smooth rhs: y' = -y
rhs = lambda t, y: -y

t_span = (0.0, 1.0)
y0 = np.array([1.0])

# identity projection, VI solver via composite integrator
sol = solve_ivp_ns(
    fun=rhs,
    t_span=t_span,
    y0=y0,
    method='composite',
    projection='identity',
    solver='VI',
)

print(sol[0][:5], sol[1][:5])  # t, y samples
```

See `examples/` for notebooks on friction stick–slip, bouncing ball (contact/impact), SOC constraints, and sliding-mode control.

## Running tests

```bash
pytest -q
```

## Building the documentation

```bash
cd docs
make clean html
```
Open `docs/_build/html/index.html`.

## RL experiments (optional)

The `RL_Adaption/` folder contains optional experiments (TD3/TQC) for learned adaptivity on challenging nonsmooth problems. Large artifacts are ignored by Git and not required for core installation or testing.

## Citation

See `CITATION.cff`. If you use this software, please cite the JOSS paper once available.

## License

MIT License (see `LICENSE`).
