OutputFunctions

class cubie.outputhandling.OutputFunctions(n_states: int, n_observables: int, precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], output_types: list[str] = None, saved_state_indices: Sequence[int] | ArrayLike = None, saved_observable_indices: Sequence[int] | ArrayLike = None, summarised_state_indices: Sequence[int] | ArrayLike = None, summarised_observable_indices: Sequence[int] | ArrayLike = None, sample_summaries_every: float | None = None, **compile_flags: object)

Bases: CUDAFactory

Factory that compiles and caches output management functions.

Parameters:

• n_states – Maximum number of state variables in the system.

• n_observables – Maximum number of observable variables in the system.

• output_types – Types of output to generate. Defaults to [“state”].

• saved_state_indices – Indices of state variables to save in time-domain output.

• saved_observable_indices – Indices of observable variables to save in time-domain output.

• summarised_state_indices – Indices of state variables to include in summary calculations.

• summarised_observable_indices – Indices of observable variables to include in summary calculations.

• sample_summaries_every – Time interval between summary metric samples. Used by derivative metrics to scale finite differences. Defaults to None.

• precision – Numerical precision for output calculations. Defaults to np.float32.

Notes

The constructor converts the provided options into an OutputConfig instance and installs it as the compile settings. CUDA callables are only built once per configuration and cached by cubie.CUDAFactory.

_update(updates: Dict[str, Any], silent: bool) → set[str]

Trim stored indices to new maxima, then apply the settings.

Parameters:

• updates – Setting names to new values; gains trimmed index arrays when n_states or n_observables changes.

• silent – Whether update() ignores unrecognised names.

Returns:

Names the output settings recognised.

Return type:

set[str]

Notes

Explicit indices in the same update win over trimmed ones.

property buffer_sizes_dict: dict[str, int]

Dictionary of buffer sizes for each output type.

build() → OutputFunctionCache

Compile output functions and calculate memory requirements.

Returns:

Container with compiled functions that target the current configuration.

Return type:

OutputFunctionCache

Notes

This method is invoked lazily by cubie.CUDAFactory the first time a compiled function is requested. The resulting cache is reused until configuration settings change.

property compile_flags: OutputCompileFlags

Compile flags for the active configuration.

property has_summary_outputs: bool

Whether any summary output is enabled.

property has_time_domain_outputs: bool

Whether any time-domain output is enabled.

property n_saved_observables: int

Number of observable variables saved in time-domain output.

property n_saved_states: int

Number of state variables saved in time-domain output.

property observable_summaries_buffer_height: int

Total height of the buffer for observable summary calculations.

property observable_summaries_output_height: int

Height of the observable summary output array.

property output_array_heights: OutputArrayHeights

Output array height helper built from the active configuration.

property output_types: set[str]

Configured output types.

property save_counters: bool

Whether iteration counters are saved at each save point.

property save_state_fn: Callable

Compiled state saving function.

property save_summaries_fn: Callable

Compiled summary saving function.

property save_time: bool

Whether time samples are saved alongside states.

property saved_observable_indices: NDArray[int64]

Indices of observables saved in time-domain output.

property saved_state_indices: NDArray[int64]

Indices of states saved in time-domain output.

settings_keys: frozenset | None = frozenset({'afn', 'arcp', 'contract', 'ftz', 'lineinfo', 'lto', 'nsz', 'output_types', 'precision', 'reassoc', 'sample_summaries_every', 'saved_observable_indices', 'saved_state_indices', 'summarised_observable_indices', 'summarised_state_indices', 'unroll_accumulator', 'unroll_krylov_exits', 'unroll_newton_exits', 'unroll_norms', 'unroll_other_small', 'unroll_solver_element', 'unroll_stage', 'unroll_step_element'})

Loose keys the factory accepts; None accepts every field.

property state_summaries_buffer_height: int

Total height of the buffer for state summary calculations.

property state_summaries_output_height: int

Height of the state summary output array.

property summaries_buffer_height_per_var: int

Height of the summary buffer required per variable.

property summaries_output_height_per_var: int

Height of the summary output array per variable.

property summarised_observable_indices: NDArray[int64]

Indices of observables tracked by summary metrics.

property summarised_state_indices: NDArray[int64]

Indices of states tracked by summary metrics.

property summary_legend_per_variable: dict[str, int]

Mapping of summary metric names to their per-variable heights.

property summary_unit_modifications: dict[int, str]

Mapping of summary indices to unit modification strings.

classmethod system_inputs(system: Any) → Dict[str, Any]

Return output settings from a system object.

property update_summaries_fn: Callable

Compiled summary update function.