Skip to content

particula.execution.cpu_context

Caller-owned, transactional random streams for CPU box execution.

This module does not import Warp or share the resident GPU stream format. Context views share continuation state, while transactions stage independent generators until a successful runnable substep publishes them.

Classes

NameDescription
CPUExecutionContextRetain persistent process-specific streams keyed by logical box ID.
_CPUStreamTransactionStage stream continuation without touching caller-owned state.

Functions

NameDescription
_box_idsValidate stable, unique logical identities without normalization.
_extension_rng_namespaceEncode identity components without delimiter collisions.
_validate_pcg64_stateReject coercible or out-of-range words before NumPy state assignment.

CPUExecutionContextclass#

class CPUExecutionContext(root_seed: int, box_ids: tuple[str, ...])

Retain persistent process-specific streams keyed by logical box ID.

Parameters

NameTypeDescription
root_seedintNonnegative integer seed; booleans are not accepted.
box_idstuple[str, ...]Unique nonempty strings in current numeric-array box order.

Reordering numeric storage requires a matching with_box_ids view. Reusing a context and process namespace deliberately continues its streams. Create a new context to reset them. Contexts are not thread-safe and must not be used concurrently. No CPU/GPU bitwise equivalence is implied.

_box_idsattributeinstance attribute#

_box_ids: tuple[str, ...] = _box_ids(box_ids)

_root_seedattributeinstance attribute#

_root_seed: int = int(root_seed)

_streamsattributeinstance attribute#

_streams: dict[tuple[str, str], np.random.Generator] = {}

box_idsproperty#

box_ids: tuple[str, ...]

Return logical IDs in this view’s numeric-array order.

root_seedproperty#

root_seed: int

Return the immutable root seed.

__init__method#

def __init__(root_seed: int, box_ids: tuple[str, ...]) -> None

Validate metadata without creating or advancing random streams.

_beginmethod#

def _begin(n_boxes: int) -> _CPUStreamTransaction

Validate layout and begin a private substep transaction.

_checkpointmethod#

def _checkpoint() -> bytes

Own canonical JSON bytes for exact PCG64 continuation.

_new_generatormethod#

def _new_generator(namespace: str, box_id: str) -> np.random.Generator

Derive a versioned PCG64 stream independently of lane/order.

_restoremethodclassmethod#

def _restore(payload: bytes, *, root_seed, box_ids, namespaces)

Validate continuation records before creating generators.

with_box_idsmethod#

def with_box_ids(box_ids: tuple[str, ...]) -> CPUExecutionContext

Create a reordered, reduced, or extended continuation-sharing view.

New IDs acquire streams lazily; existing IDs retain continuation even when absent from a view. The caller must reorder arrays consistently.

_CPUStreamTransactionclass#

class _CPUStreamTransaction(context: CPUExecutionContext)

Stage stream continuation without touching caller-owned state.

_contextattributeinstance attribute#

_context = context

_stagedattributeinstance attribute#

_staged: dict[tuple[str, str], np.random.Generator] = {}

__init__method#

def __init__(context: CPUExecutionContext) -> None

commitmethod#

def commit() -> None

Publish staged streams after successful numeric publication.

generatormethod#

def generator(namespace: str, box: int) -> np.random.Generator

Return a staged generator for one process and logical box.

_box_idsfunction#

def _box_ids(values: tuple[str, ...]) -> tuple[str, ...]

Validate stable, unique logical identities without normalization.

_extension_rng_namespacefunction#

def _extension_rng_namespace(extension_id: str, name: str) -> str

Encode identity components without delimiter collisions.

_validate_pcg64_statefunction#

def _validate_pcg64_state(state)

Reject coercible or out-of-range words before NumPy state assignment.