Determinants and Configuration State Functions¶

Determinant files specify the multideterminant expansion of the trial wavefunction in quantum Monte Carlo calculations. For systems requiring correlation beyond a single Slater determinant, these files define which molecular orbital configurations contribute to the wavefunction and with what weights. Configuration State Functions (CSFs) provide an alternative spin-adapted representation that ensures proper spin symmetry.

Overview¶

The multideterminant trial wavefunction is expressed as:

\[\Psi_T = e^J \sum_{i=1}^{N_{\text{det}}} c_i D_i\]

where:

\(D_i\) is the i-th Slater determinant
\(c_i\) are determinant coefficients
\(e^J\) is the Jastrow factor
\(N_{\text{det}}\) is the number of determinants

Alternatively, using Configuration State Functions:

\[\Psi_T = e^J \sum_{k=1}^{N_{\text{CSF}}} C_k \Phi_k\]

where:

\(\Phi_k\) are spin-adapted CSFs
\(C_k\) are CSF coefficients
Each CSF is a linear combination of determinants

Key Concepts¶

Slater determinant: Antisymmetrized product of molecular orbitals
Configuration State Function (CSF): Spin-adapted linear combination of determinants
CSF map: Defines how determinants combine to form CSFs
Multireference: Multiple configurations with significant weights
Active space: Orbitals and electrons included in correlation treatment

File Format¶

Determinant files (.det extension) are stored in the pool/ directory and are automatically generated by the trex2champ converter from TREXIO files or quantum chemistry outputs.

TREXIO file for determinants information

The trexio file contains the determinants information in the determinants group. CHAMP can directly read this information without any additional conversion.

Complete File Structure¶

A determinant file can contain up to three sections:

determinants: Required - specifies determinants and coefficients
csf: Optional - Configuration State Functions
csfmap: Optional - mapping between determinants and CSFs

Example File¶

