cscf(1)

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

💖 cscf(1) — the cscf manual page, bestie edition 💖

okay so real talk, this is cscf, section 1 of the manual, and she is long, so buckle up 🎀

✨ NAME ✨

cscf — solves the Hartree-Fock equations 🧚

🌸 DESCRIPTION 🌸

So what does cscf actually do? She carries out the iterative procedure to solve the Hartree-Fock equations. That's the whole vibe. No cap. 💅

Now here's the tea, and it's important tea: this program is restricted to D2h symmetry and its subgroups, and the orbital occupations are required to be integers. Which means certain pure angular momentum states derived from partial occupation of degenerate orbitals just... cannot be obtained with the present codes. It's giving limitations, unfortunately. 😭

For example: the 2PIu (doublet PI u) state of linear O-N-O derived from the lowest energy linear (pi u)1 configuration may only be computed as the 2B2u (doublet B2u) or 2B3u (doublet B 3u) component of the 2PIu (doublet PI u) state, and the resulting spatial wavefunction will not have PI symmetry. 🙈

But wait — in a certain sense, this is actually desirable, bestie, because the energy will be a continuous function of the bending angle. Whereas calculating the energy of bent configurations as 2B2u (doublet B 2u) or 2B3u (doublet B 3u) and doing a pure 2PIu (doublet PI u) state at linear geometries results in a pronounced discontinuity. So like... pick your struggle. 💀

