solprop.backends.numpy_ref.session_parts#

The building blocks the reference’s session composes (SEP 47 section 5).

The reference’s session (solprop.backends.numpy_ref.session.HostSession) runs its own plane schedule over its own march, and composes the parts below, none of which names a march; the native session keeps the same bookkeeping in session.cpp:

  • SessionLedger is the lifecycle bookkeeping: receipts, the pending barrier, closing and poisoning; it holds no numerical state;

  • AttemptCounter forwards a march’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 (section 5.4);

  • merge_summaries(), bind() and EMPTY_SUMMARY assemble events.

The refusals a preparation makes before any session starts are both backends’ (solprop.backends.session.check_preparation()).

Module Attributes

EMPTY_SUMMARY

The summary of a launch plane, which no propagation reached.

Functions

bind(event, receipt)

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

export_weight(problem, z, recipe)

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

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).

SessionLedger()

The lifecycle bookkeeping of a Python session; no numerical state.

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.numpy_ref.session_parts.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.numpy_ref.session_parts.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.numpy_ref.session_parts.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 committed 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 (the next step replaces the state rather than writing into it), so an export with nothing to convert is that array on a spatial grid, and every other export a new array (or the caller’s destination). 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 committed state, draining the 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.numpy_ref.session_parts.SessionLedger[source]#

Bases: object

The lifecycle bookkeeping of a Python session; no numerical state.

It issues receipts, records the pending barrier, refuses stale or foreign receipts and advancing across an unacknowledged barrier, and remembers whether the session finished, failed or closed.

Examples

>>> from solprop.backends.numpy_ref.session_parts import SessionLedger
>>> ledger = SessionLedger()
>>> receipt = ledger.issue()
>>> ledger.ticket_valid(receipt)
True
>>> ledger.acknowledge(receipt)
>>> ledger.ticket_valid(receipt)
False
acknowledge(receipt)[source]#

Accept the pending batch’s receipt.

Parameters:
receiptsolprop.backends.events.Receipt

The receipt to acknowledge.

Raises:
SessionError

If the receipt is not the pending one: foreign, stale or repeated.

check_advance()[source]#

Refuse to advance a session that is pending, finished or closed.

Raises:
SessionError

Naming the state that forbids it.

check_open()[source]#

Refuse a closed session.

Raises:
SessionError

If the session was closed.

check_ticket(ticket)[source]#

Refuse an export with an expired or foreign ticket.

Parameters:
ticketsolprop.backends.events.ExportTicket

The ticket presented.

Raises:
SessionError

If its batch is no longer pending.

close()[source]#

Mark the session closed.

Returns:
bool

True the first time, False when it was already closed.

property finished: bool[source]#

Whether a terminal batch was issued.

issue(*, outcome=None)[source]#

Issue the receipt of a new pending batch.

Parameters:
outcomesolprop.backends.events.Outcome or None, optional

The batch’s terminal outcome, when it ends the session.

Returns:
solprop.backends.events.Receipt

The batch’s receipt.

outcome: Outcome | None#
property pending: Receipt | None[source]#

Pending batch’s receipt, or None.

ticket_valid(receipt)[source]#

Return whether tickets of a batch can still be exported.

Parameters:
receiptsolprop.backends.events.Receipt

The batch’s receipt.

Returns:
bool

True while that batch is the pending one.

class solprop.backends.numpy_ref.session_parts.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.numpy_ref.session_parts.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.numpy_ref.session_parts.bind(event, receipt)[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.

Returns:
solprop.backends.events.Event

The event, its ticket bound; the same event when it carries none.

solprop.backends.numpy_ref.session_parts.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.numpy_ref.session_parts.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.