pycsamt.forward.maxwell.backends#

Capability checks and lazy registration for Maxwell solver backends.

Backends are integrations, not deep-learning frameworks. Each adapter must declare its physical and numerical scope before it can receive a problem. Factories are stored lazily so optional solver packages are imported only when a caller explicitly creates that backend.

Module Attributes

backend_registry

Process-wide registry used by the convenience functions.

Functions

`create_backend`(name, **options)	Create a registered Maxwell adapter lazily.
`list_backends`(*[, available_only])	Describe registered Maxwell backends without creating them.
`register_backend`(registration, *[, replace])	Register a lazy backend in the process-wide registry.
`unregister_backend`(name)	Remove a backend from the process-wide registry.

Classes

`BackendCapabilities`(name, version, ...[, ...])	Declare a Maxwell adapter's supported physical and numerical scope.
`BackendRegistration`(capabilities, factory[, ...])	Store one lazy backend factory and its availability probe.
`BackendRegistry`()	Thread-safe registry of lazy Maxwell backend factories.
`CompatibilityReport`(backend_name, compatible)	Describe whether a backend can solve a particular problem.
`MaxwellBackend`(args, *kwargs)	Runtime-checkable interface implemented by Maxwell adapters.

class pycsamt.forward.maxwell.backends.BackendCapabilities(name, version, dimensions, components, time_conventions=('exp(+iwt)',), supports_nonuniform_mesh=True, supports_inactive_cells=False, supports_topography=False, supports_anisotropy=False, maximum_cells=None, maximum_frequencies=None, verified_benchmarks=())[source]

Bases: object

Declare a Maxwell adapter’s supported physical and numerical scope.

Parameters:

name (str) – Stable backend identifier and adapter/solver version.
version (str) – Stable backend identifier and adapter/solver version.
dimensions (tuple containing 2 and/or 3) – Spatial problem dimensions genuinely supported.
components (tuple of str) – Impedance tensor components the adapter can return.
time_conventions (tuple of str, default=("exp(+iwt)",)) – Phasor conventions accepted without conversion.
supports_nonuniform_mesh (bool, default=True) – Whether variable cell widths are supported.
supports_inactive_cells (bool, default=False) – Whether MaxwellProblem.active_cells is honored.
supports_topography (bool, default=False) – Whether an inactive/air mask may describe non-flat terrain.
supports_anisotropy (bool, default=False) – Reserved declaration for future tensor-conductivity contracts.
maximum_cells (int or None, optional) – Enforced adapter limits. None means no declared limit.
maximum_frequencies (int or None, optional) – Enforced adapter limits. None means no declared limit.
verified_benchmarks (tuple of str, optional) – Stable benchmark identifiers passed by this adapter version.

Examples

>>> capability = BackendCapabilities("mt2d", "1.0", (2,), ("zxy", "zyx"))
>>> capability.supports_dimension(2), capability.supports_component("zxy")
(True, True)

name: str

version: str

dimensions: tuple[int, ...]

components: tuple[str, ...]

time_conventions: tuple[str, ...] = ('exp(+iwt)',)

supports_nonuniform_mesh: bool = True

supports_inactive_cells: bool = False

supports_topography: bool = False

supports_anisotropy: bool = False

maximum_cells: int | None = None

maximum_frequencies: int | None = None

verified_benchmarks: tuple[str, ...] = ()

supports_dimension(dimension)[source]

Return whether a spatial dimension is supported.

Parameters:: dimension (int) – Requested dimension.
Returns:: Capability status.
Return type:: bool

Examples

>>> BackendCapabilities("b", "1", (2,), ("zxy",)).supports_dimension(3)
False

supports_component(component)[source]

Return whether an impedance component is supported.

Parameters:: component (str) – Canonical tensor component name.
Returns:: Capability status.
Return type:: bool

Examples

>>> BackendCapabilities("b", "1", (2,), ("zxy",)).supports_component(
...     "ZYX"
... )
False

assess(problem)[source]

Assess a problem without invoking the numerical backend.

