pauli_expansion_view_prepare_operator_fused_application#

cuquantum.bindings.cupauliprop.pauli_expansion_view_prepare_operator_fused_application( intptr_t handle, intptr_t view_in, int32_t num_quantum_operators, quantum_operators, adjoints, int32_t num_truncation_strategies, truncation_strategies, int64_t max_workspace_device_size, intptr_t min_workspace, intptr_t average_workspace, intptr_t max_workspace, ) → tuple[source]#

Prepares a Pauli expansion view for fused quantum operator application.

Unlike the single-operator prepare function, fused application may incidentally succeed or fail on the fly depending on the supplied workspace and output expansion capacities. This function therefore reports the minimum, maximum, and average memory required by the subsequent compute call, updating three separate workspace descriptors and returning the corresponding output expansion term capacities, in the respective scenarios of least, most, and expected expansion growth.

Since memory costs can grow exponentially with num_quantum_operators, the average-case and worst-case quantities may overflow. Any overflowed quantity (both the returned capacity and the corresponding attached workspace size) is set to -1 and should not be consulted; the remaining outputs stay valid and no error is raised. If the operator sequence exceeds a hardware-imposed fused-launch limitation, this function raises cuPauliPropError with CUPAULIPROP_STATUS_INSUFFICIENT_DEVICE_PROPERTY.

Parameters:

handle (intptr_t) – Library handle.
view_in (intptr_t) – Pauli expansion view to apply the operator sequence upon.
num_quantum_operators (int32_t) – Number of quantum operators to be applied (length of quantum_operators and adjoints).
quantum_operators (object) –
Sequence of quantum operators given in order of their intended application. It can be:
- an int as the pointer address to the array, or
- a Python sequence of intptr_t (as pointer addresses).
adjoints (object) –
A sequence specifying whether each corresponding operator is to be adjointed. It can be:
- an int as the pointer address to the array, or
- a Python sequence of int.
num_truncation_strategies (int32_t) – Number of Pauli expansion truncation strategies.
truncation_strategies (object) –
Pauli expansion truncation strategies. It can be:
- an int as the pointer address to the array, or
- a Python sequence of cupaulipropTruncationStrategy_t.
max_workspace_device_size (int64_t) – Maximum workspace device-memory size limit in bytes.
min_workspace (intptr_t) – Workspace descriptor to be updated with the minimum workspace necessary to begin the subsequent compute call.
average_workspace (intptr_t) – Workspace descriptor to be updated with the workspace necessary to handle the average (expected) expansion growth.
max_workspace (intptr_t) – Workspace descriptor to be updated with the maximum workspace necessary to guarantee operator application succeeds.

Returns:

int64_t: Minimum output expansion term capacity required to begin the subsequent compute call.
int64_t: Average (expected) output expansion term capacity (-1 if it overflowed).
int64_t: Maximum output expansion term capacity required to guarantee operator application succeeds (-1 if it overflowed).

Return type:

A 3-tuple containing