Metadata-Version: 2.4
Name: jnlr
Version: 0.1.0
Summary: Jax-based library for nonlinear reconciliation and learning
Author-email: Lorenzo Nespoli <lorenzo.nespoli@supsi.ch>
Maintainer-email: Lorenzo Nespoli <lorenzo.nespoli@supsi.ch>
License-Expression: MIT
Project-URL: Homepage, https://github.com/SUPSI-DACD-ISAAC/JNLR
Project-URL: Documentation, https://supsi-dacd-isaac.github.io/JNLR/
Project-URL: Repository, https://github.com/SUPSI-DACD-ISAAC/JNLR
Project-URL: Issues, https://github.com/SUPSI-DACD-ISAAC/JNLR/issues
Keywords: jax,reconciliation,nonlinear,manifold,geodesics,optimization,constraint-satisfaction
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: diffrax>=0.7.0
Requires-Dist: jax>=0.7.1
Requires-Dist: numpy>=2.1.0
Requires-Dist: optax>=0.2.5
Requires-Dist: plotly>=6.3.0
Requires-Dist: pygeodesic>=0.1.11
Requires-Dist: scikit-image>=0.26.0
Requires-Dist: scikit-learn>=1.7.1
Requires-Dist: scipy>=1.14.0
Requires-Dist: tqdm>=4.60.0
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6.1; extra == "docs"
Requires-Dist: mkdocs-material>=9.6.18; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.30.0; extra == "docs"
Dynamic: license-file

# JNLR Jax-based non-linear reconciliation and learning 

<p align="center">
  <img src="docs/logo.webp" alt="JNLR Logo" width="300">
</p>

**J-NLR** is a Python library for non-linear reconciliation, learning, and geometric analysis on constraint manifolds. Built on [JAX](https://github.com/google/jax), it leverages automatic differentiation and GPU/TPU acceleration to efficiently project predicted values onto surfaces defined by implicit constraints $f(z) = 0$.

📚 **[Documentation](https://supsi-dacd-isaac.github.io/JNLR/)** - Full API reference, examples, and interactive notebooks

## Key Features

- **Non-linear Reconciliation**: Multiple solvers (Augmented Lagrangian, curvature-aware Newton, vanilla projections) for projecting forecasts onto constraint manifolds
- **SHOULD Analysis**: Curvature-based methods to determine *when* reconciliation is beneficial—verify if RMSE is guaranteed to reduce before applying corrections
- **Manifold Sampling**: Sample from explicit (graph) or implicit manifolds using volume-weighted sampling, Latin hypercube, or Langevin dynamics on the constraint surface
- **Mesh Generation**: Create triangulated meshes from explicit parameterizations for visualization and geodesic computation
- **Geodesics**: Compute geodesic distances and shortest paths on manifolds via exact MMP algorithm or fast graph-based approximations; includes probabilistic scores like pointcloud geodesic distance
- **Visualization**: Interactive 3D rendering of manifolds, projections, and geodesic paths with Plotly
- **JAX-native**: Fully JIT-compiled and vectorized (`vmap`) for high-performance batch processing


## Running the notebooks
If you want to run the notebooks, the suggested way is to install `uv` packet manager, cloning the repo and, from a terminal:
`uv pip install -e .`


## Citation

If you use **JNLR** in academic work, please cite the associated paper:

Lorenzo Nespoli, Anubhab Biswas, Roberto Rocchetta, and Vasco Medici.  
"Nonlinear reconciliation: Error reduction theorems."  
Transactions on Machine Learning Research (TMLR), 2026.  
OpenReview: https://openreview.net/forum?id=dXRWuogm3J

### BibTeX

```bibtex
@article{nespoli2026nonlinear_reconciliation,
  title   = {Nonlinear reconciliation: Error reduction theorems},
  author  = {Nespoli, Lorenzo and Biswas, Anubhab and Rocchetta, Roberto and Medici, Vasco},
  journal = {Transactions on Machine Learning Research},
  year    = {2026},
  url     = {https://openreview.net/forum?id=dXRWuogm3J},
  note    = {Accepted by TMLR}
}
```

## Acknowledgements

This work has been funded by the Swiss State Secretariat for Education, Research and Innovation (SERI) under the Swiss contribution to the Horizon Europe projects DR-RISE (Horizon Europe, Grant Agreement No. 101104154) and REEFLEX (Horizon Europe, Grant Agreement No. 101096192).