Parameters:: problem (MaxwellProblem or TriProblem) – Validated problem contract, rectilinear or triangular. Both expose the same mesh/frequencies_hz/components/ time_dependence/active_cells shape this method reads; only cell_widths_m is rectilinear-only, so the nonuniform-mesh check below is skipped (not applicable) for an unstructured TriMesh.
Returns:: All hard errors plus advisory validation warnings.
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"])
... )
>>> BackendCapabilities("b", "1", (2,), ("zxy", "zyx")).assess(
...     problem
... ).compatible
True

to_dict()[source]

Return a JSON-compatible capability declaration.

Returns:: Versioned capability state.
Return type:: dict

Examples

>>> BackendCapabilities("b", "1", (2,), ("zxy",)).to_dict()[
...     "dimensions"
... ]
[2]

classmethod from_dict(data)[source]

Restore a validated capability declaration.

Parameters:: data (mapping) – State returned by to_dict().
Returns:: Restored declaration.
Return type:: BackendCapabilities

Examples

>>> cap = BackendCapabilities("b", "1", (2,), ("zxy",))
>>> BackendCapabilities.from_dict(cap.to_dict()).name
'b'

class pycsamt.forward.maxwell.backends.CompatibilityReport(backend_name, compatible, errors=(), warnings=())[source]

Bases: object

Describe whether a backend can solve a particular problem.

Parameters:

backend_name (str) – Normalized backend identifier.
compatible (bool) – Whether all hard capability requirements are satisfied.
errors (tuple of str, optional) – Hard incompatibilities and advisory concerns.
warnings (tuple of str, optional) – Hard incompatibilities and advisory concerns.

Examples

>>> report = CompatibilityReport("demo", False, ("3-D unsupported",))
>>> report.require()
Traceback (most recent call last):
...
ValueError: backend 'demo' is incompatible: 3-D unsupported

backend_name: str

compatible: bool

errors: tuple[str, ...] = ()

warnings: tuple[str, ...] = ()

require()[source]

Raise a consolidated error when the report is incompatible.

Raises:: ValueError – If one or more hard incompatibilities were found.
Return type:: None

Examples

>>> CompatibilityReport("demo", True).require()

to_dict()[source]

Return a JSON-compatible report.

Returns:: Compatibility state and messages.
Return type:: dict

Examples

>>> CompatibilityReport("demo", True).to_dict()["compatible"]
True

class pycsamt.forward.maxwell.backends.MaxwellBackend(*args, **kwargs)[source]

Bases: Protocol

Runtime-checkable interface implemented by Maxwell adapters.

Examples

A conforming adapter exposes immutable capabilities and a solve method.

>>> class Demo:
...     capabilities = BackendCapabilities(
...         "demo", "1", (2,), ("zxy", "zyx")
...     )
...
...     def solve(self, problem):
...         raise NotImplementedError
>>> isinstance(Demo(), MaxwellBackend)
True

property capabilities: BackendCapabilities[source]: Return the adapter’s immutable capability declaration.

solve(problem)[source]

Solve a compatible problem and return canonical output.

Parameters:: problem (MaxwellProblem)
Return type:: ForwardResult

class pycsamt.forward.maxwell.backends.BackendRegistration(capabilities, factory, availability_probe=None)[source]

Bases: object

Store one lazy backend factory and its availability probe.

Parameters:

capabilities (BackendCapabilities) – Static capability declaration, available without importing the solver.
factory (callable) – Factory returning a MaxwellBackend.
availability_probe (callable or None, optional) – Lightweight function returning (available, reason).

Examples

>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> registration = BackendRegistration(cap, lambda: object())
>>> registration.availability()
(True, None)

capabilities: BackendCapabilities

factory: Callable[[...], MaxwellBackend]

availability_probe: Callable[[], tuple[bool, str | None]] | None = None

availability()[source]

Return whether the optional backend can currently be created.

Returns:

available (bool) – Probe status.
reason (str or None) – Human-readable reason when unavailable.

Return type:

tuple[bool, str | None]

Examples

>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> BackendRegistration(
...     cap, lambda: None, lambda: (False, "missing")
... ).availability()
(False, 'missing')

create(**options)[source]

Create and validate a backend instance.

