solve-nonsmooth-problem
Use this skill whenever the user wants to solve an inverse problem on PyLops operators with a non-smooth, constrained or non-convex term - load it before writing the objective, choosing a solver or writing optimisation code, even when a SciPy bounded solver or a hand-written FISTA/ADMM loop would also work. Covers total variation, L1/sparsity in a transform, joint sparsity across signals sharing the same components, bounds/positivity/ball/affine constraints, low-rank matrix completion (nuclear norm) and plug-and-play priors with a denoiser (median filter, BM3D), solved with PyProximal (ProximalGradient, ADMM, PrimalDual, ...), step sizes from operator norms. E.g. "add TV regularisation", "keep the model within physical bounds", "recover several signals that share their components", "fill in missing entries of a low-rank matrix", "use PyProximal". Not for purely quadratic regularisation (Tikhonov, damping, derivative smoothing), which is plain least squares - use the pylops skill solve-inverse-problem.
- License 许可
- LGPL-2.1
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- solve-nonsmooth-problem
- description
- Use this skill whenever the user wants to solve an inverse problem on PyLops operators with a non-smooth, constrained or non-convex term - load it before writing the objective, choosing a solver or writing optimisation code, even when a SciPy bounded solver or a hand-written FISTA/ADMM loop would also work. Covers total variation, L1/sparsity in a transform, joint sparsity across signals sharing the same components, bounds/positivity/ball/affine constraints, low-rank matrix completion (nuclear norm) and plug-and-play priors with a denoiser (median filter, BM3D), solved with PyProximal (ProximalGradient, ADMM, PrimalDual, ...), step sizes from operator norms. E.g. "add TV regularisation", "keep the model within physical bounds", "recover several signals that share their components", "fill in missing entries of a low-rank matrix", "use PyProximal". Not for purely quadratic regularisation (Tikhonov, damping, derivative smoothing), which is plain least squares - use the pylops skill solve-inverse-problem.
02 资源文件 2
- 参考文档reference/solver_guide.md4.1 KB
- 脚本reference/tv_template.py4.1 KB
03 SKILL.md 正文
Goal: a runnable script that solves the user's non-smooth problem with a
formulation written down explicitly, provably valid step sizes, and a convergence
check. Do not modify the installed pyproximal / pylops packages.
If the problem is a plain (Tikhonov-)regularised least squares, or L1 with an
orthogonal transform, PyLops alone is simpler: use the pylops plugin skill
solve-inverse-problem instead.
0. Check the environment
- Use the project's Python runner; check
python -c "import pyproximal, pylops; print(pyproximal.__version__, pylops.__version__)". PyProximal requires a recent PyLops (≥ 2.4 for 0.12); ask before installing or upgrading. - Signatures and return values of solvers changed across versions (e.g.
AcceleratedProximalGradient→ProximalGradient(acceleration=...),DouglasRachfordSplittingroles of x/y): inspect the installed ones.reference/solver_guide.mdsummarises PyProximal 0.12.
1. Write the objective
Write the problem in the form min_x f(x) + g(K x) (or f(x) + ε g(x))
before coding, and show it to the user:
- data term: usually
f = ½‖Op x − y‖²→pyproximal.L2(Op=Op, b=y)(smooth, has.grad), orL2(b=y)applied toK = Opinside a stack; - regulariser/constraint:
L1,L21(+pylops.Gradient= isotropic TV),Box,EuclideanBall,L1Ball,AffineSet,Nuclear, … (table in the guide); K: a PyLops operator (Gradient, a transform,Op, orpylops.VStack([...])withpyproximal.VStack([...], nn=[...])for several terms at once);- weights: scale proxes with floats (
lam * pyproximal.L21(ndim=2)withlam = float(...)): an integer (2 * f) silently yieldsNoneinstead of a scaled operator.
2. Pick the solver
| Structure | Solver |
|---|---|
f smooth (e.g. L2 data) + simple g on x (L1, Box) |
ProximalGradient(proxf, proxg, x0, epsg, tau, acceleration="fista") |
f + g(Kx) with K non-trivial (TV, analysis L1 with non-orthogonal transform) |
PrimalDual(proxf, proxg, K, x0, tau, mu) or LinearizedADMM(proxf, proxg, K, x0, tau, mu) |
| several signals sharing a sparse support (joint / group sparsity) | one joint problem: stack the coefficients (BlockDiag of the per-signal operators), g = L21(ndim=n_signals) in ProximalGradient; not one L1 problem per signal |
| low-rank matrix from partially observed entries | ProximalGradient with L2(Op=Restriction(...), b=y) and Nuclear((n, m)); ‖Restriction‖ = 1, so tau = 1 |
½‖Op x − b‖² + g(Ax) with a good inner least-squares solver |
ADMML2(proxg, Op, b, A, x0, tau) |
f(x) + g(x) both non-smooth with cheap proxes |
ADMM or DouglasRachfordSplitting |
| constraints + data + regulariser | PrimalDual with f = Box(...), g = VStack([L2(b=y), lam*L21]), K = VStack([Op, Gradient]) |
| many terms | GeneralizedProximalGradient, PPXA, ConsensusADMM |
| denoiser as prior (median filter, BM3D, network) | pnp.PlugAndPlay(proxf, denoiser, dims, x0, solver=ProximalGradient or ADMM, tau=...); denoiser(x, tau) receives x reshaped to dims and runs at every iteration (applying it once to an lsqr result is post-processing, not PnP) |
State the choice and why.
Use the PyProximal solver and proximal operators from the table; do not hand-write the iteration (gradient + clip, SVT loops, "median filter then lsqr" alternations) or switch to scipy/cvxpy. If the first formulation does not work after one or two attempts, go back to the table and use the row that matches the problem structure instead of trying variants of the same approach.
3. Step sizes and parameters
- Compute operator norms, do not guess:
L = ‖K‖²withpylops.optimization.eigs.power_iteration(K.H @ K, niter=100)[0](inflate ~5 %) or(K.H @ K).eigs(neigs=1)(ARPACK may raiseArpackNoConvergence– raiseniteror use power iteration). - ProximalGradient:
tau ≤ 1/LwithL = ‖Op‖²for½‖Op x − b‖²(ortau=Nonefor backtracking); PrimalDual:tau * mu * ‖K‖² < 1(e.g.tau = mu = 0.95/sqrt(L)); LinearizedADMM:mu ≤ tau / ‖K‖². - Inner solves:
L2(Op=..., niter=...)needs an inner iterative solve at every prox; keepnitersmall (10–30) withwarm=True, or moveOpintoKand useL2(b=y)instead. - Choose every free parameter (regularisation weight, threshold,
tau/mufor ADMM/PnP, rank,niter, denoiser strength) with a criterion that does not use the true model: discrepancy principle (residual ≈ noise level), held-out observed data, L-curve, or a stated scale argument. Never pick a value because it gives the best SNR against the true model; that is an oracle, and it will not transfer to real data. The same applies to information that is only known from how the synthetic was built (the true support, number of components or rank).
4. Write, run, verify
Adapt reference/tv_template.py (TV deblurring with and without box
constraints via PrimalDual):
- a
callbackstoring the objective value per iteration; plot it (log scale); - stop criterion: relative change of the objective / model below a tolerance, or
a fixed
nitershown to be enough by the cost curve; - check constraints are satisfied (e.g. bounds), and compare with the unconstrained / L2 solution to show what the non-smooth term changes;
- use a synthetic with known model first when possible, but only to evaluate the result (
pylops.utils.metrics.snrof the final model); the true model must not feed into the solve or into choosing its parameters. A table of SNR vs parameter can be shown as a diagnostic, next to the parameter picked by the truth-free criterion.
If the cost oscillates or diverges, the step sizes violate the conditions above
(recompute ‖K‖²), or K fails the dot-test
(pylops.utils.dottest).
5. Hand off
Report, with numbers from the run: the objective as written, the proxes/solver chosen and why, the step
sizes and how they were derived, how each free parameter was chosen (the truth-free criterion used), convergence evidence as the iterations used and the cost at the start and end (from the callback, not only the niter you set), the result compared with a baseline, and parameters left to tune.
04 同仓库更多 Skills
wrap-operator
Wrap a user's own forward model as a PyLops linear operator inside their project (not inside the PyLops library), with a verified adjoint, a dot-test and a small test suite. Use when the user wants to turn existing forward/adjoint code, a script at a URL, or a mathematical description into a PyLops operator they can pass to PyLops solvers (e.g. "make my blurring function a PyLops operator", "wrap this forward model so I can invert it with lsqr", "I have a forward and adjoint, plug them into PyLops").
tune-regularization
Choose regularisation weights and thresholds for a PyLops inversion (epsRs in regularized_inversion, damp in cgls/lsqr, eps in ista/fista, epsRL1s in splitbregman, sigma/tau in spgl1, niter as implicit regularisation) with a principled, reproducible sweep - L-curve, discrepancy principle, GCV for small problems, or a synthetic test with a known model. Use when the user asks "how do I choose epsilon / lambda / damping", "my inversion is too smooth / too noisy", "make an L-curve", or after solve-inverse-problem produced a working but untuned inversion.
solve-inverse-problem
Use this skill whenever the user has (or can build) a PyLops operator and data and wants to invert it - load it before choosing a solver or writing any inversion code, even when the right solver or regularisation seems obvious. It sets up and runs the inversion in the user's project - choose the solver (lsqr, cgls, cg, regularized_inversion, preconditioned_inversion, fista, spgl1, omp, irls, splitbregman), the regularisation and the stopping parameters, and write a runnable script that reports convergence. E.g. "invert my data with this operator", "which PyLops solver should I use", "add Tikhonov / smoothness / sparsity regularisation to my inversion", "solve y = Op x". Not for an inversion that already misbehaves (use debug-inversion) or for choosing regularisation weights with an L-curve or sweep (use tune-regularization).
sliding-patch-processing
Set up PyLops windowed operators - Sliding1D, Sliding2D, Sliding3D, Patch2D, Patch3D - to apply a local transform or operator over overlapping windows of 1-D/2-D/3-D data, choosing window size, overlap, taper and model size with the *_design and *_pad_to_next helpers, checking coverage and the dot-test, and using them for local denoising, interpolation or inversion. Use when the user asks "apply FFT/Radon/any operator in overlapping windows", "local transform / patching with PyLops", "Patch2D gives artefacts at the edges", "how do I pick nwin, nover, nop".
pick-sparsifying-transform
Choose a sparsifying transform for a signal or image in a PyLops sparsity-promoting inversion (FFT/FFT2D/FFTND, DCT, DWT/DWT2D/DWTND, DTCWT, Seislet, curvelets via UDCT, Radon/FourierRadon/ChirpRadon, windowed versions with Sliding/Patch), check its optional dependencies and frame properties, compare candidates quantitatively with a best-k-term compressibility test, and wire the winner into fista/spgl1 in synthesis or analysis form. Use when the user asks "which transform should I use for sparsity", "wavelets or curvelets for my data", "make my model sparse for fista/spgl1", "compressive sensing / interpolation with PyLops".
debug-inversion
Use this skill whenever a user shares PyLops code or results that misbehave and asks what is wrong - load it first, before running the user's code, testing a hypothesis or answering, even when the bug looks obvious from the code. Covers a crash or traceback (dtype/casting errors, shape mismatches), a solver (lsqr, cgls, cg, fista, ista, spgl1, regularized_inversion, splitbregman) that stalls, diverges, returns NaNs, zeros, ringing or a wrong model, one dataset or block being ignored in a stacked/joint inversion, or a custom FunctionOperator/LinearOperator that may have a wrong adjoint. Diagnoses with evidence (block-by-block dot-tests incl. complex, dtype and dims checks, operator/data scaling, solver and eps/damp choice), then proposes the smallest fix and verifies it. Not for choosing a solver for a new, working setup (use solve-inverse-problem) or picking regularisation weights (use tune-regularization).