qlass.quantum_chemistry package

The quantum_chemistry module provides tools for generating and manipulating quantum chemistry Hamiltonians for VQE algorithms to simulate molecular systems.

Key Features

Hamiltonian Generation

• LiH_hamiltonian: Generates Hamiltonians for lithium hydride molecules, a standard benchmark in quantum chemistry.

• LiH_hamiltonian_tapered: Tapered version with reduced qubit count utilizing symmetry reduction.

• Hchain_KS_hamiltonian: Generates Kohn-Sham Hamiltonians for hydrogen chains. This utilizes Density Functional Theory (DFT), specifically solving the Kohn-Sham equations [KS65] to map the electronic structure problem.

  • Returns tuple: (hamiltonian, scf_mo_energy, n_orbs)

  • Parameters: num_atoms (int), bond_length (float)

Hamiltonian Utilities

• hamiltonian_matrix: Converts Pauli string Hamiltonian to matrix form

• brute_force_minimize: Computes exact ground state energy via diagonalization (Full CI) for benchmarking.

Submodules

qlass.quantum_chemistry.Hchain_KS_hamiltonian(n_hydrogens: int = 2, R: float = 1.2) → tuple[dict[str, float], ndarray, int]

Generate the one-body Hamiltonian for a linear chain of hydrogen atoms at a given bond length.

This function constructs a non-interacting one-body Hamiltonian for a chain of hydrogen atoms using Density Functional Theory (DFT) with a closed-shell Hartree-Fock (RHF) method. The hydrogen atoms are placed linearly along the z-axis with a uniform bond length R. The resulting molecular orbitals are transformed into a qubit Hamiltonian representation.

Parameters:

• n_hydrogens (int, optional) – Number of hydrogen atoms in the linear chain. Must be an even integer. Default is 2.

• R (float, optional) – Bond length between adjacent hydrogen atoms in angstroms. Default is 1.2.

Returns:

• H_qubit_dic (dict) – Dictionary representation of the qubit Hamiltonian in terms of Pauli operators. The keys correspond to Pauli strings and the values are their coefficients.

• mo_energy (list of float) – Molecular orbital energies computed from PySCF.

• n_molecular_orbital (int) – Number of molecular orbitals.

Notes

• The electronic structure is calculated using the minimal sto-3g basis set.

• The function internally performs the following steps:

  1. Builds the molecular geometry.

  2. Runs RHF self-consistent field (SCF) calculation via PySCF.

  3. Constructs the Fock and overlap matrices in the atomic orbital (AO) basis.

  4. Transforms to an orthogonalized atomic orbital (OAO) basis.

  5. Maps the resulting Hamiltonian to a qubit representation.

• The transformation to the qubit Hamiltonian uses a helper function transformation_Hmatrix_Hqubit and a dictionary builder sparsepauliop_dictionary.

qlass.quantum_chemistry.Hchain_hamiltonian_WFT(n_hydrogens: int = 2, R: float = 0.8, charge: int = 0, spin: int = 0, num_electrons: int = 2, num_orbitals: int = 2, tampering: bool = False) → dict[str, float]

Construct the qubit Hamiltonian for a linear hydrogen chain (Hₙ) using

wavefunction-based methods.

This function builds the molecular geometry, performs a PySCF electronic structure calculation through OpenFermion, extracts an active-space molecular Hamiltonian, and maps it to a qubit Hamiltonian.

Nuclear repulsion energy is included manually. The resulting Hamiltonian is returned as a dictionary mapping Pauli strings to coefficients.

n_hydrogensint, optional

Number of hydrogen atoms in the linear chain. Must be even, as atoms are paired symmetrically about the origin. Default is 2.

Rfloat, optional

Bond length between adjacent hydrogens in ångström. Default is 0.8.

chargeint, optional

Total molecular charge. Default is 0.

spinint, optional

Spin multiplicity parameter such that multiplicity = 2S + 1. For example, spin=0 corresponds to a singlet. Default is 0.

num_electronsint, optional

Number of electrons. Default is 2.

num_orbitalsint, optional

Number of spatial molecular orbitals. Default is 2.

tampering: bool, optional

