Interfaces API

PySCF/PennyLane Bridge

PySCF-PennyLane bidirectional conversion interface.

class q2m3.interfaces.pyscf_pennylane.UnifiedDensityMatrix(dm_data, source='pyscf')

Bases: object

Unified density matrix interface for quantum-classical data exchange.

Provides seamless conversion between PySCF and PennyLane representations.

Parameters:

• dm_data (np.ndarray)

• source (str)

__init__(dm_data, source='pyscf')

Initialize unified density matrix.

Parameters:

• dm_data (ndarray) – Density matrix data

• source (str) – Source format (‘pyscf’ or ‘pennylane’)

to_pennylane_observable()

Convert to PennyLane observable format.

Returns:

PennyLane Hermitian observable

Return type:

Any

from_quantum_state(quantum_state)

Update density matrix from quantum state vector.

Parameters:

quantum_state (ndarray) – Quantum state vector from QPE

Return type:

None

class q2m3.interfaces.pyscf_pennylane.PySCFPennyLaneConverter(basis='sto-3g', mapping='jordan_wigner')

Bases: object

Converter for molecular integrals and Hamiltonians between PySCF and PennyLane.

Parameters:

• basis (str)

• mapping (str)

__init__(basis='sto-3g', mapping='jordan_wigner')

Initialize converter.

Parameters:

• basis (str) – Basis set for calculations

• mapping (str) – Fermion-to-qubit mapping scheme

pyscf_to_pennylane_hamiltonian(symbols, coords, charge=0, active_electrons=None, active_orbitals=None)

Convert molecular structure to PennyLane qubit Hamiltonian.

Parameters:

• symbols (list[str]) – List of atomic symbols [‘O’, ‘H’, ‘H’, ‘H’]

• coords (ndarray) – Atomic coordinates in Angstrom, shape (n_atoms, 3) or (n_atoms*3,)

• charge (int) – Total molecular charge (default 0)

• active_electrons (int | None) – Number of active electrons for active space (optional)

• active_orbitals (int | None) – Number of active orbitals for active space (optional)

Returns:

(hamiltonian, n_qubits, hf_state)

• hamiltonian: PennyLane Hamiltonian operator

• n_qubits: Number of qubits required

• hf_state: Hartree-Fock reference state as numpy array

Return type:

tuple

Raises:

ValueError – If symbols and coords dimensions don’t match

Example

>>> converter = PySCFPennyLaneConverter()
>>> symbols = ["H", "H"]
>>> coords = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.74]])
>>> H, n_qubits, hf_state = converter.pyscf_to_pennylane_hamiltonian(
...     symbols, coords, charge=0
... )

pyscf_to_pennylane_hamiltonian_with_mm(symbols, coords, charge=0, mm_charges=None, mm_coords=None, active_electrons=None, active_orbitals=None, energy_shift=None, embedding_mode='diagonal')

Build PennyLane Hamiltonian with MM point charge embedding.

Uses a perturbative approach: 1. Get vacuum Hamiltonian from molecular_hamiltonian (correct eigenspectrum) 2. Compute MM corrections to single-electron integrals 3. Add MM correction as Pauli operators to the vacuum Hamiltonian 4. Optionally apply energy shift for QPE precision enhancement

This approach preserves the correct eigenspectrum structure from molecular_hamiltonian while adding MM electrostatic effects.

The energy_shift parameter enables “shifted QPE”, where H' = H - E_ref * I. This allows QPE to measure ΔE = E - E_ref instead of absolute energy E, enabling higher precision for detecting small energy changes (like MM effects) without phase overflow in QPE circuits.

Parameters:

• symbols (list[str]) – List of atomic symbols [‘O’, ‘H’, ‘H’, ‘H’]

• coords (ndarray) – Atomic coordinates in Angstrom, shape (n_atoms, 3)

• charge (int) – Total molecular charge

• mm_charges (ndarray | None) – MM point charges array

• mm_coords (ndarray | None) – MM charge coordinates in Angstrom, shape (n_mm, 3)

• active_electrons (int | None) – Number of active electrons

• active_orbitals (int | None) – Number of active orbitals

• energy_shift (float | None) – Reference energy to subtract from Hamiltonian (optional). If provided, the returned Hamiltonian is H' = H - E_shift * I. This enables QPE to measure ΔE with higher precision.

• embedding_mode (Literal['diagonal', 'full_oneelectron']) – MM embedding mode. "diagonal" preserves the historical Identity/Z coefficient update path. "full_oneelectron" adds the full fixed-MO one-electron perturbation as a fixed operator Hamiltonian.

Returns:

(hamiltonian, n_qubits, hf_state)

Return type:

tuple

