PauliExpansionView#

class cuquantum.pauliprop.experimental.PauliExpansionView( pauli_expansion: PauliExpansion, start_index: int, end_index: int, *, options: PauliExpansionOptions | dict | None = None, )[source]#

A view on a contiguous range of Pauli terms inside a Pauli operator expansion.

Parameters:

pauli_expansion – The Pauli expansion.
start_index – The start index of the view.
end_index – The end index of the view.
options – Either a PauliExpansionOptions object or a dict with matching keywords (allocator, memory_limit, blocking). If not provided, defaults inherit from the parent expansion.

Methods

__init__( pauli_expansion: PauliExpansion, start_index: int, end_index: int, *, options: PauliExpansionOptions | dict | None = None, )[source]#

apply_gate( gate: PauliNoiseChannel | PauliRotationGate | CliffordGate | AmplitudeDampingChannel, truncation: Truncation | None = None, expansion_out: PauliExpansion | None = None, adjoint: bool = False, sort_order: SortOrder | None | Literal['internal', 'little_endian_bitwise'] = None, keep_duplicates: bool = False, rehearse: bool | None = None, stream=None, ) → GateApplicationRehearsalInfo | PauliExpansion[source]#

Applies a quantum operator to the Pauli expansion view.

The truncation is applied during gate application.

If rehearse=True, only the prepare phase is executed to determine resource requirements.

Parameters:

gate – The gate to apply.
truncation – Truncation strategy to apply (optional).
expansion_out – The Pauli expansion to write the result to. If not provided, a new expansion will be allocated with the required capacity.
adjoint – Whether to apply the adjoint of the gate (defaults to False).
sort_order – Sort order for the output expansion. One of None or "internal" (defaults to None).
keep_duplicates – Whether to keep duplicate Pauli strings in the output (defaults to False).
rehearse – If True, only rehearse the operation. If None (default), automatically set to True for rehearsal expansions, False otherwise.
stream – A stream object from the array package, a stream pointer (int), or None to use the package’s current stream.

Returns:

A RehearsalInfo with the required resources. If rehearse=False: The output PauliExpansion.

Return type:

If rehearse=True

Raises:

RuntimeError – If the base expansion is a rehearsal expansion and rehearse=False.

apply_gate_backward_diff( gate: PauliNoiseChannel | PauliRotationGate | CliffordGate | AmplitudeDampingChannel, cotangent_out: PauliExpansionView, truncation: Truncation | None = None, cotangent_in: PauliExpansion | None = None, param_grads_out: ndarray | None = None, adjoint: bool = False, sort_order: SortOrder | None | Literal['internal', 'little_endian_bitwise'] = None, keep_duplicates: bool = False, rehearse: bool | None = None, stream=None, ) → GateApplicationRehearsalInfo | tuple[PauliExpansion, ndarray | None][source]#

Backward pass for apply_gate().

Computes the input cotangent (written to cotangent_in) and accumulates parameter gradients into param_grads_out (or an auto-allocated buffer).

Parameters:

gate – The quantum operator (must match the forward apply_gate() call).
cotangent_out – Cotangent of the forward output, as a PauliExpansionView.
truncation – Truncation strategy (must match the forward call).
cotangent_in – Pre-allocated PauliExpansion for the input cotangent. If None, one is allocated automatically.
param_grads_out – A numpy array to accumulate parameter gradients into. Must have shape (gate.num_differentiable_params,) and dtype matching the expansion coefficient type. If None (default), a zeroed numpy array of the correct shape/dtype is allocated automatically.
adjoint – Must match the adjoint flag used in the forward call.
sort_order – Sort order for the output cotangent expansion.
keep_duplicates – Whether the output may contain duplicates.
rehearse – If True, only the prepare phase runs.
stream – A stream object, stream pointer (int), or None.

Returns:

a GateApplicationRehearsalInfo. If rehearse=False: a tuple (cotangent_in, param_grads) where cotangent_in is the input cotangent PauliExpansion and param_grads is a numpy array of parameter gradients (or None for non-differentiable operators).

Return type:

If rehearse=True

Deduplicates the Pauli expansion view (removes duplicate Pauli strings and sums their coefficients) and writes the result to the output expansion.

