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.

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 | float | complex[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: The trace value (scalar). Type matches the data type of the views.

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.

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 | float | complex[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: The trace value (scalar). Type matches the data type of the view.

Return type:

If rehearse=True

Raises:

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

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.