cubie.outputhandling.output_functions

Output function management for CUDA-accelerated batch solving.

This module provides classes for managing output functions that handle state saving, summary calculations, and writing to memory for CUDA batch solvers. The functions are automatically cached and compiled on demand through the CUDAFactory base class.

Classes

`OutputFunctionCache`(save_state_function, ...)	Cache container for compiled output functions.
`OutputFunctions`(max_states, max_observables)	Output function factory with automatic caching.

class cubie.outputhandling.output_functions.OutputFunctionCache(save_state_function: Callable, update_summaries_function: Callable, save_summaries_function: Callable)[source]

Bases: object

Cache container for compiled output functions.

This class holds the three main compiled functions used in output handling: state saving, summary updates, and summary saving. It serves as a data container returned by the OutputFunctions.build() method.

save_state_function

Compiled CUDA function for saving state values.

Type:: Callable

update_summaries_function

Compiled CUDA function for updating summary metrics.

Type:: Callable

save_summaries_function

Compiled CUDA function for saving summary results.

Type:: Callable

save_state_function: Callable

save_summaries_function: Callable

update_summaries_function: Callable

Bases: CUDAFactory

Output function factory with automatic caching.

This class manages the creation and caching of CUDA-compiled output functions for state saving and summary calculations. It extends CUDAFactory to provide automatic function caching and invalidation when settings change.

Parameters:

max_states (int) – Maximum number of state variables in the system.
max_observables (int) – Maximum number of observable variables in the system.
output_types (list[str], optional) – Types of output to generate. Default is [“state”].
saved_state_indices (Sequence[int] or ArrayLike, optional) – Indices of state variables to save in time-domain output.
saved_observable_indices (Sequence[int] or ArrayLike, optional) – Indices of observable variables to save in time-domain output.
summarised_state_indices (Sequence[int] or ArrayLike, optional) – Indices of state variables to include in summary calculations.
summarised_observable_indices (Sequence[int] or ArrayLike, optional) – Indices of observable variables to include in summary calculations.

Notes

The class automatically creates an OutputConfig object from the provided parameters and sets it up as compile settings through the CUDAFactory interface. Functions are compiled lazily when first accessed.

build() → OutputFunctionCache[source]

Compile output functions and calculate memory requirements.

Compiles three main functions: save state, update summary metrics, and save summaries. Also calculates memory requirements for buffer and output arrays based on the current configuration.

Returns:: Container with all compiled functions and memory requirements.
Return type:: OutputFunctionCache

Notes

This method is called automatically by the CUDAFactory when functions are first accessed. The compiled functions are optimized for the current configuration settings.

property compile_flags

Get the compile flags for output functions.

Returns:: Compile flags indicating which output types are enabled.
Return type:: OutputCompileFlags

property n_saved_observables: int

Get number of observables that will be saved in time-domain output.

Returns:: Number of observable variables that will actually be saved.
Return type:: int

property n_saved_states: int

Get number of states that will be saved in time-domain output.

Returns:: Number of state variables to save, which equals the length of saved_state_indices when save_state is True.
Return type:: int

property n_summarised_observables: int

Get number of observables that will be summarised.

Returns:: Number of observable variables that will actually be summarised.
Return type:: int

property n_summarised_states: int

Get number of states that will be summarised.

Returns:: Number of state variables included in summary calculations, which equals the length of summarised_state_indices when save_summaries is active.
Return type:: int

property observable_summaries_buffer_height: int

Get height of the observable summaries buffer.

Returns:: Total height of the buffer for observable summary calculations.
Return type:: int

property observable_summaries_output_height: int

Get height of the output array for observable summaries.

Returns:: Height of the output array for observable summary data.
Return type:: int

property output_array_heights: OutputArrayHeights

Get output array height information.

Returns:: Object containing height information for output arrays.
Return type:: OutputArrayHeights

Notes

Exposes OutputArrayHeights from the child OutputArrayHeights object.

property output_types

Get the output types configured for compilation.

Returns:: Set of output types requested/compiled into the functions.
Return type:: set

property save_state_func

Access the compiled state saving function.

Returns:: Compiled CUDA function for saving state values.
Return type:: Callable

Notes

Exposes save_state_function from the cached OutputFunctionCache object. The function is compiled on first access if not already cached.

property save_summary_metrics_func

Access the compiled summary saving function.

Returns:: Compiled CUDA function for saving summary results.
Return type:: Callable

Notes

Exposes save_summaries_function from the cached OutputFunctionCache object. The function is compiled on first access if not already cached.

property save_time

Check if time saving is enabled.

Returns:: True if time values are being saved with state data.
Return type:: bool

property saved_observable_indices

Get indices of observables to save in time-domain output.

Returns:: Array of observable variable indices for time-domain saving.
Return type:: np.ndarray

property saved_state_indices

Get indices of states to save in time-domain output.

Returns:: Array of state variable indices for time-domain saving.
Return type:: np.ndarray

property state_summaries_buffer_height: int

Get height of the state summaries buffer.

Returns:: Total height of the buffer for state summary calculations.
Return type:: int

property state_summaries_output_height: int

Get height of the output array for state summaries.

Returns:: Height of the output array for state summary data.
Return type:: int

property summaries_buffer_height_per_var: int

Get height of the summary buffer per variable.

Returns:: Height of the summary buffer required per variable.
Return type:: int

property summaries_buffer_sizes: SummariesBufferSizes

Get summary buffer size information.

Returns:: Object containing buffer size information for summary calculations.
Return type:: SummariesBufferSizes

Notes

Exposes SummariesBufferSizes from the child SummariesBufferSizes object.

property summaries_output_height_per_var: int

Get height of the summary output per variable.

Returns:: Height of the summary output array per variable.
Return type:: int

property summarised_observable_indices

Get indices of observables to include in summary calculations.

Returns:: Array of observable variable indices for summary calculations.
Return type:: np.ndarray

property summarised_state_indices

Get indices of states to include in summary calculations.

Returns:: Array of state variable indices for summary calculations.
Return type:: np.ndarray

property summary_legend_per_variable: dict[str, int]

Get mapping of summary names to their heights per variable.

Returns:: Dictionary mapping summary metric names to their required heights per variable.
Return type:: dict[str, int]

property total_summary_buffer_size: int

Get total size of the summaries buffer.

Returns:: Total size required for all summary buffers combined.
Return type:: int

update(updates_dict=None, silent=False, **kwargs)[source]

Update compile settings through the CUDAFactory interface.

Pass updates to compile settings, which will invalidate the function cache if an update is successful. This allows dynamic reconfiguration of output parameters.

Parameters:

updates_dict (dict, optional) – Dictionary of parameter updates to apply.
silent (bool, optional) – If True, suppress warnings about unrecognized parameters. Default is False.
**kwargs – Additional parameter updates to apply.

Returns:

Set of recognized parameter names that were successfully updated.

Return type:

set

Raises:

KeyError – If unrecognized parameters are provided and silent=False.

Notes

This method is useful for bulk updates with other component parameters when silent=True is used to suppress warnings about keys not found in this component.

property update_summaries_func

Access the compiled summary update function.

Returns:: Compiled CUDA function for updating summary metrics.
Return type:: Callable

Notes

Exposes update_summaries_function from the cached OutputFunctionCache object. The function is compiled on first access if not already cached.