Full/CIPHI CI

FCI Module

This module contains a translation of the FCI C++ code of Gerald Knizia and extensions for selected CI and CIPHI (CIΦ - Selected CI via Perturbation, Heat-Bath and Iterations).

CIPHIContext

Lightweight context for CIPHI (CIΦ - CI via Perturbative and Heat-Bath Iterative selection) calculations.

Unlike FCIContext, CIPHIContext does NOT pre-compute full-space address tables or diagonal Hamiltonian elements. Instead, it only stores the minimal data needed:

• Integral data (FCIDump)
• Calculation options (CIPHIOptions)
• System size parameters
• Modified core Hamiltonian (for correct diagonal element calculation)

Address tables and diagonal elements are computed on-demand only for the selected determinants during CIPHI iterations. This provides:

• Faster initialization (no full-space addressing)
• Lower memory usage (proportional to Nselected, not Ndeterminants)
• Better scaling for large orbital spaces

Fields

• fcidump::FCIDump - Integral data
• options::CIPHIOptions - CIPHI-specific calculation options
• n_orb::Int - Number of spatial orbitals
• n_elec::Tuple{Int,Int} - (nalpha, nbeta) electron counts
• reference_det::Determinant - Reference determinant
• mod_core_h_a::Matrix{Scalar} - Modified core Hamiltonian for alpha spin
• mod_core_h_b::Matrix{Scalar} - Modified core Hamiltonian for beta spin
• heval_data::HEvalData - Precomputed arrays for diagonal and Fock elements

FCIContext

Main FCI calculation context.

run_ciphi!(ctx::CIPHIContext; initial_dets=nothing, initial_coeffs=nothing) 
  -> (energies, coeffs, determinants, pt2_result)

Convenience method for CIPHIContext that uses bundled options.

This lightweight interface avoids FCIContext initialization overhead:

• No full-space address tables computed upfront
• No full-space diagonal H computed upfront
• Initialization time proportional to Norbitals, not Ndeterminants

Keyword Arguments

• initial_dets: Starting determinants from previous calculation (for restart)
• initial_coeffs: Starting CI coefficients (optional, for warm start)

Returns

Same as runciphi!(ctx, options): (energies, coeffs, determinants, pt2result)

run_ciphi!(ctx::Union{FCIContext, CIPHIContext}, options::CIPHIOptions; 
                 initial_dets=nothing, initial_coeffs=nothing) 
  -> (Vector{Float64}, Matrix{Float64}, Vector{Determinant}, Vector{(Float64, Float64)})

Run CIPHI (CIΦ - Selected CI via Perturbation, Heat-Bath and Iterations) calculation with support for multiple states.

Arguments

• ctx: FCI context
• options: CIPHI options (including nstates for multi-state)

Keyword Arguments

• initial_dets::Union{Nothing, Vector{<:AbstractDeterminant}}: Starting determinants from previous calculation
• initial_coeffs::Union{Nothing, AbstractVecOrMat{Float64}}: Starting CI coefficients (optional, for warm start)

Returns

• energies: Vector of length nstates with total energies (electronic + nuclear)
• coefficients: Matrix (n_dets × nstates) with CI coefficients for all states
• variational_dets: Vector of determinants in final variational space
• pt2_result: PT2 correction results for all states

Notes

• For nstates=1 (default), uses single-state selection strategy
• For nstates>1, uses multi-state selection with state-maximum probability
• If initial_dets is provided, these determinants are used as the starting variational space

run_fci!(context::FCIContext) -> Vector{Scalar}

Run full FCI calculation.

CIPHISetupData

Setup data: Pre-computed and sorted double excitation matrix elements.

For each pair of orbitals {p,q}, stores a list of triplets {r,s,|H(rs←pq)|}, sorted by |H| in decreasing order. This enables efficient generation of only important excitations during iterative selection.

Following Holmes et al. (2016), Algorithm Step IIa.

Determinant

Represents a single determinant with alpha and beta orbital occupation patterns. Used for selected space determinant storage and manipulation.

DeterminantLookupIndex{OPattern}

Fast lookup index for finding connected determinants in O(1) time.

Stores three dictionaries:

• same_alpha: Maps alpha OPattern → Vector{Int} of determinant indices sharing that alpha
• same_beta: Maps beta OPattern → Vector{Int} of determinant indices sharing that beta
• singlexc_alpha: Maps alpha OPattern → Vector{OPattern} of alpha patterns connected by single excitation

This enables efficient lookup of candidates for:

• Double-beta excitations (via same_alpha)
• Double-alpha excitations (via same_beta)
• Mixed alpha-beta excitations (via singlexcalpha then samealpha)

Reduces extendSelectedHamiltonianMatrix from O(N²) to O(N×Nconnections) where N_connections << N.

ExcVals

Holds excitation values: coefficient and Hamiltonian matrix element required to calculate the contribution to the perturbative energy.

FCIVector{OPattern}

FCI vector storing coefficients as matrix M[iAdrA, iAdrB] where iAdrA and iAdrB are indices of orbital occupation strings for alpha/beta electrons.

FockDiagonal

Holds diagonal of the Fock matrix for alpha and beta spins.

HEvalData

Precomputed data for evaluating diagonal Hamiltonian and single excitations elements.

1. The jkaa, jkbb, jab, ha, hb arrays store precomputed Coulomb and exchange contributions needed for efficient diagonal Hamiltonian element evaluation.

   • jkaa[i, j] = 0.5 * [(ii|jj) - (ij|ji)] for alpha spin
   • jkbb[i, j] = 0.5 * [(ii|jj) - (ij|ji)] for beta spin
   • jab[i, j] = (ii|jj) mixed alpha-beta
   • ha[i] = ⟨i|h|i⟩ for alpha spin
   • hb[i] = ⟨i|h|i⟩ for beta spin

2. The h1e2 arrays contain combinations of two-electron integrals that appear frequently in single excitation matrix elements and Fock matrix construction. For example, for alpha-alpha excitations: h1e2[i, p, q] = v_{pi}^{qi} - v_{pi}^{iq} = (pq|ii) - (pi|iq)

   These arrays enable efficient computation of single excitation matrix elements via compute_fock_element.

