SolveResult

class cubie.batchsolving.solveresult.SolveResult(time_domain_array: ndarray[Any, dtype[_ScalarType_co]] = NOTHING, summaries_array: ndarray[Any, dtype[_ScalarType_co]] = NOTHING, time: ndarray[Any, dtype[_ScalarType_co]] | None = NOTHING, iteration_counters: ndarray[Any, dtype[_ScalarType_co]] = NOTHING, status_codes: ndarray[Any, dtype[_ScalarType_co]] | None = None, time_domain_legend: dict[int, str] | None = NOTHING, summaries_legend: dict[int, str] | None = NOTHING, solve_settings: SolveSpec | None = None, singlevar_summary_legend: dict[int, str] | None = NOTHING, active_outputs: ActiveOutputs | None = NOTHING, stride_order: tuple[str, ...] | list[str] = ('time', 'variable', 'run'))[source]

Bases: object

Aggregate output arrays and related metadata for a solver run.

Parameters:

  • time_domain_array (numpy.ndarray[Any, numpy.dtype[numpy._typing._array_like._ScalarType_co]]) – NumPy array containing time-domain results.

  • summaries_array (numpy.ndarray[Any, numpy.dtype[numpy._typing._array_like._ScalarType_co]]) – NumPy array containing summary results.

  • time (numpy.ndarray[Any, numpy.dtype[numpy._typing._array_like._ScalarType_co]] | None) – Optional NumPy array containing time values.

  • iteration_counters (numpy.ndarray[Any, numpy.dtype[numpy._typing._array_like._ScalarType_co]]) – NumPy array containing iteration counts per run.

  • status_codes (numpy.ndarray[Any, numpy.dtype[numpy._typing._array_like._ScalarType_co]] | None) – Optional NumPy array containing solver status codes per run (0 for success, nonzero for errors). Shape is (n_runs,) with dtype int32.

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

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

  • solve_settings (cubie.batchsolving.solveresult.SolveSpec | None) – Optional solver run configuration.

  • active_outputs – Optional ActiveOutputs instance describing enabled arrays.

  • stride_order – Sequence describing the order of axes in host arrays.

  • singlevar_summary_legend – Optional mapping from summary offsets to legend labels.

property active_outputs: ActiveOutputs

Return the active output flags.

property as_numpy: dict[str, ndarray[Any, dtype[_ScalarType_co]] | None]

Return the results as 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[Any, dtype[_ScalarType_co]] | 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[Any, dtype[_ScalarType_co]] | FakeCUDAArray | None, time_saved: bool = False, stride_order: Tuple[str, ...] | None = None) → tuple[ndarray[Any, dtype[_ScalarType_co]] | None, ndarray[Any, dtype[_ScalarType_co]]][source]

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]

static combine_summaries_array(state_summaries: ndarray[Any, dtype[_ScalarType_co]] | FakeCUDAArray | None, observable_summaries: ndarray[Any, dtype[_ScalarType_co]] | FakeCUDAArray | None, summarise_states: bool, summarise_observables: bool) → ndarray[source]

Combine state and observable summary arrays into a single array.

Parameters:

  • state_summaries – Array containing state summaries.

  • observable_summaries – Array containing observable summaries.

  • summarise_states – Flag indicating if state summaries are active.

  • summarise_observables – Flag indicating if observable summaries are active.

Returns:

Combined summary array along the variable axis (axis=1).

Return type:

ndarray

static combine_time_domain_arrays(state: ndarray[Any, dtype[_ScalarType_co]] | FakeCUDAArray | None, observables: ndarray[Any, dtype[_ScalarType_co]] | FakeCUDAArray | None, state_active: bool = True, observables_active: bool = True) → ndarray[Any, dtype[_ScalarType_co]][source]

Combine state and observable arrays into a single time-domain array.

Parameters:

  • state – Array of state values.

  • observables – Array of observable values.

  • state_active – Flag indicating if state values are active.

  • observables_active – Flag indicating if observable values are active.

Returns:

Combined array along the variable axis (axis=1) for 3D arrays, or a copy of the active array.

Return type:

NDArray

classmethod from_solver(solver: Solver | BatchSolverKernel, results_type: str = 'full', nan_error_trajectories: bool = True) → SolveResult | dict[str, Any][source]

Create a SolveResult from a solver instance.

Parameters:

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

  • results_type – Format of the returned results. Options are "full", "numpy", "numpy_per_summary", raw, and "pandas". Defaults to "full". raw shortcuts all processing and outputs numpy arrays that are a direct copy of the host, without legends or supporting information.

  • nan_error_trajectories – When True (default), trajectories with nonzero status codes are set to NaN. When False, all trajectories are returned with original values regardless of status. This parameter is ignored when results_type is "raw".

Returns:

SolveResult when results_type is "full"; otherwise a dictionary containing the requested representation.

Return type:

SolveResult or dict[str, Any]

iteration_counters: ndarray[Any, dtype[_ScalarType_co]]
property per_summary_arrays: dict[str, ndarray[Any, dtype[_ScalarType_co]]]

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
status_codes: ndarray[Any, dtype[_ScalarType_co]] | None
summaries_array: ndarray[Any, dtype[_ScalarType_co]]
summaries_legend: dict[int, str] | None
static summary_legend_from_solver(solver: Solver) → dict[int, str][source]

Generate a summary legend from the solver instance.

Parameters:

solver – Solver instance providing saved states, observables, and summary legends.

Returns:

Dictionary mapping summary array indices to labels with units.

Return type:

dict[int, str]

time: ndarray[Any, dtype[_ScalarType_co]] | None
time_domain_array: ndarray[Any, dtype[_ScalarType_co]]
time_domain_legend: dict[int, str] | None
static time_domain_legend_from_solver(solver: Solver) → dict[int, str][source]

Generate a time-domain legend from the solver instance.

Parameters:

solver – Solver instance providing saved states and observables.

Returns:

Dictionary mapping time-domain indices to labels with units.

Return type:

dict[int, str]