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.
- License 许可
- LGPL-2.1
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- tune-regularization
- description
- 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.
02 资源文件 1
- 脚本reference/lcurve_template.py5.8 KB
03 SKILL.md 正文
Goal: a sweep script in the user's project that evaluates a regularisation
parameter over a range, applies one or more selection criteria, and reports the
chosen value with a plot that justifies it. PyLops has no built-in L-curve / GCV /
discrepancy helper, so the skill provides reference/lcurve_template.py.
Requires a working inversion (operator passes the dot-test, solver runs). If there
is none, use solve-inverse-problem first.
0. Check the environment
Same as the other PyLops skills: use the project's Python runner, check
pylops.__version__, inspect solver signatures in the installed version.
1. Identify the parameter(s)
Map the user's solver to the knob being tuned and its meaning:
| Solver | Parameter | Objective term |
|---|---|---|
cgls / lsqr |
damp |
damp² ‖x‖² (for lsqr only with x0=None, see step 3) |
regularized_inversion |
epsRs=[ε₁, ε₂, …] |
Σ εᵢ² ‖Rᵢ x‖² |
normal_equations_inversion |
epsI, epsRs (and epsNRs) |
epsI² ‖x‖², Σ εᵢ² ‖Rᵢ x‖² (same scaling as regularized_inversion) |
ista / fista |
eps |
eps ‖SOpᴴ x‖₁ (effective threshold is eps·alpha/2) |
splitbregman |
epsRL1s, epsRL2s, mu |
L1 and L2 weights, data weight |
spgl1 |
sigma (BPDN) or tau (LASSO) |
residual bound or L1-ball radius |
| any Krylov solver without explicit regularisation | niter |
early stopping (semi-convergence) |
With more than one weight, tune one at a time (fix the others at a scale-based guess), or fix their ratio and sweep an overall factor. Do not launch a full grid over several parameters unless the problem is small.
2. Pick the criterion
Choose based on what the user knows:
- Known noise level (sigma per sample, or an estimate from a noise-only
window): discrepancy principle - choose the largest regularisation whose
data residual
‖y − Op x‖is ≤τ · σ · sqrt(N),τ ≈ 1.0–1.1. Forspgl1, this is exactlysigma = τ σ sqrt(N). - Synthetic with a true model: maximise
pylops.utils.metrics.snr(xtrue, x)(report it, but warn it does not transfer 1:1 to field data). - Nothing known: L-curve - plot
log ‖Rx‖vslog ‖y − Op x‖and pick the point of maximum curvature. Needs a wide enough range to show both branches. - Small problem (
Op.todense()affordable, N, M ≲ 3000) and quadratic regularisation: GCV computed exactly on the dense matrices (implemented in the template).
Report more than one criterion when they are cheap; disagreement between them is information for the user.
3. Write and run the sweep
Adapt reference/lcurve_template.py:
- replace
build_problemwith the user's operator, data and regularisation; - replace
solve(eps, x0)with the user's solver call with everything else fixed (sameniter, tolerance,x0policy); - use a log-spaced grid spanning at least 4 orders of magnitude around a
scale-based guess (e.g.
ε₀ ≈ ‖Opᴴ y‖ / ‖Rᴴ R Opᴴ y‖for quadratic terms, oreps₀ ≈ max|Opᴴ y|scale for L1 thresholds, where larger values give all-zero models); - solve from large to small ε and warm start from the previous solution
(
x0=...) to save iterations - unless the solver ignoresx0. Exception:dampoflsqr(PyLops and SciPy): withx0it solves for the correctionx - x0, so it penalisesdamp² ‖x - x0‖², notdamp² ‖x‖², and a warm-started sweep is biased (residual too low, discrepancy pick too large). Usex0=Nonefor everylsqr(damp=...)solve, or put the penalty in the operator (VStack([Op, eps*Reg]),regularized_inversion), wherex0is safe.cgls(damp=...)andepsRsare not affected (checked numerically); - keep
niterlarge enough that each solve has converged, otherwise the curve measures iteration count, not regularisation (check a couple of cost curves); - for early stopping as regulariser, run once with a callback that stores
xevery k iterations and compute the same criteria on iteration number.
Run it, then look at the plot before trusting the automatic pick: an L-curve with
no clear corner (common with L1 terms or very noisy data) should be reported as
such, not forced. With derivative regularisers a second knee often appears at
very large ε (the model collapses into the null space of R, e.g. a linear
trend for SecondDerivative); it bends the other way and is not the L-curve
corner – the template's curvature orientation already excludes it.
4. Hand off
Report:
- the parameter swept, the range and the number of solves;
- the value picked by each criterion and the one recommended, with the reason;
- the plot file(s) (L-curve, residual vs ε, SNR vs ε if available) and the model at the chosen value next to one over- and one under-regularised model;
- the exact line to change in the user's inversion script.
04 同仓库更多 Skills
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.
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").
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).