solprop.backends.session_core#

The building blocks the Python execution sessions share (SEP 47 sections 5 and 6.7).

The reference’s sessions (solprop.backends.host.session.HostSession and solprop.backends.host.group_session.HostGroupSession) run their own plane schedule over their own driver, and compose the parts below, none of which names a driver; the native backend’s prepared execution (solprop_native.session) makes the same preparation refusals:

AttemptCounter forwards a driver’s attempts to a progress listener and counts them, and YieldDue reads that count and the clock for a bounded advance (SEP 47 section 5.1);
SnapshotLatch coalesces snapshot requests until one is serviced (section 5.5);
ObservedField observes a committed field once per ticket and shares it among its exports, converting it in place where nothing else holds it (section 5.4);
merge_summaries(), bind() and EMPTY_SUMMARY assemble events;
foreign_request() and check_preparation() are the refusals a preparation makes before any session starts (section 5.2).

The lifecycle bookkeeping – receipts, the pending barrier, closing and poisoning – is solprop.backends.session.SessionLedger.

Module Attributes

`AttemptListener`	Called with each attempt's end, length and acceptance, for a progress reporter.
`EMPTY_SUMMARY`	The summary of a launch plane, which no propagation reached.

Functions

`bind`(event, receipt[, member])	Return an event with its ticket bound to the batch that delivers it.
`check_preparation`(name, own, problem, request)	Refuse a run a constructed backend cannot prepare, by name (SEP 47 5.2).
`export_weight`(problem, z, recipe)	Return the recipe an export applies at z, and its true-power weight.
`foreign_request`(own, request)	Return why request is not a run of own, or `None` when it is.
`merge_summaries`(before, step)	Merge a propagation's summary with the yields before it on the same plane.

Classes

`AttemptCounter`([listener, started])	Counts a driver's attempts and forwards them and its start, and nothing else.
`ObservedField`(problem, drain)	One committed field per ticket, shared by every export of it (SEP 47 5.4).
`SnapshotLatch`()	Holds one outstanding snapshot request until it is serviced (SEP 47 5.5).
`YieldDue`(counter, limit, started, deadline)	Says whether a bounded advance has reached its attempt bound or its deadline.

class solprop.backends.session_core.AttemptCounter(listener=None, started=None)[source]#

Bases: NullReporter

Counts a driver’s attempts and forwards them and its start, and nothing else.

The service loop reports planes itself; NullReporter drops the rest.

Parameters:

listenercallable or None, optional: Called with each attempt; None only counts it.
startedcallable or None, optional: Called once, when the driver first propagates; None drops it.

Attributes:

countint: The attempts heard so far.

started(z_start, z_end, n_planes)[source]#

Forward the driver’s start, made when it first propagates.

Parameters:

z_startfloat: Where propagation starts, m.
z_endfloat: Where it ends, m.
n_planesint: The number of save planes.

step(z, dz, accepted)[source]#

Count one attempt and forward it.

Parameters:

zfloat: Where the attempt ended, m.
dzfloat: Its length, m.
acceptedbool: Whether it was accepted.

solprop.backends.session_core.AttemptListener#

Called with each attempt’s end, length and acceptance, for a progress reporter.

alias of Callable[[float, float, bool], None]

solprop.backends.session_core.EMPTY_SUMMARY = StepSummary(z=0.0, n_steps=0, n_rejected=0, max_norm=0.0, mean_norm=0.0, wall_time=0.0, met_tolerance=True)#: The summary of a launch plane, which no propagation reached.

class solprop.backends.session_core.ObservedField(problem, drain)[source]#

Bases: object

One committed field per ticket, shared by every export of it (SEP 47 5.4).

A session observes its driver’s field once per state generation, when a consumer first asks for it; every export of that ticket reads the same observation. An observation’s arrays are read-only and nothing writes to them again (solprop.backends.protocol.Backend.observe()), so an export with nothing to convert is that array; one the driver made for the session alone is converted in place when it was not handed out unconverted. Attempts a field fetch drains are kept for the next event’s chunk.

Parameters:

problemsolprop.translate.problem.PropagationProblem: The run’s problem, for the true-power conversion.
draincallable: drain(field=True) observes the driver, draining its attempts.

export(ticket, recipe, out=None)[source]#

Fill a destination with a valid ticket’s converted field.

Parameters:

ticketsolprop.backends.events.ExportTicket: A ticket the session’s ledger has checked.
recipesolprop.backends.export.ExportRecipe: The conversion.
outnumpy.ndarray or None, optional: The destination; a new array by default.

Returns:

numpy.ndarray: The converted field.

noise_phase(ticket)[source]#

Return the noise phase at a valid ticket.

Parameters:

