solprop.backends.batch

Establish fixed-schedule lockstep with independent backend workspaces.

This runner is the correctness baseline for fused batch kernels. It executes the selected backend’s existing kernels for each member at each shared step. It does not amortise GPU kernel launches and is not a device-batching performance claim.

Classes

LockstepRunner(members)

Advance loaded member workspaces through one shared fixed-schedule march.

class solprop.backends.batch.LockstepRunner(members)

Bases: StepDriver[tuple[object, …]]

Advance loaded member workspaces through one shared fixed-schedule march.

Each workspace retains its own parameter tables, noise, error estimate and statistics storage hooks. The maximum norm is a batch diagnostic only: fixed replay does not use it to change any member’s schedule. Member observations carry their own error histories, never that maximum.

The caller validates layout compatibility and admits memory before constructing this runner. Ownership of the loaded workspaces transfers to the runner after successful construction; close releases every member.

Each member watches its own time window (SEP 21). A member whose monitor stops it stops watching while the others go on, and member_stops says which, so that a batched scan fails that point alone, as a run of it alone would fail.

Parameters:

memberssequence of solprop.backends.driver.StepDriver

Nonempty sequence of loaded singleton backends with the same name and fixed schedule. All must be at the entrance with no previously attempted steps.

Raises:

BackendError

If members mix backends, lack a common fixed schedule, are already advanced, or have different save planes or periodic-statistics requests.

attach_monitor(monitor)

Give every member its own copy of the boundary monitor (SEP 21).

Parameters:

monitorsolprop.monitor.BoundaryMonitor

A monitor with nothing recorded, copied per member.

attach_monitors(monitors)

Give each member its own boundary monitor, or none (SEP 21).

A launch the monitor refuses stops that member’s watch alone (member_stops).

Parameters:

monitorscollections.abc.Sequence

One monitor with nothing recorded, or None, per member, in member order.

Raises:

BackendError

If the count differs from the members’.

available_device_memory()

Read the selected device’s free bytes through its first member.

Returns:

int or None

Free device bytes, or None for a host batch.

close()

Release every member workspace and the common march state.

finish_monitors()

Report each still-watched member’s removed fraction at the run’s end.

A warning raised as an error fails that member alone (member_stops), as a run of it alone would fail.

member_metadata()

Return each member’s resolved policies with the shared batch strategy.

Returns:

tuple of dict

Complete backend provenance in member order.

property member_records: tuple[Mapping[str, object] | None, ...]

Return each member’s monitor record, as it closed, in member order.

A stopped member’s is its record at the stop; a watched one’s is read now.

Returns:

tuple

The summary() of each member, or None for one never watched.

property member_stops: tuple[BoundaryError | BoundaryWarning | None, ...]

Return what stopped each member’s watch, in member order.

Returns:

tuple

The BoundaryError that stopped a member, the BoundaryWarning raised as an error for it under an "error" warnings filter, or None for one still watched or never watched.

memory_ledger()

Name each member’s workspace allocations separately.

Returns:

dict of str to int

Backend allocation bytes under member-prefixed names. Shared translation products are accounted separately by the common driver’s host budget.

metadata()

Describe the lockstep execution strategy without implying fused kernels.

Returns:

dict

Selected backend, member count and workspace strategy.

observe(*, field=True)

Refuse an observation that would substitute a shared member history.

Parameters:

fieldbool, optional

Unused: the observation is refused either way.

Raises:

BackendError

Always; use observe_members to retain each member’s error norms.

observe_members()

Drain each member’s host observation and its own diagnostic history.

Returns:

tuple of solprop.backends.protocol.Observation

Singleton observations in batch order, with unchanged field shapes and independently retained periodic rows.

stats(spec)

Collect member statistics with a leading batch axis.

Parameters:

specsolprop.stats.StatsSpec

Names and windows evaluated independently by each member.

Returns:

dict of str to numpy.ndarray

Host statistics concatenated on their existing batch axes.