Ubuntu Manpage: psi3 - master execution driver for the PSI programs

NAME

       psi3 - master execution driver for the PSI programs

DESCRIPTION

       The  program  psi3  reads your input deck, determines what type of calculation you are trying to perform,
       and runs the appropriate programs.  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 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.

COMMAND-LINE OPTIONS

       The following command-line arguments are available:

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

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

       -p     This  flag  is  used  to  specify  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 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 psi3 driver not to run input program. This flag is useful for scripting and debugging.

       --check or -c
              This  tells  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 psi3 driver not to run 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 a 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). Thus if you want to run ints at some point, you could have

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

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.

       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!

                                                 25 August, 2003                                         psi3(1)