ofex.linalg

This module provides utilities for sparse matrix operations and exponential operations on Pauli matrices.

The module includes: - sparse_tools: Tools and operations for sparse matrix manipulations. - pauli_expm: Functions for computing the matrix exponential of Pauli operators.

ofex.linalg.pauli_expm

This module provides functionality for computing the matrix exponential of Pauli operators.

It supports both single-term Pauli operators and reflective operators, enabling efficient generation of exponential matrix representations for use in quantum computing.

Functions included: - single_pauli_expm: Computes the exponential of a single Pauli operator. - reflective_pauli_expm: Efficiently computes the exponential of reflective Pauli operators.

ofex.linalg.pauli_expm.single_pauli_expm(pauli: QubitOperator, n_qubits: int | None = None) → spmatrix

Compute the exponential of a single Pauli operator.

This function generates the matrix representation of exp(pauli) for a given single-term Pauli operator expressed as a QubitOperator.

Parameters:

• pauli (QubitOperator) – A single-term QubitOperator representing the Pauli operator.

• n_qubits (Optional[int]) – The number of qubits in the system. If not specified, the number of qubits is inferred from the operator.

Returns:

A sparse matrix representing the exponential of the given Pauli operator.

Return type:

spmatrix

Raises:

ValueError – If the number of qubits specified is invalid or if the operator contains more than one term.

ofex.linalg.pauli_expm.reflective_pauli_expm(pauli: QubitOperator, n_qubits: int | None = None, check_reflective: bool = True) → spmatrix

Compute the exponential of reflective qubit operator efficiently.

This function generates the matrix representation of exp(pauli) for a given Pauli operator, under the assumption that the operator is reflective (i.e., the square of the operator is constant). For example, a sum of mutually anti-commuting Pauli operators or an LCU-fragment is reflective. The exponential of a reflective operator can be computed efficiently.

Parameters:

• pauli (QubitOperator) – The operator for which the exponential is to be calculated.

• n_qubits (Optional[int]) – The number of qubits in the system. If not specified, the number of qubits is inferred from the operator.

• check_reflective (bool) – Whether to validate that the operator is reflective. Set to False to bypass this validation.

Returns:

A sparse matrix representing the exponential of the given Pauli operator.

Return type:

spmatrix

Raises:

ValueError – If the number of qubits specified is invalid or if the operator is not reflective when check_reflective is True.

ofex.linalg.sparse_tools

This module provides utilities and functions for handling quantum state operations and sparse matrix computations. Key functionalities include quantum state transitions, expectation value calculations, operator applications, diagonalization of operators, and state manipulation in both dense and sparse formats.

The primary goal of this module is to enhance the efficiency and scalability of quantum operator applications and computations by leveraging sparse representations where applicable.

Definitions:

• State: Representations of quantum states using formats like numpy arrays, sparse matrices, or dictionaries as supported by ofex.state.types.

• Operator: Quantum operators applied to states, supporting formats like QubitOperator, scipy sparse matrices, or LinearOperators.

ofex.linalg.sparse_tools.transition_amplitude(operator: QubitOperator | spmatrix | LinearOperator, state1: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, state2: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, sparse1: bool = False, sparse2: bool = False) → complex

Compute the transitional amplitude, <φ1|O|φ2>.

Parameters:

• operator – The operator to apply, which can be a QubitOperator, a scipy sparse matrix, or a scipy LinearOperator.

• state1 – A quantum state supported as defined in ofex.state.types (e.g., a numpy array, sparse matrix, or dict).

• state2 – A second quantum state in the same format as state1. If set to None, the expectation value of state1 is calculated instead.

• sparse1 – A boolean indicating whether to perform sparse operations for state1.

• sparse2 – A boolean indicating whether to perform sparse operations for state2.

Returns:

A complex number representing the transitional amplitude between the two states.

ofex.linalg.sparse_tools.expectation(operator: QubitOperator | spmatrix | LinearOperator, state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, sparse: bool = False) → complex

