psi3(1)

✨ psi3 — bestie edition ✨

okay so this is the manual page for psi3, aka the master execution driver for the PSI programs. it's giving main character energy for your whole quantum chemistry workflow, and honestly? iconic. 💅

---

🌸 NAME 🌸

psi3 — the master execution driver for the PSI programs. no cap, this is the one that runs the whole show. 👑

---

🦋 DESCRIPTION 🦋

so here's the vibe: psi3 reads your input deck, figures out what type of calculation you're trying to perform, and then runs the appropriate programs. like a little manager with a clipboard. 📋✨

by default, psi3 reads the file /usr/local/psi3/share/psi.dat. that file contains macros for some standard calculations.

but here's the thing bestie — Psi is very flexible. anything in the psi.dat file can be overridden by the user. so literally everything written below should be taken with a grain of salt. 🧂

experimentation is the best way to learn the psi3 command, and nothing written here should be taken as gospel. fr fr.

a good place to look for syntax is in the psi.dat file. hopefully this man page and the psi.dat file should tell you all you need to know to get started. you got this. 🫶

---

💖 COMMAND-LINE OPTIONS 💖

the following command-line arguments are available:

• -i or -f — this flag specifies the input file name, e.g. psi3 -i h2o.in where h2o.in is the name of the input file. by default, psi3 and the PSI modules that it calls will look for input.dat. 🍓
• -o — this flag specifies the output file name, e.g. psi3 -o h2o.out where h2o.in is the name of the output file. by default, psi3 and the PSI modules that it calls will look for output.dat. 📝
• -p — this flag specifies the PSI file prefix, e.g. psi3 -p h2o.dzp where h2o.dzp is the prefix that will be used for all PSI files. by default, psi3 and the PSI modules that it calls will use psi for the file prefix. hence, the checkpoint file is by default called psi.32. 🗂️
• --noinput or -n — this tells the psi3 driver not to run the input program. this flag is useful for scripting and debugging. 🛠️
• --check or -c — this tells the psi3 driver to check the input and print out the list of programs which would be executed. equivalent to setting CHECK=TRUE in the input file. 🔍
• --messy or -m — this tells the psi3 driver not to run the cleanup program psiclean. usually, the cleanup program is invoked via the $done macro defined in psi.dat. this flag is useful for scripting and debugging. 🙈

---

🌈 INPUT FORMAT 🌈

the psi3 program searches through the default keyword path (first PSI and then DEFAULT) for the following keywords:

• JOBTYPE = string — this tells the psi3 driver program what kind of calculation you want to run. acceptable choices are: SP (for a single-point energy computation), OPT (for an optimization, either using gradients or energies), FREQ (for harmonic vibrational frequencies), FC (for force constants by finite differences of internal coordinates), SYMM_FC (for force constants by finite differences of internal coordinates, symmetric modes only), DISP (for a series of single-points at different displaced geometries), DBOC (to compute the Diagonal Born-Oppenheimer Correction [DBOC] to electronic energy). the default is SP. ⭐
• WFN = string — this is the type of wavefunction which is ultimately desired. as of this writing, acceptable values for WFN are SCF, MP2, CCSD, CCSD_T, DETCI, CASSCF, and RASSCF. having WFN defined as anything else is not necessarily bad, but don't expect psi3 to be able to figure out what to do. if you have a non-standard WFN, then it would probably be best to provide an EXEC section (see below). there is no default. 😭
• REFERENCE = string — this specifies the reference wavefunction desired. it can be one of RHF (for a closed shell spin-restricted Hartree-Fock), ROHF (for an open-shell spin-restricted Hartree-Fock), UHF (for an open-shell spin-unrestricted Hartree-Fock), or TWOCON (for a two configuration singlet). the default is RHF. 💜
• DERTYPE = string — this specifies the order of derivative that is to eventually be done. the default is NONE. 📐
• OPT = boolean — set this equal to true if you are performing a geometry optimization. the default is false. note: this is an old keyword which is now obsolete; it has been replaced by the JOBTYPE keyword. 💀
• NOPT = integer — this gives the maximum number of iterations if OPT is true. the default is 1.
• DISP = boolean — set this equal to true if you are performing finite displacements. the default is false. note: this is an old keyword which is now obsolete; it has been replaced by the JOBTYPE keyword. 💀
• NDISP = integer — this gives the maximum number of displacements if DISP is true. the default is 1.
• NCASITER = integer — this gives the maximum number of CASSCF iterations if WFN = CASSCF. the default is 1.
• CHECK = boolean — if this is true, then psi3 will parse your input deck, and print out the sequence of commands to be executed. the default is false. ✅
• EXEC = string_vector — the EXEC vector contains a list of commands to be executed by psi3. explicit commands can be entered in double quotes, or preset variables can be entered using the convention $variable (see examples below). so if you want to run ints at some point, you could have

psi: (
  exec = (
    ...
    "ints"
    ...
    )
  )

or

psi: (
  ints = "ints"
  exec = (
    ...
    $ints
    ...
    )
  )

in your input.

---

🎀 LOOP CONTROL 🎀

loop control is handled via the "repeat" and "end" built-in commands. the syntax is

 repeat n  [commands to be executed] end

where n is the number of times to repeat the loop. an inspection of the psi.dat file will show that this is how geometry optimizations and finite displacements are performed; in these cases n is set equal to NOPT or NDISP. 🔁✨

---

🧚 EXAMPLES 🧚

let's say you want to do an scf geometry optimization. your psi3 input could then be:

default: (
  jobtype = opt
  wfn = scf
  dertype = first
  reference = rhf
  nopt = 5
  ...
  )

what psi3 would do with this is look in psi.dat or your input for a variable called SCFCLOSEDFIRSTOPT (you see, psi catenates the values (roughly) for WFN, REFERENCE, DERTYPE, and OPT/DISP, in approximately that order (case doesn't matter)), and then executes the commands defined in the SCFCLOSEDFIRSTOPT vector. got it? 👑

---

so now, let's say you want to run a program "myscf" instead of whatever scf psi3 thinks you should run. what you would do is put the line

 scf = "myscf"

in your input. slay. 💅

---

okay, one last example, then you're on your own. i want to run proper after deriv in my scf gradient. i would have several ways to do this.

1. Brute force

default: (
  exec = (
   repeat 5
     "cints"
     "cscf"
     $deriv       % this is defined in psi.dat as "cints
--deriv1"
     "oeprop"
     $geomupdate  % this is defined in psi.dat
   end
   $done
   )
  )

2. Elegant

default: (
  SCFFirst = ($ints $scf $deriv $oeprop)
  )

3. Obscure

default: (
  deriv = ("cints --deriv1" "oeprop")
  )

and there are others. the only limit is your own tortured imagination. 😌

---

like i said, the best way to find out what psi3 can do is to look in psi.dat, and to play around for awhile. the CHECK option is very useful for this. good luck! 🍀

---

and that's a wrap, bestie!! 🫶 this little gem is from the 25 August, 2003 era — yeah, vintage, we love a classic — and it's rocking the psi3(1) manual-page energy, version and date and all. go forth and compute. 💖✨🌸