.TH psi3 1 "25 August, 2003" "\*(]W" "\*(]D"
.SH NAME
psi3 \- master execution driver for the PSI programs

.SH DESCRIPTION
.LP
The program
.B psi3
reads your input deck, determines what type of calculation you are
trying to perform, and runs the appropriate programs.  
.B psi3
reads the file /usr/local/psi3/share/psi.dat by default.  This file
contains macros for some standard calculations.  Psi is very flexible,
however, and anything in the psi.dat file can be overridden by the user.
Thus, all that is written below should be taken with a grain of salt.
Experimentation is the best way to learn the 
.B psi3
command, and nothing that is written here should be taken as gospel.
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.

.sL
.pN INPUT
.pN psi.dat
.eL "FILES REQUIRED"

.SH COMMAND-LINE OPTIONS

.LP
The following command-line arguments are available:

.IP "\fI-i\fP or \fI-f\fP"
This flag is used to specify the input file name, e.g.
.B psi3 -i h2o.in
where
.B h2o.in
is the name of input file. By default,
.B psi3
and PSI modules that it calls will look for
.B input.dat .

.IP "\fI-o\fP"
This flag is used to specify the output file name, e.g.
.B psi3 -o h2o.out
where
.B h2o.in
is the name of output file. By default,
.B psi3
and PSI modules that it calls will look for
.B output.dat .

.IP "\fI-p\fP"
This flag is used to specify the PSI file prefix, e.g.
.B psi3 -p h2o.dzp
where
.B h2o.dzp
is the prefix that will be used for all PSI files. By default,
.B psi3
and PSI modules that it calls will use
.B psi
for the file prefix. Hence, the checkpoint
file is by default called
.B psi.32 .

.IP "\fI--noinput\fP or \fI-n\fP"
This tells
.B psi3
driver not to run
.B input
program. This flag is useful for scripting and debugging.

.IP "\fI--check\fP or \fI-c\fP"
This tells
.B psi3
driver to check the input and print out the list of programs
which would be executed. Equivalent to setting
.BR CHECK=TRUE
in the input file.

.IP "\fI--messy\fP or \fI-m\fP"
This tells
.B psi3
driver not to run cleanup program
.B psiclean .
Usually, the cleanup program is invoked via the
.B $done
macro defined in
.B psi.dat .
This flag is useful for scripting and debugging.

.SH INPUT FORMAT

.LP
The
.B psi3
program
searches through the default keyword path (first
.B PSI
and then
.BR DEFAULT )
for the following keywords:

.IP "\fBJOBTYPE =\fP \fIstring\fP"
This tells the 
.B psi3
driver program what kind of calculation you want
to run.  Acceptable choices are:
.B SP
(for a single-point energy computation),
.B OPT
(for an optimization, either using gradients or energies),
.B FREQ
(for harmonic vibrational frequencies),
.B FC
(for force constants by finite differences of internal coordinates ),
.B SYMM_FC
(for force constants by finite differences of internal coordinates, symmetric modes only),
.B DISP
(for a series of single-points at different displaced geometries),
.B DBOC
(to compute the Diagonal Born-Oppenheimer Correction [DBOC] to electronic energy).
The default is 
.BR SP .

.IP "\fBWFN =\fP \fIstring\fP"
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 
.B 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.

.IP "\fBREFERENCE =\fP \fIstring\fP"
This specifies the reference wavefunction desired.  It can be one of
.B RHF
(for a closed shell spin-restricted Hartree-Fock),
.B ROHF
(for an open-shell spin-restricted Hartree-Fock),
.B UHF
(for an open-shell spin-unrestricted Hartree-Fock), or
.B TWOCON
(for a two configuration singlet).
The default is
.BR RHF .

.IP "\fBDERTYPE =\fP \fIstring\fP"
This specifies the order of derivative that is to eventually be done.
The default is
.BR NONE .

.IP "\fBOPT =\fP \fIboolean\fP"
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 \fBJOBTYPE\fP keyword.

.IP "\fBNOPT =\fP \fIinteger\fP"
This gives the maximum number of iterations if OPT is true.
The default is 1.

.IP "\fBDISP =\fP \fIboolean\fP"
Set this equal to true if you are performing a finite displacements.
The default is false.
Note: This is an old keyword which is now obsolete; it has been replaced
by the \fBJOBTYPE\fP keyword.

.IP "\fBNDISP =\fP \fIinteger\fP"
This gives the maximum number of displacements if DISP is true.
The default is 1.

.IP "\fBNCASITER =\fP \fIinteger\fP"
This gives the maximum number of CASSCF iterations if WFN = CASSCF.
The default is 1.

.IP "\fBCHECK =\fP \fIboolean\fP"
If this is true, then 
.B psi3
will parse your input deck, and print out the sequence of commands to
be executed.  The default is false.

.IP "\fBEXEC =\fP \fIstring_vector\fP"
The EXEC vector contains a list of commands to be executed by 
.BR psi3 .
Explicit commands can be entered in double quotes, or preset variables can
be entered using the convention $\fIvariable\fP (see examples below).
Thus if you want to run 
.B ints
at some point, you could have

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

or

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

in your input. 


.SH LOOP CONTROL
.LP
Loop control is handled via the "repeat" and "end" built-in commands.
The syntax is

.DS
 repeat \fIn\fP  [commands to be executed] end
.DE

where \fIn\fP 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 \fIn\fP is set equal
to NOPT or NDISP.

.SH EXAMPLES
.LP
Let's say you want to do an scf geometry optimization. Your 
.B psi3
input could then be:

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

What \fBpsi3\fP would do with this is look in psi.dat or your input for
a variable called SCFCLOSEDFIRSTOPT (you see, \fBpsi\fP 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?

.LP
So now, let's say you want to run a program "myscf" instead of whatever
scf \fBpsi3\fP thinks you should run.  What you would do is put the line

.DS
 scf = "myscf"
.DE

in your input.  

.LP
Okay, one last example, then you're on your own.  I want to run
\fBproper\fP after \fBderiv\fP in my scf gradient. I would have several
ways to do this.

.IP "1) Brute force"

.DS
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
   )
  )
.DE

.IP "2) Elegant"

.DS
default: (
  SCFFirst = ($ints $scf $deriv $oeprop)
  )
.DE

.IP "3) Obscure"

.DS
default: (
  deriv = ("cints --deriv1" "oeprop")
  )
.DE

And there are others.  The only limit is your own tortured imagination.

.LP
Like I said, the best way to find out what \fBpsi3\fP can do is to look in
psi.dat, and to play around for awhile.  The CHECK option is very useful
for this.  Good luck!