deisa.ray.window_handler module

class deisa.ray.window_handler.Deisa(feedback_queue_size: int = 1024, *args: Any, **kwargs: Any)

Bases: IDeisa

Entry point that orchestrates analytics callbacks on Ray.

Provides an API for registering sliding window callbacks and executing them as arrays arrive from simulation ranks.

execute_callbacks() → None

Execute the registered simulation callback loop.

Notes

Supports a single registered callback at present. Manages array retrieval from the head actor, windowed array delivery, and garbage collection between iterations.

register(*callback_args: CallbackArgs, exception_handler: ExceptionHandler = <function IDeisa.__default_exception_handler>, when: Literal['AND', 'OR']='AND') → Callable

Decorator that registers a sliding-window analytics callback.

Parameters:

• *callback_args (CallbackArgs) – Array descriptions the callback should receive.

• exception_handler (Optional[Callable], optional) – Handler invoked when the user callback raises. Defaults to deisa.core.IDeisa.__default_exception_handler().

• when (Literal["AND", "OR"], optional) – Governs whether all arrays ("AND") or any array ("OR") must be available before the callback runs. Defaults to "AND".

Returns:

Decorator that registers simulation_callback with the window handler.

Return type:

Callable

register_callback(callback: Callback, *callback_args: CallbackArgs, exception_handler: ExceptionHandler = <function IDeisa.__default_exception_handler>, when: Literal['AND', 'OR']='AND') → Callable

Register the analytics callback and array descriptions.

Parameters:

• callback (Callable) – Function to run for each iteration; receives arrays as kwargs and timestep.

• *callback_args (CallbackArgs) – Descriptions of arrays to stream to the callback (with optional sliding windows). Maximum iterations to execute. Default is a large sentinel.

• exception_handler (Optional[Callable]) – Exception handler to handle any exception thrown by simulation (like division by zero). Defaults to printing the error and moving on.

• when (Literal['AND', 'OR']) – When callback have multiple arrays, govern when callback should be called. AND: only call callback if ALL required arrays have been shared for a given timestep. OR: call callback if ANY array has been shared for a given timestep.

Returns:

The original callback, allowing decorator-style usage.

Return type:

Callable

set(key: str, value: Any, timestep: int) → None

Publish a feedback value for bridges.

Parameters:

• key (Hashable) – Identifier for the shared value.

• value (Any) – Value to store.

• timestep (Hashable) – Timestep associated with value.

Notes

Timestamped values are stored in a fixed-size queue on the head actor. For a given key, timesteps must be strictly increasing; publishing the same timestep twice or publishing an older timestep raises ValueError. Bridges retrieve them collectively with bridge.get("foo", timestep=t).