HamiltonianTerm

Abstract base type for Hamiltonian terms.

HamiltonianTerm1e <: HamiltonianTerm

One-electron Hamiltonian term: hij c^i cj

HamiltonianTerm2e <: HamiltonianTerm

Two-electron Hamiltonian term: $\[1/2\] (ij|kl) E^i_j E^k_l$

WARNING: Uses (ij|kl) integrals, NOT ⟨ij|kl⟩ and includes factor 1/2.

OrbSpaces

Holds occupied and virtual orbital indices for alpha and beta spins.

OrbSpaces(n_orb::Int, buf::AbstractVector{Int}) -> OrbSpaces

Create OrbSpaces using provided buffer for occupied and virtual orbitals. Buffer size must be at least n_orb * 4.

OrbSpaces(n_orb::Int) -> OrbSpaces

Create OrbSpaces with pre-allocated buffers for occupied and virtual orbitals.

OrbStringAdrTable{OPattern}

Auxiliary object for addressing orbital occupation patterns for one spin. Provides addressing of all patterns with a fixed total number of electrons in a given number of orbitals.

(table::OrbStringAdrTable{OPattern})(bit_string::OPattern) where OPattern -> Address

Get 1-based address for a given bit string pattern.

PSpaceData

Container for P-space determinants, Hamiltonian matrix, and eigenvectors. Contains all data needed for P-space enhanced initial guess generation.

SelectedCIContext

Context for Selected CI calculations using direct H*c operations.

SelectedCIDeterminants{OPattern}

Container for selected determinants with efficient storage and fast lookup index.

SmallSpaceResult

Result from small-space Hamiltonian diagonalization.

StrInfo{OPattern}

Information about string substitutions for a block of strings.

SubstResult{OPattern}

Result of string substitution operation c^k c_l.

Base.copy(vec::FCIVector{OPattern}) where OPattern -> FCIVector{OPattern}

Create a deep copy of an FCIVector, including all data.

Base.getindex(vec::FCIVector{OPattern}, i_a::Integer, i_b::Integer) where OPattern -> Scalar

Access coefficient vec[ia, ib].

resize!(sel_ham::SelectedHamiltonianMatrix, dets::SelectedCIDeterminants, connections::Vector{Vector{Int}}, cursize)

Resize the SelectedHamiltonianMatrix to preallocate space for new elements.

Base.setindex!(vec::FCIVector{OPattern}, val::Scalar, i_a::Integer, i_b::Integer) where OPattern

Set coefficient vec[ia, ib] = val.

Base.zero(vec::FCIVector{OPattern}) where OPattern -> FCIVector{OPattern}

Create a zero FCIVector with the same dimensions.

absorb_1e!(int2::Array{Scalar, 4}, n_orb::Integer, n_elec::Integer, 
           core_h_x::Matrix{Scalar}, core_h_y::Matrix{Scalar})

Absorb one-electron operators into two-electron operator.

add!(r::FCIVector{OPattern}, x::FCIVector{OPattern}, f::Scalar) where OPattern

Compute r += f * x using LinearAlgebra.

add_1rdm_for_spin!(rdm::AbstractMatrix{Scalar}, coeff_l::AbstractVector{Scalar}, 
                  coeff_r::AbstractVector{Scalar}, adr1::OrbStringAdrTable, 
                  adr2::OrbStringAdrTable, st1::Integer, st2::Integer)

Add contribution to 1-RDM for one spin.

add_excitations!(excitations::VecDict{Determinant, ExcVals}, det::Determinant, coef::Scalar,
                coef_dg::Union{Scalar, Nothing}, alpha_occ, beta_occ, n_orb, 
                pchb_excitations, fa, fb, ecorr, shift, epsilon::Float64, epsilon_c::Float64)

Generate mixed-spin double excitations from occupied alpha and beta orbitals using pre-computed Heat-Bath lists, adding only those with |H| > epsilon.

add_excitations!(excitations::VecDict{Determinant, ExcVals}, det::Determinant,
                coef::Scalar, coef_dg::Union{Scalar, Nothing}, single_excitation_phase::Function, 
                occs, virts, occs_opp, int1, h1e2_same, h1e2_opp,
                fdiag, ecorr, shift, epsilon::Float64, epsilon_c::Float64)

Add single excitations to the excitations dictionary.

add_excitations!(excitations::VecDict{Determinant, ExcVals}, det::Determinant,
                coef::Scalar, coef_dg::Union{Scalar, Nothing}, double_excitation_phase::Function,
                occ, pchb_excitations, fdiag, ecorr, shift, epsilon::Float64, epsilon_c::Float64)

Generate same-spin double excitations from occupied orbitals using pre-computed Heat-Bath lists, adding only those with |H| > epsilon and storing in excitations dictionary together with their weighted matrix elements.

add_strings_to_table_recursive!(table::OrbStringAdrTable{OPattern}, old_pat::OPattern, 
                               n_elec_left::Integer, i_first_orb::Integer) where OPattern

Recursively add patterns with nelecleft electrons in the remaining orbitals.

address_from_determinant(context::FCIContext, det::Determinant) -> Address

Convert a determinant to its linear address in the CI vector.

apply_1e_op!(result::AbstractVector{Scalar}, coeffs::AbstractVector{Scalar}, 
            prefactor::Scalar, op_matrix_1e::AbstractMatrix{Scalar},
            adr1::OrbStringAdrTable, adr2::OrbStringAdrTable,
            st1::Integer, st2::Integer)

Apply 1-electron operator on specified spin branch.

apply_cop1(input_pattern::OPattern, iorb::Integer, create_or_destroy::Integer) where OPattern -> Tuple{OPattern, Int8}

Apply orbital creation (+1) or destruction (-1) operator on a determinant string. Returns (output_pattern, sign) where:

• sign = +1: operation has positive parity
• sign = -1: operation has negative parity
• sign = 0: operation annihilates input

binomial_coefficient(N::Integer, k::Integer) -> UInt64

