mpqcoo.dox

大型并行量子化学软件；支持密度泛函（DFT）。可以进行各种量子化学计算。支持CHARMM并行计算。非常具有应用价值。

/** \page mpqcoo Object-Oriented Input

MPQC is an object-oriented program that directly allows the user to
specify objects that MPQC then manipulates to obtain energies,
properties, etc.  This makes the input very flexible, but very complex.
However, most calculations should be quite similar to the one of the
examples given later in this chapter.  The best way to get started is to
use one of the example input files and modify it to meet your needs.

<ul>
 <li> \ref mpqcooover
 <li> \ref mpqcoowalk
 <li> \ref mpqcoosamp
</ul>

\section mpqcooover Overview of the Object-Oriented Input

MPQC starts off by creating a ParsedKeyVal object that parses the
input file specified on the command line.  The format of the input file
is documented in \ref keyval.  It is basically a free
format input that associates keywords and logical groupings of keywords
with values.  The values can be scalars, arrays, or objects.

The keywords recognized by MPQC begin with the mpqc prefix.  That is, they
must be nested between an <tt>mpqc:(</tt> and a <tt>)</tt>.  Alternately,
each keyword can be individually prefixed by <tt>mpqc:</tt>.  The primary
keywords are given below.  Some of the keywords specify objects, in which
case the object will require more ParsedKeyVal input.  These objects are
created from the input by using their ParsedKeyVal constructors.  These
constructors are documented with the source code documentation for the
class.

<dl>

<dt><tt>mole</tt><dd> This is the most important keyword for MPQC.  It
        specifies the MolecularEnergy object.  This is an object that knows
        how to compute the energy of a molecule.  The specializations of
        MolecularEnergy that are most commonly used are CLKS, HSOSKS, UKS,
        CLHF, HSOSHF, UHF, and MBPT2.

<dt><tt>opt</tt><dd> This keyword must be specified for optimizations.  It
        specifies an Optimize object.  Usually, QNewtonOpt is best for
        finding minima and EFCOpt is best for transition states.

<dt><tt>freq</tt><dd> This keyword must be specified to compute
        frequencies.  It specifies a MolecularFrequencies object.

<dt><tt>thread</tt><dd> This specifies an object of type ThreadGrp that can
        be used to advantage on shared-memory multiprocessor machines for
        certain types of calculations.  This keyword can be overridden by
        giving the ThreadGrp in the environment or command line.  See the
        section on running MPQC for more information.

<dt><tt>checkpoint</tt> </dt> <dd> The value of this keyword is boolean.

        <ul>

        <li><tt>true</tt> and optimization is to be performed <br>

        <tt>opt</tt> object will be checkpointed after each iteration.
        The checkpoint file suffix is ".ckpt".

        <li><tt>true</tt> and optimization is not performed <br>

        <tt>mole</tt> object will be checkpointed at intermediate points.
        The manner in which
        <tt>mole</tt> will be checkpointed depends on its particular type.
        The checkpoint file suffix is usually ".wfn", however
        in general it will depend on the particular specialization of
        <tt>MolecularEnergy</tt>.

        </ul>

        The default is to not checkpoint.
        </dd>

<dt><tt>checkpoint_freq</tt><dd> This specifies how often to checkpoint
        certain MolecularEnergy specializations which compute iteratively.
        Currently, mole objects of SCF type can use this keyword.
        The default is 1, which means to checkpoint after every iteration.

<dt><tt>savestate</tt><dd> The value of this keyword is boolean.  If true,
        then the states of the Optimize and MolecularEnergy objects will be
        saved after the calculation completes.  The output file suffixes are
        ".ckpt" and ".wfn", respectively.  The default is to save state.

<dt><tt>restart</tt><dd> The value of this keyword is boolean.  If true,
        mpqc will attempt to restart the calculation.  If the checkpoint
        file is not found, the calculation will continue as if the value
        were false. The default is true.

<dt><tt>restart_file</tt><dd> This gives the name of a file from which
        restart information is read. If the file name ends with ".wfn"
        then MPQC will try to restore a <tt>MolecularEnergy</tt> object from it
        and query for the <tt>opt</tt> object in the input file.
        If the file name ends with ".ckpt" MPQC will try to restore an <tt>Optimize</tt>
        object from this file. The default file
        name is formed by appending ".ckpt" to the input file name
        with the extension removed.

<dt><tt>do_energy</tt><dd> The value of this keyword is boolean.  If true a
        single point energy calculation will be done for the
        MolecularEnergy object given with the mole keyword.  The default is
        true.

<dt><tt>do_gradient</tt><dd> The value of this keyword is boolean.  If true
        a single point gradient calculation will be done for the
        MolecularEnergy object given with the mole keyword.  The default is
        false.

<dt><tt>optimize</tt><dd> The value of this keyword is boolean.  If true
        and the opt keyword was set to a valid value, then an optimization
        will be performed.  The default is true.

<dt><tt>write_pdb</tt><dd> The value of this keyword is boolean.  If true a
        PDB file with the molecular coordinates will be written.

<dt><tt>filename</tt><dd> The value of this keyword is a string that gives
        a name from which checkpoint and other filenames are constructed.
        The default is the basename of the input file.

<dt><tt>print_timings</tt><dd> If this is true, timing information is
        printed at the end of the run.  The default is true.

</dl>

There are also some utility keywords that tell mpqc some technical
details about how to do the calculation:
<dl>
<dt><tt>debug</tt><dd> This optional keyword gives a Debugger
        object which can used to help find the problem
        if MPQC encounters a catastrophic error.
<dt><tt>matrixkit</tt><dd>
        This optional keyword gives a SCMatrixKit specialization
        which is used to produce matrices of the desired type.
        The default is a ReplSCMatrixKit which replicates
        matrices on all of the nodes.  Other choices are not thoroughly
        tested.
</dl>

\section mpqcoowalk A Walk-Through of an Object-Oriented Input File

This example input does a Hartree-Fock calculation on water.
Following is the entire input, followed by a breakdown with
descriptions.

<pre>
% This input does a Hartree-Fock calculation on water.
molecule<Molecule>: (
  symmetry = C2V
  unit = angstrom
  { atoms geometry } = {
    O     [     0.00000000     0.00000000     0.37000000 ]
    H     [     0.78000000     0.00000000    -0.18000000 ]
    H     [    -0.78000000     0.00000000    -0.18000000 ]
  }
)
basis<GaussianBasisSet>: (
  name = "STO-3G"
  molecule = $:molecule
)
mpqc: (
  mole<CLHF>: (
    molecule = $:molecule
    basis = $:basis
  )
)
</pre>

We start with a descriptive comment.  Comments begin with a <tt>%</tt>.
Everything from the <tt>%</tt> to the end of the line is ignored.

<pre>
% This input does a Hartree-Fock calculation on water.
</pre>

Now lets set up a Molecule object.  The name of the object comes first, it
is <tt>molecule</tt>.  Then, in angle brackets, comes the type of the
molecule, which is the class Molecule.  The keyword and class name are
followed by a <tt>:</tt> and then several pieces of input grouped between a
pair of matching parentheses.  These parentheses contain the information
that will be given to Molecule KeyVal constructor.

<pre>
molecule<Molecule>: (
</pre>

The point group of the molecule is needed.  This is done by assigning
<tt>symmetry</tt> to a case insensitive Schoenflies symbol that is used to
initialize a PointGroup object.  An Abelian point group should be used.

<pre>
  symmetry = C2V
</pre>

The default unit for the Cartesian coordinates is Bohr.  You can
specify other units by assigned <tt>unit</tt> to a string that will be
used to initialize a Units object.

<pre>
  unit = angstrom
</pre>

Finally, the atoms and coordinates are given.  This can be given in the
shorthand table syntax shown below.  The headings of the table are the
keywords between the first pair of brackets.  These are followed by an <tt>=</tt>
and another pair of brackets that contain the data.  The first datum is
assigned to the first element of the array that corresponds to the first
heading, <tt>atom</tt>.  The second datum is assigned to the first element of the
array associated with the second heading, <tt>geometry</tt>, and so on.  Here the
second datum is actually a vector: the x, y and z coordinates of the first
atom.

<pre>
  { atoms                       geometry                   } = {
    O     [     0.00000000     0.00000000     0.37000000 ]
    H     [     0.78000000     0.00000000    -0.18000000 ]
    H     [    -0.78000000     0.00000000    -0.18000000 ]
  }
)
</pre>

Next, a basis set object is given.

<pre>
basis<GaussianBasisSet>: (
  name = "STO-3G"
  molecule = $:molecule
)
</pre>

Now we will give the main body of input.  All the subsequent
keywords will be grouped in the <tt>mpqc</tt> section of the input
(that is, each keyword will be prefixed with <tt>mpqc:</tt>).

<pre>
mpqc: (
</pre>

Next we give the <tt>mole</tt> keyword which provides a specialization of
the MolecularEnergy class.  In this case we will do a closed-shell
Hartree-Fock calculation.  That is done with an object of type CLHF.  The
keywords that CLHF accepts are given with the documentation for the CLHF
class, usually in the description of the <tt>const RefKeyVal&</tt>
constructor for the class.  Also with the CLHF documentation is a list of
parent classes.  Each of the parent classes may also have input.  This
input is included with the rest of the input for the child class.

<pre>
  mole<CLHF>: (
</pre>

The next line specifies the molecule to be used.  There are two things to
note, first that this is actually a reference to complete molecule
specification elsewhere in the input file.  The <tt>$</tt> indicates that this is
a reference and the keyword following the <tt>$</tt> is the actual location of the
molecule.  The <tt>:</tt> in front of the keyword means that the keyword is not
relative to the current location in the input, but rather relative to the
root of the tree of keywords.  Thus, this line grabs the molecule that was
specified above.  The molecule object could have been placed here, but
frequently it is necessary that several objects refer to the exact same
object and this can only be done using references.

The second point is that if you look at the documentation for CLHF,
you will see that it doesn't read <tt>molecule</tt> keyword.  However, if you
follow its parent classes up to MolecularEnergy, you'll find that
<tt>molecule</tt> is indeed read.

<pre>
    molecule = $:molecule
</pre>

Just as we gave <tt>molecule</tt>, specify the basis set with the <tt>basis</tt> keyword
as follows:

<pre>
    basis = $:basis
</pre>

Now we close off the parentheses we opened above and we are finished.

<pre>
  )
)
</pre>

\section mpqcoosamp Sample Object-Oriented Input Files

The easiest way to get started with mpqc is to start with
one of sample inputs that most nearly matches your problem.  All
of the samples inputs shown here can be found in the directory
<tt>src/bin/mpqc/samples</tt>.

<ul>
  <li> \ref mpqcoosamphf
  <li> \ref mpqcoosampmp2
  <li> \ref mpqcoosampmp2r12
  <li> \ref mpqcoosamphfopt
  <li> \ref mpqcoosamphessopt
  <li> \ref mpqcoosampoptnewt
  <li> \ref mpqcoosamphffreq
  <li> \ref mpqcoosampcoor
  <li> \ref mpqcoosamphb
  <li> \ref mpqcoosampfixopt
  <li> \ref mpqcoosampts
  <li> \ref mpqcoosamptshess
  <li> \ref mpqcoosamphfckpt
  <li> \ref mpqcoosampmp2r12ckpt
  <li> \ref mpqcoosamphfgradfromwfn
  <li> \ref mpqcoosampmp2usinghfwfn
</ul>

\subsection mpqcoosamphf Hartree-Fock Energy

The following input will compute the Hartree-Fock energy of water.

<pre>
% emacs should use -*- KeyVal -*- mode
% molecule specification
molecule<Molecule>: (
  symmetry = C2V
  unit = angstrom
  { atoms geometry } = {
    O     [     0.00000000     0.00000000     0.37000000 ]
    H     [     0.78000000     0.00000000    -0.18000000 ]
    H     [    -0.78000000     0.00000000    -0.18000000 ]
  }
)
% basis set specification
basis<GaussianBasisSet>: (
  name = "STO-3G"
  molecule = $:molecule
)
mpqc: (
  checkpoint = no
  savestate = no
  % method for computing the molecule's energy
  mole<CLHF>: (
    molecule = $:molecule
    basis = $:basis
    memory = 16000000
  )
)
</pre>

\subsection mpqcoosampmp2 MP2 Energy

The following input will compute the MP2 energy of water.

<pre>
% emacs should use -*- KeyVal -*- mode
% molecule specification
molecule<Molecule>: (
  symmetry = C2V
  unit = angstrom
  { atoms geometry } = {
    O     [     0.00000000     0.00000000     0.37000000 ]
    H     [     0.78000000     0.00000000    -0.18000000 ]
    H     [    -0.78000000     0.00000000    -0.18000000 ]
  }
)
% basis set specification
basis<GaussianBasisSet>: (
  name = "STO-3G"
  molecule = $:molecule
)
mpqc: (
  checkpoint = no
  savestate = no
  % method for computing the molecule's energy
  mole<MBPT2>: (
    molecule = $:molecule
    basis = $:basis
    memory = 16000000
    % reference wavefunction
    reference<CLHF>: (
      molecule = $:molecule
      basis = $:basis
      memory = 16000000
    )
  )
)
</pre>

\subsection mpqcoosampmp2r12 MP2-R12 energy

The following will compute the MP2-R12 energy of water in standard approximation A'
(MP2-R12/A').

<pre>
% emacs should use -*- KeyVal -*- mode
% molecule specification
molecule<Molecule>: (
  symmetry = C2V
  unit = angstrom
  { atoms geometry } = {
    O     [     0.00000000     0.00000000     0.37000000 ]
    H     [     0.78000000     0.00000000    -0.18000000 ]
    H     [    -0.78000000     0.00000000    -0.18000000 ]
  }
)
% basis set specification
basis<GaussianBasisSet>: (
  name = "cc-pVDZ"
  molecule = $:molecule
)
% auxiliary basis set specification
abasis<GaussianBasisSet>: (
  name = "aug-cc-pVDZ"
  molecule = $:molecule
)
mpqc: (
  checkpoint = no