GCIM (Generalized Configuration Interaction Method)#

QCANT provides GCIM via QCANT.gcim.gcim().

What it does#

The GCIM routine:

  • builds the active-space electronic Hamiltonian from PySCF/CASCI integrals,

  • constructs an anti-Hermitian operator pool (sd, singlet_sd, or gsd),

  • selects one operator per iteration using commutator magnitude,

  • builds a non-orthogonal state basis from cumulative and individual states, and

  • solves a projected generalized eigenvalue problem to estimate the ground-state energy at each iteration.

The public API is intentionally aligned with QCANT.adapt_vqe() so users can switch workflows with minimal code changes.

Basic usage#

import numpy as np
from QCANT.gcim import gcim

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

params, excitations, energies = gcim(
   symbols=symbols,
   geometry=geometry,
   adapt_it=50,  # kept for API compatibility; ignored in GCIM
   basis="sto-3g",
   charge=0,
   spin=0,
   active_electrons=2,
   active_orbitals=2,
   pool_type="sd",
   device_name="default.qubit",
)

print(len(excitations))
print(energies[-1])

Key options#

  • theta: fixed angle in exp(theta * A / 2) (default pi/4).

  • pool_sample_size/pool_seed: random operator-pool subsampling.

  • pool_type: operator pool construction strategy:

    • "sd": reference-based singles+doubles pool,

    • "singlet_sd": complete spin-adapted singles+doubles pool (closed-shell active spaces),

    • "gsd": generalized spin-conserving singles+doubles pool.

  • regularization: overlap-matrix diagonal regularization before solving M c = S c E.

  • return_details: return debug artifacts (state basis, projected matrices).

Complete SingletSD pool#

For o occupied and v virtual spatial orbitals, singlet_sd contains o*v singles and C(o+1,2)*C(v+1,2) + C(o,2)*C(v,2) doubles. Both double channels commute with total spin; the triplet-pair contraction is a spin scalar, not a triplet-state ansatz. CAS(6e,6o) therefore has 9 singles + 45 doubles = 54 operators. CAS(4e,4o), CAS(8e,6o), and CAS(10e,8o) have 14, 44, and 135.

Every generator is normalized to unit Euclidean norm of its normal-ordered fermionic coefficients, following the original SingletSD GCIM construction. This corrects the former paired-only implementation (18 operators for CAS(6e,6o)), which also left its coefficients unnormalized. Consequently old singlet_sd trajectories are not preserved at the same numerical theta. The angle convention, overlap regularization, unique-selection policy, and other pool types are unchanged. This pool correction alone does not establish reproduction of any historical convergence figure.

Returned SingletSD excitation labels use spatial indices: [i,a] for singles and [i,j,a,b,pair_spin] for doubles, with pair_spin 0 or 1. This replaces the paired-only implementation’s spin-orbital labels. return_details=True also reports pool_type, pool_size, and all pool_excitations.

Iteration policy#

GCIM iteration count is fixed to the full size of the selected operator pool:

  • n_iterations = len(pool)

This behavior is hardcoded. Therefore:

  • adapt_it is accepted only for API compatibility with QCANT.adapt_vqe(), and

  • allow_repeated_operators is accepted only for API compatibility.

GCIM always enforces unique operator selection and runs until the chosen pool is exhausted.

Returns#

The function returns (params, ash_excitation, energies):

  • params: selected parameter vector (all values equal to theta),

  • ash_excitation: selected excitation list in ADAPT-style format,

  • energies: per-iteration minimum projected energy.

If return_details=True, a fourth dictionary is returned.