AGENT SKILL

accelerate-on-gpu

Move an existing PyLops workflow (operators, custom LinearOperators and solvers) from NumPy on CPU to GPU with CuPy, or to JAX, and benchmark it against the CPU version. Covers backend-agnostic custom operators, dtype choice, host/device transfers, operators without GPU support, mixed CPU/GPU setups with ToCupy, and correct GPU timing. Use when the user asks "run my PyLops inversion on GPU", "use cupy with pylops", "my PyLops code is too slow", "port this operator to JAX".

License 许可
LGPL-2.1
最近更新
2026-11-02
Stars
★ 1
Forks
0

01 前言 Front Matter

name
accelerate-on-gpu
description
Move an existing PyLops workflow (operators, custom LinearOperators and solvers) from NumPy on CPU to GPU with CuPy, or to JAX, and benchmark it against the CPU version. Covers backend-agnostic custom operators, dtype choice, host/device transfers, operators without GPU support, mixed CPU/GPU setups with ToCupy, and correct GPU timing. Use when the user asks "run my PyLops inversion on GPU", "use cupy with pylops", "my PyLops code is too slow", "port this operator to JAX".

02 资源文件 1

03 SKILL.md 正文

Goal: the user's workflow runs on the GPU (CuPy) or with JAX, gives the same result as on CPU (within dtype precision), and a benchmark shows whether it is actually faster. Do not modify the installed pylops package.

0. Check the environment

  • Use the project's Python runner. Check pylops.__version__, and whether a GPU and backend are usable:
    • CuPy: python -c "import cupy as cp; print(cp.__version__, cp.cuda.runtime.getDeviceCount())"
    • JAX: python -c "import jax; print(jax.__version__, jax.devices())"
  • PyLops detects CuPy/JAX at import time: they must be installed before (or alongside) PyLops, and CUPY_PYLOPS=0 / JAX_PYLOPS=0 in the environment disable them. If import pylops fails after installing CuPy/JAX, check versions against the PyLops installation docs. Ask before installing anything; the CuPy wheel must match the CUDA version (cupy-cuda12x, cupy-cuda13x, or PyLops extras pylops[gpu-cu12]/pylops[gpu-cu13]).
  • If no GPU is available, still make the code backend-agnostic and test it on CPU with NumPy (and with JAX on CPU if installed); say clearly that GPU performance was not measured.

1. Inventory the workflow

List every operator in the chain and check GPU support in the PyLops GPU page (https://pylops.readthedocs.io/en/stable/gpu.html) or the table below. Summary for PyLops 2.x:

  • Work on CuPy and JAX: basic operators (MatrixMult, Diagonal, Identity, Restriction, VStack/HStack/BlockDiag, Kronecker, Transpose, Roll, Pad, …), all derivatives, FFT/FFT2D/FFTND, Shift, Convolve2D/ND, Fredholm1, Interp, ChirpRadon2D/3D, MDC, UpDownComposition2D/3D, Blending*, PoststackLinearModelling, AVOLinearModelling.
  • CuPy only (not JAX): Sliding*, Patch*, Bilinear, NonStationaryConvolve2D, FourierRadon2D/3D (engine="cuda"); Convolve1D and PrestackLinearModelling are partial on JAX.
  • CPU only: DWT*, DCT, Seislet, UDCT, Radon2D/3D, Spread, PWSprayer2D, PWSmoother2D, Kirchhoff (its engine="cuda" is Numba-CUDA, not CuPy arrays), AcousticWave2D; LinearOperator.eigs, .cond, .trace, .tosparse.
  • Solvers in pylops.optimization work with CuPy/JAX arrays. Wrappers that default to SciPy (regularized_inversion, preconditioned_inversion, normal_equations_inversion, irls, omp, splitbregman) switch to the PyLops inner solver for non-NumPy arrays, so their kwargs_solver must then use PyLops names (niter, not SciPy's iter_lim): pass engine="pylops" explicitly so CPU and GPU runs take the same arguments. spgl1 is CPU only.

The installed version is authoritative: when unsure, try the operator on a small CuPy array and compare with NumPy.

2. Port

  • One switch: introduce a backend variable (xp = cupy or numpy, or a backend="numpy"|"cupy"|"jax" argument) and create every array the operators hold (matrices, filters, wavelets, masks, diagonals) and the data/x0 with it. PyLops picks the backend from the arrays: an operator built with NumPy arrays applied to CuPy data fails or silently copies. pylops.utils.backend.get_module(backend) returns the module.
  • dtype: prefer float32/complex64 on GPU (consumer GPUs are much slower in double precision); pass dtype= to operators consistently. Check the accuracy impact against the float64 CPU run.
  • Custom operators (LinearOperator subclasses written by the user): replace np. calls on inputs with ncp = get_array_module(x) and ncp.; move stored parameters to the input's device with to_cupy_conditional(x, self.param); avoid np.asarray, .tolist(), Python loops over elements and SciPy functions on CuPy arrays (use cupyx.scipy equivalents). Re-run the dot-test with dottest(..., backend="cupy").
  • JAX: wrap the final operator in pylops.JaxOperator(Op) (JIT-compiles matvec/rmatvec); Op.rmatvecad(x, y) gives an autodiff adjoint to test a hand-written one. JAX arrays are immutable: replace in-place assignments (x[idx] = v) in the user's setup code with NumPy construction followed by jnp.asarray, or with x.at[idx].set(v). ToCupy/inoutengine mixed setups are not available with JAX.
  • Unsupported operators: keep them on CPU and sandwich GPU parts with pylops.ToCupy (Top1.H @ GpuOp @ Top), or use VStack/BlockDiag with inoutengine=("numpy", "cupy") when the model fits on GPU but the data does not. This is also the pattern when the full data do not fit in GPU memory.
  • Transfers: move data to the GPU once (cp.asarray) and results back once (cp.asnumpy or pylops.utils.backend.to_numpy) – not inside callbacks or loops. Plotting needs NumPy arrays.
  • LinearOperator.eigs / cond are CPU only. ista/fista with alpha=None already switch to pylops.optimization.eigs.power_iteration for non-NumPy arrays, but eigsdict keys then go to power_iteration (niter, tol) instead of eigs; for your own estimates call power_iteration(Op.H @ Op, niter=..., dtype=..., backend="cupy"), or compute alpha once on CPU and pass it.

3. Verify and benchmark

Adapt reference/benchmark_template.py:

  • compare forward, adjoint and final inversion result CPU vs GPU (np.allclose with a tolerance matching the dtype, e.g. rtol=1e-4 for float32);
  • time matvec, rmatvec and the full solve after a warm-up call (CuPy compiles kernels and JAX JIT-compiles on first use) and with synchronisation (cp.cuda.Device().synchronize(), jax.block_until_ready) – otherwise GPU timings are meaningless;
  • repeat several times and report median; try at least two problem sizes (small problems are often faster on CPU).

4. Hand off

Report: what changed (backend switch, custom-operator edits, operators kept on CPU), the accuracy check, the timing table (CPU vs GPU, per size), and remaining bottlenecks (CPU-only operators, transfers).

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

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.

★ 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