qscEOM#

QCANT provides a qscEOM routine exposed as QCANT.qscEOM().

What it does#

At a high level, the routine:

  • builds a molecular Hamiltonian using PennyLane’s quantum chemistry tooling,

  • evaluates diagonal and off-diagonal matrix elements for a set of configurations,

  • forms an effective matrix, and

  • returns its eigenvalues (sorted).

Dependencies#

This function requires scientific Python dependencies that are installed with QCANT.

If you are developing from source and see ImportError, install the required dependencies (see below).

Minimum expected dependencies:

pip install numpy
pip install pennylane

PennyLane’s quantum chemistry features often require additional packages (e.g. PySCF). If you see runtime errors during Hamiltonian construction, install:

pip install pyscf

Basic usage#

import numpy as np
import QCANT

symbols = ["H", "H"]
geometry = np.array(
    [
        [0.0, 0.0, 0.0],
        [0.0, 0.0, 0.74],
    ]
)

active_electrons = 2
active_orbitals = 2
charge = 0

# These are typically obtained from a separate ansatz/VQE routine.
params = np.array([0.0])
ash_excitation = [[0, 1]]

values = QCANT.qscEOM(
    symbols=symbols,
    geometry=geometry,
    active_electrons=active_electrons,
    active_orbitals=active_orbitals,
    charge=charge,
    params=params,
    ash_excitation=ash_excitation,
    basis="sto-3g",
    method="pyscf",
    shots=0,
)

print(values)

Parallel matrix construction#

qscEOM matrix elements are independent once the ansatz is fixed. QCANT now supports optional concurrent construction of diagonal/off-diagonal elements:

values = QCANT.qscEOM(
    symbols=symbols,
    geometry=geometry,
    active_electrons=active_electrons,
    active_orbitals=active_orbitals,
    charge=charge,
    params=params,
    ash_excitation=ash_excitation,
    basis="sto-3g",
    method="pyscf",
    shots=0,
    parallel_matrix=True,
    parallel_backend="process",  # process|thread|auto
    max_workers=4,        # optional; defaults to os.cpu_count()
    matrix_chunk_size=16, # optional task granularity control
)

Notes:

  • symmetric=True remains the recommended default to avoid redundant off-diagonal evaluations.

  • Parallel mode preserves the same matrix/eigenvalue definitions as serial mode.

  • No additional package is required for this parallel mode; it uses Python’s standard-library concurrent.futures.

  • In restricted environments where process pools are unavailable, QCANT automatically falls back to thread-based execution.

  • For tuning guidance, see Parallelization Guide.

Inputs#

A few practical notes:

  • geometry is expected to be array-like with shape (n_atoms, 3).

  • params and ash_excitation must be consistent with each other: the number of parameters must match the number of excitations.

  • include_identity=True by default, so the qscEOM basis is the standard I + singles + doubles projected space.

  • For ADAPT runs built from the QE pool, qscEOM can replay the ansatz using ansatz_type="qubit_excitation" (or automatically when using ansatz=(params, ash_excitation, energies) returned by QCANT.adapt_vqe).

  • The same ansatz=(params, ash_excitation, history) handoff also works for QCANT.tepid_adapt because it returns the same ansatz/excitation structure.

Notes#

  • This implementation is currently targeted at research experimentation.

  • For reproducible results, keep shots=0 (analytic mode) where possible.