Metadata-Version: 2.4
Name: fastprox
Version: 0.3.0
Summary: Exact proximal operators and projections with derivatives
Keywords: proximal operator,projection,total variation,optimization,bilevel,autodiff
Author-Email: David Villacís <david@villacis.net>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Project-URL: Homepage, https://github.com/dvillacis/fastprox
Project-URL: Documentation, https://github.com/dvillacis/fastprox/blob/master/docs/api.md
Project-URL: Changelog, https://github.com/dvillacis/fastprox/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/dvillacis/fastprox/issues
Requires-Python: >=3.12
Requires-Dist: numpy>=1.26
Description-Content-Type: text/markdown

# fastprox

Exact proximal operators and projections with derivatives. A C++17 core
behind a plain-C API, with Python bindings.

- **Exact or certified.** Direct algorithms (Condat's 1D TV and simplex
  projection, the taut string, pool-adjacent-violators, closed forms) where
  they exist. The image TV solvers stop on a certified duality gap, and
  anisotropic TV is polished to the exact solution once its regions are
  found.
- **Differentiable.** Jacobian-vector and vector-Jacobian products in the
  input, the step and the operator's parameters, for bilevel learning and
  implicit differentiation, also inside PyTorch and JAX programs
  (`fastprox.torch`, `fastprox.jax`, since 0.3).
- **Batched.** Applied along any axis of a float32 or float64 array, with rows
  processed in parallel on fastprox's own threads (no OpenMP runtime to clash
  with PyTorch or others) and results bit-identical for any number of threads.
- **Permissive.** MIT licensed; every kernel is written from the papers.

## Install

```sh
pip install fastprox
```

Wheels are abi3 for CPython 3.12 and later on Linux (x86_64, aarch64), macOS
(arm64 from 11.0, x86_64 from 10.15) and Windows (amd64), and depend on
nothing but NumPy. The PyTorch and JAX wrappers and image TV on GPUs (since
0.3) use PyTorch and JAX when they are installed, and never require them.

## Use

```python
import numpy as np
import fastprox as fp

x = np.random.default_rng(0).normal(size=(64, 1000))

z = fp.tv1d(x, gamma=0.5)                 # 1D total variation along the last axis
p = fp.project_simplex(x, radius=1.0)     # each row onto the simplex
s = fp.soft_threshold(x, lam=0.1)

# Operators with derivatives
op = fp.TV1D(weights=0.8)
z, ctx = op.prox(x, 0.5, keep=True)
dz = op.jvp(ctx, dx=np.ones_like(x))      # Jacobian-vector product
gx, grads = op.vjp(ctx, g=x)              # vector-Jacobian product
print(grads.gamma, grads.weights)         # gradients in the step and the weights
```

## Operators

- **Elementwise:** soft thresholding (weighted), elastic net, Huber, box,
  nonnegative orthant, log barrier, ℓ1 over a box.
- **Nonconvex:** ℓ0, ℓq (0 < q < 1), SCAD and MCP (weighted), log penalty, with an explicit tie rule.
- **Groups and trees:** group ℓ2, group Huber, group SCAD and MCP, tree-structured group norms and the sparse group lasso.
- **Projections:** ℓ2 ball, simplex, weighted ℓ1 ball, hyperplane or
  half-space intersected with a box, second-order cone. Also the ℓ∞ norm and
  the support functions max and the sum of the k largest entries.
- **Signals:** isotonic regression, 1D total variation with per-edge weights, its ℓ2-of-differences
  variant, and the projection onto a 1D TV ball.
- **Images:** anisotropic and isotropic total variation in 2D and 3D, with warm starts (since 0.2), also on GPUs through the PyTorch and JAX wrappers (since 0.3).
- **Graphs:** total variation on any graph, exact, by parametric max-flow, and on trees and paths by dynamic programming (since 0.3).

Each one has a conjugate prox through the Moreau identity. The elementwise maps with kinks report
which entries sit at a breakpoint, and their derivatives can be taken on either side of it.

## Documentation

- [API reference](https://github.com/dvillacis/fastprox/blob/master/docs/api.md) (C and Python)
- [Examples](https://github.com/dvillacis/fastprox/tree/master/examples): denoising, image denoising, proximal gradient, sparse recovery, group sparsity, the weighted graphical lasso, derivatives, bilevel learning, PyTorch and JAX
- [Benchmarks](https://github.com/dvillacis/fastprox/blob/master/docs/benchmarks.md) against proxTV and Condat's C code
- [Using fastprox in place of DeepInverse's TV denoisers](https://github.com/dvillacis/fastprox/blob/master/docs/deepinv.md)
- [Design specification](https://github.com/dvillacis/fastprox/blob/master/docs/spec.md)
- [Roadmap](https://github.com/dvillacis/fastprox/blob/master/ROADMAP.md) and [changelog](https://github.com/dvillacis/fastprox/blob/master/CHANGELOG.md)

## C library

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build && cmake --install build --prefix /usr/local
```

Then `find_package(fastprox)` and link `fastprox::fastprox`, or use
`pkg-config --cflags --libs fastprox`. The header is
[`include/fastprox.h`](https://github.com/dvillacis/fastprox/blob/master/include/fastprox.h).

## License

MIT
