QCANT.adapt_vqe#

QCANT.adapt_vqe(symbols: Sequence[str], geometry, *, adapt_it: int, basis: str = 'sto-6g', charge: int = 0, spin: int = 0, active_electrons: int, active_orbitals: int, device_name: str | None = None, shots: int | None = None, commutator_shots: int | None = None, commutator_mode: str = 'ansatz', commutator_debug: bool = False, hamiltonian_cutoff: float = 1e-20, hamiltonian_source: str = 'casci', pool_type: str = 'fermionic_sd', pool_sample_size: int | None = None, pool_seed: int | None = None, parallel_gradients: bool = False, parallel_backend: str = 'auto', max_workers: int | None = None, gradient_chunk_size: int | None = None, optimizer_method: str = 'BFGS', optimizer_maxiter: int = 100000000, pauli_grouping: bool = False, grouping_type: str = 'qwc', device_kwargs: Mapping[str, Any] | None = None, return_history: bool = False, iteration_callback: Callable[[Mapping[str, Any]], None] | None = None)[source]#

Run an ADAPT-style VQE loop for a user-specified molecular geometry.

The core ADAPT loop selects operators from a singles+doubles pool based on commutator magnitude, then optimizes the ansatz parameters at each iteration.

Parameters:

  • symbols – Atomic symbols, e.g. ["H", "H"].

  • geometry – Nuclear coordinates, array-like with shape (n_atoms, 3) in Angstrom.

  • adapt_it – Number of ADAPT iterations.

  • basis – Basis set name understood by PySCF (e.g. "sto-3g", "sto-6g").

  • charge – Total molecular charge.

  • spin – Spin multiplicity parameter used by PySCF as 2S (e.g. 0 for singlet).

  • active_electrons – Number of active electrons in the CASCI reference.

  • active_orbitals – Number of active orbitals in the CASCI reference.

  • shots – If provided and > 0, run with shot-based sampling on the chosen device.

  • commutator_shots – If provided, override the shot count for commutator evaluations.

  • commutator_mode – "ansatz" uses the ansatz circuit to evaluate commutators; "statevec" prepares the current statevector via qml.StatePrep before measuring.

  • commutator_debug – If True, compute both commutator modes per operator and report the maximum absolute difference per ADAPT iteration.

  • hamiltonian_cutoff – Drop Hamiltonian terms with absolute value below this cutoff when building the fermionic operator.

  • hamiltonian_source – Source Hamiltonian used for ADAPT optimization:

    • "casci" (default): CASCI-effective active-space Hamiltonian.

    • "molecular": PennyLane molecular Hamiltonian from qml.qchem.molecular_hamiltonian using the same active-space arguments as qscEOM.

  • pool_type – Operator-pool family used by ADAPT:

    • "fermionic_sd"/"sd"/"fermionic": reference SD fermionic pool with FermionicSingle/DoubleExcitation ansatz updates.

    • "qubit_excitation"/"qe"/"qubit": qubit excitation pool with Single/DoubleExcitation ansatz updates.

  • pool_sample_size – If provided, randomly sample this many operators from the pool per ADAPT iteration to reduce commutator evaluations.

  • pool_seed – Seed for the operator-pool sampler.

  • parallel_gradients – If True, evaluate candidate ADAPT commutators concurrently.

  • parallel_backend – Parallel backend used when parallel_gradients=True: "process", "thread", or "auto" (default). "auto" selects processes on POSIX and threads on Windows.

  • max_workers – Maximum number of worker threads used when parallel_gradients=True. If omitted, os.cpu_count() is used.

  • gradient_chunk_size – Number of candidate operators per submitted worker task. If omitted, a balanced chunk size based on max_workers is used.

  • optimizer_method – SciPy optimization method (e.g. "BFGS", "COBYLA", "Nelder-Mead").

  • pauli_grouping – If True, pre-compute Pauli grouping metadata (e.g. QWC) for Hamiltonian and commutator observables before shot-based measurements.

  • grouping_type – Grouping strategy passed to compute_grouping when pauli_grouping=True.

  • device_kwargs – Optional keyword arguments forwarded to qml.device. This is useful when selecting hardware/noise-model specific backends that require extra constructor parameters.

  • return_history – If True, also return a per-iteration history payload containing ADAPT selection/optimization snapshots.

  • iteration_callback – Optional callback invoked after each ADAPT iteration with a snapshot dictionary containing the selected operator index, max gradient, current energy, parameters, and excitations.

Returns:

(params, ash_excitation, energies) as produced by the optimization. If return_history=True, a fourth element is appended: history (list of iteration snapshots).

Return type:

tuple

Raises:

  • ValueError – If symbols/geometry sizes are inconsistent.

  • ImportError – If required optional dependencies are not installed.