Compute the expectation value <φ|O|φ>.

Parameters:

• operator – The operator for which the expectation value is calculated. This can be a QubitOperator, a scipy sparse matrix, or a LinearOperator.

• state – A quantum state supported as defined in ofex.state.types (e.g., a numpy array, sparse matrix, or dict).

• sparse – A boolean indicating whether to perform sparse operations for state.

Returns:

A complex number representing the expectation value of the operator for the given state.

ofex.linalg.sparse_tools.apply_operator(operator: QubitOperator | spmatrix | LinearOperator, state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → ndarray | Dict[BinaryFockVector, Number] | lil_matrix

Apply a given operator to a quantum state.

Parameters:

• operator – The operator to apply, which can be a QubitOperator, scipy sparse matrix, or a LinearOperator.

• state – A quantum state supported as defined in ofex.state.types (e.g., a numpy array, sparse matrix, or dict).

Returns:

The resulting quantum state after applying the operator, preserving the input type. If the state is zero, it returns the same state without modification.

ofex.linalg.sparse_tools.diagonalization(operator: QubitOperator | FermionOperator, n_qubits: int, sparse_eig: bool, n_eigen: int | None = None, **kwargs) → Tuple[ndarray, ndarray] | ndarray

Compute the eigenvalues and eigenvectors of an operator.

Parameters:

• operator – QubitOperator or FermionOperator to be diagonalized.

• n_qubits – The number of qubits represented in the operator.

• sparse_eig – A boolean value indicating whether to compute eigenvalues for a sparse operator representation.

• n_eigen – The number of eigenvalues/vectors to calculate if sparse_eig is True. Defaults to None, indicating all eigenvalues/vectors.

• **kwargs – Additional arguments to be passed to the scipy eigensolver.

Returns:

If sparse_eig is True, returns a tuple (eigenvalues, eigenvectors) for the sparse representation. Otherwise, returns a dense numpy array of eigenvalues and eigenvectors.

ofex.linalg.sparse_tools.sparse_apply_operator(operator: QubitOperator, state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → ndarray | Dict[BinaryFockVector, Number] | lil_matrix

Apply a QubitOperator to a state using sparse representations.

Parameters:

• operator – The QubitOperator to apply.

• state – The quantum state to which the operator will be applied. This can be specified in sparse or dense format.

Returns:

The resulting state after applying the operator, preserving the original state format.

ofex.linalg.sparse_tools.state_dot(state_1: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, state_2: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → complex

Compute the Hermitian dot product <state_1|state_2> between two quantum states.

Parameters:

• state_1 (State) – The first quantum state, which can be in any supported format defined in ofex.state.types (e.g., numpy array, scipy sparse matrix, or dict).

• state_2 (State) – The second quantum state in the computation, in the same formats supported as state_1.

Returns:

A complex number representing the Hermitian dot product of state_1 and state_2. If either state represents a “zero” state, the result will be zero.

ofex.linalg.sparse_tools.collect_degen_eigspace_hierarchy(eig_values: ndarray, eig_vectors: ndarray, degen_tol: float = 1e-08) → Dict[complex, ndarray]

Group eigenvalues and their corresponding eigenvectors into degenerate eigenspaces based on hierarchical clustering.

This function uses hierarchical clustering to group eigenvalues that are considered degenerate (close in value within a defined tolerance) and collects the corresponding eigenvectors into subspaces.

Parameters:

• eig_values (np.ndarray) – A 1D numpy array containing eigenvalues.

• eig_vectors (np.ndarray) – A 2D numpy array containing eigenvectors as columns, corresponding to the eigenvalues in eig_values.

• degen_tol (float) – A float defining the maximum allowable distance between eigenvalues to consider them degenerate. Defaults to 1e-8.

Returns:

A dictionary where each key is a representative eigenvalue (the first one in each cluster), and the value is a 2D numpy array containing the eigenvectors (columns) associated with the degenerate eigenspace.