v0.13.0

.claude/skills/newop/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: newop
+description: Create a new PyProximal proximal operator following docs/source/adding.rst - class file, docstring, registration, Moreau/edge-case tests, docs entry and example. Use when the user asks to add/implement/port a proximal operator, penalty, norm, or indicator/projection into PyProximal, including porting an existing prox implementation from a paper, a URL or a local file (e.g. "add a Foo proximal operator", "implement the prox of this penalty", "port the prox at <link>").
+---
+
+Goal: add a new, PyProximal-compliant `ProxOperator` to the library, complete with
+docstring, registration, tests, docs entry and a gallery example, following
+`docs/source/adding.rst` (the authoritative guide - read it if unsure).
+
+The operator may be written from scratch (from a mathematical description or a
+paper) or **ported** from an existing implementation supplied as a **web link** or a
+**local file**. Ask for the operator name and the source only if neither is
+inferable from the invocation.
+
+## 0. Get the source material
+
+- **Web link**: fetch it with `WebFetch` (or the browser tools if the page needs
+  JS). Extract the actual prox/dual prox code or formulas, not the prose.
+- **Local file**: read it in full.
+- **Neither**: work from the user's mathematical description, and state the
+  assumed definition of the function before writing code.
+
+Then write down explicitly, before touching `pyproximal/`:
+
+- the function \(f(\mathbf{x})\), its parameters and its domain;
+- whether a closed form exists for `prox`, for `proxdual`, or both;
+- whether the source's "prox" really is \(\prox_{\tau f}\) and not \(\prox_f\) -
+  **a missing or misplaced `tau` is the most common porting bug**;
+- whether \(f\) is differentiable (`hasgrad=True` and a `grad` override);
+- whether \(f\) is convex or non-convex (decides the docs section);
+- whether \(f\) is an indicator function (then a projection class is needed);
+- whether it acts on vectors or on matrices (e.g. singular-value penalties);
+- which source parameters become `__init__` arguments, which become derived
+  members, and which are irrelevant (plotting, I/O, CLI args).
+
+## 1. Place the file
+
+- File `pyproximal/proximal/<ClassName>.py` in **UpperCamelCase**, matching the
+  class (`HalfSpace.py` holds `HalfSpace`). Closely related variants share a file
+  (`L1`/`L1Ball` in `L1.py`, `Log`/`Log1` in `Log.py`).
+- For an **indicator function**, first add `pyproximal/projection/<Name>.py` with a
+  `<Name>Proj` class exposing `__call__(x)` (pattern: `projection/HalfSpace.py`),
+  register it in `projection/__init__.py` (docstring table, star import, `__all__`),
+  then wrap it in the proximal operator (pattern: `proximal/HalfSpace.py`).
+- Reuse existing helpers instead of re-deriving them, e.g. `_softthreshold` and
+  `_current_sigma` (callable `sigma`) in `proximal/L1.py`, and the projections in
+  `pyproximal.projection` (`BoxProj`, `L1BallProj`, ...).
+
+## 2. Write the class
+
+Use `reference/operator_template.py` as the skeleton. Key rules:
+
+- Inherit from `pyproximal.ProxOperator.ProxOperator` and call
+  `super().__init__(Op, hasgrad)`: pass a PyLops `LinearOperator` as `Op` only if
+  the function uses one (else `None`), and `hasgrad=True` only if you override
+  `grad` with the true gradient (else `False`, and the base `grad` returns the
+  gradient of the Moreau envelope).
+- `__call__(x)` returns the function value (`float`), or membership (`bool`) for an
+  indicator.
+- Implement `prox(self, x, tau)` and/or `proxdual(self, x, tau)`, **each decorated
+  with `@_check_tau`**. At least one is required: the base class derives the other
+  through the Moreau identity. Implement both when closed forms exist.
+- Keep it backend-agnostic: use `ncp = get_array_module(x)` from
+  `pylops.utils.backend` for array operations inside `prox`/`proxdual`, so CuPy
+  inputs work. Numba/CUDA paths are optional and go through an `engine` argument
+  with a runtime fallback (see `proximal/Simplex.py`); do not add them unless asked.
+- Type-annotate everything (`NDArray` from `pylops.utils.typing`,
+  `FloatCallableLike` from `pyproximal.utils.typing`): `mypy --strict` runs over
+  `pyproximal/`.
+- Validate inputs in `__init__` as `msg = "..."; raise ValueError(msg)` (ruff `EM`).
+- Write the `numpydoc` docstring (`r"""`) with, at minimum: one-line summary, the
+  definition of the function in maths, `.. versionadded:: X.Y.Z` (next release after
+  `git describe --tags`), `Parameters`, `Raises` (when `__init__` validates), and a
+  `Notes` section giving the prox (and dual prox, if implemented) in `.. math::`
+  blocks with a `.. [1]` reference. Match the detail of neighbouring operators.
+
+## 3. Register
+
+In `pyproximal/proximal/__init__.py` add: a row in the module docstring table,
+`from .<ClassName> import *`, and the class name in `__all__`. The top-level
+`pyproximal/__init__.py` re-exports with `from .proximal import *`, so the operator
+is then available as `pyproximal.<ClassName>`.
+
+## 4. Add tests
+
+Add to the matching existing file (`test_norms.py`, `test_proximal.py`,
+`test_concave_penalties.py`, `test_projection.py`) or create a new one. Follow
+`reference/test_template.py`:
+
+- module-level `par*` dicts (float32 even size / float64 odd size) with
+  `@pytest.mark.parametrize("par", [(par1), (par2)])` and `np.random.seed(10)`;
+- a `__call__` check against an independently computed value;
+- **both `prox` and `proxdual` in closed form**: `assert moreau(op, x, tau)`;
+- **only one in closed form**: ad-hoc edge cases with known answers (x=0, points
+  inside/outside the set, `tau`→0 returns `x`, large `tau`), and the defining
+  property where cheap - for indicators the output lies in the set and projecting
+  twice is idempotent; in general, compare against a brute-force
+  `scipy.optimize.minimize` of \(f(\mathbf{y}) + \|\mathbf{y}-\mathbf{x}\|_2^2/(2\tau)\)
+  on a small vector;
+- with `hasgrad=True`, add a `gradtest_proximal` test in `test_grads.py`;
+- an error-path test for every `raise` in `__init__` (see
+  `test_Quadratic_nonsquare` in `test_proximal.py`).
+
+Never loosen the `moreau` tolerance to make a wrong dual pass: fix the maths.
+
+## 5. Run
+
+Always use `uv`:
+
+```bash
+uv run pytest pytests/test_<file>.py -k <ClassName> -q
+make lint_uv
+make typeannot_uv
+```
+
+Iterate until all tests pass and lint/mypy are clean.
+
+## 6. Document
+
+- Add the class name (alphabetically) to the right `autosummary` block in
+  `docs/source/api/index.rst`: *Vector → Convex* / *Vector → Non-Convex*,
+  *Matrix-only*, or *Other*; a new projection goes under *Orthogonal projections*.
+- Use the operator in at least one example: extend an existing gallery script when
+  it fits (`examples/plot_norms.py`, `plot_indicators.py`,
+  `plot_concave_penalties.py`), or add `examples/plot_<name>.py` in sphinx-gallery
+  format (`r"""` title/underline/description header, `###...` comment blocks between
+  narrative and code, a matplotlib figure of `x` vs `prox(x)` vs `proxdual(x)`).
+  Prefer a script in `tutorials/` when the operator is best shown inside a solver.
+
+## 7. Final checklist (from `docs/source/adding.rst`)
+
+Report back confirming each item:
+
+- [ ] class in its own UpperCamelCase file in `pyproximal/proximal/` (plus a
+      projection in `pyproximal/projection/` for indicators)
+- [ ] `__init__`, `__call__`, and `prox` and/or `proxdual` (both with `@_check_tau`)
+      implemented; `grad` only with `hasgrad=True`
+- [ ] exported in `pyproximal/proximal/__init__.py` (table, import, `__all__`)
+- [ ] numpydoc docstring with `Parameters` and a mathematical `Notes` section with
+      a reference
+- [ ] tests added (Moreau or edge cases, `__call__`, raises) and passing
+- [ ] listed in `docs/source/api/index.rst`
+- [ ] used in at least one `examples/` or `tutorials/` script
+- [ ] `make lint_uv` and `make typeannot_uv` clean
+
+When porting, close with a short note on what differed between the source
+implementation and the PyProximal version (`tau` scaling, dual in closed form vs
+derived via Moreau, shape/dtype handling, removed I/O).