# Determinants, CSF, and CSF mapping from the GAMESS output / TREXIO file.
# Converted from the trexio file using trex2champ converter https://github.com/TREX-CoE/trexio_tools
determinants 36 1
-0.92276500 0.08745570 0.08745570 -0.03455773 -0.03455773 0.15892000 -0.00958342 -0.00958342 0.03141700 0.06827967 0.06827967 -0.02315988 -0.02315988 0.01639443 -0.00751472 0.00887972 0.00887972 -0.00751472 0.01639443 0.14336029 0.14336029 -0.06358518 -0.06358518 -0.00177625 -0.00177625 -0.01588657 -0.01588657 0.16425900 0.02504927 0.02504927 0.11380000 0.00560594 0.00560594 0.01069429 0.01069429 -0.04482000
1  2  3  4  5  6  7  8  9  10  11   1  2  3  4  5  6  7  8  9  10  11
1  2  3  4  5  6  7  8  9  10  11   1  2  3  4  5  6  7  8  9  10  13
1  2  3  4  5  6  7  8  9  10  13   1  2  3  4  5  6  7  8  9  10  11
1  2  3  4  5  6  7  8  9  10  11   1  2  3  4  5  6  7  8  9  11  13
1  2  3  4  5  6  7  8  9  11  13   1  2  3  4  5  6  7  8  9  10  11
1  2  3  4  5  6  7  8  9  10  13   1  2  3  4  5  6  7  8  9  10  13
1  2  3  4  5  6  7  8  9  10  13   1  2  3  4  5  6  7  8  9  11  13
1  2  3  4  5  6  7  8  9  11  13   1  2  3  4  5  6  7  8  9  10  13
1  2  3  4  5  6  7  8  9  11  13   1  2  3  4  5  6  7  8  9  11  13
1  2  3  4  5  6  7  8  9  10  11   1  2  3  4  5  6  7  8  9  10  12
1  2  3  4  5  6  7  8  9  10  12   1  2  3  4  5  6  7  8  9  10  11
1  2  3  4  5  6  7  8  9  10  11   1  2  3  4  5  6  7  8  9  11  12
1  2  3  4  5  6  7  8  9  11  12   1  2  3  4  5  6  7  8  9  10  11
1  2  3  4  5  6  7  8  9  10  11   1  2  3  4  5  6  7  8  9  12  13
1  2  3  4  5  6  7  8  9  10  13   1  2  3  4  5  6  7  8  9  11  12
1  2  3  4  5  6  7  8  9  10  12   1  2  3  4  5  6  7  8  9  11  13
1  2  3  4  5  6  7  8  9  11  13   1  2  3  4  5  6  7  8  9  10  12
1  2  3  4  5  6  7  8  9  11  12   1  2  3  4  5  6  7  8  9  10  13
1  2  3  4  5  6  7  8  9  12  13   1  2  3  4  5  6  7  8  9  10  11
1  2  3  4  5  6  7  8  9  10  13   1  2  3  4  5  6  7  8  9  10  12
1  2  3  4  5  6  7  8  9  10  12   1  2  3  4  5  6  7  8  9  10  13
1  2  3  4  5  6  7  8  9  11  13   1  2  3  4  5  6  7  8  9  11  12
1  2  3  4  5  6  7  8  9  11  12   1  2  3  4  5  6  7  8  9  11  13
1  2  3  4  5  6  7  8  9  10  13   1  2  3  4  5  6  7  8  9  12  13
1  2  3  4  5  6  7  8  9  12  13   1  2  3  4  5  6  7  8  9  10  13
1  2  3  4  5  6  7  8  9  11  13   1  2  3  4  5  6  7  8  9  12  13
1  2  3  4  5  6  7  8  9  12  13   1  2  3  4  5  6  7  8  9  11  13
1  2  3  4  5  6  7  8  9  10  12   1  2  3  4  5  6  7  8  9  10  12
1  2  3  4  5  6  7  8  9  10  12   1  2  3  4  5  6  7  8  9  11  12
1  2  3  4  5  6  7  8  9  11  12   1  2  3  4  5  6  7  8  9  10  12
1  2  3  4  5  6  7  8  9  11  12   1  2  3  4  5  6  7  8  9  11  12
1  2  3  4  5  6  7  8  9  10  12   1  2  3  4  5  6  7  8  9  12  13
1  2  3  4  5  6  7  8  9  12  13   1  2  3  4  5  6  7  8  9  10  12
1  2  3  4  5  6  7  8  9  11  12   1  2  3  4  5  6  7  8  9  12  13
1  2  3  4  5  6  7  8  9  12  13   1  2  3  4  5  6  7  8  9  11  12
1  2  3  4  5  6  7  8  9  12  13   1  2  3  4  5  6  7  8  9  12  13
end
csf 20 2
0.92276500 -0.12368100 0.04887200 -0.15892000 0.01355300 -0.03141700 -0.09656200 0.03275300 0.02839600 -0.20274200 -0.00136500 0.08992300 -0.00251200 -0.02246700 -0.16425900 -0.03542500 -0.11380000 0.00792800 0.01512400 0.04482000
0.13390600 -0.08999000 -0.04327600 0.07929200 0.06217900 -0.00658100 0.96025800 -0.00444100 0.01898800 0.15434900 -0.04594200 -0.01868700 0.00187600 0.04520300 -0.06578900 -0.04536600 0.04834200 -0.00269300 -0.04316900 -0.02239200
end
csfmap
20 36 40
1
  1  -1.000000
2
  2  -0.707107
  3  -0.707107
2
  4  -0.707107
  5  -0.707107
1
  6  -1.000000
2
  7  -0.707107
  8  -0.707107
1
  9  -1.000000
2
  10  -0.707107
  11  -0.707107
2
  12  -0.707107
  13  -0.707107
6
  14  0.577350
  15  -0.288675
  16  0.288675
  17  0.288675
  18  -0.288675
  19  0.577350
2
  20  -0.707107
  21  -0.707107
4
  15  -0.500000
  16  -0.500000
  17  -0.500000
  18  -0.500000
2
  22  -0.707107
  23  -0.707107
2
  24  0.707107
  25  0.707107
2
  26  0.707107
  27  0.707107
1
  28  -1.000000
2
  29  -0.707107
  30  -0.707107
1
  31  -1.000000
2
  32  0.707107
  33  0.707107
2
  34  0.707107
  35  0.707107
1
  36  -1.000000
end

Determinants Section¶