Calculate binomial coefficient C(N,k) = N! / (k! * (N-k)!)

block_contract_cc1!(data_k::AbstractArray{Scalar, 3}, info1::Vector{StrInfo},
                    coeffs::AbstractMatrix{Scalar},
                    direction::Char, c_sum::Ref{Scalar}, prefactor::Scalar)

Block contraction for c^k c_l operators. Direction: 'c' for contraction, 'R' for residual formation.

block_contract_cc1_nosym!(data_k, info_1, coeffs, c_sum, prefactor)

Helper function for 2-RDM calculation. Performs block contraction for non-symmetric pairs.

Forms: data_k[k,l,iBlk1,iBlk2] += <K_1|c†_k c_l|J_1> * coeffs[J_1,K_2] * sign * prefactor

Arguments

• data_k: Output array [norb, norb, nblk1, nblk2]
• info_1: Array of StrInfo for spin 1 substitutions
• coeffs: CI coefficients as AbstractMatrix [n_str_1, n_blk_2] (can be StridedView)
• c_sum: Accumulator for sum of contributions (for screening)
• prefactor: Multiplicative prefactor (typically ±1)

build_lookup_index!(index::DeterminantLookupIndex{OPattern}, determinants::Vector{Determinant{OPattern}}, 
                   start_idx::Int, end_idx::Int, verbosity::Int) where OPattern

Build samealpha, samebeta and singleexcalpha index dictionaries for determinants in range [startidx:endidx]. samealpha/beta: Appends determinant indices to vectors for each unique alpha/beta pattern. singleexc_alpha: Maps alpha patterns to vectors of connected alpha patterns via single excitations.

build_pspace_hamiltonian!(context::FCIContext)

Build the P-space Hamiltonian matrix using efficient Selected CI machinery. This replaces the slow full-space approach with fast selected-space operations.

build_pspace_hamiltonian_selected!(context::FCIContext)

Build P-space Hamiltonian using selected CI framework.

build_small_space_hamiltonian(context::Union{FCIContext, CIPHIContext}, determinants::Vector{Determinant}) -> Matrix{Scalar}

Build Hamiltonian matrix for small space of determinants. Uses Selected CI framework for efficient matrix element computation.

Arguments

• context: FCI or CIPHIContext
• determinants: Vector of determinants spanning the small space

Returns

• Hamiltonian matrix H[i,j] = ⟨deti|H|detj⟩

calc_diagonalH(hed::HEvalData, occa::AbstractVector{Int}, occb::AbstractVector{Int}) -> Scalar

Evaluate diagonal Hamiltonian element ⟨Ψ|H|Ψ⟩ for determinant |occa, occb⟩.

calc_fock_diagonal4det!(fock::FockDiagonal, ctx::Union{FCIContext, CIPHIContext}, occa, occb)

Compute diagonal of the Fock matrix for a given determinant defined by occupied orbitals occa and occb.

fock is modified in-place and returned.

calc_mod_core_h!(mod_core_h::Matrix{Scalar}, int2::Array{Scalar, 4}, n_orb::Integer, c1_integrals::Bool)

Calculate modified core Hamiltonian by absorbing two-electron contributions arising from changed order of creation/annihilation operators.

calculate_double_excitation_phase(pattern::OPattern, orb_i::Int, orb_j::Int, orb_a::Int, orb_b::Int) where OPattern -> Int

Calculate phase factor for double excitation ij -> ab.

The phase is calculated by decomposing into two successive single excitations:

1. First excitation: i -> a, with phase φ₁
2. Second excitation: j -> b in modified determinant, with phase φ₂

Total phase = φ₁ × φ₂

This approach correctly handles the fermionic anticommutation relations.

calculate_excitation_phase(pattern::OPattern, orb_i::Int, orb_a::Int) where OPattern -> Int

Calculate phase factor for single excitation i -> a.

clear!(vec::FCIVector{OPattern}) where OPattern

Set all coefficients to zero.

compatible(a::FCIVector{OPattern}, b::FCIVector{OPattern}) where OPattern -> Bool

Check if two FCI vectors are compatible for operations.

compute_diagonal_element(occa::AbstractVector{Int}, occb::AbstractVector{Int}, ctx) -> Scalar

Compute diagonal matrix element ⟨det|H|det⟩ for a single determinant using HEvalData. Works with both FCIContext and CIPHIContext.

compute_diagonal_element(det::Determinant, ctx) -> Scalar

Compute diagonal matrix element ⟨det|H|det⟩ for a single determinant using HEvalData. Works with both FCIContext and CIPHIContext.

compute_fock_element(int1, h1e2_same, h1e2_opp, occ_same::AbstractVector, occ_opp::AbstractVector,
                    a::Int, i::Int) -> Float64

Compute Fock matrix element fai fai = hai + Σj (vaijj - vajji)SS + Σj (vaijj)OS where SS = same spin, OS = opposite spin.

compute_fock_element(int1, h1e2_same, h1e2_opp, str_same::OPattern, str_opp::OPattern,
                    a::Int, i::Int) where OPattern -> Float64

Compute Fock matrix element fai fai = hai + Σj (vaijj - vajji)SS + Σj (vaijj)OS where SS = same spin, OS = opposite spin.

compute_matrix_element_direct(det_i::Determinant, det_j::Determinant, 
                             context, occa=nothing, occb=nothing) -> Scalar

Compute ⟨detj|Ĥ|deti⟩ directly using orbital excitation analysis. Works with both FCIContext and CIPHIContext.

occa/occb are either Nothing or lists of occupied orbitals (makes the calculation more efficient).

compute_pt2_correction!(selected_ctx, coefficients, E_var, setup_data, options)

Compute second-order perturbative correction to variational energy.

Following Holmes et al. (2016), Section III.B: ΔE = ∑k [ (∑i Hki ci)² / (E⁽⁰⁾ - H_kk) ]

where k runs over external determinants (not in variational space) and i runs over internal determinants (in variational space).

Returns PT2 energies as a vector.

contract!(term::HamiltonianTerm, r::FCIVector, c::FCIVector, prefactor::Scalar)

