Metadata-Version: 2.4
Name: FLToptim
Version: 0.3.0
Summary: Fast Legendre-transform convex optimisation for energy-storage operation and spatial economic dispatch
Author-email: Robin Girard <robin.girard@minesparis.psl.eu>
License-Expression: MIT
Project-URL: Homepage, https://git.persee.minesparis.psl.eu/energy-alternatives/FLToptim
Project-URL: Source, https://git.persee.minesparis.psl.eu/energy-alternatives/FLToptim
Keywords: energy,storage,hydro,battery,dynamic programming,Legendre transform,convex optimisation,economic dispatch,parametric simplex,linear programming
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: highspy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: scipy; extra == "test"
Dynamic: license-file

# FLToptim — Fast Legendre Transform Optim

Fast convex optimisation for energy-storage operation and spatial economic dispatch, built around the
**Legendre-transform dynamic program** for convex piecewise-linear (and quadratic) value functions.

## What's inside

- **`cplfunction` / `cpqfunction`** — the convex piecewise-linear/quadratic value-function DP
  (`OptimMargInt`). Each function is stored as a `map<position, slope-increment>`, so the
  inf-convolutions of the Legendre / dynamic-programming recursion stay near-linear. This is the
  original *dynprogstorage* core (Girard, Barbesant, Foucault, Kariniotakis, 2013).
- **`param_simplex`** — a bespoke parametric right-hand-side **dual simplex** that traces the exact
  injection-cost curve φ_n(y) of a small dense network LP in a single pass (one dual pivot per
  breakpoint), carrying its basis across hours.
- **`elec` / `mr_decompose`** — the **spatial-LP ↔ storage-DP decomposition** for perfect-foresight
  annual dispatch: alternate a per-hour spatial network LP with the per-node storage DP, passing each
  node's convex injection-cost *curve* (not a scalar price) so the scheme is curvature-damped and
  converges to the monolithic optimum. Handles reservoirs, batteries (efficiency kink) and coupled
  multi-energy (electricity + hydrogen) networks, with optional parallelism (hour-chunk curve build;
  Jacobi across storages).

## Install / build

```sh
pip install fltoptim          # from PyPI (builds from source on platforms without a wheel)
# or, from a checkout:
pip install -e .              # builds the Cython DP extension + the parametric-simplex shared library
# or
python setup.py build_ext --inplace
```

Building from source needs a C++17 compiler (Linux/macOS); `numpy` and `highspy` are the runtime
dependencies. The reference frontal solves in the decomposition use Gurobi when available (optional).

The test suite ships with the package:

```sh
pip install "fltoptim[test]"
python -m pytest --pyargs FLToptim.tests -m "not slow" -q
```

## Reference

R. Girard, V. Barbesant, F. Foucault, G. Kariniotakis, *Fast dynamic programming with application to
storage planning*, 2013. Please cite it if you use this software (see `CITATION.cff`).