Format Specification¶

Header line: Number of determinants and types

determinants 36 1

Format: determinants ndet nwftype

ndet = 36: Number of Slater determinants in expansion
nwftype = 1: Number of wavefunction types (typically 1)

Coefficient line: Weights for each determinant

-0.92276500 0.08745570 0.08745570 -0.03455773 ... (36 coefficients on one line)

One coefficient per determinant
Can be positive or negative
Normalized: \(\sum_i c_i^2 = 1\) (typically)
Leading coefficient usually largest in magnitude

Determinant specifications: Orbital occupation lists

Each determinant is specified by two set of numbers (one for spin-up and one for spin-down orbitals):

1  2  3  4  5  6  7  8  9  10  11   1  2  3  4  5  6  7  8  9  10  11

Format per determinant:

First part of the row: Spin-up (α) occupied orbital index
Second part of the row: Spin-down (β) occupied orbital index

Example breakdown (first determinant):

# Determinant 1: coefficient = -0.92276500
1 2 3 4 5 6 7 8 9 10 11   1 2 3 4 5 6 7 8 9 10 11

This is the reference closed-shell configuration (Hartree-Fock ground state).

Example excited determinant:

# Determinant 2: coefficient = 0.08745570
1 2 3 4 5 6 7 8 9 10 11   1 2 3 4 5 6 7 8 9 10 13
(β electron promoted 11→13)

This represents a single excitation from orbital 11 to orbital 13 for a β electron.

Determinant Notation¶

Orbital indices:

Start at 1 (Fortran convention)
Refer to molecular orbitals from the .lcao file
Ordered by occupation (typically ascending)

Excitation types:

Type	Description	Example (from 11-11 ref)
Reference	Ground state	11 11
Single α	One spin-up excitation	13 11
Single β	One spin-down excitation	11 13
Double αα	Two spin-up excitations	13 14 11
Double ββ	Two spin-down excitations	11 13 14
Double αβ	Mixed spin excitation	13 13

CSF Section (Optional)¶

Configuration State Functions provide a spin-adapted representation of the wavefunction.

Format Specification¶

Header line: Number of CSFs and spin multiplicity

csf 20 2

Format: csf ncsf nstates

ncsf = 20: Number of Configuration State Functions
nstates = 2: Number of electronic states

CSF coefficients: Two rows of coefficients

0.92276500 -0.12368100 0.04887200 -0.15892000 ... (20 coefficients for state 1)
0.13390600 -0.08999000 -0.04327600 0.07929200 ... (20 coefficients for state 2)

Number of rows = number of electronic states
Each row has ncsf coefficients
CSFs are spin-eigenfunctions with proper S and Sz

Relationship to determinants:

CSFs are linear combinations of determinants ensuring proper spin symmetry:

\[\Phi_k = \sum_{i=1}^{N_{\text{det}}} a_{ki} D_i\]

where \(a_{ki}\) are the CSF expansion coefficients from the csfmap section.

Advantages of CSF Representation¶

Spin symmetry: CSFs are eigenfunctions of \(\hat{S}^2\) and \(\hat{S}_z\)
Reduced dimension: Fewer CSFs than determinants for same accuracy
Physical interpretation: CSFs correspond to electronic states
Optimization: More efficient parameter optimization

CSF Map Section (Optional)¶

The CSF map defines how determinants combine to form Configuration State Functions.

Format Specification¶

Header line: Dimensions

csfmap
20 36 40

Format: ncsf ndet num_maps

ncsf = 20: Number of CSFs (matches csf section)
ndet = 36: Number of determinants (matches determinants section)
num_maps = 40: Number of maps of determinants to CSFs

CSF definitions: One block per CSF

Each CSF block specifies which determinants contribute:

1
  1  -1.000000

Format:

First line: Number of determinants in this CSF
Following lines: det_index coefficient

Example CSF blocks:

CSF 1 (single determinant):

1
  1  -1.000000

Contains only determinant 1
Coefficient = -1.0
Pure closed-shell reference

CSF 2 (two determinants):

2
  2  -0.707107
  3  -0.707107

Linear combination of determinants 2 and 3
Equal weights: \(1/\sqrt{2} \approx 0.707107\)
Spin-adapted singlet combination

