QCANT.tepid_adapt#

QCANT.tepid_adapt(symbols: Sequence[str], geometry, *, adapt_it: int, temperature: float | None = None, beta: float | None = None, basis: str = 'sto-3g', charge: int = 0, spin: int = 0, active_electrons: int, active_orbitals: int, shots: int = 0, hamiltonian_cutoff: float = 1e-20, hamiltonian_source: str = 'molecular', pool_type: str = 'fermionic_sd', include_identity: bool = True, basis_occupations=None, pool_sample_size: int | None = None, pool_seed: int | None = None, gradient_eps: float = 1e-07, gradient_tol: float | None = None, optimizer_method: str = 'BFGS', optimizer_maxiter: int = 200, return_details: bool = False, iteration_callback: Callable[[Mapping[str, Any]], None] | None = None)[source]#

Run the ancilla-free TEPID-ADAPT workflow on a molecule.

Parameters:

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

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

  • adapt_it – Maximum number of TEPID-ADAPT iterations.

  • temperature – Positive temperature in the same energy units as the Hamiltonian with k_B = 1. Exactly one of temperature or beta must be given.

  • beta – Positive inverse temperature. Exactly one of temperature or beta must be given.

  • basis – Basis set name understood by PySCF / PennyLane.

  • charge – Total molecular charge.

  • spin – Spin parameter used by PySCF as 2S.

  • active_electrons – Number of active electrons in the chosen active space.

  • active_orbitals – Number of active spatial orbitals in the active space.

  • shots – Analytic-only placeholder for API symmetry. Must be 0.

  • hamiltonian_cutoff – Drop Hamiltonian terms below this absolute coefficient threshold when building the CASCI effective Hamiltonian.

  • hamiltonian_source – "molecular" (default) uses qml.qchem.molecular_hamiltonian(); "casci" uses the CASCI-effective active-space Hamiltonian.

  • pool_type – Operator-pool family used by the adaptive ansatz: "fermionic_sd"/"sd"/"fermionic" or "qubit_excitation"/"qe"/"qubit".

  • include_identity – If True (default), prepend the Hartree-Fock reference to the truncated computational basis before the single/double excitations.

  • basis_occupations – Optional custom occupation configurations. When omitted, the truncated basis defaults to HF + singles + doubles, matching qscEOM’s basis construction.

  • pool_sample_size – If provided, randomly sample this many operators from the pool per adaptive iteration.

  • pool_seed – Seed for the operator-pool sampler.

  • gradient_eps – Finite-difference step used to build candidate gate derivatives at zero.

  • gradient_tol – Optional stopping threshold for the absolute free-energy gradient score.

  • optimizer_method – SciPy optimization method for the variational parameters.

  • optimizer_maxiter – Maximum SciPy iterations for the ansatz re-optimization after each adaptive selection.

  • return_details – If True, append a details dictionary containing the final truncated energies, thermal weights, basis metadata, and full iteration history.

  • iteration_callback – Optional callback invoked after each adaptive iteration with a snapshot dictionary.

Returns:

(params, ash_excitation, free_energies). When return_details=True, a fourth item is appended: details.

Return type:

tuple

Notes

This implementation uses the ancilla-free ensemble objective from the TEPID paper’s Appendix C. The thermal weights are updated analytically from the current transformed-basis energies at each objective evaluation.