Apply Hamiltonian term: |r⟩ += prefactor * H |c⟩

contract!(term::HamiltonianTerm1e, r::FCIVector, c::FCIVector, prefactor::Scalar)

Apply one-electron Hamiltonian term.

contract!(term::HamiltonianTerm2e, r::FCIVector, c::FCIVector, prefactor::Scalar)

Apply two-electron Hamiltonian term.

contract_hamiltonian!(context::FCIContext, r::FCIVector, c::FCIVector, prefactor::Scalar)

Apply full Hamiltonian: |r⟩ += prefactor * H |c⟩

contract_hamiltonian!(selected_ctx::SelectedCIContext, result::Vector{Scalar}, 
                     input::Vector{Scalar}, prefactor::Scalar)

Interface to existing Davidson solver infrastructure for Selected CI.

contract_hamiltonian_selected!(result::Vector{Scalar}, input::Vector{Scalar}, 
                              selected_ctx::SelectedCIContext, prefactor::Scalar)

Compute H*c matrix-vector product using precomputed Hamiltonian elements.

convert_op2_to_pair_matrix(op::AbstractArray{Scalar}, n_orb::Int)

Convert 4D integral tensor to pair matrix format.

count_excitation_level(det1::Determinant, det2::Determinant) -> Int

Count the excitation level between two determinants. Returns the number of orbital differences (alpha + beta).

davidson_fci!(context::FCIContext, n_states::Union{Int, Nothing} = nothing) 
-> Tuple{Vector{Scalar}, Vector{FCIVector}}

Unified Davidson diagonalization for FCI with subspace refresh capability. Always returns arrays of energies and states for type stability.

Arguments

• context: FCI context containing system information
• n_states: Number of electronic states to compute (default: uses context.options.nstates)

Returns

• Tuple{Vector{Scalar}, Vector{FCIVector}}: Arrays of energies and corresponding eigenvectors

davidson_selected_ci!(selected_ctx, initial_guesses; kwargs...)

Davidson diagonalization in selected CI space.

This is a specialized Davidson algorithm for selected CI calculations where the Hamiltonian matrix elements are computed on-the-fly. It uses the same Davidson algorithm as davidson_fci! but operates on a selected subset of determinants rather than the full CI space.

Automatically detects whether the Hamiltonian is Hermitian or non-Hermitian based on the context (similarity-transformed integrals are non-Hermitian).

Arguments

• selected_ctx::SelectedCIContext: Selected CI context containing determinants
• initial_guesses::Matrix{Scalar}: Initial guess vector in selected CI basis (nselected × nguess)

Keyword Arguments

• nstates::Int=1: Number of lowest eigenvalues to compute
• max_iterations::Int=50: Maximum number of Davidson iterations
• convergence_threshold::Float64=1e-8: Energy convergence threshold
• shift::Float64=0.1: (square of imaginary) level shift for preconditioner
• max_subspace::Int=30: Maximum subspace size before refresh
• verbose::Bool=false: Print iteration information

Returns

• Tuple{Vector{Float64}, Matrix{Float64}}: Eigenvalues and eigenvectors
  • eigenvalues: Vector of lowest nstates eigenvalues
  • eigenvectors: Matrix of eigenvectors (n_selected × nstates(times 2 for non-Hermitian))

Algorithm

Uses the Davidson iterative diagonalization method:

1. Build subspace by expanding with correction vectors
2. Project Hamiltonian onto subspace
3. Diagonalize small projected Hamiltonian (Hermitian or non-Hermitian)
4. Compute residuals and check convergence
5. Add correction vectors to expand subspace
6. Refresh subspace when it becomes too large

For non-Hermitian Hamiltonians (similarity-transformed integrals):

• Uses standard eigen() instead of eigen(Hermitian())
• Preconditioner uses complex shift to handle non-real eigenvalues
• The left eigenvectors are returned in the same array as right eigenvectors (after the right ones)

The key difference from davidson_fci! is that matrix elements are computed on-the-fly using contract_hamiltonian_selected!, maintaining O(Nselected) memory usage rather than O(Nfull).

determinant_from_address(context::FCIContext, addr::Address) -> Determinant

Convert a determinant address to alpha/beta orbital patterns. Uses the addressing tables to reconstruct the determinant.

determinants(selected_ctx::SelectedCIContext) -> Vector{Determinant}

Get selected determinants.

diagonal_matrix_element(det::Determinant, context) -> Scalar

Compute diagonal matrix element ⟨det|Ĥ|det⟩. For FCIContext uses precomputed diagonal, for CIPHIContext computes on-the-fly.

diagonalize_pspace_hamiltonian!(context::FCIContext)

Diagonalize the P-space Hamiltonian matrix to obtain eigenvalues and eigenvectors.

diagonalize_selected_space(selected_ctx::SelectedCIContext; 
                           nstates::Int=1,
                           previous_vectors::Union{Nothing,Matrix{Float64}}=nothing,
                           conv_tol::Float64=1e-6) 
  -> (Vector{Float64}, Matrix{Float64})

Diagonalize the Hamiltonian in the selected CI space. Returns eigenvalues and eigenvectors for nstates lowest states.

For small spaces (< 1000 determinants), uses direct diagonalization via eigen(). For large spaces (≥ 1000 determinants), uses Davidson iterative diagonalization.

Arguments

• selected_ctx: Selected CI context with determinants
• nstates: Number of lowest eigenstates to compute (default: 1)
• previous_vectors: Optional previous eigenvectors to use as initial guess for Davidson. Should be a matrix of size (nprev, nstates) where nprev is the number of determinants in the previous iteration. Will be projected onto the current determinant space.

Returns

• eigenvalues: Vector of length nstates with lowest eigenvalues
• eigenvectors: Matrix of size (n_selected, nstates) with eigenvectors
• For non-Hermitian Hamiltonians (similarity-transformed integrals), both right and left eigenvectors are computed and returned in the same matrix (right vectors first, then left).

double_alpha_beta_excitation_matrix_element(context, orb_i::Int, orb_j::Int, orb_a::Int, orb_b::Int) -> Scalar