ticketsolprop.backends.events.ExportTicket: A ticket the session’s ledger has checked.

Returns:

numpy.ndarray or None: The phase, shape (n_modes, n_pol, n_omega), or None without noise.

observation(ticket)[source]#

Observe the field for a ticket once, sharing it among its consumers.

Parameters:

ticketsolprop.backends.events.ExportTicket: A valid ticket.

Returns:

solprop.backends.protocol.Observation: The driver’s observation with its field.

release()[source]#

Forget the observation: the next export of any ticket observes again.

undelivered()[source]#

Return, once, the attempts field fetches drained since the last call.

Returns:

list of tuple: The attempts and rows of each fetch that drained any, in order.

class solprop.backends.session_core.SnapshotLatch[source]#

Bases: object

Holds one outstanding snapshot request until it is serviced (SEP 47 5.5).

Attributes:

pendingint or None: The outstanding request’s number, or None.

clear()[source]#

Mark the outstanding request serviced.

pending: int | None#

request()[source]#

Latch a request, or join the outstanding one.

Returns:

solprop.backends.session.SnapshotReceipt: The request’s receipt, coalesced when it joined an outstanding one.

class solprop.backends.session_core.YieldDue(counter, limit, started, deadline)[source]#

Bases: object

Says whether a bounded advance has reached its attempt bound or its deadline.

A class rather than a closure in a session’s advance, so that no function object is made per call (each one costs the coverage lane’s import hook a compile).

Parameters:

counterAttemptCounter: The session’s attempt count.
limitint: The attempt count at which the march halts.
startedfloat: The advance’s start, in time.perf_counter() seconds.
deadlinefloat: The seconds after started at which the march halts.

solprop.backends.session_core.bind(event, receipt, member=None)[source]#

Return an event with its ticket bound to the batch that delivers it.

Parameters:

eventsolprop.backends.events.Event: An event, with an unbound ticket or none.
receiptsolprop.backends.events.Receipt: The batch’s receipt.
memberint or None, optional: The group member the ticket names; None for a lone session.

Returns:

solprop.backends.events.Event: The event, its ticket bound; the same event when it carries none.

solprop.backends.session_core.check_preparation(name, own, problem, request)[source]#

Refuse a run a constructed backend cannot prepare, by name (SEP 47 5.2).

Parameters:

namestr: The backend’s registered name, for the message.
ownsolprop.translate.run_request.RunRequest: The request the backend was built for.
problemsolprop.translate.problem.PropagationProblem: The run’s problem.
requestsolprop.translate.run_request.RunRequest: The run’s request.

Raises:

solprop.backends.session.SessionError: If the request is not one run of the backend’s own (foreign_request()).
solprop.exceptions.BackendError: If the request asks for statistics the problem does not carry (statistics_unavailable()).

solprop.backends.session_core.export_weight(problem, z, recipe)[source]#

Return the recipe an export applies at z, and its true-power weight.

Parameters:

problemsolprop.translate.problem.PropagationProblem: The run’s problem.
zfloat: The observation’s position, m.
recipesolprop.backends.export.ExportRecipe: The conversion asked for.

Returns:

tuple: The recipe, without the power conversion on a spatial route, whose field measure is already the stored quantity, and the weight, or None when no power conversion is made.

solprop.backends.session_core.foreign_request(own, request)[source]#

Return why request is not a run of own, or None when it is.

A backend lowers its method, error control, replay and itinerary where it is built (SEP 47 section 5.2), so a run it serves may differ from its own request only where for_run() changes it: the start, retention, statistics, monitor, history and snapshots. for_run keeps the other sections by identity, which is what is checked.

Parameters:

ownsolprop.translate.run_request.RunRequest: The request the backend was built for.
requestsolprop.translate.run_request.RunRequest: The request one run asks it to serve.

Returns:

str or None: The first section that differs, named, or None.

Examples

>>> from solprop.stepper import DOPRI5, PIController
>>> from solprop.translate.problem import StepperSettings
>>> from solprop.translate.run_request import describe_run
>>> settings = StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14),
...                            1e-9, 0.1, 1e-3, 1.1, None, [0.5, 1.0], "auto")
>>> own = describe_run(settings)
>>> foreign_request(own, own.for_run(start_plane=1)) is None
True
>>> foreign_request(own, describe_run(settings))
"the run's integration is not the backend's own"

solprop.backends.session_core.merge_summaries(before, step)[source]#

Merge a propagation’s summary with the yields before it on the same plane.

Parameters:

beforesolprop.backends.protocol.StepSummary or None: The plane so far, or None when step is its first propagation.
stepsolprop.backends.protocol.StepSummary: The latest propagation.

Returns:

solprop.backends.protocol.StepSummary: The summary of the plane so far.