CSF 10 (six determinants):

6
  14   0.577350
  15  -0.288675
  16   0.288675
  17   0.288675
  18  -0.288675
  19   0.577350

Coefficients ensure proper S=0 state
\(\sqrt{1/3} \approx 0.577350\), \(\sqrt{1/12} \approx 0.288675\)

Understanding CSF Coefficients¶

Common coefficient values arise from Clebsch-Gordan coupling:

Value	Fraction	Appears in
1.000000	1	Single determinant CSF
0.707107	\(1/\sqrt{2}\)	Two-determinant singlet
0.577350	\(1/\sqrt{3}\)	Three-determinant coupling
0.500000	\(1/2\)	Four-determinant coupling
0.408248	\(1/\sqrt{6}\)	Six-determinant coupling
0.288675	\(1/(2\sqrt{3})\)	Complex multiplets

Examples¶

Example 1: Single Determinant (Hartree-Fock)¶

System: N₂ molecule, closed shell, 14 electrons

Determinant file (N2.det):

determinants 1 1
1.000000
   1    2    3    4    5    6    7      1    2    3    4    5    6    7
end

Explanation:

Single determinant (Hartree-Fock reference)
Coefficient = 1.0 (normalized)
7 spin-up electrons in orbitals 1-7
7 spin-down electrons in orbitals 1-7
Closed-shell ground state

Example 2: CAS(2,2) - Small Active Space¶

System: H₂ dissociation, 2 electrons in 2 orbitals

Determinant file (H2_cas22.det):

determinants 4 1
0.932000 0.342000 0.342000 0.092000
   1      1
   2      1
   1      2
   2      2
end

Explanation:

4 determinants: all configurations in CAS(2,2)
Determinant 1 (0.932): both electrons in orbital 1 (dominant)
Determinants 2-3 (0.342 each): singly-excited configurations
Determinant 4 (0.092): both electrons in orbital 2
Describes bond breaking/forming

Example 3: Multireference with CSF¶

System: O₂ molecule (triplet ground state)

Determinant file (O2.det):

determinants 12 1
0.62370 0.45123 0.45123 -0.23456 -0.23456 0.18234 0.18234 -0.12345 -0.12345 0.08123 0.08123 -0.05234
   1    2    3    4    5    6    7    8      1    2    3    4    5    6    7    8
   1    2    3    4    5    6    7    9      1    2    3    4    5    6    7    8
   1    2    3    4    5    6    7    8      1    2    3    4    5    6    7    9
   1    2    3    4    5    6    7    8      1    2    3    4    5    6    8    9
   1    2    3    4    5    6    8    9      1    2    3    4    5    6    7    8
   1    2    3    4    5    6    7    9      1    2    3    4    5    6    7    9
   1    2    3    4    5    6    8    9      1    2    3    4    5    6    7    9
   1    2    3    4    5    6    7    9      1    2    3    4    5    6    8    9
   1    2    3    4    5    6    8    9      1    2    3    4    5    6    8    9
   1    2    3    4    5    6    7   10      1    2    3    4    5    6    7    8
   1    2    3    4    5    6    7    8      1    2    3    4    5    6    7   10
   1    2    3    4    5    6    7   10      1    2    3    4    5    6    7   10
end
csf 8 1
0.62370 -0.63824 0.25735 -0.32245 0.11482 -0.14567 0.09867 -0.05234
end
csfmap
8 12 12
1
  1  1.000000
2
  2  0.707107
  3  0.707107
2
  4  0.707107
  5  0.707107
2
  6  0.707107
  7  0.707107
2
  8  0.707107
  9  0.707107
1
  10  1.000000
1
  11  1.000000
1
  12  1.000000
end

Explanation:

12 determinants describing triplet oxygen
8 spin-adapted CSFs (multiplicity = 3, S=1)
Degenerate π* orbitals (8-9) partially occupied
CSF map ensures proper triplet spin coupling
Reference + single and double excitations

Example 4: Determinants Only (Simplified)¶

System: Water molecule, CISD calculation

Determinant file (water_cisd.det):

