invexapi 0.1.0__tar.gz

invexapi-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+
+# ---- Python bytecode ---------------------------------------------------------
+__pycache__/
+*.py[cod]
+*.pyo
+
+# ---- IDE / editor artefacts --------------------------------------------------
+.cache/
+.vscode/
+.claude/
+.pytest_cache/
+probes/
+graphify-out/
+
+# ---- Example data (fetched separately, see examples/data/download.py) --------
+examples/data/
+
+# ---- Miscellaneous -----------------------------------------------------------
+CLAUDE.md
+.gitignore

invexapi-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Samuel Pinilla
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

invexapi-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.5
+Name: invexapi
+Version: 0.1.0
+Summary: PyTorch Optimizers and Neural Network building blocks for Invex Results.
+Project-URL: Homepage, https://github.com/samuelpinilla/invexapi
+Author-email: Samuel Pinilla <spinilla@ieee.org>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: numpy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: imageio; extra == 'examples'
+Requires-Dist: matplotlib; extra == 'examples'
+Requires-Dist: numpy; extra == 'examples'
+Requires-Dist: pillow; extra == 'examples'
+Requires-Dist: pywavelets; extra == 'examples'
+Requires-Dist: scipy; extra == 'examples'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="imgs/logo.png" alt="InvexAPI" width="480">
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: BSD-3-Clause" src="https://img.shields.io/badge/license-BSD--3--Clause-blue.svg"></a>
+  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue.svg">
+  <img alt="PyTorch only" src="https://img.shields.io/badge/backend-PyTorch-ee4c2c.svg">
+</p>
+
+<h1 align="center">invexapi</h1>
+
+<p align="center">
+  A minimal, PyTorch-only toolkit for <b>invex</b> optimization: penalties with
+  proven optimality certificates, and the solvers that use them.
+</p>
+
+---
+
+## Why invexity?
+
+Invex functions are a strict generalization of convexity: every stationary point
+is still a global minimum, but the function itself need not be convex. That gives
+non-convex penalties (sparsity-promoting, non-smooth, highly structured) the same
+global-optimality guarantee convex optimization enjoys — without paying for it
+with local minima.
+
+`invexapi` packages this idea as code: penalties that carry a machine-checkable
+**certificate** of which mathematical class they belong to (convex, invex,
+quasi-convex, quasi-invex), and generic solvers that read those certificates to
+warn you when no optimality guarantee applies.
+
+## Install
+
+```bash
+pip install -e .              # editable install
+pip install -e ".[dev]"       # + pytest, numpy for the test suite
+pip install -e ".[examples]"  # + deps used only by examples/
+```
+
+## Quick start
+
+```python
+import torch
+from invexapi import QuasinormInvexPenalty
+from invexapi.optim import FISTA
+
+class DataFidelity:
+    def __init__(self, y): self.y = y
+    def value(self, x): return 0.5 * torch.sum((x - self.y) ** 2)
+    def grad(self, x): return x - self.y
+
+y = torch.randn(100)
+smooth = DataFidelity(y)
+penalty = QuasinormInvexPenalty(lamb=0.1, q=0.5)
+solver = FISTA(smooth, penalty, step=1.0)
+
+x_hat, history = solver.run(y.clone())
+```
+
+Any object exposing the right methods (`value`, `grad`, `prox`) works as a
+`smooth`/`penalty`/`objective` — the built-in penalties are just one plug-in
+choice.
+
+## What's inside
+
+**Penalties** (`invexapi.penalties`) — loss/penalty terms plus a certificate of
+what's provably known about each one:
+
+| Penalty | Form | Certified as |
+|---|---|---|
+| `QuasinormInvexPenalty(lamb, q)` | `λ·\|x\|^q` | invex |
+| `LogInvexPenalty(lamb)` | `log(1+\|x\|) − \|x\|/(2+2\|x\|)` | invex |
+| `TikhonovPenalty(lamb)` | `λ/2·‖x‖²` | convex, invex, quasi-convex |
+| `L1Penalty(lamb)` | `λ·‖x‖₁` | convex, invex, quasi-convex |
+
+Certificates are attached explicitly and never inferred — convexity composes
+additively, but invexity does not, so a combined objective only carries a
+certificate someone has actually proven for it.
+
+**Solvers** (`invexapi.optim`) — generic, decoupled from the penalties above:
+
+- `GradientDescent` — with optional Armijo backtracking line search
+- `FISTA` — accelerated proximal gradient for `smooth(x) + penalty(x)`
+- `NonlinearCG` — Polak-Ribière+ with automatic restart
+- `LinearizedADMM` — for `smooth(x) + penalty(D@x)` (e.g. total variation)
+
+All four warn (never error) when run on an objective without a convex/invex
+certificate, since no global-optimum guarantee applies in that case.
+
+**Linear operators** (`invexapi.penalties.operators`) — `Identity` and
+`FiniteDifference2D` (2D total variation), each with a verified adjoint.
+
+**Structured documentation** (`invexapi.metadata`) — design provenance,
+rejected alternatives, and invariants as introspectable dataclasses rather than
+prose, exportable as JSON for downstream tooling:
+
+```python
+import invexapi
+print(invexapi.metadata.dump_all_json(indent=2))
+```
+
+## GPU support
+
+Nothing in `invexapi` is device-specific — every operation derives its device
+from its input tensors. Move your data to CUDA before calling a solver and
+everything downstream follows:
+
+```python
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+x_hat, history = solver.run(y.to(device))
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+Penalty math is validated against independent NumPy reference implementations on
+fixed-seed random inputs, with no CUDA dependency anywhere in this repo.
+
+## Examples
+
+See `examples/` for denoising and deblurring scripts covering FISTA and
+Linearized ADMM with total variation, using both the quasinorm and log invex
+penalties. The ADMM/TV examples need a test image, fetched separately:
+
+```bash
+python examples/data/download.py
+```
+
+## License
+
+BSD 3-Clause, see [LICENSE](LICENSE).
+
+## References
+
+This library reproduces and generalizes results from the following papers:
+
+1. Pinilla, S., Sanabria, A., Bi, J., & Egiazarian, K. (2025). *What makes neural
+   networks trainable? Invexity as a structural design principle in AI*.
+2. Pinilla, S., & Thiyagalingam, J. (2024). *Global optimality for non-linear
+   constrained restoration problems via invexity*. International Conference on
+   Learning Representations (ICLR), 2024, pp. 11990–12027.
+3. Pinilla, S., Mu, T., Bourne, N., & Thiyagalingam, J. (2022). *Improved imaging
+   by invex regularizers with global optima guarantees*. Advances in Neural
+   Information Processing Systems (NeurIPS), 35, pp. 10780–10794.
+4. Pinilla, S., Yeung, S.-L., & Thiyagalingam, J. (2024). *Global convergence of
+   alternating direction method of multipliers for invex objective losses*. IEEE
+   International Conference on Acoustics, Speech and Signal Processing (ICASSP)
+   2024, pp. 9361–9365.

invexapi-0.1.0/README.md

@@ -0,0 +1,152 @@
+<p align="center">
+  <img src="imgs/logo.png" alt="InvexAPI" width="480">
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: BSD-3-Clause" src="https://img.shields.io/badge/license-BSD--3--Clause-blue.svg"></a>
+  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue.svg">
+  <img alt="PyTorch only" src="https://img.shields.io/badge/backend-PyTorch-ee4c2c.svg">
+</p>
+
+<h1 align="center">invexapi</h1>
+
+<p align="center">
+  A minimal, PyTorch-only toolkit for <b>invex</b> optimization: penalties with
+  proven optimality certificates, and the solvers that use them.
+</p>
+
+---
+
+## Why invexity?
+
+Invex functions are a strict generalization of convexity: every stationary point
+is still a global minimum, but the function itself need not be convex. That gives
+non-convex penalties (sparsity-promoting, non-smooth, highly structured) the same
+global-optimality guarantee convex optimization enjoys — without paying for it
+with local minima.
+
+`invexapi` packages this idea as code: penalties that carry a machine-checkable
+**certificate** of which mathematical class they belong to (convex, invex,
+quasi-convex, quasi-invex), and generic solvers that read those certificates to
+warn you when no optimality guarantee applies.
+
+## Install
+
+```bash
+pip install -e .              # editable install
+pip install -e ".[dev]"       # + pytest, numpy for the test suite
+pip install -e ".[examples]"  # + deps used only by examples/
+```
+
+## Quick start
+
+```python
+import torch
+from invexapi import QuasinormInvexPenalty
+from invexapi.optim import FISTA
+
+class DataFidelity:
+    def __init__(self, y): self.y = y
+    def value(self, x): return 0.5 * torch.sum((x - self.y) ** 2)
+    def grad(self, x): return x - self.y
+
+y = torch.randn(100)
+smooth = DataFidelity(y)
+penalty = QuasinormInvexPenalty(lamb=0.1, q=0.5)
+solver = FISTA(smooth, penalty, step=1.0)
+
+x_hat, history = solver.run(y.clone())
+```
+
+Any object exposing the right methods (`value`, `grad`, `prox`) works as a
+`smooth`/`penalty`/`objective` — the built-in penalties are just one plug-in
+choice.
+
+## What's inside
+
+**Penalties** (`invexapi.penalties`) — loss/penalty terms plus a certificate of
+what's provably known about each one:
+
+| Penalty | Form | Certified as |
+|---|---|---|
+| `QuasinormInvexPenalty(lamb, q)` | `λ·\|x\|^q` | invex |
+| `LogInvexPenalty(lamb)` | `log(1+\|x\|) − \|x\|/(2+2\|x\|)` | invex |
+| `TikhonovPenalty(lamb)` | `λ/2·‖x‖²` | convex, invex, quasi-convex |
+| `L1Penalty(lamb)` | `λ·‖x‖₁` | convex, invex, quasi-convex |
+
+Certificates are attached explicitly and never inferred — convexity composes
+additively, but invexity does not, so a combined objective only carries a
+certificate someone has actually proven for it.
+
+**Solvers** (`invexapi.optim`) — generic, decoupled from the penalties above:
+
+- `GradientDescent` — with optional Armijo backtracking line search
+- `FISTA` — accelerated proximal gradient for `smooth(x) + penalty(x)`
+- `NonlinearCG` — Polak-Ribière+ with automatic restart
+- `LinearizedADMM` — for `smooth(x) + penalty(D@x)` (e.g. total variation)
+
+All four warn (never error) when run on an objective without a convex/invex
+certificate, since no global-optimum guarantee applies in that case.
+
+**Linear operators** (`invexapi.penalties.operators`) — `Identity` and
+`FiniteDifference2D` (2D total variation), each with a verified adjoint.
+
+**Structured documentation** (`invexapi.metadata`) — design provenance,
+rejected alternatives, and invariants as introspectable dataclasses rather than
+prose, exportable as JSON for downstream tooling:
+
+```python
+import invexapi
+print(invexapi.metadata.dump_all_json(indent=2))
+```
+
+## GPU support
+
+Nothing in `invexapi` is device-specific — every operation derives its device
+from its input tensors. Move your data to CUDA before calling a solver and
+everything downstream follows:
+
+```python
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+x_hat, history = solver.run(y.to(device))
+```
+
+## Testing
+
+```bash
+pytest
+```
+
+Penalty math is validated against independent NumPy reference implementations on
+fixed-seed random inputs, with no CUDA dependency anywhere in this repo.
+
+## Examples
+
+See `examples/` for denoising and deblurring scripts covering FISTA and
+Linearized ADMM with total variation, using both the quasinorm and log invex
+penalties. The ADMM/TV examples need a test image, fetched separately:
+
+```bash
+python examples/data/download.py
+```
+
+## License
+
+BSD 3-Clause, see [LICENSE](LICENSE).
+
+## References
+
+This library reproduces and generalizes results from the following papers:
+
+1. Pinilla, S., Sanabria, A., Bi, J., & Egiazarian, K. (2025). *What makes neural
+   networks trainable? Invexity as a structural design principle in AI*.
+2. Pinilla, S., & Thiyagalingam, J. (2024). *Global optimality for non-linear
+   constrained restoration problems via invexity*. International Conference on
+   Learning Representations (ICLR), 2024, pp. 11990–12027.
+3. Pinilla, S., Mu, T., Bourne, N., & Thiyagalingam, J. (2022). *Improved imaging
+   by invex regularizers with global optima guarantees*. Advances in Neural
+   Information Processing Systems (NeurIPS), 35, pp. 10780–10794.
+4. Pinilla, S., Yeung, S.-L., & Thiyagalingam, J. (2024). *Global convergence of
+   alternating direction method of multipliers for invex objective losses*. IEEE
+   International Conference on Acoustics, Speech and Signal Processing (ICASSP)
+   2024, pp. 9361–9365.

invexapi-0.1.0/environment.yml

@@ -0,0 +1,15 @@
+name: invexapi-dev
+channels:
+  - pytorch
+  - conda-forge
+dependencies:
+  - python>=3.10
+  - pytorch>=2.0
+  - numpy
+  - scipy
+  - pywavelets
+  - imageio
+  - pillow
+  - matplotlib
+  - pytest
+  - pip

invexapi-0.1.0/examples/_data.py

@@ -0,0 +1,32 @@
+"""Shared image-loading helper for the examples/ scripts that use real data.
+
+Not part of the invexapi package — a plain sibling module the example scripts
+import from each other, kept out of invexapi/ since loading/normalizing a test
+image is an examples-only concern, not a library concern.
+"""
+
+from pathlib import Path
+
+import numpy as np
+import torch
+from PIL import Image
+
+DATA_DIR = Path(__file__).resolve().parent / "data"
+
+
+def load_image(relative_path: str) -> torch.Tensor:
+    """Load an image under examples/data/ as a float tensor normalized to [0, 1].
+
+    ``relative_path`` is relative to examples/data/, e.g. ``"images/noisy_image.tif"``.
+    Normalization divides by the dtype's max value (e.g. 65535 for uint16) so the
+    result is comparable to the [0, 1]-scaled synthetic signals the other examples
+    use; if the file is already floating point, it's returned as-is.
+    """
+    path = DATA_DIR / relative_path
+    raw = np.array(Image.open(path))
+
+    if np.issubdtype(raw.dtype, np.integer):
+        factor = float(np.iinfo(raw.dtype).max)
+        raw = raw.astype(np.float32) / factor
+
+    return torch.from_numpy(raw.astype(np.float32))

invexapi-0.1.0/examples/deblurring_log_fista.py

@@ -0,0 +1,90 @@
+"""1D deblurring with the log invex penalty, via FISTA.
+
+Adapted from the FISTA/momentum deblurring loop in
+``codes NEURIPS/model-based/modelEq10.py`` (DCT-domain deconvolution + invex prox on
+wavelet coefficients), simplified to a synthetic 1D blur/sparse signal so the example
+needs no external image files, ``pywt``, or ``scipy`` — just ``invexapi`` and
+``torch``. The structure (smooth data-fidelity gradient step + invex prox step, run
+through FISTA) mirrors the paper's pipeline exactly; only the transform (identity here
+vs. DCT+wavelet there) is simplified, so the log penalty's prox stays exact rather
+than approximated.
+
+Problem: recover a sparse signal ``x_true`` from a blurred, noisy observation
+``y = A x_true + noise`` (A = box blur), minimizing ``0.5*||Ax-y||^2 + lamb*g(x)``
+where ``g`` is the log invex penalty from ``codes NEURIPS/model-based/modelEq10.py``.
+
+Running this script still prints FISTA's UserWarning: the data-fidelity term alone
+is certified convex, but the *combined* objective isn't (see
+``invexapi.penalties.Sum`` — certificates never compose automatically), so the
+global-optimum guarantee is still withheld here even though half the objective is
+provably well-behaved.
+"""
+
+import torch
+
+from invexapi import Certificate, Loss, LogInvexPenalty
+from invexapi.optim import FISTA
+
+
+def _blur_matrix(n: int, width: int = 5) -> torch.Tensor:
+    A = torch.zeros(n, n)
+    half = width // 2
+    for i in range(n):
+        lo, hi = max(0, i - half), min(n, i + half + 1)
+        A[i, lo:hi] = 1.0 / (hi - lo)
+    return A
+
+
+class _DataFidelity(Loss):
+    """0.5*||Ax-y||^2. A@x is linear, so this quadratic is convex by inspection —
+    certified here (with no paper reference, since it's not from the source
+    papers) to show a Loss outside invexapi.penalties declaring its own certificate.
+    This does NOT silence FISTA's warning below: the *combined* smooth+penalty
+    objective (invexapi.penalties.Sum) still has no certificate of its own, by
+    design (see Sum's docstring) — only smooth's half is certified here."""
+
+    def __init__(self, A: torch.Tensor, y: torch.Tensor):
+        super().__init__()
+        self.A = A
+        self.y = y
+        self._certify("convex", Certificate(status="assumed", source="manual"))
+
+    def value(self, x: torch.Tensor) -> torch.Tensor:
+        r = self.A @ x - self.y
+        return 0.5 * torch.sum(r * r)
+
+    def grad(self, x: torch.Tensor) -> torch.Tensor:
+        return self.A.T @ (self.A @ x - self.y)
+
+
+def main():
+    torch.manual_seed(0)
+    n = 200
+    sparsity = 20
+
+    x_true = torch.zeros(n)
+    idx = torch.randperm(n)[:sparsity]
+    x_true[idx] = torch.randn(sparsity) * 3.0
+
+    A = _blur_matrix(n)
+    noise = torch.randn(n) * 0.01
+    y = A @ x_true + noise
+
+    smooth = _DataFidelity(A, y)
+    penalty = LogInvexPenalty(lamb=5e-3)
+
+    L = torch.linalg.eigvalsh(A.T @ A).max().item()
+    solver = FISTA(smooth, penalty, step=1.0 / L, max_iter=300, tol=1e-10)
+
+    x_hat, history = solver.run(y.clone())
+
+    blurred_mse = torch.mean((y - x_true) ** 2).item()
+    deblurred_mse = torch.mean((x_hat - x_true) ** 2).item()
+
+    print(f"objective history: {history[0]:.4f} -> {history[-1]:.4f}")
+    print(f"MSE blurred:   {blurred_mse:.4f}")
+    print(f"MSE deblurred: {deblurred_mse:.4f}")
+
+
+if __name__ == "__main__":
+    main()

invexapi-0.1.0/examples/denoising_admm_tv.py

@@ -0,0 +1,87 @@
+"""Total-variation image denoising via LinearizedADMM, on a real test image.
+
+Adapted from ``code_ICLR/ADMM/ADMM_Lq.py``: TV-regularized denoising
+(``min_x 0.5*||x-y||^2 + lamb*sum(|Dx|^q)``) where ``D`` is the 2D finite-difference
+(TV) operator and the penalty is the quasinorm invex penalty already implemented in
+this library — same configuration as the reference script, run here with
+``LinearizedADMM`` + ``FiniteDifference2D`` + ``QuasinormInvexPenalty`` instead of
+the reference's cupy/CUDA kernel, on ``examples/data/images/noisy_image.tif``
+instead of the reference's own test image.
+
+Running this script prints FISTA/GD/CG's usual UserWarning-style caveat: `smooth`
+here (this example's own `_DataFidelity`) is uncertified, so LinearizedADMM warns
+that no global-optimum guarantee applies — expected, same as the other examples.
+
+Runs on CUDA automatically if available (``python examples/denoising_admm_tv.py``),
+or force CPU with ``--device cpu``. Nothing in invexapi is device-specific — every
+op inherits its device from its input tensors — so the only thing this script does
+for GPU support is move the image tensor to the target device before construction;
+everything downstream (the penalty's prox, the TV operator, the solver) follows.
+"""
+
+import argparse
+import time
+
+import matplotlib.pyplot as plt
+import torch
+
+from invexapi import Loss, QuasinormInvexPenalty
+from invexapi.optim import LinearizedADMM
+from invexapi.penalties.operators import FiniteDifference2D
+
+from _data import load_image
+
+
+class _DataFidelity(Loss):
+    def __init__(self, y: torch.Tensor):
+        super().__init__()
+        self.y = y
+
+    def value(self, x: torch.Tensor) -> torch.Tensor:
+        return 0.5 * torch.sum((x - self.y) ** 2)
+
+    def grad(self, x: torch.Tensor) -> torch.Tensor:
+        return x - self.y
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--device",
+        default="cuda" if torch.cuda.is_available() else "cpu",
+        help="torch device to run on, e.g. 'cuda', 'cuda:1', 'cpu' (default: cuda if available)",
+    )
+    args = parser.parse_args()
+    device = torch.device(args.device)
+
+    y = load_image("images/noisy_image.tif").to(device)
+
+    print(f"running on: {device}")
+
+    smooth = _DataFidelity(y)
+    penalty = QuasinormInvexPenalty(lamb=1.1e-1, q=0.85)
+    solver = LinearizedADMM(
+        smooth,
+        penalty,
+        D=FiniteDifference2D(),
+        rho=1.6,
+        project=lambda x: x.clamp(min=0.0),
+        max_iter=200,
+        tol=1e-8,
+    )
+
+    start_time = time.time()
+    x_hat, history = solver.run(y.clone())
+    end_time = time.time()
+
+    print(f"image shape: {tuple(y.shape)}")
+    print(f"objective history: {history[0]:.4f} -> {history[-1]:.4f}")
+    print(f"denoised range: [{x_hat.min().item():.4f}, {x_hat.max().item():.4f}]")
+    print(f"mean |x_hat - y|: {torch.mean((x_hat - y).abs()).item():.6f}")
+    print(f"elapsed time: {end_time - start_time:.4f} seconds")
+
+    plt.imshow(x_hat.cpu().numpy(), cmap="gray")
+    plt.show()
+
+if __name__ == "__main__":
+    main()

invexapi-0.1.0/examples/denoising_admm_tv_log.py

@@ -0,0 +1,82 @@
+"""Total-variation image denoising via LinearizedADMM, using the log penalty.
+
+Same setup as ``denoising_admm_tv.py`` (``min_x 0.5*||x-y||^2 + lamb*g(Dx)`` via
+``LinearizedADMM`` + ``FiniteDifference2D`` on
+``examples/data/images/noisy_image.tif``), but with ``g`` = ``LogInvexPenalty``
+instead of ``QuasinormInvexPenalty`` — the reference ADMM scripts only pair TV with
+the quasinorm/L1/Llq penalties, so there is no original CUDA kernel to validate
+this specific combination against; it demonstrates that any `Penalty` (paper-sourced
+or not) works as `LinearizedADMM`'s second argument, per its generic `penalty.prox`
+contract.
+
+Runs on CUDA automatically if available, or force CPU with ``--device cpu`` (see
+``denoising_admm_tv.py``'s docstring for why no other device-handling is needed).
+"""
+
+import argparse
+import time
+
+import matplotlib.pyplot as plt
+import torch
+
+from invexapi import Loss, LogInvexPenalty
+from invexapi.optim import LinearizedADMM
+from invexapi.penalties.operators import FiniteDifference2D
+
+from _data import load_image
+
+
+class _DataFidelity(Loss):
+    def __init__(self, y: torch.Tensor):
+        super().__init__()
+        self.y = y
+
+    def value(self, x: torch.Tensor) -> torch.Tensor:
+        return 0.5 * torch.sum((x - self.y) ** 2)
+
+    def grad(self, x: torch.Tensor) -> torch.Tensor:
+        return x - self.y
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--device",
+        default="cuda" if torch.cuda.is_available() else "cpu",
+        help="torch device to run on, e.g. 'cuda', 'cuda:1', 'cpu' (default: cuda if available)",
+    )
+    args = parser.parse_args()
+    device = torch.device(args.device)
+
+    y = load_image("images/noisy_image.tif").to(device)
+
+    print(f"running on: {device}")
+
+    smooth = _DataFidelity(y)
+    penalty = LogInvexPenalty(lamb=3e-1)
+    solver = LinearizedADMM(
+        smooth,
+        penalty,
+        D=FiniteDifference2D(),
+        rho=1.6,
+        project=lambda x: x.clamp(min=0.0),
+        max_iter=200,
+        tol=1e-8,
+    )
+
+    start_time = time.time()
+    x_hat, history = solver.run(y.clone())
+    end_time = time.time()
+
+    print(f"image shape: {tuple(y.shape)}")
+    print(f"objective history: {history[0]:.4f} -> {history[-1]:.4f}")
+    print(f"denoised range: [{x_hat.min().item():.4f}, {x_hat.max().item():.4f}]")
+    print(f"mean |x_hat - y|: {torch.mean((x_hat - y).abs()).item():.6f}")
+    print(f"elapsed time: {end_time - start_time:.4f} seconds")
+
+    plt.imshow(x_hat.cpu().numpy(), cmap="gray")
+    plt.show()
+
+
+if __name__ == "__main__":
+    main()