Compute matrix element for double alpha beta excitation.

double_alpha_beta_excitation_phase(det::Determinant, orb_i_alpha::Int, orb_i_beta::Int,
                                   orb_a_alpha::Int, orb_a_beta::Int) -> (Determinant, Int)

Calculate phase factor for double alpha-beta excitation iα jβ -> aα bβ.

double_alpha_excitation_matrix_element(context, orb_i::Int, orb_j::Int, orb_a::Int, orb_b::Int) -> Scalar

Compute matrix element for double alpha excitation.

double_alpha_excitation_phase(det::Determinant, orb_i::Int, orb_j::Int, orb_a::Int, orb_b::Int) -> (Determinant, Int)

Create determinant and calculate phase factor for double alpha excitation ij -> ab.

double_beta_excitation_matrix_element(context, orb_i::Int, orb_j::Int, orb_a::Int, orb_b::Int) -> Scalar

Compute matrix element for double beta excitation.

double_beta_excitation_phase(det::Determinant, orb_i::Int, orb_j::Int, orb_a::Int, orb_b::Int) -> (Determinant, Int)

Create determinant and calculate phase factor for double beta excitation ij -> ab.

double_excitation_alpha(det::Determinant{OPattern}, i::Int, j::Int, a::Int, b::Int) where OPattern -> Determinant{OPattern}

Create determinant with alpha electrons moved from orbitals i,j to orbitals a,b.

double_excitation_beta(det::Determinant{OPattern}, i::Int, j::Int, a::Int, b::Int) where OPattern -> Determinant{OPattern}

Create determinant with beta electrons moved from orbitals i,j to orbitals a,b.

double_excitation_mixed(det::Determinant, i_alpha::Int, i_beta::Int, a_alpha::Int, a_beta::Int) -> Determinant

Create determinant with one alpha excitation ialpha->aalpha and one beta excitation ibeta->abeta.

extend!(selected_ctx::SelectedCIContext, new_dets::Vector{Determinant})

Extend the SelectedCIContext with new determinants.

extend!(dets::SelectedCIDeterminants, new_dets::Vector{Determinant}, new_addresses::Vector{Address})

Extend SelectedCIDeterminants with new determinants and addresses. Incrementally updates the lookup index for efficient connected determinant queries.

extend!(sel_ham::SelectedHamiltonianMatrix, dets::SelectedCIDeterminants, context)

Extend the SelectedHamiltonianMatrix to include new determinants. Uses fast lookup index to find connected determinants in O(N×N_connections) instead of O(N²).

extract_full_to_selected!(v_selected::Vector{Scalar}, v_full::FCIVector, 
                         selected_ctx::SelectedCIContext)

Extract selected CI coefficients from full CI vector.

find_double_excitation_orbitals(pattern_i::OPattern, pattern_j::OPattern) where OPattern -> (Int, Int, Int, Int)

Find the four orbitals involved in a double excitation ij -> ab.

find_excitation_orbitals(pattern_i::OPattern, pattern_j::OPattern) where OPattern -> (Int, Int)

Find the two orbitals involved in a single excitation i -> a.

fmt_det(pat_a::OPattern, pat_b::OPattern, n_max_orb::Integer) where OPattern -> String

Format determinant (alpha and beta patterns) as string.

fmt_pat(pat::OPattern, n_max_orb::Integer) where OPattern -> String

Format orbital pattern as string.

form_string_substs_for_spin!(result::Vector{SubstResult{OPattern}}, 
                            op_matrix_1e, adr::OrbStringAdrTable{OPattern},
                            I::OPattern, ThrNeglect=1e-16) where OPattern -> Int

Form sparse list of all |K> which can be reached by applying c^k_l on string |I>.

Returns number of valid substitutions found.

generate_excitations!(excitations::VecDict{Determinant, ExcVals},
                      det::Determinant, coef::Scalar, 
                      coef_dg::Union{Scalar, Nothing}, ecorr::Scalar,
                      ctx::FCIContext,
                      setup_data::CIPHISetupData, spaces::OrbSpaces, fockd::FockDiagonal,
                      epsilon::Float64, shift) -> Int

Generate only excitations with |H| > epsilon using pre-computed data.

This is the efficient excitation generation from Holmes et al. (2016):

1. For doubles: Use pre-sorted lists to stop early when |H| < epsilon
2. For singles: Compute on-the-fly and discard if |H| < epsilon

Additionally, H*coef/denom and coef*H is computed and stored during generation for efficiency.

Works with both FCIContext and CIPHIContext.

spaces is an OrbSpaces object used for temporary storage of occupied and virtual orbitals. fockd is the Fock diagonal object used to store Fock matrix diagonals for the determinant. coef_dg is the bra coefficient of the determinant (dagger) if needed, otherwise nothing.

generate_pspace_initial_guess!(context::FCIContext, guess_vectors::Vector{FCIVector},
                              n_states::Int)

Generate high-quality initial guess vectors using P-space eigenvectors. This replaces the diagonal-based initial guess with P-space enhanced vectors.

get_connections(index::DeterminantLookupIndex, determinants::Vector{Determinant}, 
                start_idx::Int, end_idx::Int) -> Vector{Vector{Int}}

Get connected determinants for each determinant in range [startidx:endidx]

get_diagonal_element(selected_ctx::SelectedCIContext, idet::Int) -> Scalar

Get diagonal Hamiltonian element for selected determinant index.

get_diagonal_element(sel_ham::SelectedHamiltonianMatrix, idet::Int) -> Scalar

Get diagonal Hamiltonian element for selected determinant index.

get_diagonal_pair_antisym_ints(int2e::AbstractArray{Scalar})

Extract diagonal pair antisymmetrized integrals for 2-electron terms.

get_diagonal_pair_ints(int2e::AbstractArray{Scalar})

Extract diagonal pair integrals for 2-electron terms.

get_reference_determinant(context::Union{FCIContext, CIPHIContext}) -> Determinant

Return the reference determinant. This is used as the starting point for P-space determinant selection.