.claude/skills/newop/reference/operator_template.py

@@ -0,0 +1,84 @@
+"""Skeleton for a new PyProximal proximal operator.
+
+Copy into ``pyproximal/proximal/<MyProx>.py`` (UpperCamelCase, matching the class),
+rename, and fill in. The bodies below implement a scaled L1 norm only so that the
+skeleton runs and passes ``moreau`` as-is: replace them with the maths of the new
+operator. Delete anything that does not apply.
+"""
+
+import numpy as np
+from pylops.utils.backend import get_array_module
+from pylops.utils.typing import NDArray
+
+from pyproximal.ProxOperator import ProxOperator, _check_tau
+
+
+class MyProx(ProxOperator):
+    r"""One-line summary of the proximal operator.
+
+    Proximal operator of the function
+    :math:`f(\mathbf{x}) = \sigma \|\mathbf{x}\|_1` (replace with the
+    definition of the new function).
+
+    .. versionadded:: X.Y.Z
+
+    Parameters
+    ----------
+    sigma : :obj:`float`, optional
+        Multiplicative coefficient of the function.
+
+    Raises
+    ------
+    ValueError
+        If ``sigma`` is not positive.
+
+    Notes
+    -----
+    The proximal operator of :math:`f` is defined as [1]_:
+
+    .. math::
+
+        \prox_{\tau f}(\mathbf{x}) = \ldots
+
+    and, when a closed form is available, its dual proximal operator as:
+
+    .. math::
+
+        \prox_{\tau f^*}(\mathbf{x}) = \ldots
+
+    .. [1] Author, A., and Author, B., "Title of the paper", Journal,
+        volume, pp. xx-yy. Year.
+
+    """
+
+    def __init__(self, sigma: float = 1.0) -> None:
+        # Op: PyLops linear operator used inside the function (None if not needed)
+        # hasgrad: True only if f is differentiable and ``grad`` is overridden
+        super().__init__(None, False)
+        if sigma <= 0:
+            msg = "sigma must be positive"
+            raise ValueError(msg)
+        self.sigma = sigma
+
+    def __call__(self, x: NDArray) -> float:
+        # function value (return ``bool`` membership for indicator functions)
+        return float(self.sigma * np.sum(np.abs(x)))
+
+    @_check_tau
+    def prox(self, x: NDArray, tau: float) -> NDArray:
+        # use ``ncp`` (not ``np``) for array operations so that CuPy inputs work
+        ncp = get_array_module(x)
+        thresh = tau * self.sigma
+        return ncp.maximum(ncp.abs(x) - thresh, 0.0) * ncp.sign(x)
+
+    @_check_tau
+    def proxdual(self, x: NDArray, tau: float) -> NDArray:
+        # implement only if a closed form exists; otherwise delete this method
+        # and the base class derives it from ``prox`` via the Moreau identity
+        ncp = get_array_module(x)
+        return ncp.clip(x, -self.sigma, self.sigma)
+
+    # def grad(self, x: NDArray) -> NDArray:
+    #     # only with ``hasgrad=True``: true gradient of f (otherwise the base
+    #     # class returns the gradient of the Moreau envelope)
+    #     return ...

