pycsamt.forward.maxwell.adapters

Validated execution layer for solver-specific Maxwell adapters.

Subclasses implement only the backend call and conversion to ForwardResult. The public solve path is fixed here so capability, axis, provenance, and convergence checks cannot be accidentally skipped by individual integrations.

Classes

AdapterPolicy([require_convergence, ...])	Configure solver-independent result acceptance rules.
BaseMaxwellAdapter(capabilities[, policy])	Base class enforcing common preflight and postflight validation.
CallableMaxwellAdapter(capabilities, solver)	Adapt a trusted callable to the validated Maxwell backend interface.

Exceptions

BackendExecutionError	Wrap an exception raised inside a numerical backend.
IncompatibleProblemError	Indicate that declared backend capabilities reject a problem.
InvalidBackendResultError	Indicate malformed, mislabeled, or mismatched backend output.
MaxwellAdapterError	Base exception raised by the validated adapter execution layer.
SolverConvergenceError	Indicate that a valid result violates the convergence policy.

exception pycsamt.forward.maxwell.adapters.MaxwellAdapterError

Bases: RuntimeError

Base exception raised by the validated adapter execution layer.

Examples

>>> error = MaxwellAdapterError("solver failed")
>>> str(error)
'solver failed'

exception pycsamt.forward.maxwell.adapters.IncompatibleProblemError

Bases: MaxwellAdapterError

Indicate that declared backend capabilities reject a problem.

Examples

>>> isinstance(
...     IncompatibleProblemError("unsupported"), MaxwellAdapterError
... )
True

exception pycsamt.forward.maxwell.adapters.BackendExecutionError

Bases: MaxwellAdapterError

Wrap an exception raised inside a numerical backend.

Examples

>>> isinstance(BackendExecutionError("failed"), MaxwellAdapterError)
True

exception pycsamt.forward.maxwell.adapters.InvalidBackendResultError

Bases: MaxwellAdapterError

Indicate malformed, mislabeled, or mismatched backend output.

Examples

>>> isinstance(InvalidBackendResultError("bad axes"), MaxwellAdapterError)
True

exception pycsamt.forward.maxwell.adapters.SolverConvergenceError

Bases: MaxwellAdapterError

Indicate that a valid result violates the convergence policy.

Examples

>>> isinstance(
...     SolverConvergenceError("residual too large"), MaxwellAdapterError
... )
True

class pycsamt.forward.maxwell.adapters.AdapterPolicy(require_convergence=True, maximum_relative_residual=None, require_all_valid=True, emit_capability_warnings=True, wrap_backend_exceptions=True)

Bases: object

Configure solver-independent result acceptance rules.

Parameters:

• require_convergence (bool, default=True) – Reject a result when any solve reports non-convergence.

• maximum_relative_residual (float or None, optional) – Reject a result whose worst reported residual exceeds this value. None delegates residual acceptance entirely to the backend.

• require_all_valid (bool, default=True) – Reject results containing masked or non-finite observations.

• emit_capability_warnings (bool, default=True) – Emit advisory messages from capability assessment.

• wrap_backend_exceptions (bool, default=True) – Wrap ordinary backend exceptions in BackendExecutionError.

Examples

>>> policy = AdapterPolicy(maximum_relative_residual=1e-6)
>>> policy.maximum_relative_residual
1e-06

require_convergence: bool = True

maximum_relative_residual: float | None = None

require_all_valid: bool = True

emit_capability_warnings: bool = True

wrap_backend_exceptions: bool = True

class pycsamt.forward.maxwell.adapters.BaseMaxwellAdapter(capabilities, policy=None)

Bases: ABC

Base class enforcing common preflight and postflight validation.

Parameters:

• capabilities (BackendCapabilities) – Immutable declaration for the exact backend version.

• policy (AdapterPolicy or None, optional) – Result acceptance policy. Defaults to AdapterPolicy.

Notes

Implementations override only _solve_backend(). They must return a canonical ForwardResult; all validation is performed by solve().

Examples

See CallableMaxwellAdapter for a minimal concrete adapter.

property capabilities: BackendCapabilities

Return the immutable backend capability declaration.

Returns:

Physical and numerical scope of this adapter.

Return type:

BackendCapabilities

Examples

>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> CallableMaxwellAdapter(
...     cap, lambda problem: None
... ).capabilities is cap
True

property policy: AdapterPolicy

Return the immutable result acceptance policy.

Returns:

Policy applied after every solve.

Return type:

AdapterPolicy

Examples

>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> CallableMaxwellAdapter(
...     cap, lambda problem: None
... ).policy.require_convergence
True

assess(problem)

Assess a problem against declared backend capabilities.

Parameters:

problem (MaxwellProblem) – Candidate simulation problem.

Returns:

Consolidated errors and warnings without invoking the solver.

Return type:

CompatibilityReport

Examples

>>> from .contracts import MaxwellMesh, ReceiverSet
>>> mesh = MaxwellMesh([0, 1, 2], [0, 1, 2])
>>> problem = MaxwellProblem(
...     mesh,
...     np.ones((2, 2)),
...     [1],
...     ReceiverSet([[0, 0]], ["S"]),
...     ("zxy",),
... )
>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> CallableMaxwellAdapter(cap, lambda problem: None).assess(
...     problem
... ).compatible
True

solve(problem)

Validate, execute, and verify one Maxwell problem.

Parameters:

problem (MaxwellProblem) – Solver-neutral simulation input.

Returns:

Canonical, problem-matched impedance result.

Return type:

ForwardResult

Raises:

• IncompatibleProblemError – If preflight capability checks fail.

• BackendExecutionError – If the numerical backend raises an ordinary exception.

• InvalidBackendResultError – If returned output violates the result contract or problem axes.

• SolverConvergenceError – If convergence, residual, or validity policy fails.

Examples

Concrete execution examples require a backend callback; see CallableMaxwellAdapter.

solve_many(problems)

Solve problems sequentially while preserving input order.

Parameters:

problems (iterable of MaxwellProblem) – Finite problem stream. Execution stops at the first failure.

Returns:

Results in exactly the supplied order.

Return type:

tuple of ForwardResult

Examples

An empty collection performs no backend calls:

>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> CallableMaxwellAdapter(cap, lambda problem: None).solve_many([])
()

class pycsamt.forward.maxwell.adapters.CallableMaxwellAdapter(capabilities, solver, policy=None)

Bases: BaseMaxwellAdapter

Adapt a trusted callable to the validated Maxwell backend interface.

Parameters:

• capabilities (BackendCapabilities) – Static declaration matching callback output identity.

• solver (callable) – Function accepting MaxwellProblem and returning ForwardResult.

• policy (AdapterPolicy or None, optional) – Solver-independent acceptance policy.

Examples

>>> from .contracts import MaxwellMesh, ReceiverSet, SolverDiagnostics
>>> mesh = MaxwellMesh([0, 1, 2], [0, 1, 2])
>>> problem = MaxwellProblem(
...     mesh, np.ones((2, 2)), [1], ReceiverSet([[0, 0]], ["S"]), ("zxy",)
... )
>>> cap = BackendCapabilities(
...     "demo", "1", (2,), ("zxy",), verified_benchmarks=("half-space",)
... )
>>> def solver(value):
...     diagnostics = SolverDiagnostics([[True]], [[0]], [[0]], 0)
...     return ForwardResult(
...         value.problem_hash,
...         value.frequencies_hz,
...         value.receivers.names,
...         value.components,
...         [[[1j]]],
...         None,
...         "demo",
...         "1",
...         diagnostics,
...     )
>>> CallableMaxwellAdapter(cap, solver).solve(problem).success
True