hamiltonian_matrix(selected_ctx::SelectedCIContext) -> Matrix{Scalar}

Construct full Hamiltonian matrix for selected determinants.

heatbath_selection(selected_ctx::SelectedCIContext,
                   variational_coeffs::AbstractVector{Scalar},
                   options::CIPHIOptions,
                   E_current::Float64,
                   setup_data::CIPHISetupData,
                   detorder::Union{Nothing, Vector{Int}}=nothing, store_dets::Bool=true) 
                   -> (VecDict{Determinant, Scalar}, (Float64, Float64))

Select determinants using Heat-Bath preselection + perturbative selection. Uses efficient excitation generation with threshold-based filtering. Works with both FCIContext and CIPHIContext.

Returns selected determinants together with the weights and PT2 energy correction. If store_dets is false, only the PT2 energy is returned (with empty determinant list).

init!(table::OrbStringAdrTable{OPattern}, n_elec::Integer, n_orb::Integer) where OPattern

Initialize the orbital string addressing table.

init_hamiltonian_terms!(context::CIPHIContext)

Initialize Hamiltonian terms for the CIPHI calculation and precompute intermediate data.

init_hamiltonian_terms!(context::FCIContext)

Initialize Hamiltonian terms for the FCI calculation and compute diagonal Hamiltonian.

initialize_multistate_from_small_space(context::Union{FCIContext, CIPHIContext}, target_selection::Int, nstates::Int) -> SmallSpaceResult

Initialize multi-state CIPHI using small-space Hamiltonian diagonalization. This provides better initial guesses for all states, preventing missed excited states.

Algorithm

1. Select small space: max(100, sqrt(target_selection), 5*nstates) determinants
2. Build Hamiltonian in small space
3. Diagonalize to get nstates lowest eigenstates
4. Return determinants and eigenvectors as initial guess for CIPHI

Arguments

• context: FCI or CIPHI context
• target_selection: Target CIPHI variational space size (for adaptive sizing)
• nstates: Number of states to compute

Returns

• SmallSpaceResult containing determinants, eigenvalues, and eigenvectors

inject_pspace_to_full!(c::FCIVector, c_pspace::Vector{Scalar}, 
                      pspace_data::PSpaceData)

Map P-space correction vector back to full CI space. Sets coefficients at P-space determinant positions.

is_hermitian(ctx::SelectedCIContext) -> Bool

Get whether the Hamiltonian is Hermitian.

jacobi_davidson_correction!(t::FCIVector, r::FCIVector, u::FCIVector,
                           theta::Scalar, context::FCIContext, shift::Scalar)

Compute Jacobi-Davidson correction vector using P-space enhanced preconditioning: (I - uu^T) * (H - θI) * (I - u*u^T) * t = -r

This solves the projected correction equation to ensure the result is orthogonal to the current approximate eigenvector u, preventing linear dependency in the Davidson subspace.

Algorithm:

1. Project residual to ensure orthogonality: r_proj = (I - u*u^T) * r
2. If P-space available:
   • Extract P-space components of r_proj and u
   • Solve projected P-space system with double projection
   • Inject P-space correction into full space
   • Apply projected Davidson-Jacobi to Q-space
3. Otherwise:
   • Apply projected Davidson-Jacobi to all determinants
4. Final projection to enforce orthogonality

Arguments:

• t: Output correction vector (modified in-place)
• r: Residual vector
• u: Current Ritz vector (approximate eigenvector, should be normalized)
• theta: Current Ritz value (approximate eigenvalue)
• context: FCI context with Hamiltonian and P-space data
• shift: Level shift for regularization

Result: t is orthogonal to u by construction (dot(t, u) ≈ 0)

make_1rdms!(rdm_a::Matrix{Scalar}, rdm_b::Matrix{Scalar},
            coeff_l::FCIVector, coeff_r::FCIVector)

Compute 1-RDMs for alpha and beta spins as transition density matrices.

Computes:

• Γα[r,s] = <coeffl|c†{rα} c{sα}|coeff_r>
• Γβ[r,s] = <coeffl|c†{rβ} c{sβ}|coeff_r>

For a single state (coeffl == coeffr), this gives the regular 1-RDM. For different states, this gives the transition density matrix.

Arguments

• rdm_a: Pre-allocated norb × norb matrix for alpha 1-RDM
• rdm_b: Pre-allocated norb × norb matrix for beta 1-RDM
• coeff_l: Left FCI vector (bra state)
• coeff_r: Right FCI vector (ket state)

make_1rdms!(rdm_a::Matrix{Scalar}, rdm_b::Matrix{Scalar}, coeff::FCIVector)

Convenience method for computing 1-RDM of a single state (self-transition).

make_2rdm!(rdm2::Array{Scalar, 4}, coeff::FCIVector, rdm1::Matrix{Scalar}, ThrNeglect=1e-16)

Compute 2-particle reduced density matrix (2-RDM).

Computes: Γ[r,s,t,u] = <coeff|e^{rs}_{tu}|coef> = <coef| E^r_t E^s_u - \delta_t^s E^r_u |coeff> where E^r_s = c†_r c_s is the singlet excitation operator.

The algorithm:

1. Loop over blocks of alpha/beta strings
2. Form intermediate matrices: Inp[kl,K] = <K|c†_k c_l|J> c[J,K]
3. Contract to 2-RDM (E^rt E^su): R[tr,su] += Inp[tr,K] * Inp[su,K]
4. Permute and subtract to get final 2-RDM: Γ[r,s,t,u] = R[t,r,s,u] - RDM1[r,u] * δ_t^s

Arguments

• rdm2: Pre-allocated 4D array [norb, norb, norb, norb]
• coeff: FCI vector

Notes

• Computational cost: O(Ndet × norb^4)

make_diagonal_h!(context::FCIContext, diag_h::FCIVector)

Compute diagonal Hamiltonian matrix elements using precomputed heval_data.

make_pattern(table::OrbStringAdrTable{OPattern}, adr::Address) where OPattern -> OPattern

Create orbital pattern from address.

make_string_table!(table::OrbStringAdrTable{OPattern}) where OPattern

