PauliExpansion#

class cuquantum.pauliprop.experimental.PauliExpansion( library_handle: LibraryHandle, num_qubits: int, num_terms: int, xz_bits, coeffs, sort_order: SortOrder | None | Literal['internal', 'little_endian_bitwise'] = None, has_duplicates: bool = True, *, options: PauliExpansionOptions | dict | None = None, )[source]#

A Pauli operator expansion.

This is a container for a set of Pauli strings and their coefficients, to which quantum operators can be applied.

Parameters:

library_handle – The library handle.
num_qubits – The number of qubits.
num_terms – The number of terms.
xz_bits – The XZ bits buffer.
coeffs – The coefficients buffer.
sort_order – The sort order of the expansion (None, "internal", or "little_endian_bitwise").
has_duplicates – Whether the expansion may contain duplicate Pauli strings.
options – Either a PauliExpansionOptions object or a dict with matching keywords (allocator, memory_limit, blocking).

Methods

__init__( library_handle: LibraryHandle, num_qubits: int, num_terms: int, xz_bits, coeffs, sort_order: SortOrder | None | Literal['internal', 'little_endian_bitwise'] = None, has_duplicates: bool = True, *, options: PauliExpansionOptions | dict | None = 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 (out-of-place).

This operation does not modify the input expansion; the result is written to a new or provided output expansion.

This is a convenience method that creates a default view covering all terms and delegates to PauliExpansionView.apply_gate().

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

Deduplicates the Pauli expansion (out-of-place).

Removes duplicate Pauli strings and sums their coefficients. This operation does not modify the input expansion; the result is written to a new or provided output expansion.

This is a convenience method that creates a default view covering all terms and delegates to PauliExpansionView.deduplicate().

Note: The expansion must be sorted before calling this method.

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

classmethod empty( library_handle: LibraryHandle, num_qubits: int, num_terms: int, dtype: str = 'complex128', sort_order: SortOrder | None | Literal['internal', 'little_endian_bitwise'] = None, has_duplicates: bool = True, *, options: PauliExpansionOptions | dict | None = None, ) → PauliExpansion[source]#

Create a rehearsal-only expansion for determining resource requirements.

This expansion cannot be used for actual computation. All compute methods will raise an error if rehearse=False. To execute operations, create a normal (non-rehearsal) expansion using from_empty() on the rehearsal object.

Parameters:

library_handle – The library handle.
num_qubits – The number of qubits.
num_terms – The number of terms (used for rehearsal calculations).
dtype – The data type for coefficients (defaults to “complex128”).
sort_order – The sort order of the expansion (defaults to None).
has_duplicates – Whether the expansion may contain duplicate Pauli strings (defaults to True).
options – Either a PauliExpansionOptions object or a dict with matching keywords.

Returns:

A rehearsal-only PauliExpansion instance.

from_empty( xz_bits, coefs, num_terms: int = 0, sort_order: SortOrder | None | Literal['internal', 'little_endian_bitwise'] = None, has_duplicates: bool | None = None, *, options: PauliExpansionOptions | dict | None = None, ) → PauliExpansion[source]#

Create a PauliExpansion backed by user-provided (preallocated) buffers.

This is an out-of-place conversion from a rehearsal-only expansion to a normal (non-rehearsal) expansion backed by real buffers.

Parameters:

xz_bits – The XZ bits buffer.
coefs – The coefficient buffer.
num_terms – The initial number of valid terms (defaults to 0).
sort_order – The sort order of the expansion (defaults to the rehearsal expansion’s sort_order).
has_duplicates – Whether the expansion may contain duplicate Pauli strings (defaults to the rehearsal expansion’s value).
options – Either a PauliExpansionOptions object or a dict with matching keywords. If not provided, uses the original options passed to empty() (which may be None or partial). The constructor then derives any unset defaults (e.g., allocator) from the provided buffers.

Returns:

A non-rehearsal PauliExpansion instance.

populate_from( other: PauliExpansion | PauliExpansionView, stream=None, ) → None[source]#

Write coefficients and xzbits from another Pauli expansion to this Pauli expansion or Pauli expansion view. This will reset the number of valid terms to the number of terms in the other Pauli expansion or Pauli expansion view.

Raises:: RuntimeError – If this expansion is a rehearsal expansion.

product_trace( other: PauliExpansion | 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) with another Pauli expansion.

This is a convenience method that creates default views covering all terms and delegates to PauliExpansionView.product_trace().

Parameters:

other – The other Pauli expansion (or view) to compute the product trace with.
adjoint – If True, computes Tr(self^† * other). If False, computes Tr(self * other). 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 trace value (scalar). Type matches the data type of the expansions.

Return type:

If rehearse=True

Sorts the Pauli expansion by the specified sorting order (out-of-place).

This operation does not modify the input expansion; the result is written to a new or provided output expansion.

This is a convenience method that creates a default view covering all terms and delegates to PauliExpansionView.sort().

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

to( device: Literal['cpu', 'gpu'], package: Literal['cupy', 'torch', 'cuda'], stream=None, *, options: PauliExpansionOptions | dict | None = None, ) → PauliExpansion[source]#

Copy the Pauli expansion to the specified device.

Parameters:

device – Target device. Use "cpu" for host memory, or the library handle’s current GPU ("gpu").
package – Array package to use for the target tensors. Must be one of "cupy", "torch", "numpy" or "cuda". Note that “cuda” and "cupy" are only valid for transfers to GPU, while "numpy" is only valid for transfers to CPU.
stream – Optional stream (package stream object or pointer) to use for the transfer when copying from host to device. Ignored for host-to-host copies.

Returns:

A PauliExpansion on the requested location. If already on that location, the current object is returned; otherwise a new PauliExpansion is created on host or on the handle’s device. Transfers between different GPU devices are not supported.

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

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

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

This is a convenience method that creates a default view covering all terms and delegates to PauliExpansionView.trace_with_zero_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 expansion.

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 based on the given truncation strategy (out-of-place).

This operation does not modify the input expansion; the result is written to a new or provided output expansion.

This is a convenience method that creates a default view covering all terms and delegates to PauliExpansionView.truncate().

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

valid_xz_bits()[source]#: A view on the XZ bits buffer that only contains the valid terms.

view( start_index: int = 0, end_index: int = None, *, options: PauliExpansionOptions | dict | None = None, ) → PauliExpansionView[source]#

Creates a non-owning view on a contiguous range of Pauli terms inside a Pauli operator expansion.

Parameters:

start_index – The start index of the view (inclusive). If not specified, the view will start at the beginning of the Pauli expansion.
end_index – The end index of the view (exclusive, one past the last element). If not specified, the view will end at the end of the currently valid terms in the Pauli expansion.

Returns:

A view on a contiguous range of Pauli terms inside a Pauli operator expansion. The view covers the range [start_index, end_index).

Attributes

capacity#: The maximum number of terms that the Pauli expansion can accommodate.

coeffs#: The coefficient buffer.

dtype#: Returns the data type of the coefficients.

has_duplicates#

Returns whether the Pauli expansion may contain duplicate Pauli strings.

After calling deduplicate(), this will return False.

is_rehearsal#

Whether this is a rehearsal-only expansion (created via empty()).

A rehearsal expansion can only be used with rehearse=True. To execute operations, create a normal (non-rehearsal) expansion using from_empty().

is_sorted#: Returns whether the Pauli expansion is sorted (any sort order).

num_qubits#: The number of qubits for this Pauli expansion.

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

package#: The backend package for this Pauli expansion, inferred from the expansion’s tensor type, e.g. “numpy”, “cupy”, “torch”, or “cuda”.

sort_order#

Returns the sort order of the Pauli expansion.

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

storage_location#: The storage location of the Pauli expansion.

valid_coeffs#: A view on the coefficients buffer that only contains the valid terms.

xz_bits#: The XZ bits buffer.