build_qmmm_hamiltonian(qm_mol, mm_charges, mm_coords)

Build QM/MM Hamiltonian with MM embedding using classical simulation.

Parameters:

• qm_mol (Any) – PySCF molecule object

• mm_charges (ndarray) – MM region point charges

• mm_coords (ndarray) – MM charge coordinates

Returns:

Dictionary containing molecular data for QPE simulation

Return type:

dict[str, Any]

extract_molecular_orbitals(scf_result)

Extract molecular orbital coefficients from PySCF.

Parameters:

scf_result (Any) – PySCF SCF calculation result

Returns:

MO coefficient matrix

Return type:

ndarray

compute_overlap_integrals(mol)

Compute overlap integrals for Mulliken analysis.

Parameters:

mol (Any) – PySCF molecule object

Returns:

Overlap matrix

Return type:

ndarray

estimate_qpe_resources(symbols, coords, charge=0, mm_charges=None, mm_coords=None, active_electrons=None, active_orbitals=None, target_error=0.0016, embedding_mode='full_oneelectron')

Estimate EFTQC resources for QPE algorithm using PennyLane.

Uses PennyLane’s qml.estimator.DoubleFactorization to estimate quantum computing resources (Toffoli gates and logical qubits) required for Quantum Phase Estimation on molecular systems.

Supports both vacuum Hamiltonian and MM-embedded (solvated) Hamiltonian. When mm_charges/mm_coords are provided, the single-electron integrals include QM-MM electrostatic interaction terms. The default embedding_mode="full_oneelectron" preserves the historical resource-estimation behavior by adding the full fixed-MO active-space Delta h matrix. Use embedding_mode="diagonal" to request the diagonal-only compatibility row used by the current QPE coefficient path.

Parameters:

• symbols (list[str]) – List of atomic symbols (e.g., [‘O’, ‘H’, ‘H’, ‘H’])

• coords (ndarray) – Atomic coordinates in Angstrom, shape (n_atoms, 3)

• charge (int) – Total molecular charge (default: 0 for neutral)

• mm_charges (ndarray | None) – MM point charges array (optional, for solvated Hamiltonian)

• mm_coords (ndarray | None) – MM charge coordinates in Angstrom, shape (n_mm, 3)

• active_electrons (int | None) – Number of electrons in active space (optional)

• active_orbitals (int | None) – Number of spatial orbitals in active space (optional)

• target_error (float) – Target energy error in Hartree (default: 0.0016 = 1 kcal/mol)

• embedding_mode (Literal['diagonal', 'full_oneelectron']) – MM embedding mode for resource rows. "full_oneelectron" adds the full active-space perturbation; "diagonal" adds only its diagonal. Ignored when no MM charges are provided, but still validated.

Returns:

• logical_qubits: Number of logical qubits for EFTQC

• toffoli_gates: Toffoli gate count (non-Clifford gates)

• hamiltonian_1norm: Lambda (1-norm of Hamiltonian) in Hartree

• qpe_iterations: Estimated QPE iterations (= ceil(λ/ε))

• trotter_steps: Recommended Trotter steps (heuristic: 10 × n_orbitals)

• target_error: Target error in Hartree

• n_electrons: Number of electrons in the system

• n_orbitals: Number of spatial orbitals

• basis: Basis set used

• mm_embedded: Whether MM embedding was applied

• n_mm_charges: Number of MM point charges (0 if vacuum)

• active_electrons: Active-space electron count passed to the estimator

• active_orbitals: Active-space orbital count passed to the estimator

• embedding_mode: Effective embedding state (“none” for vacuum)

• requested_embedding_mode: Requested MM mode, or None for vacuum

• fixed_mo: Whether a fixed-MO MM perturbation was used

• two_electron_tensor_fixed: Whether the two-electron tensor is vacuum

• active_indices: Vacuum MO indices included in the active space

• delta_h_* diagnostics for the MM one-electron perturbation

Return type:

Dictionary containing

Raises:

ValueError – If coords shape does not match number of symbols

Example

>>> converter = PySCFPennyLaneConverter()
>>> symbols = ['H', 'H']
>>> coords = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.74]])
>>> # Vacuum Hamiltonian
>>> result = converter.estimate_qpe_resources(symbols, coords)
>>> # Solvated Hamiltonian with MM charges
>>> mm_charges = np.array([-0.834, 0.417, 0.417])
>>> mm_coords = np.array([[3.0, 0.0, 0.0], [3.5, 0.8, 0.0], [3.5, -0.8, 0.0]])
>>> result_mm = converter.estimate_qpe_resources(
...     symbols, coords, mm_charges=mm_charges, mm_coords=mm_coords
... )