beamax.solvers.solverbase

Abstract solver interface used across concrete backend implementations.

Purpose

• Defines a consistent contract for forward/time-reversal/adjoint style solvers.
• Helps interchange backends (MSGB, k-Wave, hybrid, learned surrogates) in examples and benchmarks.

API Reference

beamax.solvers.solverbase

SupportsArray

Bases: Protocol

Minimal protocol to accept JAX/NumPy arrays without importing heavy deps.

Solver

Bases: ABC

Unified solver interface.

All implementations MUST accept keyword-only arguments and MUST document the exact shapes they expect for each argument.

Conventions

• p0: initial pressure in the image domain. Real-valued unless otherwise stated.
• dpdt: initial time derivative (may be None; treat as zeros if not used).
• domain: geometry/medium object with physical grid and c(x).
• sensors: either a Sensor object or an array mask / positions consistent with the solver.
• ts: time grid, shape (Nt,).
• All methods return arrays with time leading: shape (Nt, *S) unless documented.

Notes

Implementations that do not support time_reversal or adjoint must raise NotImplementedError with a clear message at call time.

forward(p0: Array, domain: object, sensors: object, ts: Array, **solver_kwargs) -> Array abstractmethod

Simulate forward propagation from initial conditions.

Parameters:

Name	Type	Description	Default
p0	array	Initial pressure field (image domain).	required
domain	object	Geometry/medium descriptor.	required
sensors	object	Sensor geometry or mask.	required
ts	(array, shape(Nt))		required

Returns:

Type	Description
array	Sensor time series, shape (Nt, *S).

time_reversal(data: Array, domain: object, sensors: object, sources: object, ts: Array, **solver_kwargs) -> Array abstractmethod

Time-reversal reconstruction.

Parameters:

Name	Type	Description	Default
data	(Array, shape(Nt, *S))	Sensor measurements in time.	required
domain	Domain	Reconstruction domain (where to reconstruct on).	required
sensors	Sensor	Sensor geometry.	required
sources	Sensor	Source positions for data injection. Pass None if the solver does not distinguish between sources and receivers.	required
ts	(Array, shape(Nt))	Time grid corresponding to data.	required
**solver_kwargs		Solver-specific arguments (e.g. wpt, domain_data for MSGB).	{}

Returns:

Type	Description
(Array, shape(*N))	Reconstructed initial pressure on the image grid.

adjoint(data: Array, domain: object, sensors: object, sources: object, ts: Array, **solver_kwargs) -> Array abstractmethod

Adjoint reconstruction.

Parameters:

Name	Type	Description	Default
data	(Array, shape(Nt, *S))	Sensor measurements in time.	required
domain	Domain	Reconstruction domain (where to reconstruct on).	required
sensors	Sensor	Sensor geometry.	required
sources	Sensor	Source positions for data injection. Pass None if the solver does not distinguish between sources and receivers.	required
ts	(Array, shape(Nt))	Time grid corresponding to data.	required
**solver_kwargs		Solver-specific arguments (e.g. wpt, domain_data for MSGB).	{}

Returns:

Type	Description
(Array, shape(*N))	Reconstructed initial pressure on the image grid. Unlike time-reversal, the adjoint is the exact transpose of the discretised forward map.