Create the string table with all valid orbital patterns.

modify_excitation!(excitations::Dict{Determinant, ExcVals},
                   det::Determinant, vals::ExcVals) -> Float64

Modify existing excitation entry in the excitations dictionary by adding new ExcVals. If the determinant is not present, returns the energy contribution from the new ExcVals.

n_data(vec::FCIVector{OPattern}) where OPattern -> Int

Total number of data elements.

n_old_dets(selci::SelectedCIContext) -> Int

Get the number of determinants in the previous iteration.

n_selected(selci::SelectedCIContext) -> Int

Get number of selected determinants.

n_selected(selci::SelectedCIDeterminants) -> Int

Get number of selected determinants.

n_spin(vec::FCIVector{OPattern}) where OPattern -> FCIUInt

Total spin quantum number.

noccupied(pattern::OPattern) where OPattern -> Int

Count number of occupied orbitals in the given orbital pattern.

noccupied_alpha(det::Determinant) -> Int

Count number of occupied alpha orbitals in the determinant.

noccupied_beta(det::Determinant) -> Int

Count number of occupied beta orbitals in the determinant.

occupied_and_virtual_orbitals!(occ, virt, pattern, n_orb)

Get lists of occupied and virtual orbital indices and store in occ and virt.

occupied_orbitals!(orbs, pattern, n_orb)

Get list of occupied orbital indices and store in orbs.

orthogonalize_against!(v::Vector{Scalar}, u::Vector{Scalar})

