cubie.outputhandling

This module manages the saving and summarising of the solver system.

This module provides the core infrastructure for saving and summarising the solver system, including registration and function dispatch for CUDA device functions.

class cubie.outputhandling.OutputConfig(max_states: int, max_observables: int, saved_state_indices: List | ndarray[Any, dtype[_ScalarType_co]] | None = NOTHING, saved_observable_indices: List | ndarray[Any, dtype[_ScalarType_co]] | None = NOTHING, summarised_state_indices: List | ndarray[Any, dtype[_ScalarType_co]] | None = NOTHING, summarised_observable_indices: List | ndarray[Any, dtype[_ScalarType_co]] | None = NOTHING, output_types: List[str] = NOTHING)[source]

Bases: object

Configuration class for output handling with validation.

This class manages output configuration settings including which variables to save, which to summarize, and various validation logic to ensure proper configuration. It handles the conversion between user-friendly output type specifications and internal boolean flags.

Parameters:

_max_states (int) – Maximum number of state variables in the system.
_max_observables (int) – Maximum number of observable variables in the system.
_saved_state_indices (list or NDArray, optional) – Indices of state variables to save. Defaults to empty list.
_saved_observable_indices (list or NDArray, optional) – Indices of observable variables to save. Defaults to empty list.
_summarised_state_indices (list or NDArray, optional) – Indices of state variables to summarize. Defaults to empty list.
_summarised_observable_indices (list or NDArray, optional) – Indices of observable variables to summarize. Defaults to empty list.
_output_types (list[str], optional) – List of requested output types. Defaults to empty list.

Notes

Uses private attributes with property accessors to handle circular dependencies when setting indices and output flags. This design allows for proper validation while maintaining a clean public interface.

The class automatically validates that: - At least one output type is requested - All indices are within valid ranges - No duplicate indices are specified

_check_for_no_outputs()[source]

Ensure at least one output type is requested.

Raises:: ValueError – If no output types are enabled.

_check_saved_indices()[source]

Convert saved indices to numpy arrays and set defaults if empty.

Notes

If index arrays are empty, creates arrays containing all possible indices for the respective variable types.

_check_summarised_indices()[source]

Set summarised indices to saved indices if not provided.

Notes

If summarised indices are empty, defaults them to the corresponding saved indices arrays.

_validate_index_arrays()[source]

Validate that all index arrays are within bounds and contain no duplicates.

Notes

Called post-init to allow None arrays to be replaced with default arrays before validation.

property compile_flags: OutputCompileFlags

Get compile flags for this configuration.

Returns:: Flags indicating which output features should be compiled.
Return type:: OutputCompileFlags

classmethod from_loop_settings(output_types: List[str], saved_state_indices=None, saved_observable_indices=None, summarised_state_indices=None, summarised_observable_indices=None, max_states: int = 0, max_observables: int = 0) → OutputConfig[source]

Create configuration from integrator-compatible specifications.

Parameters:

output_types (list[str]) – Output types from [“state”, “observables”, “time”] plus summary metrics like [“max”, “peaks”, “mean”, “rms”, “min”].
saved_state_indices (array-like, optional) – Indices of states to save in time-domain output.
saved_observable_indices (array-like, optional) – Indices of observables to save in time-domain output.
summarised_state_indices (array-like, optional) – Indices of states for summary calculations. If None, defaults to saved_state_indices.
summarised_observable_indices (array-like, optional) – Indices of observables for summary calculations. If None, defaults to saved_observable_indices.
max_states (int, default 0) – Total number of state variables in the system.
max_observables (int, default 0) – Total number of observable variables in the system.

Returns:

Configured output configuration object.

Return type:

OutputConfig

Notes

This class method provides a convenient interface for creating OutputConfig objects from the parameter format used by integrator classes. It handles None values appropriately by converting them to empty arrays.

property max_observables

Get the maximum number of observables.

Returns:: Maximum number of observable variables.
Return type:: int

property max_states

Get the maximum number of states.

Returns:: Maximum number of state variables.
Return type:: int

