cubie.outputhandling.output_config

Output configuration management system for flexible, user-controlled output selection.

This module provides configuration classes for managing output settings in CUDA batch solvers, including validation of indices and output types, and automatic configuration from user-specified parameters.

Classes

`OutputCompileFlags`([save_state, ...])	Compile-time flags for output functionality.
`OutputConfig`(max_states, max_observables[, ...])	Configuration class for output handling with validation.

class cubie.outputhandling.output_config.OutputCompileFlags(save_state: bool = False, save_observables: bool = False, summarise: bool = False, summarise_observables: bool = False, summarise_state: bool = False)[source]

Bases: object

Compile-time flags for output functionality.

This class holds boolean flags that determine which output features should be compiled into CUDA kernels for optimal performance.

save_state

Whether to save state variables.

Type:: bool, default False

save_observables

Whether to save observable variables.

Type:: bool, default False

summarise

Whether to compute summary statistics.

Type:: bool, default False

summarise_observables

Whether to compute summaries for observables.

Type:: bool, default False

summarise_state

Whether to compute summaries for states.

Type:: bool, default False

save_observables: bool

save_state: bool

summarise: bool

summarise_observables: bool

summarise_state: bool

class cubie.outputhandling.output_config.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.

cubie.outputhandling.output_config._indices_validator(array, max_index)[source]

Validate that indices are valid numpy arrays within bounds.

Parameters:

array (np.ndarray or None) – Array of indices to validate.
max_index (int) – Maximum allowed index value (exclusive).

Raises:

TypeError – If array is not a numpy array of integers.
ValueError – If indices are out of bounds or contain duplicates.