GPU Extensions (Experimental)

The _ext subpackage provides experimental GPU-accelerated backends. These modules are optional and do not affect core functionality if their external dependencies are unavailable.

sbd Subprocess

GPU-native Selected Basis Diagonalisation via the external sbd binary (r-ccs-cms/sbd). Requires a compiled sbd binary and MPI runtime.

qvartools._ext.sbd_subprocess.sbd_available()[source]

Check if sbd binary and mpirun are both available.

Return type:

bool

qvartools._ext.sbd_subprocess.sbd_diagonalize(h1e, h2e, n_orb, n_elec, nuclear_repulsion, alpha_strings, beta_strings, *, ms2=0, tolerance=1e-08, max_iterations=50, n_threads=4, timeout=600)[source]

Run sbd diagonalization via subprocess.

Parameters:

  • h1e (np.ndarray) – One-electron integrals, shape (n_orb, n_orb).

  • h2e (np.ndarray) – Two-electron integrals, shape (n_orb, n_orb, n_orb, n_orb).

  • n_orb (int) – Number of spatial orbitals.

  • n_elec (int) – Total number of electrons.

  • nuclear_repulsion (float) – Nuclear repulsion energy.

  • alpha_strings (torch.Tensor) – Unique alpha occupation strings, shape (n_alpha, n_orb).

  • beta_strings (torch.Tensor) – Unique beta occupation strings, shape (n_beta, n_orb).

  • ms2 (int, optional) – Twice the spin projection (default 0 for singlet).

  • tolerance (float, optional) – Davidson convergence tolerance.

  • max_iterations (int, optional) – Maximum Davidson iterations.

  • n_threads (int, optional) – Number of OpenMP threads per MPI rank (default 4). Passed via mpirun -x OMP_NUM_THREADS. The subprocess runs with a single MPI rank (-np 1).

  • timeout (int, optional) – Subprocess timeout in seconds (default 600).

Returns:

Ground state energy (electronic + nuclear repulsion).

Return type:

float

Raises:

  • ValueError – If integral shapes are inconsistent with n_orb, or if alpha_strings/beta_strings have wrong rank or column count.

  • RuntimeError – If the sbd binary or mpirun is not found, the subprocess fails, or the energy cannot be parsed from the output.

CUDA-QX VQE

VQE and ADAPT-VQE pipeline wrapper using CUDA-QX Solvers. Requires CUDA-Q >= 0.14 and CUDA-QX Solvers >= 0.5.

qvartools._ext.cudaq_vqe.run_cudaq_vqe(geometry, basis='sto-3g', charge=0, spin=0, method='vqe', optimizer='cobyla', max_iterations=200, target='nvidia', nele_cas=None, norb_cas=None, gate_fusion=4, verbose=False)[source]

Run VQE or ADAPT-VQE using CUDA-QX Solvers on GPU.

Parameters:

  • geometry (list of (str, (float, float, float))) – Molecular geometry in Angstroms.

  • basis (str) – Gaussian basis set (default "sto-3g").

  • charge (int) – Net charge (default 0).

  • spin (int) – Number of unpaired electrons, i.e. 2S (default 0 for singlet). This matches PySCF convention: 0 = singlet, 1 = doublet, 2 = triplet.

  • method (str) – "vqe" for VQE-UCCSD or "adapt-vqe" for ADAPT-VQE.

  • optimizer (str) – Optimizer name (default "cobyla"). Applied to both VQE and ADAPT-VQE.

  • max_iterations (int) – Maximum optimizer iterations.

  • target (str) – CUDA-Q simulator target (default "nvidia" for GPU). Use "qpp-cpu" for CPU-only environments.

  • nele_cas (int or None, optional) – Number of active-space electrons. If None (default), all electrons are included. Setting this reduces qubit count and speeds up computation for large molecules.

  • norb_cas (int or None, optional) – Number of active-space orbitals. If None (default), all orbitals are included. Must be set together with nele_cas.

  • gate_fusion (int) – Maximum qubit count for gate fusion optimization (default 4). CUDA-Q combines consecutive gates involving up to this many qubits into a single matrix operation. Set 0 to disable.

  • verbose (bool) – Print progress.

Returns:

energy : float — final VQE/ADAPT-VQE energy (Ha). fci_energy : float or None — CASCI FCI reference. hf_energy : float or None — Hartree-Fock reference. error_mha : float or None — error vs FCI (mHa). wall_time : float — wall-clock time (s). n_params : int — number of optimized parameters. iterations : int — optimizer iterations. method : str — "vqe" or "adapt-vqe". n_qubits : int — problem qubit count. n_electrons : int — active-space electron count. optimal_parameters : list[float] — optimal variational params.

Return type:

dict

Raises:

  • ValueError – If method is not "vqe" or "adapt-vqe".

  • RuntimeError – If VQE fails to converge (energy is NaN or inf).

Notes

fci_energy is the CASCI FCI energy within the active space, not the full-space FCI. For small molecules with minimal basis (e.g. H2/sto-3g), the active space equals the full space.