property n_saved_observables: int

Get number of observables that will be saved.

Returns:: Number of observable variables to save in time-domain output.
Return type:: int

property n_saved_states: int

Get number of states that will be saved.

Returns:: Number of state variables to save in time-domain output.
Return type:: int

Notes

Returns the length of saved_state_indices when save_state is True, otherwise 0.

property n_summarised_observables: int

Get number of observables that will be summarised.

Returns:: Number of observable variables for summary calculations.
Return type:: int

property n_summarised_states: int

Get number of states that will be summarised.

Returns:: Number of state variables for summary calculations.
Return type:: int

Notes

Returns the length of summarised_state_indices when save_summaries is active, otherwise 0.

property observable_summaries_buffer_height: int

Calculate total buffer height for observable summaries.

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

property observable_summaries_output_height: int

Calculate total output height for observable summaries.

Returns:: Total output height for all observable summary results.
Return type:: int

property output_types: List[str]

Get the configured output types.

Returns:: List of requested output type names.
Return type:: list[str]

property save_observables

Check if observable saving is enabled and has valid indices.

Returns:: True if observable saving is enabled and indices are available.
Return type:: bool

property save_state: bool

Check if state saving is enabled and has valid indices.

Returns:: True if state saving is enabled and indices are available.
Return type:: bool

property save_summaries: bool

Check if any summary calculations are needed.

Returns:: True if any summary types are configured.
Return type:: bool

property save_time

Check if time saving is enabled.

Returns:: True if time values should be saved.
Return type:: bool

property saved_observable_indices

Get indices of observables to save.

Returns:: Array of observable indices, empty if observable saving is disabled.
Return type:: np.ndarray

property saved_state_indices

Get indices of states to save.

Returns:: Array of state indices, empty if state saving is disabled.
Return type:: np.ndarray

property state_summaries_buffer_height: int

Calculate total buffer height for state summaries.

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

property state_summaries_output_height: int

Calculate total output height for state summaries.

Returns:: Total output height for all state summary results.
Return type:: int

property summaries_buffer_height_per_var: int

Calculate buffer size per variable for summary calculations.

Returns:: Buffer height required per variable for summary metrics.
Return type:: int

property summaries_output_height_per_var: int

Calculate output array height per variable for summaries.

Returns:: Output height required per variable for summary results.
Return type:: int

property summarise_observables: bool

Check if observable variables will be summarised.

Returns:: True if summaries are enabled and observable indices are available.
Return type:: bool

property summarise_state: bool

Check if state variables will be summarised.

Returns:: True if summaries are enabled and state indices are available.
Return type:: bool

property summarised_observable_indices

Get indices of observables to summarise.

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

property summarised_state_indices

Get indices of states to summarise.

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

property summary_legend_per_variable

Get mapping of summary types to indices per variable.

Returns:: Dictionary mapping index numbers to summary type names.
Return type:: dict[str, int]

property summary_parameters

Get parameters for summary metrics.

Returns:: Parameters required by the summary metrics system.
Return type:: dict

property summary_types

Get the configured summary types.

Returns:: Tuple of summary metric names.
Return type:: tuple[str]

property total_summary_buffer_size: int

Calculate total size of all summary buffers.

Returns:: Combined size of state and observable summary buffers.
Return type:: int

update_from_outputs_list(output_types: list[str])[source]

Update configuration from a list of output type names.

Parameters:: output_types (list[str]) – List of output type names to configure.

Notes

Parses the output types list to set internal boolean flags and extract summary metric specifications. Unknown output types generate warnings but do not cause errors.

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.

Modules

`output_config`	Output configuration management system for flexible, user-controlled output selection.
`output_functions`	Output function management for CUDA-accelerated batch solving.
`output_sizes`	Array sizing classes for output buffer and array management.
`save_state`	CUDA device function factory for saving state and observable values.
`save_summaries`	CUDA device function factory for saving summary metrics.
`summarymetrics`	Summary metrics.
`update_summaries`	CUDA device function factory for updating summary metrics during integration.