detci(1)

📦 version 3.4.0, in debian bookworm, ubuntu jammy, ubuntu noble

🎀 detci(1) — Determinant Configuration Interaction Program 🎀

okay bestie, sit down, hydrate, because this one is a whole era. This is the manual for detci, the Determinant Configuration Interaction Program ✨ it's giving quantum chemistry main character energy and honestly? obsessed.

💖 NAME 💖

detci — the Determinant Configuration Interaction Program. that's it, that's the name, and it ate.

🌸 DESCRIPTION 🌸

so like, what does detci actually do? bestie. it diagonalizes the nonrelativistic electronic Hamiltonian operator in a basis of Slater determinants. slay. 🔥

the set of determinants it uses (that's your CI space) can be picked in a bunch of different ways. the program handles any CI space that can be formulated as a Restricted Active Space CI 👑

that includes:

  • CISD, CISDT, CISDTQ, etc., all the way up to Full CI
  • multireference CI's, where the references are chosen as all determinants in which up to n electrons are excited in some MO active space
  • and that in turn covers CISD[T], CISD[TQ], and second-order CI (SOCI) 💅

📚 REFERENCES 📚

Restricted Active Space CI

  1. Determinant Based Configuration Interaction Algorithms for Complete and Restricted Configuration Interaction Spaces, J. Olsen, B. O. Roos, P. Jorgensen, and H. J. Aa. Jensen, J. Chem. Phys. 89, 2185 (1988).
  2. Passing the One-Billion Limit in Full Configuration-Interaction (FCI) Calculations, J. Olsen, P. Jorgensen, and J. Simons, Chem. Phys. Lett. 169, 463 (1990).

Tertiary virtual subspaces (RAS IV)

  1. Compact Variational Wavefunctions Incorporating Limited Triple and Quadruple Excitations, C. D. Sherrill and H. F. Schaefer, J. Phys. Chem. 100, 6069-6075 (1996).

DETCI Program

  1. C. D. Sherrill, Computational Algorithms for Large-Scale Full and Multi-Reference Configuration Interaction Wavefunctions, PhD thesis, University of Georgia, Athens, GA, 1996.

like, cite your sources bestie, it's called academia 🎓✨

🗂️ FILES REQUIRED 🗂️

these ones must be there or the vibe check fails:

input.dat          - Input file
file71             - Transformed one-electron integrals
file72             - Transformed two-electron integrals

🧚 TEMPORARY FILES USED 🧚

scratch files, the little helpers, the supporting cast 🫶

file50             - Diagonal of Hamiltonian
file51             - CI vectors
file52             - Sigma vectors
file53             - D file (correction vectors)

✏️ FILES UPDATED ✏️

output.dat         - Output file

⌨️ INPUT FORMAT ⌨️

command-line arguments, the moment you've been waiting for

here's what you can throw at it from the command line:

  • -quiet — does the exact same thing as PRINT=0. silent mode. stealth mode. ninja mode 🥷
  • -o fname — sets the filename for the output file. defaults to output.dat.
  • -e — makes the total CI energy (or energies, plural, we contain multitudes) get written out to a file called detci_energies.dat 💾
  • -c value — gives you a looser convergence on the CI vector, which is handy in DETCAS calculations. heads up: value here is a real number, not an integer like in CONVERGENCE. the convergence that actually gets used will be the looser of value and CONVERGENCE 👀
also, additional input for this program gets read from the file, and the following keywords are all valid:

✨ the keywords ✨

  • CONVERGENCE = integer — how converged you want the CI vector to be. convergence is achieved when the RMS of the error in the CI vector is less than 10**(-n). default is 4 for energies and 7 for gradients. and no, this is not the same CI vector convergence criterion you'll find in GUGACI, don't @ me 😤
  • DOCC = integer_array — this vector tells the program how many doubly occupied orbitals there are in each irrep. there is no default.
  • SOCC = integer_array — this vector tells the program how many singly occupied orbitals there are in each irrep. also no default.
  • DIAG_METHOD = string — which method to use when diagonalizing the Hamiltonian. the valid options are:
    • RSP — forms the entire H matrix and diagonalizes it using libciomr to get all eigenvalues. (n.b. requires HUGE memory 😭)
    • OLSEN — uses Olsen's preconditioned inverse subspace method (1990).
    • MITRUSHENKOV — uses a 2x2 Olsen/Davidson method.
    • DAVIDSON (or SEM) — uses Liu's Simultaneous Expansion Method, which is identical to the Davidson method if only one root is to be found.
    • there's also a SEM debugging mode, SEMTEST.

the SEM method is the most robust, but it also requires 2(N*M)+1 CI vectors on disk, where N is the maximum number of iterations and M is the number of roots. robust but hungry, iconic behavior 💅

  • PRECONDITIONER = string — the type of preconditioner to use in whichever diagonalization method you picked. valid options:
    • DAVIDSON — approximates the Hamiltonian matrix by the diagonal elements.
    • H0BLOCK_INV — uses an exact Hamiltonian of H0_BLOCKSIZE and explicitly inverts it.
    • GEN_DAVIDSON — does a spectral decomposition of H0BLOCK.
    • ITER_INV — uses an iterative approach to obtain the correction vector of H0BLOCK.

H0BLOCK_INV, GEN_DAVIDSON, and ITER_INV are all formally equivalent, but ITER_INV is the least computationally expensive of the three 🤑 default is DAVIDSON.

  • REFERENCE = string — the type of reference function. this is RHF or ROHF. UHF and TWOCON are not supported. for ROHF, a multiplicity of 1 implies an open-shell singlet.
real talk: the program will run for open-shell singlets, but it hasn't been properly adapted to use a correct two-determinant reference in that case, so running with open-shell singlet references is not advised — except for full CI's. consider yourself warned bestie 🙈
  • UPDATE = string — DAVIDSON uses the standard DAVIDSON update (a.k.a. the correction vector formula), while OLSEN uses the OLSEN correction vector. default is DAVIDSON.
  • HD_OTF = boolean — if TRUE, the diagonal elements of the Hamiltonian matrix are computed on-the-fly; otherwise a diagonal element vector gets written to a separate file on disk. default is TRUE.
  • HD_AVE = string — the diagonal-energy vibe selector:
    • HD_EXACT — uses the exact diagonal energies, which results in expansion vectors that break spin symmetry 💀
    • HD_KAVE — averages the diagonal energies over a spin-coupling set, yielding spin pure expansion vectors.
    • ORB_ENER — employs the sum of orbital energy approximation, giving spin pure expansion vectors but usually doubles the number of davidson iterations 😭
    • EVANGELISTI — uses the sums and differences of orbital energies with the SCF reference energy to produce spin pure expansion vectors.
    • LEININGER — the approximation which subtracts the one-electron contribution from the orbital energies, multiplies by 0.5, and adds the one-electron contribution back in, producing spin pure expansion vectors, developed by yours truly 💅 and it works as well as EVANGELISTI.
  • NODFILE = boolean — only possible if NUM_ROOTS = 1. uses the last vector space in the BVEC file to write scratch DVEC rather than using a separate DVEC file. recycling queen ♻️
  • ENERGY_CONVERGENCE = integer — how converged you want the CI energy. default is 6 for single point energies and 8 for gradients or CASSCF.
  • EX_LVL = integer — excitation level for excitations into virtual orbitals (default 2, i.e. CISD).
  • VAL_EX_LVL = integer — excitation level for references in orbitals of RAS II. defaults to zero.
  • FCI = boolean — if this flag is set to TRUE, then the storage of strings is simplified for a Full CI and the calculation requires less overhead. however, the final results should be identical to those when FCI = FALSE.
⚠️ may cause unpredictable results if FCI = TRUE but EX_LVL is not consistent with a Full CI. like, don't do that. fr fr.
  • FROZEN_DOCC = integer_array — the number of lowest energy doubly occupied orbitals in each irreducible representation from which there will be no excitations. the Cotton ordering of the irreducible representations is used. the default is the zero vector.
  • FROZEN_UOCC = integer_vector — the number of highest energy unoccupied orbitals in each irreducible representation into which there will be no excitations. the default is the zero vector.
  • FREEZE_CORE = boolean — determines whether the frozen core orbitals get included implicitly (true) or explicitly (false). in the implicit case, the energetic contributions from the frozen core orbitals are folded into the one-electron integrals and into the "frozen core energy" computed by the transformation program. default is true.
  • EXPORT_VECTOR = boolean — whether to store the converged vector(s) at the end of the run. the vector(s) is(are) stored in a transparent format so other programs can use it easily 🫶 the format is specified in src/lib/libqt/slaterdset.h. default is false.
  • NUM_EXPORT = integer — if EXPORT_VECTOR is set to true, then this determines the number of vectors that need to be exported at the end of the run. default is 1.
  • GUESS_VECTOR = string — which type of guess vector to use in the CI iteration. currently only used by the SEM iteration method. accepted values are:
    • UNIT — a unit vector guess (NUM_ROOTS and NUM_INIT_VECS must both be 1)
    • H0_BLOCK — use eigenvectors from the H0 BLOCK submatrix (default)
    • DFILE — use NUM_ROOTS previously converged vectors in the D file
    • MP2 — use the MP2 wavefunction as a guess (not working at the moment 😭)
  • H0_BLOCKSIZE = integer — the size of the "H0" block of the Hamiltonian which gets solved exactly. the n determinants with the lowest SCF energy are selected, and a submatrix of the Hamiltonian is formed using these determinants. this submatrix is used to accelerate convergence of the CI iterations in the OLSEN and MITRUSHENKOV iteration schemes, and also to find a good starting guess for the SEM method if GUESS_VECTOR = H0_BLOCK. defaults to 40.
heads up: the program may change the given size for Ms=0 cases (Ms0 = TRUE) if it determines that the H0 block includes only one member of a pair of determinants related by time reversal symmetry. for very small block sizes, this could conceivably eliminate the entire H0 block; the program should print warnings if this occurs 👀
  • H0_BLOCK_COUPLING_SIZE = integer — specifies the size of the coupling block within the generalized davidson preconditioner. default value is 1000.
  • MAX_DET = integer — sets the maximum number of determinants; if the CI space is larger than this, the program aborts 💀 this option exists to make sure that very large calculations don't get run by accident. during the current developmental phase, the default is 10000, but it will be raised before long.

and bestie, that's not even the whole thing — more of this iconic page is coming, so don't go anywhere 💖

  • MAXITER = integer — the max number of iterations to diagonalize the Hamiltonian. Defaults to 12. Don't be dramatic, it's just the cap. ✨
  • Ms0 = boolean — if TRUE, use the Ms=0 component of the state. Defaults to TRUE if closed-shell and to FALSE otherwise. It's related to the S parameter. Spin tea 🌀
  • NPRINT = integer — how many determinants get printed, along with their coefficients, in the list of most important determinants in the final CI vector. Default is 20. It's giving top 20 countdown but for CI. 💅
  • NUM_ROOTS = integer — number of roots to obtain from the secular equations. Default is one. If more than one root is required, set DIAG_METHOD to SEM (or, for very small cases, RSP or SEMTEST). Roots era 👑
  • NUM_INIT_VECS = integer — number of initial vectors to use in the CI iterative procedure. Defaults to the number of roots. Starter pack vibes 🌱
  • OPDM = boolean — if TRUE, calculate the one-particle density matrix and make OPDM_WRITE default to TRUE. The default value of OPDM is FALSE. Lowkey important 🧮
  • OPDM_FILE = integer — file (unit number) for writing the one-particle density matrix if OPDM_WRITE = TRUE. The default value is currently 73. 📁
  • OPDM_WRITE = boolean — flag for whether or not to write the one-particle density matrix to disk. Yes/no situation 💾
  • OPDM_PRINT = boolean — flag for whether or not to print the one-particle density matrix. For the nosy ones. 🖨️
  • OPDM_DIAG = boolean — flag for whether or not to diagonalize the one-particle density matrix. Diagonalize, bestie ✨
  • WRTNOS = boolean — flag for whether or not to write the CI natural orbitals to PSIF_CHKPT. Checkpoint slay 💖
  • ORBSFILE = integer — file (unit number) for writing various CI natural orbitals. The default value is 76. 📂
  • OPDM_AVE = boolean — flag for whether or not to average the OPDM over several roots in order to obtain a state-average one-particle density matrix. This density matrix can be diagonalized to obtain the CI natural orbitals. Average era ⚖️
  • ORBS_ROOT = integer — flag for setting the root number for which CI natural orbitals are written to PSIF_CHKPT. The default value is 1 (lowest root). Main character root 🌟
  • PRINT = integer — this option determines the verbosity of the output. A value of 1 or 2 specifies minimal printing, a value of 3 specifies verbose printing. Values of 4 or 5 are used for debugging. Do not use level 5 unless the test case is very small (e.g. STO H2O CISD). Too much information, respectfully 🗣️
  • ROOT = integer — the root to write out the two-particle density matrix for (the one-particle density matrices are written for all roots). Useful for a state-specific CASSCF or CI optimization on an excited state. Excited state energy ⚡
  • S = integer — the value of the spin quantum number S is given by this option. The default is 0 (singlet). The only thing this is actually used for is determining the phase of the redundant half of the CI vector when the Ms=0 component is used (i.e., Ms0 = TRUE). For cases where S is not an integer, this parameter need not be entered because such a state can't have an Ms=0 component. Quantum tea ☕
  • TPDM = boolean — if TRUE, calculate the two-particle density matrix and make TPDM_WRITE default to TRUE. The default value of TPDM is FALSE. Two-particle bestie 🧬
  • TPDM_FILE = integer — file (unit number) for writing the two-particle density matrix if TPDM_WRITE = TRUE. The default value is currently 74. 📁
  • TPDM_WRITE = boolean — flag for whether or not to write the two-particle density matrix to disk. Disk go brrr 💾
  • TPDM_PRINT = boolean — flag for whether or not to print the two-particle density matrix. Typically a very bad idea except for debugging small cases. Do not print the whole thing unless you're built different 💀

There is also some less commonly used input, which novice users of PSI will have no need to use. Secret menu energy 🤫

  • BENDAZZOLI = boolean — use some routines to calculate sigma based on the papers of Bendazzoli et al. Seems to be slower and not worthwhile; may disappear eventually. Works only for full CI and the author doesn't remember if they could see how their clever scheme might be extended to RAS in general. Experimental 🧪
  • CALC_SSQ = boolean — if TRUE, calculate the expectation value of the S^2 operator for the final CI wavefunction for each root. In principle, DETCI should yield S^2 eigenfunctions. The default is FALSE. Spin check 🌀
  • COLLAPSE_SIZE integer — gives the number of vectors to retain when the Davidson subspace is collapsed (see MAXNVECT below). If greater than one, the collapsed subspace retains the best estimate of the CI vector for the previous n iterations. Defaults to 1. Keep the good ones 🧠
  • FIRST_TMP_UNIT = integer — gives the file (unit) number associated with the first scratch file used by DETCI. Other scratch files are numbered consecutively from this point, in the order H(diag), C, S, D. Each of these logical files takes up a number of physical files specified by the even more obscure input parameters NUM_HD_TMP_UNITS, NUM_C_TMP_UNITS, NUM_S_TMP_UNITS, NUM_D_TMP_UNITS. The user can also specify different starting points for each of these sets using the parameters FIRST_HD_TMP_UNIT and so forth. Splitting a file across several units may help avoid the size-of-integer problem in addressing large files that is present in DETCI and in PSI I/O libraries; but then again, the author hasn't tested it to see what happens. The first unit of each section is printed out under the heading FILES in the parameter output beginning the DETCI run. Unhinged but maybe useful 🌀
  • FZC = boolean — determines whether the frozen core orbitals are treated as truly frozen (i.e., absent entirely from calculation, FZC = TRUE) or whether they are present but restricted to be doubly occupied (FZC = FALSE). In the GUGA CI program, this is the distinction between what it calls FZC and COR orbitals. Generally, the integrals for frozen core orbitals are not needed by DETCI but they may be needed for MCSCF or gradients. Frozen core lore ❄️
  • ICORE = integer — specifies how to handle buffering of CI vectors. A value of 0 makes the program perform I/O one RAS subblock at a time; 1 uses entire CI vectors at a time; and 2 uses one irrep block at a time. Values of 0 or 2 cause some inefficiency in the I/O (requiring multiple reads of the C vector when constructing H in the iterative subspace if DIAG_METHOD = SEM), but require less core memory. Memory vs. speed, classic ⚖️
  • ISTOP = boolean — if TRUE then DETCI will stop after string information is formed and before integrals are read. May eventually change to an integer so that the user can select from multiple stopping points. Early exit 🚪
  • MAXNVECT = integer — gives the maximum number of Davidson subspace vectors which can be held on disk for the CI coefficient and sigma vectors. (There is one H(diag) vector and the number of D vectors is equal to the number of roots). When the number of vectors on disk reaches the value of MAXNVECT, the Davidson subspace will be collapsed to COLLAPSE_SIZE vectors for each root. This is very helpful for saving disk space. Defaults to MAXITER * NUM_ROOTS + NUM_INIT_VECS. Disk space icon 💽
  • MIXED = boolean — this determines whether "mixed" RAS II/RAS III excitations are allowed into the CI space. This is useful for placing additional constraints on a RAS CI. Mixed vibes 🌀
  • MIXED4 = boolean — this is similar to the MIXED keyword, but refers to excitations into RAS IV. Part two 🪩
  • NUNITS = integer — number of scratch files to be used in storing the C vectors (and also for the sigma vectors). More files, more friends 📚
  • OEI_ERASE = boolean — this determines whether the program erases the one-electron integrals file after it has been read. The default will eventually be true, but during development the default is false. Development era 🚧
  • OEI_FILE = integer — this keyword allows the user to specify the transformed one-electron integral file. The default is 71. 📁
  • PRINT_CIBLKS = boolean — specifies whether the program should print out a summary of all the blocks in the CI vector (which can be cast into matrix form, see refs.). Block party 🧱
  • R4S = boolean — restricts the RAS IV strings to the minimal set, saving memory. If you are concerned about this option, you should write David for advice unless you are a DETCI expert. Ask before you touch 🙋
  • REF_SYM = integer — this option allows the user to look for CI vectors of a different irrep than the reference. This probably only makes sense for Full CI, and it would probably not work with unit vector guesses. Numbering starts from zero for the totally-symmetric irrep. Symmetry switch 🔄
  • REPL_OTF = boolean — tells DETCI whether or not to do string replacements on the fly. Can save a gigantic amount of memory (especially for truncated CI's) but is somewhat flaky and hasn't been tested for a while. As the author recalls, it only works for certain classes of RAS calculations. Contact David for assistance. Eventually, the on-the-fly replacement stuff should be redone in a much smarter way so that it doesn't take eons of CPU time. Work along these lines was once started and may be completed eventually. Flaky icon ⚠️
  • RESTART = boolean — this option allows the user to resume a DETCI iteration that terminated prematurely. It assumes that the CI and sigma vectors are on disk; the number of vectors specified by RESTART_VECS is collapsed down to one vector per root. Comeback era 🔁
  • RESTART_VECS = integer — if RESTART = TRUE this specifies the number of CI (and sigma) vectors to read from disk. Typically this is the number of successfully completed iterations from a previous run times the number of roots for that run. Math bestie 🧮
  • TEI_ERASE = boolean — this determines whether the program erases the two-electron integrals file after it has been read. The default will eventually be true, but during development the default is false. Same development energy 🚧
  • TEI_FILE = integer — this keyword allows the user to specify the transformed two-electron integral file. The default is 72. 📁
  • MPN = boolean — set this to TRUE and DETCI will go off and compute the MPn series out to kth order, where k is decided by maxnvect. That's the whole vibe, no cap. ✨

And like, for open-shell systems (REF=ROHF, WFN = ZAPTN) DETCI doesn't do MPn, it computes the ZAPTn series instead. Same energy, different name. 🦋

But bestie, you don't just get to flip this on and dip — there are three things you MUST have set first or it's not happening:

  • GUESS_VECTOR must be set to TRUE. non-negotiable.
  • HD_OTF must be set to TRUE. also non-negotiable.
  • HD_AVE must be set to orb_ener. literally that value. not vibing with anything else.
Not me having to say this twice: all three of those need to be TRUE/orb_ener before you turn MPN on. It's giving prerequisites. 💅
  • SAVE_MPN2 = integer — okay so this one only becomes valid when MPN is TRUE and WIGNER is TRUE. Both. Together. Then she activates. 🎀

Here's the breakdown, and the number you pick literally changes which energy gets saved:

  • set it to 1 → the MP(2n-1) energy is saved.
  • set it to 2 → the MP(2n-2) energy is saved.
  • set it to any other value → the MPn energy is saved.

The default is 0, which is not 1 and not 2, so yeah — you already know which branch that lands in. 😭

And that's the whole page, bestie — you made it to the end, iconic behavior honestly. 🫶

This was detci(1), dated 9 Feb, 1996 — yes, she's an elder but she still slays, and now you know her fr fr. go compute something beautiful, mwah 💖✨

📦 where this page comes from