if True, symmetry-conserving Bravyi–Kitaev transformed Hamiltonian if False, Full Hamiltonian transformed using JW

Dict[str, float]

A dictionary representing the qubit Hamiltonian, where keys are Pauli strings (e.g., "XIZY") and values are real coefficients.

• Geometry is generated as a symmetric linear chain along the z-axis.

• PySCF is used to compute SCF and FCI energies through OpenFermion.

• Active-space selection freezes no core orbitals.

• If symmetry is True, the Hamiltonian is mapped to qubits using the symmetry-conserving Bravyi–Kitaev transformation else Full Hamiltonian using Jordan–Wigner mapping.

qlass.quantum_chemistry.LiH_hamiltonian(R: float = 1.5, charge: int = 0, spin: int = 0, num_electrons: int = 2, num_orbitals: int = 2) → dict[str, float]

Generate the qubit Hamiltonian for the LiH molecule at a given bond length.

This function uses OpenFermion and PySCF to compute molecular integrals, applies active space transformation, and maps to qubits via Jordan-Wigner.

Note: Nuclear repulsion energy is excluded to maintain compatibility with qiskit_nature behavior.

Parameters:

• R (float) – Bond length in Angstroms

• charge (int) – Charge of the molecule

• spin (int) – Spin of the molecule

• num_electrons (int) – Number of electrons in active space

• num_orbitals (int) – Number of molecular orbitals in active space

Returns:

Hamiltonian dictionary with Pauli string keys

Return type:

Dict[str, float]

qlass.quantum_chemistry.LiH_hamiltonian_tapered(R: float) → dict[str, float]

Generate the Hamiltonian for the LiH molecule at a given bond length using tapering technique.

This function applies active space reduction equivalent to qiskit_nature’s tapering approach, which reduces the number of qubits by removing orbitals that don’t contribute significantly to bonding.

The implementation uses specific orbital selection to mimic the behavior of ActiveSpaceTransformer with active_orbitals=[1,2,5].

Parameters:

R (float) – Bond length in Angstroms

Returns:

Hamiltonian dictionary with reduced qubit count

Return type:

Dict[str, float]

qlass.quantum_chemistry.brute_force_minimize(H: dict[str, float]) → float

Compute the minimum eigenvalue of a Hamiltonian using brute force.

Parameters:

H (Dict[str, float]) – Hamiltonian dictionary

Returns:

Minimum eigenvalue of the Hamiltonian

Return type:

float

qlass.quantum_chemistry.eig_decomp_lanczos(R: ndarray, n: int = 1, m: int = 100) → ndarray

Compute the eigenvalues of a matrix using the Lanczos algorithm.

Parameters:

• R (np.ndarray) – Matrix to compute the eigenvalues of

• n (int) – Number of eigenvalues to compute

• m (int) – Number of iterations

Returns:

Eigenvalues of the matrix

Return type:

np.ndarray

qlass.quantum_chemistry.generate_random_hamiltonian(num_qubits: int) → dict[str, float]

Generate a random Hamiltonian.

Creates a random Pauli operator by generating all possible Pauli strings for the given number of qubits and assigning random coefficients.

Parameters:

num_qubits (int) – Number of qubits

Returns:

Hamiltonian dictionary with random coefficients

Return type:

Dict[str, float]

qlass.quantum_chemistry.group_commuting_pauli_terms(hamiltonian: dict[str, float]) → list[dict[str, float]]

Group commuting Pauli terms in a Hamiltonian.

This function takes a Hamiltonian represented as a dictionary of Pauli strings and their coefficients, and returns a list of Hamiltonians where each group contains only mutually commuting Pauli terms. This grouping can be used to reduce the number of measurements needed in quantum algorithms like VQE.

This function provides a more general approach than OpenFermion’s group_into_tensor_product_basis_sets, which only groups terms that are diagonal in the same tensor product basis. Our function groups all mutually commuting terms regardless of the measurement basis required.

Parameters:

hamiltonian (Dict[str, float]) – Hamiltonian dictionary with Pauli string keys and coefficient values

Returns:

List of grouped Hamiltonians, where each group

contains mutually commuting Pauli terms

Return type:

List[Dict[str, float]]