.claude/skills/newop/reference/test_template.py

@@ -0,0 +1,66 @@
+"""Skeleton tests for a new PyProximal proximal operator.
+
+Merge into the ``pytests/test_*.py`` file that matches the operator
+(``test_norms.py``, ``test_proximal.py``, ``test_concave_penalties.py``,
+``test_projection.py``) and reuse its existing ``par*`` dicts. Keep the Moreau
+test when both ``prox`` and ``proxdual`` have closed forms; otherwise rely on
+the edge-case and brute-force tests.
+"""
+
+import numpy as np
+import pytest
+from numpy.testing import assert_array_almost_equal
+from scipy.optimize import minimize
+
+from pyproximal.proximal import MyProx  # adjust import
+from pyproximal.utils import moreau
+
+par1 = {"nx": 10, "sigma": 1.0, "dtype": "float32"}  # even float32
+par2 = {"nx": 11, "sigma": 2.0, "dtype": "float64"}  # odd float64
+
+
+@pytest.mark.parametrize("par", [(par1), (par2)])
+def test_MyProx(par):
+    """MyProx function and proximal/dual proximal"""
+    np.random.seed(10)
+    myprox = MyProx(sigma=par["sigma"])
+
+    # function value, checked against an independent computation
+    x = np.random.normal(0.0, 1.0, par["nx"]).astype(par["dtype"])
+    assert myprox(x) == pytest.approx(par["sigma"] * np.sum(np.abs(x)), rel=1e-5)
+
+    # prox / dualprox (only when both have a closed form)
+    tau = 2.0
+    assert moreau(myprox, x, tau)
+
+
+@pytest.mark.parametrize("par", [(par1), (par2)])
+def test_MyProx_edgecases(par):
+    """MyProx proximal on cases with a known answer"""
+    np.random.seed(10)
+    myprox = MyProx(sigma=par["sigma"])
+
+    # prox of zero (replace with the known answer for the new function)
+    x = np.zeros(par["nx"], dtype=par["dtype"])
+    assert_array_almost_equal(myprox.prox(x, 1.0), x)
+
+    # tau -> 0 leaves x unchanged
+    x = np.random.normal(0.0, 1.0, par["nx"]).astype(par["dtype"])
+    assert_array_almost_equal(myprox.prox(x, 1e-10), x, decimal=5)
+
+    # brute-force minimization of f(y) + ||y - x||^2 / (2 tau) on a small vector
+    tau = 0.5
+    x = np.random.normal(0.0, 1.0, 5)
+    y = minimize(
+        lambda y: myprox(y) + np.sum((y - x) ** 2) / (2 * tau),
+        x,
+        method="Powell",
+        options={"xtol": 1e-8, "ftol": 1e-10},
+    ).x
+    assert_array_almost_equal(myprox.prox(x, tau), y, decimal=4)
+
+
+def test_MyProx_raises():
+    """Check input validation of MyProx"""
+    with pytest.raises(ValueError, match="sigma must be positive"):
+        _ = MyProx(sigma=-1.0)