Vector version for P-space operations. Remove component of v parallel to u: v = v - (u' * v) * u Assumes u is normalized. Modifies v in-place.

orthogonalize_against!(v::FCIVector{OPattern}, u::FCIVector{OPattern}) where OPattern

Remove component of v parallel to u: v = v - (u' * v) * u Assumes u is normalized. Modifies v in-place. This is the projection operator: (I - u*u^T) * v

pair_index(i::Int, j::Int) -> Int

Get the pair index for a given pair of orbital indices.

project_pspace_to_fullspace!(v_full::FCIVector, v_pspace::Vector{Scalar}, 
                             pspace_data::PSpaceData)

Project P-space eigenvector onto full CI space. Zeros coefficients for determinants not in P-space and normalizes.

project_selected_to_full!(v_full::FCIVector, v_selected::Vector{Scalar}, 
                         selected_ctx::SelectedCIContext)

Project selected CI vector onto full CI space.

project_to_pspace(r::FCIVector, pspace_data::PSpaceData) -> Vector{Scalar}

Extract P-space components from full CI vector. Returns a vector of size n_pspace containing the coefficients at P-space determinants.

refresh_davidson_subspace!(V, HV, eigenvecs, k::Int, n_keep::Int)

Refresh Davidson subspace by keeping the most important eigenvectors. This is called when the subspace becomes too large.

Arguments

• V: Array of subspace vectors
• HV: Array of Hamiltonian-vector products
• eigenvecs: Current eigenvectors
• k: Current subspace size
• n_keep: Number of vectors to keep after refresh

Returns

• New subspace size after refresh

select_pspace_determinants!(context::FCIContext)

Select P-space determinants based on the configured selection method. Populates context.pspace_data with selected determinants and their indices.

select_small_space_determinants(context::CIPHIContext, target_size::Int, nstates::Int=1) -> Vector{Determinant}

Select determinants for small-space Hamiltonian diagonalization. For CIPHIContext, generates determinants by excitation level from reference, then calculates diagonal energies only for the generated determinants.

Arguments

• context: CIPHI context
• target_size: Target number of determinants (adaptive: max(100, sqrt(target_selection), 5*nstates))
• nstates: Number of states to compute (used for sizing)

Returns

• Vector of selected determinants

select_small_space_determinants(context::FCIContext, target_size::Int, nstates::Int=1) -> Vector{Determinant}

Select determinants for small-space Hamiltonian diagonalization. Uses the same hybrid selection method as traditional P-space.

Arguments

• context: FCI context
• target_size: Target number of determinants (adaptive: max(100, sqrt(target_selection), 5*nstates))
• nstates: Number of states to compute (used for sizing)

Returns

• Vector of selected determinants

set_n_old_dets!(selci::SelectedCIContext, n::Int)

Set the number of determinants in the previous iteration.

set_occupied_orbspaces!(orbspaces::OrbSpaces, det::Determinant)

Set occupied orbital indices in orbspaces based on the given det.

The occa, and occb fields of orbspaces have to be pre-allocated with sufficient size (at least norb).

set_orbspaces!(orbspaces::OrbSpaces, det::Determinant)

Set occupied and virtual orbital indices in orbspaces based on the given det.

The occa, virta, occb, and virtb fields of orbspaces have to be pre-allocated with sufficient size (at least norb).

setup_ciphi!(ctx::Union{FCIContext, CIPHIContext}) -> CIPHISetupData

Setup: Pre-compute and store sorted double excitation matrix elements.

For each pair of orbitals {p,q}, computes H(rs ← pq) for all distinct {r,s} pairs that don't include {p,q}, and stores them sorted by |H| in decreasing order.

This enables efficient generation of only important excitations, avoiding computation of matrix elements that would be below threshold.

Algorithm from Holmes et al. (2016), IIa:

• Time complexity: O(M^4 log M)
• Space complexity: O(M^4)

where M is the number of orbitals.

setup_ciphi_rhf!(ctx::Union{FCIContext, CIPHIContext}) -> CIPHISetupData

Setup for RHF systems using spatial orbital integrals.

setup_ciphi_uhf!(ctx::Union{FCIContext, CIPHIContext}) -> CIPHISetupData

Setup for UHF systems using spin-separated integrals. Handles three types of double excitations:

• Alpha-alpha (using int2aa)
• Beta-beta (using int2bb)
• Mixed alpha-beta (using int2ab)

setup_pspace!(context::FCIContext, n_states::Int=1)

Complete P-space setup: select determinants, build Hamiltonian, and diagonalize. This is the main entry point for P-space initialization.

Supports two modes:

1. Traditional: Excitation-based or energy-based determinant selection
2. HBCI: Uses Heat-Bath CI to select important determinants (more efficient)

Arguments

• context: FCI context
• n_states: Number of states to compute in subsequent Davidson (for CIPHI multi-state P-space)

setup_pspace_ciphi!(context::FCIContext, n_states::Int=1)

Use CIPHI to select P-space determinants. This provides a more efficient and targeted selection compared to traditional methods.

The selected determinants from CIPHI variational space become the P-space for subsequent full FCI Davidson iterations.

Arguments

• context: FCI context
• n_states: Number of states to compute (CIPHI will compute the same number of roots)

setup_selected_ci_from_addresses!(context::FCIContext, addresses::Vector{Address}) -> SelectedCIContext

Create SelectedCIContext from list of addresses.

setup_selected_ci_from_determinants!(context::Union{FCIContext, CIPHIContext}, determinants::Vector{Determinant}, hamiltonian=SelectedHamiltonianMatrix()) -> SelectedCIContext

Create SelectedCIContext from list of determinants.

single_alpha_excitation_matrix_element(det_i::Determinant, orb_i::Int, orb_a::Int, context,
                                       occa=nothing, occb=nothing) -> Scalar

Compute matrix element for single alpha excitation.

single_alpha_excitation_phase(det::Determinant, orb_i::Int, orb_a::Int) -> (Determinant{OPattern}, Int)

Create determinant and calculate phase factor for single alpha excitation i -> a.

single_beta_excitation_matrix_element(det_i::Determinant, orb_i::Int, orb_a::Int, context,
                                      occa=nothing, occb=nothing) -> Scalar

Compute matrix element for single beta excitation.

single_beta_excitation_phase(det::Determinant, orb_i::Int, orb_a::Int) -> (Determinant{OPattern}, Int)

Create determinant and calculate phase factor for single beta excitation i -> a.

single_excitation_alpha(det::Determinant{OPattern}, i::Int, a::Int) where OPattern -> Determinant{OPattern}

Create determinant with alpha electron moved from orbital i to orbital a.

single_excitation_beta(det::Determinant{OPattern}, i::Int, a::Int) where OPattern -> Determinant{OPattern}

Create determinant with beta electron moved from orbital i to orbital a.

slater_condon_allowed(det_i::Determinant, det_j::Determinant) -> Bool

Check if two determinants differ by at most two orbital occupations (same, single, or double excitations). Returns true if they differ by ≤ 2 orbitals, false otherwise.

solve_projected_pspace_system(r_P::Vector{Scalar}, u_P::Vector{Scalar}, 
                              theta::Scalar, pspace_data::PSpaceData, 
                              shift::Scalar, alpha::Scalar)

Solve the projected P-space correction equation with Q-space coupling: [(I - uP*uP^T)(HPP - θI)(I - uPu_P^T) + αuP*uP^T] tP = rP

This is part of the Jacobi-Davidson P-Q coupled preconditioner algorithm. The α term accounts for energy shift from Q-space component of Ritz vector.

Arguments:

• r_P: Residual vector in P-space
• u_P: Current Ritz vector in P-space (should be normalized)
• theta: Current Ritz value (approximate eigenvalue)
• pspace_data: P-space data structure with Hamiltonian
• shift: Level shift for regularization
• alpha: Q-space energy shift term (α = uQ^T(HQQ - E)u_Q)

Returns: Correction vector tP (orthogonal to uP)

string_parity_before_pos(pat::OPattern, ipos::Integer) where OPattern -> UInt

Return 0 if number of bits SET in bits [0..ipos) is even, 1 if it is odd.

sum_h1e2(h1e2, occ::AbstractVector, a, i) -> Float64

Compute Σ_j h1e2[j, a, i] over occupied orbitals j.

sum_h1e2(h1e2, str::OPattern, a, i) where OPattern -> Float64

Compute Σ_j h1e2[j, a, i] over occupied orbitals j.

sym_dof(N::Integer, ndim::Integer) -> UInt64

Number of symmetric degrees of freedom for dimension ndim.

symmetrize_ci_vector!(x::FCIVector)

Symmetrize CI vector for systems with equal alpha and beta electrons.

transpose_inplace_sqr!(mat_view::AbstractMatrix)

Transpose a square matrix in-place.

Transposes indices: mat[i,j] ↔ mat[j,i].

trip_index(p, q, n) -> Int

Compute unique index for orbital pair (p, q), with n orbitals per spin.

trip_index(p, q) -> Int

Compute unique index for orbital pair (p, q) with p < q.

update_ci_vector!(c::FCIVector, r::FCIVector, diag_h::FCIVector,
                 energy::Scalar, context::FCIContext, shift::Scalar,
                 u::Union{FCIVector,Nothing}=nothing)

Update CI vector using Davidson preconditioner with optional Jacobi-Davidson projection.

Two modes available:

1. Jacobi-Davidson (jacobi_davidson=true, default): Uses projection to prevent linear dependency Requires current Ritz vector u to be provided
2. Simple preconditioner (jacobi_davidson=false)

When P-space is available: uses exact solution in P-space + diagonal preconditioner in Q-space. When P-space is not available: falls back to standard diagonal preconditioner.

Arguments:

• c: Output correction vector
• r: Residual vector
• diag_h: Diagonal Hamiltonian elements
• energy: Current energy estimate
• context: FCI context
• shift: Level shift for regularization
• u: Current Ritz vector (normalized approximate eigenvector). Required for Jacobi-Davidson mode.

virtual_orbitals!(orbs, pattern, n_orb)

Get list of virtual (unoccupied) orbital indices and store in orbs.

LinearAlgebra.dot(a::FCIVector{OPattern}, b::FCIVector{OPattern}) where OPattern -> Scalar

Compute dot product using LinearAlgebra.

LinearAlgebra.norm(vec::FCIVector{OPattern}) where OPattern -> Scalar

Compute norm of FCI vector using LinearAlgebra.

LinearAlgebra.normalize!(vec::FCIVector{OPattern}) where OPattern

Normalize the FCI vector.