Note: The input view must be sorted before calling this method.

If rehearse=True, only the prepare phase is executed to determine resource requirements.

Parameters:

expansion_out – The Pauli expansion to write the deduplicated result to. If not provided, a new expansion will be allocated with the required capacity.
sort_order – Sort order for the output expansion. One of None or "internal" (defaults to None).
rehearse – If True, only rehearse the operation. If None (default), automatically set to True for rehearsal expansions, False otherwise.
stream – A stream object from the array package, a stream pointer (int), or None to use the package’s current stream.

Returns:

A RehearsalInfo with the required resources. If rehearse=False: The output PauliExpansion.

Return type:

If rehearse=True

Raises:

ValueError – If the input view is not sorted.
RuntimeError – If the base expansion is a rehearsal expansion and rehearse=False.

product_trace( other: PauliExpansionView, adjoint: bool = False, rehearse: bool | None = None, stream=None, ) → RehearsalInfo | tuple[float | complex, float][source]#

Computes the product trace Tr(self^† * other) or Tr(self * other) of two Pauli expansion views.

This function computes the trace of the product of two Pauli operators by: 1. Concatenating both views into workspace memory 2. Sorting the combined terms by Pauli strings 3. Identifying Pauli strings that appear exactly twice (once in each expansion) 4. Multiplying the coefficients of matching pairs (with optional adjoint) and summing them

If rehearse=True, only the prepare phase is executed to determine resource requirements.

Parameters:

other – The other Pauli expansion view to compute the product trace with.
adjoint – If True, computes Tr(self^† * other) by taking the complex conjugate of coefficients from self. If False, computes Tr(self * other). Defaults to False.
rehearse – If True, only rehearse the operation. If None (default), automatically set to True if either expansion is a rehearsal expansion, False otherwise.
stream – A stream object from the array package, a stream pointer (int), or None to use the package’s current stream.

Returns:

A RehearsalInfo with the required resources. If rehearse=False: A tuple (trace_significand, trace_exponent) where trace = trace_significand * pow(2, trace_exponent).

Return type:

If rehearse=True

Raises:

ValueError – If the views have different numbers of qubits or data types.
RuntimeError – If either expansion is a rehearsal expansion and rehearse=False.

product_trace_backward_diff( other: PauliExpansionView, cotangent_trace, cotangent_trace_exponent, /, cotangent_expansion1: PauliExpansion | None = None, cotangent_expansion2: PauliExpansion | None = None, adjoint: bool = False, rehearse: bool | None = None, stream=None, ) → ProductTraceBackwardRehearsalInfo | tuple[PauliExpansion, PauliExpansion][source]#

Backward pass for product_trace().

Propagates the scalar cotangent of the product-trace value back to coefficient cotangents for both input views.

Parameters:

other – The other Pauli expansion view (same as in the forward product_trace() call).
cotangent_trace – Scalar cotangent \(\tilde{t} = dL/dt\).
cotangent_trace_exponent – Scalar cotangent for the trace-exponent output.
cotangent_expansion1 – Pre-allocated PauliExpansion to receive coefficient cotangents for self, or None to auto-allocate.
cotangent_expansion2 – Pre-allocated PauliExpansion to receive coefficient cotangents for other, or None to auto-allocate.
adjoint – Must match the adjoint flag used in the forward product_trace() call.
rehearse – If True, only the prepare phase runs.
stream – A stream object, stream pointer (int), or None.

Returns:

a ProductTraceBackwardRehearsalInfo. If rehearse=False: a tuple (cotangent_expansion1, cotangent_expansion2).

Return type:

If rehearse=True

Sorts the Pauli expansion view by the specified sorting order and writes the result to the output expansion.

If rehearse=True, only the prepare phase is executed to determine resource requirements.

Parameters:

expansion_out – The Pauli expansion to write the sorted result to. If not provided, a new expansion will be allocated with the required capacity.
sort_order – Sort order to apply. One of "internal" or "little_endian_bitwise" (defaults to "internal"). Note: None is not valid for sort operations.
rehearse – If True, only rehearse the operation. If None (default), automatically set to True for rehearsal expansions, False otherwise.
stream – A stream object from the array package, a stream pointer (int), or None to use the package’s current stream.

