SolveResult

class cubie.batchsolving.solveresult.SolveResult(state: NDArray | None = None, observables: NDArray | None = None, state_summaries: NDArray | None = None, observable_summaries: NDArray | None = None, status_codes: NDArray | None = None, iteration_counters: NDArray | None = None, time_domain_legend: dict[int, str] | None = NOTHING, summaries_legend: dict[int, str] | None = NOTHING, solve_settings: SolveSpec | None = None, stream: FakeStream | int | None = None, singlevar_summary_legend: dict[int, str] | None = NOTHING, active_outputs: ActiveOutputs | None = NOTHING, stride_order: tuple[str, ...] | list[str] = ('time', 'variable', 'run'), save_time: bool = False, memory_manager: Any | None = None)

Bases: object

Own the host outputs of one solve and derive views on demand.

The result takes the solve’s host buffers wholesale — no copies. state (with its time column when time is saved), observables, the summary buffers, status_codes, and iteration_counters are the arrays the kernel wrote. Combined representations (time_domain_array, summaries_array) and the RAM materialisations (as_numpy, as_pandas, as_numpy_per_summary) are built lazily on first access.

Keep the result object alive while its data is needed: once it is garbage collected the solver reuses the buffers on its next run, so arrays extracted from a dead result are not safe to read. Disk-backed (spilled) buffers release their files on close(), context exit, or collection.

Parameters:

• state – State output buffer, including the trailing time column when time saving is enabled.

• observables – Observable output buffer.

• state_summaries – State summary buffer.

• observable_summaries – Observable summary buffer.

• status_codes (numpy._typing._array_like.NDArray | None) – Per-run status codes, shape (n_runs,), dtype int32.

• iteration_counters – Per-save iteration counters when requested.

• time_domain_legend (dict[int, str] | None) – Mapping from time-domain indices to labels.

• summaries_legend (dict[int, str] | None) – Mapping from summary indices to labels.

• solve_settings (cubie.batchsolving.solveresult.SolveSpec | None) – Solver run configuration snapshot.

• stream (cubie.cuda_simsafe.FakeStream | int | None) – The kernel’s memory-manager stream the solve ran on. Work queued on this stream executes in order after the solve’s kernel launches and transfers.

• singlevar_summary_legend – Mapping from summary offsets to legend labels.

• active_outputs – ActiveOutputs flags describing enabled arrays.

• stride_order – Order of axes in the host arrays.

• save_time – Whether the state buffer carries a trailing time column.

• memory_manager – Manager used to release disk-backed buffers.

static _combine_active(first: NDArray | None, second: NDArray | None) → NDArray

Combine up to two active buffers along the variable axis.

_error_run_indices() → NDArray

Return the indices of runs with nonzero status codes.

_mask_error_runs(error_runs: NDArray) → None

NaN the given runs, keeping the state buffer’s time column.

property active_outputs: ActiveOutputs

Return the active output flags.

property as_numpy: dict[str, NDArray | None]

Return the results as in-RAM copies of NumPy arrays.

Returns:

Dictionary containing copies of time, time_domain_array, summaries_array, time_domain_legend, summaries_legend, and iteration_counters.

Return type:

dict[str, Optional[NDArray]]

property as_numpy_per_summary: dict[str, NDArray | None]

Return the results as separate NumPy arrays per summary type.

Returns:

Dictionary containing time, time_domain_array, time_domain_legend, iteration counters, and individual summary arrays.

Return type:

dict[str, Optional[NDArray]]

property as_pandas: dict[str, pd.DataFrame]

Convert the results to pandas DataFrames.

Returns:

Dictionary containing time_domain and summaries DataFrames.

Return type:

dict[str, pandas.DataFrame]

Raises:

ImportError – Raised when pandas is not available.

Notes

Pandas is an optional dependency that is imported lazily.

static cleave_time(state: NDArray | FakeCUDAArray | None, time_saved: bool = False, stride_order: Tuple[str, ...] | None = None) → tuple[NDArray | None, NDArray]

Remove time from the state array when present.

Parameters:

• state – State array potentially containing a time column.

• time_saved – Flag indicating if time is saved in the state array.

• stride_order – Optional order of dimensions in the array. Defaults to ["time", "variable", "run"] when None.

Returns:

Pair containing the time array (or None) and the state array with time removed.

Return type:

tuple[Optional[NDArray], NDArray]

close() → None

Release spill files owned by this result and drop its data.

classmethod from_solver(solver: Solver, nan_error_trajectories: bool = True) → SolveResult

Create a SolveResult owning the solver’s buffers.

The solver’s host output buffers are handed to the result without copying. The solver reuses them on its next run only after the result has been garbage collected; while the result lives, the next run allocates fresh backing.

Parameters:

• solver – Object providing access to output arrays and metadata.

• nan_error_trajectories – When True (default), trajectories with nonzero status codes are overwritten with NaN in place and a warning lists the failures. When False all trajectories are returned unchanged.

Returns:

Result owning the solve’s host buffers.

Return type:

SolveResult

property iteration_counters: NDArray | None

Iteration counters, or None when not requested.

property observable_summaries: NDArray | None

Observable summary buffer, or None when not summarised.

property observables: NDArray | None

Observable output buffer, or None when not saved.

property per_summary_arrays: dict[str, NDArray]

Split summaries_array into separate arrays keyed by summary type.

Returns:

Dictionary where each key is a summary type and the value is the corresponding NumPy array. The dictionary also includes a key ‘summary_legend’ mapping to the variable legend.

Return type:

dict[str, NDArray]

solve_settings: SolveSpec | None

property state: NDArray | None

State output buffer, with its time column when time is saved.

property state_summaries: NDArray | None

State summary buffer, or None when not summarised.

status_codes: NDArray | None

property status_messages: dict[int, List[str]]

Decode nonzero run status codes into named result flags.

Returns:

Mapping from run index to the list of CUBIE_RESULT_CODES member names set in that run’s status word. Runs that completed successfully (status 0) are omitted, so an empty mapping means every run succeeded.

Return type:

dict[int, list[str]]

stream: FakeStream | int | None

property summaries_array: NDArray

Combined summary outputs (states then observables).

summaries_legend: dict[int, str] | None

static summary_legend_from_solver(solver: Solver) → dict[int, str]

Return a copy of the kernel build’s summaries legend.

property time: NDArray | None

Time samples cleaved from the state buffer, or None.

property time_domain_array: NDArray

Combined time-domain outputs (states then observables).

A single active source is returned as a view of the owned buffer — no copy, no RAM beyond what the solve already used. Two active sources concatenate into RAM on first access.

time_domain_legend: dict[int, str] | None

static time_domain_legend_from_solver(solver: Solver) → dict[int, str]

Return a copy of the kernel build’s time-domain legend.