For the most part, triplet states resulting from double occupation of a doubly degenerate orbital — such as the 3A2 (triplet A 2) state resulting from the (e')2 or (e")2 configurations in D3h symmetry, or the 3SIGMAg (triplet SIGMA g) state of a (pi g)2 or (pi u)2 configuration in Dinfh (D infinity h) symmetry — will have the proper spatial symetry. 👑

The singlet states resulting from these same electronic configurations, though? Inherently multiconfiguration, and as such they are not well represented by single configuration wavefunctions. periodt. 🫶

📚 REFERENCES 📚

okay so the receipts, organized by topic because we're organized like that ✨

PK-file method:

  1. R. C. Raffenetti, Chem. Phys. Lett. 20 (1973) 335.

Molecular symmetry and closed shell HF calculations:

  1. M.Dupuis, and H.F.King, Int. J. Quant. Chem. 11 (1977) 613.

DIIS for closed shell:

  1. P. Pulay, Chem. Phys. Lett. 73 (1980) 393.
  2. P. Pulay, J. Comp. Chem. 3 (1982) 556.

Coupling coefficients (alpha and beta) for open shell:

  1. C. C. J. Roothaan, Rev. Mod. Phys. 32 (1960) 179.

Damping:

  1. D. R. Hartree, "The Calculation of Atomic Structures" (Wiley: New York) 1957.
  2. M. C. Zerner and M. Hehenberger, Chem. Phys. Lett. 62 (1979) 550.

Level shifting:

  1. V. R. Saunders and I. H. Hillier, Int. J. Quant. Chem. 7 (1973) 699.

🔥 CONVERGING CSCF 🔥

This section is basically the "how do I make it actually converge" survival guide, and it's highkey the most useful part, so pay attention bestie 💖

For difficult open shell cases, it is recommended that an appropriate closed shell calculation be run first (add or remove an extra electron), and that this SCF vector then be used as a guess for the desired open shell wavefunction. Iconic strategy honestly. ✨

For TCSCF cases, it is always wise to run a closed shell (or perhaps the appropriate triplet) SCF first and then use this as a guess for the TCSCF. Do it. Trust. 🦋

For open shell systems, a level shift value of 0.5 to 3.0 is recommended. Start with a high value (2.0 - 3.0) for the first SCF calculation, and then reduce it (to 0.5 - 1.0) for subsequent runs which use a converged SCF vector as the starting point. Ease into it, she's sensitive. 💅

⚠️ okay this next bit is extremely important and I need you to actually read it: it is extremely important to note that this version of the code no longer supports OPENTYPE. One must use the new keywords REFERENCE and MULTP to specify the type of SCF needed. Do not come crying to me when OPENTYPE doesn't work, because she is gone. 😭

✨ INPUT FORMAT ✨

okay so cscf goes searching through the default keyword path — first SCF, then DEFAULT — for these keywords, bestie:

  • LABEL = string — a character string that gets included in the output. It is not used by the program. No default. 💅
  • WFN = string — the type of wavefunction you ultimately want. Default is SCF. ✨
  • OPENTYPE is no longer supported 💀
  • REFERENCE = string — says what kind of SCF calculation you want. Can be one of RHF (for a closed shell singlet), ROHF (for a restricted open shell calculation), UHF (for an unrestricted open shell calculation), TWOCON (for a two configuration singlet), or SPECIAL. If you give SPECIAL, then alpha and beta coupling coefficients must be given with the ALPHA and BETA keywords. Default is RHF.
  • MULTP= integer — multiplicity of the molecule. Default is singlet. 🌸
  • CHARGE= integer — charge of the molecule. Default is 0.
  • DOCC = integer_vector — number of doubly occupied orbitals in each irreducible representation. No default. If you don't give it, CSCF will attempt to guess at the occupations using the core hamiltonian. 🧚
  • SOCC = integer_vector — number of singly occupied orbitals in each irreducible representation. No default.
  • DERTYPE = string — order of derivative that is eventually to be done. Used by the scf program to determine if certain files are to be written, and also to determine the default convergence of the wavefunction. Default is FIRST.
  • MAXITER = integer — maximum number of iterations. Default is 40.
  • CONVERGENCE = integer — how tightly the wavefunction will be converged. Convergence is determined by comparing the RMS change in the density matrix ("delta P") to the given value. The convergence criterion is 10**(-integer). Default is 7 if both DERTYPE = NONE and WFN = SCF are given, and 10 otherwise.
  • LEVELSHIFT = real — level shift. Default is 1.
  • DIRECT = boolean — whether to do the SCF calculation with an integral direct technique. Default is false.
  • PRINT_MOS = boolean — whether to print the molecular orbitals or not. Default is false. 🎀

There are also a large number of less commonly used input parameters. If you do not understand what the following options mean, then make sure that they do not appear in your input. The defaults will work in the overwhelming majority of cases. These are specified with the following keywords:

  • DELETE_INTS = boolean — Integrals files will be erased if WFN = SCF and DERTYPE = FIRST or DERTYPE = NONE. If you wish to keep integrals files then set DELETE_INTS = false. Default is true.
  • REORDER = string — controls reordering of molecular orbitals. If set to BEFORE then the guess orbitals from checkpoint file will be reordered. If set to AFTER, converged orbitals will be reordered before being written to the checkpoint file. In either case MOORDER parameter must be given to specify the reordering map. Default is not to reorder orbitals.
  • MOORDER = integer_vector — specifies a molecular orbital reordering vector. It will only be used if REORDER is set. This vector maps every orbital to its new index, e.g. MOORDER = (0 2 1) specifies that after reordering orbitals 1 and 2 will be swapped. The rank of this vector is the same as the number of MOs. The indices are in Pitzer order (ordered by symmetry, then by energy within each symmetry block), base-0. CSCF will likely fail if the given MOORDER mixes orbitals from different irreps. There is no default.
  • ALPHA = real_vector — If OPENTYPE = SPECIAL, then this parameter gives the alpha coupling coefficients. The number of elements in this vector is MM(MM+1)/2, where MM is the number of irreducible representations containing singly occupied molecular orbitals. There is no default.
  • BETA = real_vector — If OPENTYPE = SPECIAL, then this parameter gives the beta coupling coefficients. The number of elements in this vector is MM(MM+1)/2, where MM is the number of irreducible representations containing singly occupied molecular orbitals. There is no default.
  • GUESS = string — determines the type of initial guess at the eigenvector CSCF will use. The only valid options at the moment are: (1) GUESS = CORE, which causes it to use core Hamiltonian eigenvector to start the calculation; (2) GUESS = AUTO which results in an attempt to use the MO vector in the checkpoint file, or resorts to core guess if there is no eigenvector in that file. Default is AUTO.
  • IPRINT = integer — print option. Default is 0.
  • MO_OUT = boolean — Prints out the orbitals with symmetry and occupations at the end of the calculation. Default is true.
  • ROTATE = boolean — The molecular orbitals will not be rotated if this is false. The rotation only affects the virtual orbitals for open shell systems. This parameter must be true for correlated gradients and it must be false for second and higher derivatives. Default is false if WFN = SCF and true otherwise.
  • CHECK_ROT = boolean — Check the molecular orbital rotation described above to ensure that no columns of the SCF eigenvector matrix are swapped by the rotation. Has no effect if ROTATE = false. Default is true.
  • CHECK_MO_ORTHOGONALITY = boolean — Check if the molecular orbitals are orthonormal. Useful for debugging only. Default is false.
  • DIIS = boolean — determines whether diis will be used. Default is true.
  • DIISSTART = integer — first iteration for which DIIS will be used. Default is 0.
  • NDIIS = integer — number of error matrices to use in the diis procedure. Default is 6 for closed shell, 4 for open shell, and 3 for tcscf.
  • DIISDAMP = real — damping factor for the diis procedure. Default is 0.0 for closed shell, 0.02 for open shell, and 0.01 for tcscf.
  • INCR = real — used in tcscf to determine how often the ci coefficients are recalculated. A small number (~0.25) will cause them to be recalculated nearly every scf iteration. Default is 0.25.
  • DYN_ACC = boolean — When performing direct scf this specifies whether dynamic integral accuracy cutoffs will be used. Default is true (use dynamic cutoffs). Initial iterations are performed with integrals accurate to six digits. After density is converged to 10^-5 or 30 iterations are completed, full integral accuracy is used. If scf convergence problems are experienced disabling dynamic cutoffs by setting this variable to false might help.
  • ORTHOG_ONLY = boolean — Sometimes in CASSCF or other non-HF/KS schemes for orbital optimization, it is useful to reorthogonalize MO's from other geometries for the current geometry so they can be used as an initial guess for the new MO's. This can be performed by running CSCF with ORTHOG_ONLY = true. After the orbitals are orthogonalized, the program will quit without performing an SCF computation. This keyword will be ignored if there are no previous orbitals in the checkpoint file. Defaults to true if WFN = DETCAS.
That's the whole vibe, bestie. This page is from cscf(1), dated 30 May, 1991. 💖✨👑
📦 where this page comes from