qlass.quantum_chemistry.group_commuting_pauli_terms_openfermion_hybrid(hamiltonian: dict[str, float]) → list[dict[str, float]]

Hybrid approach that tries to use OpenFermion’s grouping when possible, fallback to our implementation otherwise.

This function attempts to leverage OpenFermion’s optimized grouping functions when they are applicable, while maintaining full compatibility with our general commuting term grouping for all other cases.

Parameters:

hamiltonian (Dict[str, float]) – Hamiltonian dictionary with Pauli string keys and coefficient values

Returns:

List of grouped Hamiltonians, where each group

contains mutually commuting Pauli terms

Return type:

List[Dict[str, float]]

qlass.quantum_chemistry.hamiltonian_matrix(H: dict[str, float]) → ndarray

Convert a Hamiltonian dictionary to a matrix representation.

Parameters:

H (Dict[str, float]) – Hamiltonian dictionary

Returns:

Matrix representation of the Hamiltonian

Return type:

np.ndarray

qlass.quantum_chemistry.lanczos(A: ndarray, v_init: ndarray, m: int) → tuple[ndarray, ndarray]

Core Lanczos algorithm implementation.

qlass.quantum_chemistry.pauli_commute(p1: str, p2: str) → bool

Check if two Pauli strings commute.

Two Pauli strings commute if and only if the number of positions where both have non-identity operators that are different is even.

Parameters:

• p1 (str) – First Pauli string

• p2 (str) – Second Pauli string

Returns:

True if the Pauli strings commute, False otherwise

Return type:

bool

Raises:

ValueError – If Pauli strings have different lengths

qlass.quantum_chemistry.pauli_string_to_matrix(pauli_string: str) → ndarray

Convert a Pauli string to a matrix representation.

Parameters:

pauli_string (str) – A string of Pauli operators (I, X, Y, Z)

Returns:

Matrix representation of the Pauli string

Return type:

np.ndarray

qlass.quantum_chemistry.sparsepauliop_dictionary(H: QubitOperator) → dict[str, float]

Converts an OpenFermion QubitOperator into a dictionary representation.

This function translates the structure of an OpenFermion QubitOperator, which represents a sum of Pauli strings, into a Python dictionary. The keys of the dictionary are string representations of Pauli operators (e.g., “IXYZ”), and the values are their corresponding real coefficients.

Parameters:

H – The OpenFermion QubitOperator to be converted. Each term in this operator is a product of Pauli operators acting on specific qubits.

Returns:

A dictionary where each key is a Pauli string (e.g., “IZX”) representing a term in the Hamiltonian, and its value is the real part of the coefficient for that term.

qlass.quantum_chemistry.transformation_Hmatrix_Hqubit(Hmatrix: ndarray, nqubits: int) → QubitOperator

Transform a Hamiltonian matrix into an OpenFermion QubitOperator representation.

This function converts a Hermitian matrix, expressed in the computational basis, into an equivalent Hamiltonian written as a sum of tensor products of Pauli operators (I, X, Y, Z). The result is an OpenFermion QubitOperator that can be used in quantum simulation frameworks.

Parameters:

• Hmatrix (np.ndarray) – A complex Hermitian matrix of shape (2**nqubits, 2**nqubits) representing the Hamiltonian in the computational basis.

• nqubits (int) – Number of qubits in the system. Determines the dimension of Hmatrix.

Returns:

H_qubit – The Hamiltonian expressed as a sum of Pauli operators with complex coefficients.

Return type:

openfermion.QubitOperator

Notes

• Each matrix element Hmatrix[i, j] is decomposed into a sum of tensor products of single-qubit projectors expressed in the Pauli basis.

• The transformation uses the following single-qubit projector identities:

  \[\]

  |0⟩⟨0| = (I + Z) / 2, |1⟩⟨1| = (I - Z) / 2, |0⟩⟨1| = (X + iY) / 2, |1⟩⟨0| = (X - iY) / 2

• Terms with negligible coefficients (magnitude < 1e-12) are ignored to improve numerical stability.

[KS65]

Walter Kohn and Lu Jeu Sham. Self-consistent equations including exchange and correlation effects. Physical review, 140(4A):A1133, 1965.