.github/workflows/build.yaml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       matrix:
         platform: [ ubuntu-latest, macos-latest ]
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     runs-on: ${{ matrix.platform }}
 
@@ -27,6 +27,6 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies and pyproximal
-        run: uv sync --locked --all-extras --all-groups
+        run: uv sync --locked  --extra advanced --all-groups
       - name: Test with pytest
         run: uv run pytest --color=yes pytests/

.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr *)'
+

.github/workflows/codacy-coverage-reporter.yaml

@@ -20,7 +20,7 @@ jobs:
         with:
           python-version: "3.11"
       - name: Install dependencies and pyproximal
-        run: uv sync --locked --all-extras --all-groups
+        run: uv sync --locked  --extra advanced --all-groups
       - name: Coverage with pytest
         run: |
           uv run coverage run -m pytest

.github/workflows/mypy.yaml

@@ -18,7 +18,7 @@ jobs:
           python-version: "3.11"
           enable-cache: true
       - name: Install dependencies and pyproximal
-        run: uv sync --locked --all-extras --all-groups
+        run: uv sync --locked  --extra advanced --all-groups
       - name: Run Mypy
         run: |
           uv run mypy pyproximal/

.readthedocs.yaml

@@ -22,4 +22,4 @@ build:
       create_environment:
          - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
       install:
-         - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --locked --all-extras --all-groups
+         - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --locked --extra advanced --all-groups