Preconditioners

Preconditioners in sweepx.opt are objects that pre-multiply a gradient before an optimizer's step() consumes it. They share a single contract:

class Preconditioner:
    def update(self, params, *, source_illum=None, receiver_illum=None) -> None:
        """Refresh internal state. Called once per outer iteration."""

    def __call__(self, grad: torch.Tensor, param: torch.Tensor) -> torch.Tensor:
        """Return the preconditioned gradient."""

This means any preconditioner composes with any optimizer:

import sweepx.opt

optimizer = sweepx.opt.optim.LBFGS(
    [inv_vp],
    preconditioner=sweepx.opt.precond.PseudoHessianPrecond(eps=1e-5),
)

Preconditioners can also be composed with each other (e.g. pseudo-Hessian multiplied by depth weighting); see the per-algorithm pages. The pseudo-Hessian also needs its illumination maps refreshed during the run: see hooking it into a sweep run.

Available preconditioners

Name	Class	Notes
Pseudo-Hessian	PseudoHessianPrecond	Plessix-Mulder diagonal; needs source / receiver illumination.
Depth weighting	DepthWeighting	(z / z_max)^p mask along the depth axis; composable with PH.