Returns:

A RehearsalInfo with the required resources. If rehearse=False: The output PauliExpansion.

Return type:

If rehearse=True

Raises:

ValueError – If sort_order is None.
RuntimeError – If the base expansion is a rehearsal expansion and rehearse=False.

trace_with_zero_state( rehearse: bool | None = None, stream=None, ) → RehearsalInfo | tuple[float | complex, float][source]#

Computes the trace of the Pauli expansion view with the zero state |0...0>.

This computes \(\langle 0 | \rho | 0 \rangle\) where \(\rho\) is the operator represented by the terms in this view and \(|0\rangle = |0...0\rangle\) is the all-zeros computational basis state.

Parameters:

rehearse – If True, only rehearse the operation to determine resource requirements. If None (default), automatically set to True for rehearsal expansions, False otherwise.
stream – A stream object from the array package, a stream pointer (int), or None to use the package’s current stream.

Returns:

A RehearsalInfo with the required workspace sizes. If rehearse=False: A tuple (trace_significand, trace_exponent) where trace = trace_significand * pow(2, trace_exponent).

Return type:

If rehearse=True

Raises:

RuntimeError – If the base expansion is a rehearsal expansion and rehearse=False.

trace_with_zero_state_backward_diff( cotangent_trace, cotangent_trace_exponent, /, cotangent_expansion: PauliExpansion | None = None, rehearse: bool | None = None, stream=None, ) → TraceBackwardRehearsalInfo | PauliExpansion[source]#

Backward pass for trace_with_zero_state().

Propagates the scalar cotangent of the trace value back to coefficient cotangents of this view.

Parameters:

cotangent_trace – Scalar cotangent \(\tilde{t} = dL/dt\) (same dtype as the expansion coefficients). Can be a Python scalar or a 1-element numpy array.
cotangent_trace_exponent – Scalar cotangent for the trace-exponent output.
cotangent_expansion – Pre-allocated PauliExpansion to receive the coefficient cotangents, or None to auto-allocate.
rehearse – If True, only the prepare phase runs (returns workspace requirements). If None (default), automatically set based on the base expansion’s rehearsal status.
stream – A stream object, stream pointer (int), or None.

Returns:

a TraceBackwardRehearsalInfo. If rehearse=False: the cotangent PauliExpansion.

Return type:

If rehearse=True

truncate( expansion_out: PauliExpansion | None = None, truncation: Truncation | None = None, rehearse: bool | None = None, stream=None, ) → RehearsalInfo | PauliExpansion[source]#

Truncates the Pauli expansion view based on the given truncation strategy and writes the result to the output expansion.

If rehearse=True, only the prepare phase is executed to determine resource requirements.

Parameters:

expansion_out – The Pauli expansion to write the truncated result to. If not provided, a new expansion will be allocated with the required capacity.
truncation – Truncation strategy to apply (optional).
rehearse – If True, only rehearse the operation. If None (default), automatically set to True for rehearsal expansions, False otherwise.
stream – A stream object from the array package, a stream pointer (int), or None to use the package’s current stream.

Returns:

A RehearsalInfo with the required resources. If rehearse=False: The output PauliExpansion.

Return type:

If rehearse=True

Raises:

RuntimeError – If the base expansion is a rehearsal expansion and rehearse=False.

Attributes

base#: The Pauli expansion that this view is based on.

end_index#: The end index (exclusive) of the view.

is_sorted#

Returns whether the underlying Pauli expansion is sorted.

Note: This reflects the sort status of the entire base expansion, not just the view’s range.

is_valid#

Whether the view is valid.

A view becomes invalid if the library performs a mutating operation on the underlyingPauli expansion after the view was created.

num_terms#: The number of terms in the Pauli expansion view.

sort_order#

Returns the sort order of the underlying Pauli expansion.

Note: This reflects the sort order of the entire base expansion, not just the view’s range.

Returns:: None, "internal", or "little_endian_bitwise".

start_index#: The start index (inclusive) of the view.

storage_location#

The storage location of the Pauli expansion view.

Returns:: Either "cpu" or "gpu". This is inherited from the base expansion.