API reference#

PauliWord#

class quantlop.PauliWord(coeff, string)#

Represent a weighted tensor product of single-qubit Pauli operators

\[P = c\,\bigotimes_i \sigma_i\]

where \(c\) is a complex coeff and each \(\sigma_i\) is a single-qubit Pauli operator applied to qubit \(i\). The leftmost character of string acts on the most-significant qubit in the computational-basis index. For example, "XII" represents \(X \otimes I \otimes I\) and maps \(|000\rangle\) to \(|100\rangle\).

Parameters:

  • coeff (complex) – Scalar complex coefficient of the Pauli word.

  • string (str) – Non-empty string of single-qubit Pauli operators. Each character should be one of "I", "X", "Y", or "Z". Its length determines the total number of qubits.

Variables:

  • num_qubits (int) – Number of qubits in the Pauli word.

  • coeff (complex) – Coefficient supplied at construction.

  • string (str) – Pauli string supplied at construction.

Hamiltonian#

class quantlop.Hamiltonian(pwords)#

Represent a qubit Hamiltonian expressed as a sum of PauliWord terms

\[H = \sum_k c_k P_k\]

This representation lets quantlop.evolve() apply the unitary evolution generated by \(H\) to a state vector \(|\psi\rangle\) without materializing the Hamiltonian matrix.

Parameters:

pwords (sequence of PauliWord) – Non-empty collection of Pauli terms. All words must act on the same number of qubits. The evolution algorithm assumes their sum is Hermitian.

Variables:

  • num_qubits (int) – Number of qubits of the Hamiltonian.

  • num_terms (int) – Number of Pauli words in the sum.

classmethod from_pennylane(operator, num_qubits)#

Construct a Hamiltonian from a PennyLane Pauli operator.

Parameters:

  • operator (pennylane.operation.Operator) – PennyLane operator with a defined pauli_rep. Its wire labels must be integer indices in range(num_qubits).

  • num_qubits (int) – Total number of qubits in the returned Hamiltonian. This can be larger than the number of wires used by the PennyLane operator.

Returns:

Native Hamiltonian with one term per entry in the PennyLane Pauli representation.

Return type:

Hamiltonian

classmethod from_qiskit(operator)#

Construct a Hamiltonian from a Qiskit SparsePauliOp.

Parameters:

operator (qiskit.quantum_info.SparsePauliOp) – Qiskit sparse Pauli operator. All labels are expected to have the same width.

Returns:

Native Hamiltonian with the input terms and coefficients.

Return type:

Hamiltonian

matrix()#

Return the dense matrix representation of the Hamiltonian.

The matrix is assembled as a sum of tensor products. Characters are processed from left to right, so the first character in each Pauli word is the leftmost most-significant tensor factor.

Returns:

Complex array representing the dense Hamiltonian matrix.

Return type:

numpy.ndarray

Notes

This method requires \(O(4^n)\) memory where \(n\) is the number of qubits. It is intended for inspection and validation on small systems only.

evolve#

quantlop.evolve(ham, psi, theta=1, num_threads=None)#

Apply the unitary evolution generated by the Hamiltonian to a dense state vector

\[|\psi(\theta)\rangle = e^{-i \theta H}|\psi\rangle\]

The implementation applies Pauli terms directly on the dense vector of amplitudes and never constructs the dense Hamiltonian or its exponential.

Parameters:

  • ham (Hamiltonian) – Pauli-sum quantlop Hamiltonian. The algorithm assumes that the operator is Hermitian.

  • psi (array_like) – Nonzero one-dimensional input state vector.

  • theta (float, optional) – Real parameter in the exponential. The default is 1.

  • num_threads (int or "auto" or None, optional) – OpenMP thread selection for Hamiltonian-vector products. None selects the serial implementation. A positive integer requests that many threads. "auto" requests the logical CPU count reported by the operating system. The default is None.

Returns:

Evolved state represented by a dense vector of amplitudes with the same one-dimensional shape as the input.

Return type:

numpy.ndarray

Notes

The Krylov subspace dimension is capped internally, so the result is a numerical approximation to the matrix-exponential action. For a Hermitian Hamiltonian and real theta, the exact operation is unitary and preserves the state norm up to numerical error.

num_threads only affects the native Hamiltonian-vector products implemented in C++. Whether multiple threads improve runtime depends on the system size, number of terms, and OpenMP runtime.

Examples

Evolve the input state \(|0\rangle\) under the Pauli-\(X\) Hamiltonian:

import numpy as np
import quantlop as ql

ham = ql.Hamiltonian([ql.PauliWord(1.0, "X")])
psi = np.array([1.0, 0.0])
out = ql.evolve(ham, psi, theta=np.pi / 2)

Use all logical CPUs reported by the operating system:

out = ql.evolve(ham, psi, theta=0.1, num_threads="auto")