Moreau Examples

GPU-accelerated differentiable convex optimization — a visual gallery of notebooks showcasing Moreau.

Quick Start

git clone https://github.com/moreau-opt/moreau-examples.git
cd moreau-examples
pip install jupyter numpy scipy matplotlib seaborn torch cvxpy cvxpylayers Pillow
jupyter notebook notebooks/

Moreau install: Follow the install instructions to set up Moreau for your platform before running the notebooks.

Gallery

	Notebook	Description	Features
	Portfolio Optimization	Markowitz mean-variance optimization: CVXPY, moreau.Solver, batched frontier via CompiledSolver, differentiable Jacobians via moreau.torch, warm-started rolling rebalancing.	CompiledSolvermoreau.torchbatcheddifferentiablewarm-startGPU
	MPC Trajectory Control	Model Predictive Control for a 2D vehicle. Closed-loop simulation with warm starting, animated GIF, 16 initial states solved in parallel.	CompiledSolverbatchedwarm-startanimation
	Compressed Sensing	1D sparse recovery, 2D image reconstruction via TV minimization, and learning the measurement matrix by differentiating through the reconstruction solver.	CVXPYcvxpylayersdifferentiableLP
	Schrödinger Bridges	Entropy-regularized optimal transport as a Schrödinger bridge. Batched sweep of 64 mass-conservation penalties via cvxpylayers.	cvxpylayersbatchedexp-conesanimation
	Swarm Motion Planning	100 agents swap positions on a circle without collisions. SCP with batched GPU solves — each round is one CompiledSolver call.	CompiledSolverbatchedGPUQPSCP
	Predict, then Optimize	Shortest path routing on a 20×20 grid with learned edge costs. End-to-end training through a differentiable LP layer achieves lower regret than two-stage.	cvxpylayersbatcheddifferentiableGPUPyTorchanimation
	Sudoku	Sudoku via LP relaxation — 729 variables, exact integer solution from convex relaxation. 256 puzzles solved simultaneously.	CompiledSolverbatchedLPGPU
	Differentiable Contact	Learn friction from observed motion: Coulomb friction cones (SOC3), chain of differentiable contact solves. Shows why smoothed contact (MuJoCo-style) fails where moreau.torch succeeds.	moreau.torchdifferentiableSOC
	Fair Bandwidth Allocation	Alpha-fairness via power cones: sweep the fairness-throughput tradeoff, then learn optimal link capacities by differentiating through the fair allocation solver.	cvxpylayersdifferentiableGPUpower-conesanimation
	Sparsemax Attention	Sparse attention via simplex projection QP. Train softmax, swap to sparsemax for exact-zero attention weights, fine-tune end-to-end through cvxpylayers.	CVXPYcvxpylayersdifferentiablePyTorch
	BarrierNet Safety Filter	BarrierNet: neural net + differentiable CBF-QP safety layer, trained end-to-end through Moreau. Guaranteed safe on unseen obstacle configurations where a plain neural network crashes.	cvxpylayersdifferentiableGPUPyTorchQP

Feature Matrix

Notebook	Interface	Batched	Differentiable	Warm Start	GPU	Cones
Portfolio	CompiledSolvermoreau.torch	✅	✅	✅	✅	zero, nonneg
MPC	CompiledSolver	✅		✅	✅	zero, nonneg
Compressed Sensing	CVXPYcvxpylayers		✅			zero, nonneg
Schrödinger Bridges	cvxpylayers	✅	✅			zero, nonneg, exp
Swarm Planning	CompiledSolver	✅			✅	zero, nonneg
Predict, then Optimize	cvxpylayers	✅	✅		✅	zero, nonneg
Sudoku	CompiledSolver	✅			✅	zero, nonneg
Contact Friction	moreau.torch		✅			SOC
Bandwidth Allocation	cvxpylayers		✅		✅	zero, nonneg, power
Sparsemax Attention	CVXPYcvxpylayers		✅			zero, nonneg
Safety Filter	cvxpylayers		✅		✅	nonneg

Project Structure

moreau-examples/
├── README.md
├── pyproject.toml
├── assets/ # Pre-rendered thumbnails and GIFs
├── utils/
│ ├── style.py # Shared color palette + matplotlib theme
│ ├── animation.py # GIF/animation helpers
│ └── sparse.py # CSR matrix construction helpers
├── notebooks/
│ ├── portfolio_optimization.ipynb
│ ├── mpc_trajectory.ipynb
│ ├── compressed_sensing.ipynb
│ ├── optimal_transport.ipynb
│ ├── swarm_planning.ipynb
│ ├── predict_then_optimize.ipynb
│ ├── sudoku.ipynb
│ ├── contact_friction.ipynb
│ ├── bandwidth_allocation.ipynb
│ ├── sparsemax_attention.ipynb
│ └── safety_filter.ipynb
└── scripts/
└── render_notebooks.py # Execute all notebooks + extract thumbnails

Requirements

• Python 3.12+
• Moreau
• NumPy, SciPy, Matplotlib, Seaborn, PyTorch, CVXPY, cvxpylayers, Pillow

All notebooks use float64 precision and include committed outputs — you can browse the results on GitHub without running anything.

Links

• Moreau Documentation
• Moreau API Reference

License

Apache 2.0