determinants 156 1
0.93245 0.12456 0.11234 0.08923 0.07234 ... (156 coefficients)
   1    2    3    4    5      1    2    3    4    5
   1    2    3    4    6      1    2    3    4    5
   ... (154 more determinant pairs)
end

Explanation:

156 determinants from CISD (singles + doubles)
No CSF section (determinant representation only)
Reference + all single and double excitations
Simpler file structure, acceptable for spin-adapted cases

Loading Determinant Files in CHAMP¶

Standard Loading¶

Specify the determinant file in the CHAMP input:

%module general
    title  'Multireference QMC calculation'
    pool   './pool/'
%endmodule

load trexio        molecule.hdf5
load determinants  molecule.det
load jastrow       jastrow.jas

%module electrons
    nup    11
    nelec  22
%endmodule

Priority

If both load trexio and load determinants are specified, the load determinants will have priority.

From TREXIO File¶

Determinants can be embedded in TREXIO:

load trexio  molecule.hdf5

The trex2champ converter extracts them automatically.

CSF-based Calculation¶

To use CSF representation, just include them in the determinant file:

load determinants  molecule.det  # Contains determinants, csf, csfmap

Generating Determinant Files¶

From GAMESS Output¶

For MCSCF/CASSCF calculations with GAMESS:

#!/bin/bash
python trex2champ.py \
      --trex    benzene.hdf5 \
      --gamess  benzene_hf_cc-VDZ.out \
      --det \
      --csf

This additionally: - Extracts CSF information from GAMESS output - Generates complete CSF mapping - Ensures spin-adapted representation

From Other Quantum Chemistry Codes¶

Quantum Package2: Export Full CI / selected CI to TREXIO

qp run fci
qp set trexio trexio_file h2o_fci.trexio
qp run export_trexio

ORCA: Use TREXIO interface

trexio convert-from -t orca -i h2o.json -b hdf5 trexio_orca_h2o_sph.h5
trexio convert-to -t cartesian -o trexio_orca_h2o.h5 trexio_orca_h2o_sph.h5

PySCF: Python script to generate TREXIO

from pyscf import gto, mcscf
from pyscf.tools import trexio

mol = gto.M(atom='O 0 0 0; O 0 0 1.2', basis='ccpvtz')
mc = mcscf.CASSCF(mol, 4, 4)
mc.kernel()

# Save to TREXIO
trexio.to_trexio(mc, 'O2.hdf5')

Molecular Orbitals - Orbitals used in determinants
Jastrow Factors - Complement to determinant expansion
TREXIO Files - Source of determinant data
Wavefunction Optimization - Optimizing CI coefficients
VMC Calculations - Using multideterminant wavefunctions

Getting Help¶

Verify file structure matches specification exactly
Ensure orbital indices correspond to existing MOs
Test with known systems before custom determinant lists
Consult Troubleshooting Guide for common errors

Simplified Files

For closed-shell systems or when CSF information is not needed, you can use determinant-only files. Simply include the determinants section and omit csf and csfmap sections.

Spin Consistency

Each determinant must have exactly nup occupied orbitals in the α (spin-up) list and ndn occupied orbitals in the β (spin-down) list, where nup + ndn = nelec.

CSF Benefits

Using CSF representation ensures spin-pure states and typically requires fewer parameters to optimize, leading to more stable and physically meaningful wavefunctions. When available, prefer CSF-based files from MCSCF calculations.

Determinants and Configuration State Functions¶

Overview¶

Key Concepts¶

File Format¶

Complete File Structure¶

Example File¶

Determinants Section¶

Format Specification¶

Determinant Notation¶

CSF Section (Optional)¶

Format Specification¶

Advantages of CSF Representation¶

CSF Map Section (Optional)¶

Format Specification¶

Understanding CSF Coefficients¶

Examples¶

Example 1: Single Determinant (Hartree-Fock)¶

Example 2: CAS(2,2) - Small Active Space¶

Example 3: Multireference with CSF¶

Example 4: Determinants Only (Simplified)¶

Loading Determinant Files in CHAMP¶

Standard Loading¶

From TREXIO File¶

CSF-based Calculation¶

Generating Determinant Files¶

From GAMESS Output¶

From Other Quantum Chemistry Codes¶

Related Topics¶

Getting Help¶