source: ThirdParty/mpqc_open/src/lib/chemistry/qc/psi/mpqcpsi.dox@ 47b463

/** \page mpqcpsi Running Psi 3 from MPQC

<a href="http://www.psicode.org/">Psi 3</a>
is a suite of <i>ab initio</i> codes related to the
original Psi package started in Prof. Fritz Schaefer's
group at UC Berkeley. Current version of MPQC works with stable
versions of Psi 3 starting with 3.2.0.
From now on we will refer to Psi 3 as simply Psi.
Psi is written primarily in C and executes
in serial mode only.
The interface between Psi and MPQC is intended mainly for
Psi users who wish to exploit MPQC's geometry optimization and frequency analyses
capabilities with Psi energies and gradients.

The following sections explain how to use Psi from MPQC:

<ul>
  <li> \ref psiworks
  <li> \ref psienv
  <li> \ref psiinp
  <li> \ref psiexenv
  <li> \ref psiwfn
  <li> \ref examples
</ul>

\section psiworks How the MPQC-Psi interface works

The current version of the interface is rather slim. It is only possible to
import energies and gradients computed with Psi into MPQC, i.e. wave functions
cannot be imported. All MPQC-Psi interaction happens via text files and system calls.
MPQC generates input file for Psi, calls appropriate Psi modules, and then
parses the output files for energies and gradients.


\section psienv Environmental Variables

Several environmental variables are used to control MPQC-Psi interaction:
<dl>
<dt><tt>PSIBIN</tt><dd> By default, MPQC will try to find Psi binaries under <tt>/usr/local/psi/bin</tt>.
Use <tt>PSIBIN</tt> environmental variable to point to the right location.
</dl>
The rest of the Psi environment is job specific and specified in the input file.


\section psiinp Preparing an input file

As noted above, MPQC parses the input file, and as such the input file has to be in the MPQC
OO input format. All features of usual MPQC input files are there (<tt>mpqc</tt> section,
<tt>mole</tt> MolecularEnergy object, etc.).
In addition the following rules apply:
<ul>
  <li> instead of using MPQC Wavefunction objects (CLHF, MBPT2, etc.),
the Psi specific Wavefunction types (i.e. specializations of PsiWavefunction) have to be used.
Presently the following specializations are
supported: PsiCLHF, PsiHSOSHF, PsiUHF, PsiCCSD, PsiCCSD_T . The first three are directly
analogous to MPQC Wavefunction types CLHF, HSOSHF, and UHF. The latter two do not have
MPQC analogs yet. See appropriate class documentation on how to specify them properly.
  <li> each Psi-specific Wavefunction object has to have a member object <tt>psienv</tt> of type
PsiExEnv. PsiExEnv contains job specific information, such as the directory in which
Psi input, output, and checkpoint files will be kept, filename prefix, scratch directories, etc.
It makes sense to define one such object and simply refer to it from all
PsiWavefunction objects. See PsiExEnv class documentation for more info.
</ul>

\section psiexenv Psi Execution Environment

Each PsiWavefunction-derived class has to have a member object called <tt>psienv</tt>
of type PsiExEnv. The following keywords are used by its KeyVal constructor:
<dl>
<dt><tt>cwd</tt><dd> The directory where to keep Psi input, checkpoint, stdout, stderr, and other
files. Default is <tt>/tmp</tt>.
<dt><tt>fileprefix</tt><dd> The file prefix to use for Psi checkpoint, scratch, and some ASCII files.
Equivalent to keyword <tt>name</tt> in Psi <tt>psi:files:default</tt> section.
Defaults to <tt>psi</tt>.
<dt><tt>stdout</tt><dd> The file into which to redirect standard output of Psi modules.
Defaults to <tt>psi.stdout</tt>.
<dt><tt>stderr</tt><dd> The file into which to redirect standard error of Psi modules.
Defaults to <tt>psi.stderr</tt>.
<dt><tt>nscratch</tt><dd> The number of locations over which to stripe Psi binary
files. Equivalent to keyword <tt>nvolume</tt> in Psi <tt>psi:files:default</tt> section.
Default is 1.
<dt><tt>scratch</tt><dd> The locations over which to stripe Psi binary
files. Equivalent to keyword <tt>volume<i>x</i></tt> in Psi <tt>psi:files:default</tt> section.
There's no default.
</dl>

Here's an example:
<pre>
  psienv<PsiExEnv>: (
    cwd = ./
    fileprefix = psi.test
    nscratch = 2
    scratch = [ "/scratch1/" "/scratch2/" ]
  )
</pre>
<br>


\section psiwfn PsiWavefunction specializations

Class PsiWavefunction is derived from class Wavefunction, hence its
KeyVal constructor uses all keywords that Wavefunction's KeyVal
constructor uses (<tt>basis</tt>, <tt>molecule</tt>, etc.).
In addition, PsiWavefunction's KeyVal constructor
looks for the following keywords in the input file:
<dl>
<dt><tt>psienv</tt><dd> The PsiExEnv object that provides job specific
Psi environment. There's no default.
<dt><tt>docc</tt><dd> An optional array of integers that specifies
the number of doubly-occupied orbitals in each irrep.
<dt><tt>socc</tt><dd> An optional array of integers that specifies
the number of singly-occupied orbitals in each irrep.
<dt><tt>frozen_docc</tt><dd> An optional array of integers that specifies
the number of doubly-occupied orbitals in each irrep frozen in correlated
computations.
<dt><tt>frozen_uocc</tt><dd> An optional array of integers that specifies
the number of unoccupied orbitals in each irrep frozen in correlated
computations.
<dt><tt>total_charge</tt><dd> The total charge of the system. This keyword is
queried only if neither <tt>docc</tt> nor <tt>socc</tt> are given. 
<dt><tt>multiplicity</tt><dd> The spin multiplicity of the system (2*M_S+1).
This keyword is queried only if neither <tt>docc</tt> nor <tt>socc</tt>
are given.
<dt><tt>memory</tt><dd> The number of bytes of memory Psi modules
associated with this PsiWavefunction are allowed to use. Default is
2000000 (2 million bytes, approximately 2 MB).
</dl>
Note that keywords <tt>docc</tt>, <tt>socc</tt>, <tt>frozen_docc</tt>, <tt>frozen_uocc</tt>,
<tt>total_charge</tt>, and <tt>multiplicity</tt> are used by appropriate specializations
of PsiWavefunctions, i.e. PsiCLHF only checks for <tt>docc</tt>,
etc.

PsiWavefunction specializations PsiCCSD and PsiCCSD_T also look for keyword
<tt>reference</tt> which specifies the reference wave function
(an object of type PsiSCF). All classes for correlated Psi wave functions
will require such an object.

Here are a few examples of PsiWavefunctions:
<pre>
  \%
  \% ROHF DZ on F atom
  \%
  mole<PsiHSOSHF>: (
    docc = [ 2 0 0 0 0 1 1 0 ] socc = [ 0 0 0 0 0 0 0 1]
    memory = 10000000

    \% Psi Environment data
    psienv<PsiExEnv>: (
      cwd = ./
      fileprefix = f.dz.test
      stdout = f.dz.test.stdout
      stderr = f.dz.test.stderr
      nscratch = 1
      scratch = [ "/scratch/mpqc/" ]
    )

    \% MolecularEnergy input
    molecule<Molecule>: (
        {atoms geometry} = {
          F  [   0.0  0.0   0.0 ]
         }
      )

    \% Basis input
    basis<GaussianBasisSet>: (
        molecule = $..:molecule
        name = "DZ (Dunning)"
      )

  )
</pre>
<br>

<pre>
  \%
  \% RHF CCSD/cc-pVDZ on water
  \%
  mole<PsiCCSD>: (
    frozen_docc = [1 0 0 0]
    memory = 40000000

    \% Psi Environment data
    psienv<PsiExEnv>: (
      cwd = ./
      fileprefix = h2o.ccpvdz.ccsd.test
      nscratch = 1
      scratch = [ "/tmp/" ]
    )

    \% MolecularEnergy input
    molecule<Molecule>: (
        {atoms geometry} = {
          H  [  -1.5  0.0  -0.3 ]
          H  [   1.5  0.0  -0.3 ]
          O  [   0.0  0.0   1.0 ]
         }
      )

    \% Basis input
    basis<GaussianBasisSet>: (
        molecule = $..:molecule
        name = "cc-pVDZ"
      )

    reference<PsiCLHF>: (
      psienv = $..:psienv
      molecule = $..:molecule
      basis = $..:basis
      total_charge = 0
      multiplicity = 1
    )
  )
</pre>
<br>


\section examples More examples

This section contains some examples of complete inputs that specify an MPQC/Psi computations.

Here's an optimization + subsequent frequency analysis on water molecule
at the RHF CCSD 6-311G** level:
<pre>
\% Emacs should use -*- KeyVal -*- mode
\% this file was automatically generated
\% label: water test series
\% molecule specification
molecule<Molecule>: (
  symmetry = C2V
  unit = angstrom
  { atoms geometry } = {
     O     [     0.000000000000     0.000000000000     0.369372944000 ]
     H     [     0.783975899000     0.000000000000    -0.184686472000 ]
     H     [    -0.783975899000     0.000000000000    -0.184686472000 ]
  }
)
\% basis set specification
basis<GaussianBasisSet>: (
  name = "6-311G**"
  molecule = $:molecule
)
\% Psi environment specification
psienv<PsiExEnv>: (
      cwd = ./
      fileprefix = mpqcpsi
      stdout = mpqcpsi.stdout
      stderr = mpqcpsi.stderr
      nscratch = 1
      scratch = [ "/scratch/evaleev/" ]
)

mpqc: (
  checkpoint = no
  savestate = no
  restart = no
  coor<SymmMolecularCoor>: (
    molecule = $:molecule
    generator<IntCoorGen>: (
      molecule = $:molecule
    )
  )
  \% molecular coordinates for optimization  do_energy = yes
  do_gradient = no
  \% method for computing the molecule's energy
  mole<PsiCCSD>: (
    molecule = $:molecule
    basis = $:basis
    coor = $..:coor
    psienv = $:psienv
    memory = 32000000
    reference<PsiCLHF>: (
      psienv = $:psienv
      molecule = $:molecule
      total_charge = 0
      multiplicity = 1
      basis = $:basis
      memory = 32000000
    )
    hessian<FinDispMolecularHessian>: (
      point_group<PointGroup>: symmetry = C2V
      checkpoint = no
      restart = no
    )
  )
  optimize = yes
  \% optimizer object for the molecular geometry
  opt<QNewtonOpt>: (
    max_iterations = 20
    function = $..:mole
    update<BFGSUpdate>: ()
    convergence<MolEnergyConvergence>: (
      cartesian = yes
      energy = $..:..:mole
    )
  )
\% vibrational frequency input
  freq<MolecularFrequencies>: (
    point_group<PointGroup>: symmetry = C2V
    molecule = $:molecule
  )
)
</pre>
<br>

*/