Parameters:: **options (Any) – Backend-specific constructor options.
Returns:: Conforming adapter instance.
Return type:: MaxwellBackend
Raises:: RuntimeError – If unavailable or the factory violates its registration.

Examples

>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> class Demo:
...     capabilities = cap
...
...     def solve(self, problem):
...         raise NotImplementedError
>>> BackendRegistration(cap, Demo).create().capabilities.name
'demo'

class pycsamt.forward.maxwell.backends.BackendRegistry[source]

Bases: object

Thread-safe registry of lazy Maxwell backend factories.

Examples

>>> registry = BackendRegistry()
>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> registry.register(BackendRegistration(cap, lambda: None))
>>> registry.names()
('demo',)

register(registration, *, replace=False)[source]

Register a backend under its declared capability name.

Parameters:

registration (BackendRegistration) – Lazy backend definition.
replace (bool, default=False) – Explicitly replace an existing registration.

Raises:

ValueError – If the name already exists and replacement was not requested.

Return type:

None

Examples

>>> registry = BackendRegistry()
>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> registry.register(BackendRegistration(cap, lambda: None))

unregister(name)[source]

Remove and return a registration.

Parameters:: name (str) – Backend identifier.
Returns:: Removed registration.
Return type:: BackendRegistration

Examples

>>> registry = BackendRegistry()
>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> registry.register(BackendRegistration(cap, lambda: None))
>>> registry.unregister("demo").capabilities.name
'demo'

get(name)[source]

Return one registration without creating its backend.

Parameters:: name (str) – Backend identifier.
Returns:: Lazy registration.
Return type:: BackendRegistration

Examples

>>> registry = BackendRegistry()
>>> cap = BackendCapabilities("demo", "1", (2,), ("zxy",))
>>> registry.register(BackendRegistration(cap, lambda: None))
>>> registry.get("DEMO").capabilities.version
'1'

names(*, available_only=False)[source]

Return sorted registered backend names.

Parameters:: available_only (bool, default=False) – Exclude registrations whose availability probe fails.
Returns:: Stable sorted names.
Return type:: tuple of str

Examples

>>> BackendRegistry().names()
()

describe()[source]

Return immutable availability and capability summaries.

Returns:: Backend names mapped to JSON-compatible summaries.
Return type:: mapping

Examples

>>> BackendRegistry().describe() == {}
True

create(name, **options)[source]

Create a named backend through its lazy factory.

Parameters:

name (str) – Registered backend identifier.
**options – Backend-specific constructor options.

Returns:

Validated adapter.

Return type:

MaxwellBackend

Examples

See BackendRegistration.create() for a complete adapter example.

pycsamt.forward.maxwell.backends.backend_registry = <pycsamt.forward.maxwell.backends.BackendRegistry object>: Process-wide registry used by the convenience functions.

pycsamt.forward.maxwell.backends.register_backend(registration, *, replace=False)[source]

Register a lazy backend in the process-wide registry.

Parameters:

registration (BackendRegistration) – Backend definition.
replace (bool, default=False) – Explicitly replace an existing name.

Return type:

None

Examples

Prefer a private BackendRegistry in isolated applications and tests; this function is intended for adapter package initialization.

pycsamt.forward.maxwell.backends.unregister_backend(name)[source]

Remove a backend from the process-wide registry.

Parameters:: name (str) – Backend identifier.
Returns:: Removed definition.
Return type:: BackendRegistration

Examples

This operation is primarily useful for plugin teardown and tests.

pycsamt.forward.maxwell.backends.create_backend(name, **options)[source]

Create a registered Maxwell adapter lazily.

Parameters:

name (str) – Backend identifier.
**options – Backend-specific constructor options.

Returns:

Validated backend instance.

Return type:

MaxwellBackend

Examples

Backend packages register their factories before this function is called.

pycsamt.forward.maxwell.backends.list_backends(*, available_only=False)[source]

Describe registered Maxwell backends without creating them.

Parameters:: available_only (bool, default=False) – Exclude unavailable optional backends.
Returns:: Immutable capability and availability summaries.
Return type:: mapping

Examples

>>> isinstance(list_backends(), Mapping)
True