AGENT SKILL

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

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:

  1. 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. For spgl1, this is exactly sigma = τ σ sqrt(N).
  2. 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).
  3. Nothing known: L-curve - plot log ‖Rx‖ vs log ‖y − Op x‖ and pick the point of maximum curvature. Needs a wide enough range to show both branches.
  4. 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_problem with the user's operator, data and regularisation;
  • replace solve(eps, x0) with the user's solver call with everything else fixed (same niter, tolerance, x0 policy);
  • 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, or eps₀ ≈ 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 ignores x0. Exception: damp of lsqr (PyLops and SciPy): with x0 it solves for the correction x - x0, so it penalises damp² ‖x - x0‖², not damp² ‖x‖², and a warm-started sweep is biased (residual too low, discrepancy pick too large). Use x0=None for every lsqr(damp=...) solve, or put the penalty in the operator (VStack([Op, eps*Reg]), regularized_inversion), where x0 is safe. cgls(damp=...) and epsRs are not affected (checked numerically);
  • keep niter large 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 x every 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

PyLops
PyLops/pylops-agent-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.

★ 1
PyLops
PyLops/pylops-agent-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").

★ 1
PyLops
PyLops/pylops-agent-skills

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).

★ 1
PyLops
PyLops/pylops-agent-skills

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".

★ 1
PyLops
PyLops/pylops-agent-skills

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".

★ 1
PyLops
PyLops/pylops-agent-skills

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).

★ 1