mpqc(1) MPQC mpqc(1)NAMEmpqc - The Massively Parallel Quantum Chemistry program (MPQC) computes
the properties of molecules from first principles.
This documentation is divided into the following chapters:
o MPQC Overview
o Running MPQC
o MPQC Input
o Validating MPQC
o Running Psi 3 from MPQC
o CCA Components
o MPQC License
o MPQC Warranty
MPQC Overview
The Massively Parallel Quantum Chemistry program (MPQC) computes the
properties of molecules, ab initio, on a wide variety of computer
architectures.
MPQC can compute closed shell and general restricted open-shell
Hartree-Fock energies and gradients, second order open-shell
perturbation theory (OPT2[2]) and Z-averaged perturbation theory
(ZAPT2) energies, and second order closed shell Moeller-Plesset
perturbation theory energies and gradients. It also includes methods
for optimizing molecules in either Cartesian or internal coordinates.
MPQC is designed using object-oriented programming techniques and
implemented in the C++ programming language.
Running MPQC
This chapter explains how to run MPQC in a variety of environments.
The first two sections give general information on running MPQC:
o Command Line Options
o Environmental Variables
The final sections given specific information on running MPQC in
different environments:
o Shared Memory Multiprocessor with SysV IPC
o Shared Memory Multiprocessor with POSIX Threads
o Shared or Distributed Memory Multiprocessor with MPI
o Special Notes for MP2 Gradients
o Special Notes for MP2-R12 energies
o Special Notes for CCA Components
Command Line Options
MPQC can be given options followed by an optional input file name. If
the input file name is not given, it will default to 'mpqc.in'. The
following command line options are recognized:
-o Gives the name of the output file. The default is the console.
-i Convert a simple input file to an object oriented input file and
write the result to the ouput. No calculations are done.
-messagegrp
A ParsedKeyVal specification of a MessageGrp object. The default
depends on how MPQC was compiled.
-memorygrp
A ParsedKeyVal specification of a MemoryGrp object. The default
depends on how MPQC was compiled.
-threadgrp
A ParsedKeyVal specification of a ThreadGrp object. The default
depends on how MPQC was compiled.
-integral
A ParsedKeyVal specification of an Integral object. The default is
IntegralV3. Note that some MolecularEnergy specializations require
specific choices of Integral specializations and may not work with
IntegralV3.
-l Sets a limit on the number of basis functions. The default is zero,
which means an unlimited number of basis functions.
-W Sets the working directory. The default is the current directory.
-c Check the input and exit.
-v Print the version number.
-w Print the warranty information (there is no warranty).
-d If a debugger object was given in the input, start the debugger
running as soon as MPQC is started.
-h Print a list of options.
-f The name of an object-oriented input file. The default is mpqc.in.
This cannot be used if another input file is specified. This option
is deprecated, as both input file formats can be read by given the
input file name on the command line without any option flags.
-cca-path
A colon-separated list of directories in which CCA component
libraries may be found.
-cca-load
A colon-separated list of sidl class names for CCA components which
will be instantiated from the libraries found in the path given by
-cca-path
Some MPI environments do not pass the command line to slave programs,
but supply it when MPI_Init is called. To make MPQC call MPI_Init with
the correct arguments as early as possible use the configure option
--enable-always-use-mpi.
Environmental Variables
MPQC looks at five environmental variables to set up communication,
find library files, and specify the default Integral object. Machine
specific libraries and utilities to run programs in parallel might look
at other environment variables as well. The five that apply on all
platforms are:
SCLIBDIR
The name of the library directory. See the GaussianBasisSet
documentation and look below for more information.
MESSAGEGRP
A ParsedKeyVal specification of a MessageGrp object. The default
depends on how MPQC was compiled. See the MessageGrp class
documentation for more information.
MEMORYGRP
A ParsedKeyVal specification of a MemoryGrp object. The default
depends on how MPQC was compiled and the MessageGrp in use.
THREADGRP
A ParsedKeyVal specification of a ThreadGrp object. The default
depends on how MPQC was compiled.
INTEGRAL
A ParsedKeyVal specification of an Integral object. The default is
IntegralV3. Note that some MolecularEnergy specializations require
specific choices of Integral specializations and may not work with
IntegralV3.
By default, MPQC tries to find library files first in the lib
subdirectory of the installation directory and then the source code
directory. If the library files cannot be found, MPQC must be notified
of the new location with the environmental variable SCLIBDIR.
For example, if you need to run MPQC on a machine that doesn't have the
source code distribution in the same place as it was located on the
machine on which MPQC is compiled you must do something like the
following on the machine with the source code:
cd mpqc/lib
tar cvf ../sclib.tar basis atominfo.kv
Then transfer sclib.tar to the machine on which you want to run MPQC
and do something like
mkdir ~/sclib
cd ~/sclib
tar xvf ../sclib.tar
setenv SCLIBDIR ~/sclib
The setenv command is specific to the C-shell. You will need to do what
is appropriate for your shell.
The other three keywords specify objects. This is done by giving a mini
ParsedKeyVal input in a string. The object is anonymous, that is, no
keyword is associated with it. Here is an example:
setenv MESSAGEGRP '<ShmMessageGrp>:(n = 4)'
Shared Memory Multiprocessor with SysV IPC
By default, MPQC will run on only one CPU. To specify more, you can
give a ShmMessageGrp object on the command line. The following would
run MPQC in four processes:
mpqc-messagegrp '<ShmMessageGrp>:(n = 4)' input_file
Alternately, the ShmMessageGrp object can be given as an environmental
variable:
setenv MESSAGEGRP '<ShmMessageGrp>:(n = 4)'
mpqc input_file
If MPQC should unexpectedly die, shared memory segments and semaphores
will be left on the machine. These should be promptly cleaned up or
other jobs may be prevented from running successfully. To see if you
have any of these resources allocated, use the ipcs command. The output
will look something like:
IPC status from /dev/kmem as of Wed Mar 13 14:42:18 1996
T ID KEY MODE OWNER GROUP
Message Queues:
Shared Memory:
m 288800 0x00000000 --rw------- cljanss user
Semaphores:
s 390 0x00000000 --ra------- cljanss user
s 391 0x00000000 --ra------- cljanss user
To remove the IPC resources used by cljanss in the above example on
IRIX, type:
ipcrm -m 288800
ipcrm -s 390
ipcrm -s 391
And on Linux, type:
ipcrm shm 288800
ipcrm sem 390
ipcrm sem 391
Shared Memory Multiprocessor with POSIX Threads
By default, MPQC will run with only one thread. To specify more, you
can give a PthreadThreadGrp object on the command line. MPQC is not
parallelized to as large an extent with threads as it is with the more
conventional distributed memory model, so you might not get the best
performance using this technique. On the other the memory overhead is
lower and no interprocess communication is needed.
The following would run MPQC in four threads:
mpqc-threadgrp '<PthreadThreadGrp>:(num_threads = 4)' input_file
Alternately, the PthreadThreadGrp object can be given as an
environmental variable:
setenv THREADGRP '<PthreadThreadGrp>:(num_threads = 4)'
mpqc input_file
Shared or Distributed Memory Multiprocessor with MPI
A MPIMessageGrp object is used to run using MPI. The number of nodes
used is determined by the MPI run-time and is not specified as input
data to MPIMessageGrp.
mpqc-messagegrp '<MPIMessageGrp>:()' input_file
Alternately, the MPIMessageGrp object can be given as an environmental
variable:
setenv MESSAGEGRP '<MPIMessageGrp>:()'
mpqc input_file
Usually, a special command is needed to start MPI jobs; typically it is
named mpirun.
Special Notes for MP2 Gradients
The MP2 gradient algorithm uses MemoryGrp object to access distributed
shared memory. The MTMPIMemoryGrp class is the most efficient and
reliable implementation of MemoryGrp. It requires a multi-thread aware
MPI implementation, which is still not common. To run MP2 gradients on
a machine with POSIX threads and an multi-thread aware MPI, use:
mpqc-messagegrp '<MPIMessageGrp>:()' \
-threadgrp '<PthreadThreadGrp>:()' \
-memorygrp '<MTMPIMemoryGrp>:()' \
input_file
or
setenv MESSAGEGRP '<MPIMessageGrp>:()'
setenv THREADGRP '<PthreadThreadGrp>:()'
setenv MEMORYGRP '<MTMPIMemoryGrp>:()'
mpqc input_file
Special Notes for MP2-R12 energies
Distributed Memory
The MP2-R12 energy algorithm is similar to the MP2 energy algorithm
that uses MemoryGrp object to access distributed memory. Hence the
MTMPIMemoryGrp is the recommended implementation of MemoryGrp for such
computations (see Special Notes for MP2 Gradients).
Disk I/O
In contrast to the MP2 energy and gradient algorithms, the MP2-R12
energy algorithm may have to use disk to store transformed MO integrals
if a single pass through the AO integrals is not possible due to
insufficient memory. The best option in such case is to increase the
total amount of memory available to the computation by either
increasing the number of tasks or the amount of memory per task or
both.
When increasing memory further is not possible, the user has to specify
which type of disk I/O should be used for the MP2-R12 energy algorithm.
It is done through the r12ints keyword in input for the MBPT2_R12
object. The default choice is to use POSIX I/O on the node on which
task 0 resides. This kind of disk I/O is guaranteed to work on all
parallel machines, provided there's enough disk space on the node.
However, this is hardly most efficient on machines with some sort of
parallel I/O available. On machines which have an efficient
implementation of MPI-IO the r12ints should be set instead to mpi-mem.
This will force the MBPT2_R12 object to use MPI-IO for disk I/O. It is
user's responsibility to make sure that the MO integrals file resides
on an MPI-IO-compatible file system. Hence the r12ints_file keyword,
which specifies the name of the MO integrals file, should be set to a
location which is guaranteed to work properly with MPI-IO. For example,
on IBM SP and other IBM machines which have General Parallel File
System (GPFS), the user should set r12ints = mpi-mem and r12ints_file
to a file on a GPFS file system.
Integral object
At the moment, MBPT2_R12 objects require specific specialization of
Integral, IntegralCints. Thus in order to compute MP2-R12 energies,
your version of MPQC needs to be compiled with support for
IntegralCints. A free, open-source library called libint is a
prerequisite for IntegralCints. In order to use IntegralCints as the
default Integral object, add -integral '<IntegralCints>:()' to the
command line, or set environmental variable INTEGRAL to
'<IntegralCints>:()'.
Special Notes for CCA Components
Common Component Architecture (CCA)
Portions of MPQC functionality are being packaged into CCA components.
For general overviews of CCA technology and framework usage, please see
www.cca-forum.org (the tutorial in particular) and the cca-chem-apps
documentation. MPQC components may be utilized directly within the
ccaffeine framework, while some components may be instantiated and used
within MPQC itself, making use of an embedded CCA framework.
CCA Runtime Environment
For MPQC runs utilizing embedded components, the runtime environment
for the CCA framework must be specified. The colon-separated path used
to locate component libraries must be specified either using the -cca-
path command-line option or using the cca_path key within the mpqc
section of a keyval input. The colon-separated list of component sidl
class names which will be referenced within the input must be specified
using either the -cca-load command-line option or using the cca_load
key within the mpqc section of a keyval input. If defaults for the cca-
path and cca-load options are desired, do_cca must be set to yes in the
keyval input.
MPQC Input
MPQC supports two input formats. The primary input is an object
oriented format which gives users access to all of MPQC's options. The
second format allows access to a subset of MPQC's capabilities, but is
more intuitive and easier to learn. New users are advised to start with
the simplified format. MPQC can be used to convert the simplified
format to the full object-oriented format with the -i option.
Each of these input formats is described in the following two chapters:
o Simple Input
o Object-Oriented Input
Simple Input
The simple input format consists of keywords followed by a ':' followed
by a value. The keywords are case sensitive. The values might be
modified by options found in parenthesis. For example, the following
input performs an optimization of water using density functional theory
with the B3LYP exchange-correlation functional:
% B3LYP optimization of water
optimize: yes
method: KS (xc = B3LYP)
basis: 3-21G*
molecule: (angstrom)
O 0.172 0.000 0.000
H 0.745 0.000 0.754
H 0.745 0.000 -0.754
Comments begin with a % and continue to the end of the line. Basis set
names containing special characters, such as a space or parentheses,
must be quoted inside a pair of double quotes. The accepted keywords
are:
molecule
Gives the atoms types and coordinates. The following options can be
used
bohr
The coordinates are given in Bohr.
angstrom
The coordinates are given in Angstroms (the default).
charge
This option can be given after an 'element x y z' quadruple. This
will override the charge on the atom. For example, (charge = 0) can
be given for the ghost atoms in a counterpoise correction
calculation.
multiplicity
Gives the multiplicity of the molecule. The default is 1.
optimize
If yes, then an optimization will be performed. The default is no.
The following options can be given.
cartesian
Use Cartesian coordinates.
internal
Use internal coordinates.
redundant
Use redundant internal coordinates.
gradient
If yes, then a gradient calculation will be performed. The default
is no.
frequencies
If yes, then the frequencies will be obtained. The default is no.
charge
Specificies the charge on the molecule. The default is 0.
method
Specifices the method. There is no default and the possible values
are:
HF Hartree-Fock. Unrestricted HF is used if multiplicity > 1
RHF
Restricted Hartree-Fock.
UHF
Unrestricted Hartree-Fock.
KS Kohn-Sham. Unrestricted KS is used if multiplicity > 1
RKS
Restricted Kohn-Sham.
UKS
Unrestricted Kohn-Sham.
MP2
Second order Moeller-Plesset perturbation theory. Only available
for multiplicity = 1.
MP2-R12/A
The A version of MP2-R12. Only available for multiplicity = 1. An
auxiliary basis may be specified. No gradient, optimization, or
frequencies are possible.
MP2-R12/A'
The A' version of MP2-R12. Only available for multiplicity = 1. An
auxiliary basis may be specified. No gradient, optimization, or
frequencies are possible.
ZAPT2
Z-averaged perturbation theory. Only available for multiplicity >
1. No gradient, optimization, or frequencies are possible.
The following options are valid with the KS, RKS, and UKS methods:
grid
Specifies the grid to be used for numerical integrations. The
following values can be given:
xcoarse
coarse
medium
fine
xfine
ultrafine
xc Specifies the exchange-correlation functional. There is no default.
See the table in the StdDenFunctional class documentation for the
possible values.
The following options are valid with the MP2-R12/A and MP2-R12/A'
methods. These options are mutually exclusive:
abs
Use the standard Auxiliary Basis Set method.
abs+
Use the standard Auxiliary Basis Set method, but use the union of
the orbital and the given auxiliary basis as the actual auxiliary
basis set used.
cabs
Use the Complementary Auxiliary Basis Set method.
cabs+
Use the Complementary Auxiliary Basis Set method, but use the union
of the orbital and the given auxiliary basis as the actual
auxiliary basis set used.
The following options are valid with the MP2-R12/A' method:
ebc
Assume the Extended Brillion Condition to hold. This is the
default.
gbc
Assume the Generalized Brillion Condition to hold. This is the
default.
!ebc
Do not assume the Extended Brillion Condition to hold.
!gbc
Do not assume the Generalized Brillion Condition to hold.
basis
Specifies the basis set. There is no default. See the table in the
GaussianBasisSet class documentation for the available basis sets.
auxbasis
Specifies the auxiliary basis set for MP2-R12 methods. There is no
default. See the table in the GaussianBasisSet class documentation
for the available basis sets.
restart
Set to yes to restart an optimization. The default is no.
checkpoint
Set to no to not save checkpoint files during an optimization. The
default is yes.
symmetry
Specifices the Schoenflies symbol of the point group of the
molecule. The default is auto, which will cause to program to find
the highest order Abelian subgroup of the molecule.
docc
Gives the number of doubly occupied orbitals in each each
irreducible representation in a parenthesized list. The symmetry
must be specified and not be auto. The method must be restricted.
socc
Gives the number of single occupied orbitals in each each
irreducible representation in a parenthesized list. The symmetry
must be specified and not be auto. The method must be restricted.
alpha
Gives the number of alpha occupied orbitals in each each
irreducible representation in a parenthesized list. The symmetry
must be specified and not be auto. The method must be unrestricted.
beta
Gives the number of beta occupied orbitals in each each irreducible
representation in a parenthesized list. The symmetry must be
specified and not be auto. The method must be unrestricted.
frozen_docc
Gives the number of frozen core orbitals. Can be either a single
integer or a parenthesized list giving the frozen core orbitals in
each irreducible representation. In the latter case the symmetry
must be given and not be auto.
frozen_uocc
Gives the number of frozen virtual orbitals. Can be either a single
integer or a parenthesized list giving the frozen virtual orbitals
in each irreducible representation. In the latter case the symmetry
must be given and not be auto.
memory
Gives a hint for the amount of memory in bytes that can be used.
This is typically a lower bound, more memory will be used in
practice and the exact amount cannot be precisely controlled. The
format is a fixed or floating point number optionally followed
(without spaces) by one of the following suffixes: KB, MB, GB, KIB,
MIB, or GIB.
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.
The object-oriented input format is described in the following
sections:
o Overview of the Object-Oriented Input
o A Walk-Through of an Object-Oriented Input File
o Sample Object-Oriented Input Files
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 the KeyVal documentation. 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 mpqc:( and a ). Alternately, each
keyword can be individually prefixed by mpqc:. 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.
mole
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.
opt
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.
freq
This keyword must be specified to compute frequencies. It specifies
a MolecularFrequencies object.
thread
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.
integrals
This specifies an object of type Integral that will be used as the
default integral evaluator. If MP2-R12 is used, then this should be
set to use IntegralCints with a line like integrals<IntegralCints>:
().
checkpoint
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>
checkpoint_freq
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.
savestate
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.
restart
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.
restart_file
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 MolecularEnergy object from it and query for the opt
object in the input file. If the file name ends with '.ckpt' MPQC
will try to restore an Optimize object from this file. The default
file name is formed by appending '.ckpt' to the input file name
with the extension removed.
do_energy
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.
do_gradient
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.
do_cca
The value of this keywork is boolean. If true the cca embedded
framework will be initialized. The default is false.
cca_path
The value of this keyword is a string that provides a colon-
separated list of directories in which CCA component libraries may
be found.
cca_load
The value of this keyword is a string that provides a colon-
separated list of sidl class names for CCA components which will be
instantiated from the libraries found in the path given by
cca_path.
optimize
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.
write_pdb
The value of this keyword is boolean. If true a PDB file with the
molecular coordinates will be written.
filename
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.
print_timings
If this is true, timing information is printed at the end of the
run. The default is true.
There are also some utility keywords that tell mpqc some technical
details about how to do the calculation:
debug
This optional keyword gives a Debugger object which can be used to
help find the problem if MPQC encounters a catastrophic error.
matrixkit
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.
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.
% 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
)
)
We start with a descriptive comment. Comments begin with a %.
Everything from the % to the end of the line is ignored.
% This input does a Hartree-Fock calculation on water.
Now lets set up a Molecule object. The name of the object comes first,
it is molecule. Then, in angle brackets, comes the type of the
molecule, which is the class Molecule. The keyword and class name are
followed by a : 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.
molecule<Molecule>: (
The point group of the molecule is needed. This is done by assigning
symmetry to a case insensitive Schoenflies symbol that is used to
initialize a PointGroup object. An Abelian point group should be used.
symmetry = C2V
The default unit for the Cartesian coordinates is Bohr. You can specify
other units by assigned unit to a string that will be used to
initialize a Units object.
unit = angstrom
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 =
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, atom. The second datum is assigned to the first element
of the array associated with the second heading, geometry, and so on.
Here the second datum is actually a vector: the x, y and z coordinates
of the first atom.
{ atoms geometry } = {
O [ 0.00000000 0.00000000 0.37000000 ]
H [ 0.78000000 0.00000000 -0.18000000 ]
H [ -0.78000000 0.00000000 -0.18000000 ]
}
)
Next, a basis set object is given.
basis<GaussianBasisSet>: (
name = 'STO-3G'
molecule = $:molecule
)
Now we will give the main body of input. All the subsequent keywords
will be grouped in the mpqc section of the input (that is, each keyword
will be prefixed with mpqc:).
mpqc: (
Next we give the mole 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 const RefKeyVal&
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.
mole<CLHF>: (
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 $ indicates that this is
a reference and the keyword following the $ is the actual location of
the molecule. The : 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 molecule keyword. However, if you follow
its parent classes up to MolecularEnergy, you'll find that molecule is
indeed read.
molecule = $:molecule
Just as we gave molecule, specify the basis set with the basis keyword
as follows:
basis = $:basis
Now we close off the parentheses we opened above and we are finished.
)
)
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. The src/bin/mpqc/samples
contains all of the sample inputs below:
o Hartree-Fock Energy
o MP2 Energy
o MP2-R12 energy
o Hartree-Fock Optimization
o Optimization with a Computed Guess Hessian
o Optimization Using Newton's Method
o Hartree-Fock Frequencies
o Giving Coordinates and a Guess Hessian
o Optimization with a Hydrogen Bond
o Fixed Coordinate Optimization
o Transition State Optimization
o Transition State Optimization with a Computed Guess Hessian
o Hartree-Fock energy with intermediate checkpointing
o MP2-R12 energy with intermediate checkpointing
o HF gradient computed from a previously computed HF wave funtion
o MP2 Energy computed using precomputed Hartree-Fock wave function
o CLHF energy using a CCA integrals component
Hartree-Fock Energy
The following input will compute the Hartree-Fock energy of water.
% 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
)
)
MP2 Energy
The following input will compute the MP2 energy of water.
% 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
)
)
)
MP2-R12 energy
The following will compute the MP2-R12 energy of water in standard
approximation A' (MP2-R12/A').
% 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
savestate = no
% method for computing the molecule's energy
mole<MBPT2_R12>: (
molecule = $:molecule
basis = $:basis
aux_basis = $:abasis
stdapprox = 'A''
nfzc = 1
memory = 16000000
integrals<IntegralCints>:()
% reference wavefunction
reference<CLHF>: (
molecule = $:molecule
basis = $:basis
memory = 16000000
integrals<IntegralCints>:()
)
)
)
Hartree-Fock Optimization
The following input will optimize the geometry of water using the
quasi-Newton method.
% 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 = '6-31G*'
molecule = $:molecule
)
mpqc: (
checkpoint = no
savestate = no
% molecular coordinates for optimization
coor<SymmMolecularCoor>: (
molecule = $:molecule
generator<IntCoorGen>: (
molecule = $:molecule
)
)
% method for computing the molecule's energy
mole<CLHF>: (
molecule = $:molecule
basis = $:basis
coor = $..:coor
memory = 16000000
)
% optimizer object for the molecular geometry
opt<QNewtonOpt>: (
function = $..:mole
update<BFGSUpdate>: ()
convergence<MolEnergyConvergence>: (
cartesian = yes
energy = $..:..:mole
)
)
)
Optimization with a Computed Guess Hessian
The following input will optimize the geometry of water using the
quasi-Newton method. The guess Hessian will be computed at a lower
level of theory.
% 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 = '6-31G*'
molecule = $:molecule
)
mpqc: (
checkpoint = no
savestate = no
% molecular coordinates for optimization
coor<SymmMolecularCoor>: (
molecule = $:molecule
generator<IntCoorGen>: (
molecule = $:molecule
)
)
% method for computing the molecule's energy
mole<CLHF>: (
molecule = $:molecule
basis = $:basis
coor = $..:coor
memory = 16000000
guess_hessian<FinDispMolecularHessian>: (
molecule = $:molecule
only_totally_symmetric = yes
eliminate_cubic_terms = no
checkpoint = no
energy<CLHF>: (
molecule = $:molecule
memory = 16000000
basis<GaussianBasisSet>: (
name = '3-21G'
molecule = $:molecule
)
)
)
)
% optimizer object for the molecular geometry
opt<QNewtonOpt>: (
function = $..:mole
update<BFGSUpdate>: ()
convergence<MolEnergyConvergence>: (
cartesian = yes
energy = $..:..:mole
)
)
)
Optimization Using Newton's Method
The following input will optimize the geometry of water using the
Newton's method. The Hessian will be computed at each step in the
optimization. However, Hessian recomputation is usually not worth the
cost; try using the computed Hessian as a guess Hessian for a quasi-
Newton method before resorting to a Newton optimization.
% Emacs should use -*- KeyVal -*- mode
% molecule specification
molecule<Molecule>: (
symmetry = c2v
unit = angstrom
{ atoms geometry } = {
O [ 0.00000000 0.00000000 0.36937294 ]
H [ 0.78397590 0.00000000 -0.18468647 ]
H [ -0.78397590 0.00000000 -0.18468647 ]
}
)
% basis set specification
basis<GaussianBasisSet>: (
name = '3-21G'
molecule = $:molecule
)
mpqc: (
checkpoint = no
savestate = no
restart = no
% molecular coordinates for optimization
coor<SymmMolecularCoor>: (
molecule = $:molecule
generator<IntCoorGen>: (
molecule = $:molecule
)
)
do_energy = no
do_gradient = no
% method for computing the molecule's energy
mole<CLHF>: (
molecule = $:molecule
basis = $:basis
memory = 16000000
coor = $..:coor
guess_wavefunction<CLHF>: (
molecule = $:molecule
total_charge = 0
basis<GaussianBasisSet>: (
molecule = $:molecule
name = 'STO-3G'
)
memory = 16000000
)
hessian<FinDispMolecularHessian>: (
only_totally_symmetric = yes
eliminate_cubic_terms = no
checkpoint = no
)
)
optimize = yes
% optimizer object for the molecular geometry
opt<NewtonOpt>: (
print_hessian = yes
max_iterations = 20
function = $..:mole
convergence<MolEnergyConvergence>: (
cartesian = yes
energy = $..:..:mole
)
)
)
Hartree-Fock Frequencies
The following input will compute Hartree-Fock frequencies by finite
displacements. A thermodynamic analysis will also be performed. If
optimization input is also provided, then the optimization will be run
first, then the frequencies.
% emacs should use -*- KeyVal -*- mode
% molecule specification
molecule<Molecule>: (
symmetry = C1
{ atoms geometry } = {
O [ 0.0000000000 0.0000000000 0.8072934188 ]
H [ 1.4325589285 0.0000000000 -0.3941980761 ]
H [ -1.4325589285 0.0000000000 -0.3941980761 ]
}
)
% 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
)
% vibrational frequency input
freq<MolecularFrequencies>: (
molecule = $:molecule
)
)
Giving Coordinates and a Guess Hessian
The following example shows several features that are really
independent. The variable coordinates are explicitly given, rather than
generated automatically. This is especially useful when a guess Hessian
is to be provided, as it is here. This Hessian, as given by the user,
is not complete and the QNewtonOpt object will fill in the missing
values using a guess the Hessian provided by the MolecularEnergy
object. Also, fixed coordinates are given in this sample input.
% emacs should use -*- KeyVal -*- mode
% molecule specification
molecule<Molecule>: (
symmetry = C1
{ atoms geometry } = {
H [ 0.088 2.006 1.438 ]
O [ 0.123 3.193 0.000 ]
H [ 0.088 2.006 -1.438 ]
O [ 4.502 5.955 -0.000 ]
H [ 2.917 4.963 -0.000 ]
H [ 3.812 7.691 -0.000 ]
}
)
% 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
coor = $..:coor
memory = 16000000
)
% molecular coordinates for optimization
coor<SymmMolecularCoor>: (
molecule = $:molecule
generator<IntCoorGen>: (
molecule = $:molecule
extra_bonds = [ 2 5 ]
)
% use these instead of generated coordinates
variable<SetIntCoor>: [
<StreSimpleCo>:( atoms = [ 2 5 ] )
<BendSimpleCo>:( atoms = [ 2 5 4 ] )
<OutSimpleCo>: ( atoms = [ 5 2 1 3 ] )
<SumIntCoor>: (
coor: [
<StreSimpleCo>:( atoms = [ 1 2 ] )
<StreSimpleCo>:( atoms = [ 2 3 ] )
]
coef = [ 1.0 1.0 ]
)
<SumIntCoor>: (
coor: [
<StreSimpleCo>:( atoms = [ 4 5 ] )
<StreSimpleCo>:( atoms = [ 4 6 ] )
]
coef = [ 1.0 1.0 ]
)
<BendSimpleCo>:( atoms = [ 1 2 3 ] )
<BendSimpleCo>:( atoms = [ 5 4 6 ] )
]
% these are fixed by symmetry anyway,
fixed<SetIntCoor>: [
<SumIntCoor>: (
coor: [
<StreSimpleCo>:( atoms = [ 1 2 ] )
<StreSimpleCo>:( atoms = [ 2 3 ] )
]
coef = [ 1.0 -1.0 ]
)
<SumIntCoor>: (
coor: [
<StreSimpleCo>:( atoms = [ 4 5 ] )
<StreSimpleCo>:( atoms = [ 4 6 ] )
]
coef = [ 1.0 -1.0 ]
)
<TorsSimpleCo>:( atoms = [ 2 5 4 6] )
<OutSimpleCo>:( atoms = [ 3 2 6 4 ] )
<OutSimpleCo>:( atoms = [ 1 2 6 4 ] )
]
)
% optimizer object for the molecular geometry
opt<QNewtonOpt>: (
function = $..:mole
update<BFGSUpdate>: ()
convergence<MolEnergyConvergence>: (
cartesian = yes
energy = $..:..:mole
)
% give a partial guess hessian in internal coordinates
% the missing elements will be filled in automatically
hessian = [
[ 0.0109261670 ]
[ -0.0004214845 0.0102746106 ]
[ -0.0008600592 0.0030051330 0.0043149957 ]
[ 0.0 0.0 0.0 ]
[ 0.0 0.0 0.0 ]
[ 0.0 0.0 0.0 ]
[ 0.0 0.0 0.0 ]
]
)
)
Optimization with a Hydrogen Bond
The automatic internal coordinate generator will fail if it cannot find
enough redundant internal coordinates. In this case, the internal
coordinate generator must be explicitly created in the input and given
extra connectivity information, as is shown below.
% emacs should use -*- KeyVal -*- mode
% molecule specification
molecule<Molecule>: (
symmetry = C1
{ atoms geometry } = {
H [ 0.088 2.006 1.438 ]
O [ 0.123 3.193 0.000 ]
H [ 0.088 2.006 -1.438 ]
O [ 4.502 5.955 -0.000 ]
H [ 2.917 4.963 -0.000 ]
H [ 3.812 7.691 -0.000 ]
}
)
% 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
coor = $..:coor
memory = 16000000
)
% molecular coordinates for optimization
coor<SymmMolecularCoor>: (
molecule = $:molecule
% give an internal coordinate generator that knows about the
% hydrogen bond between atoms 2 and 5
generator<IntCoorGen>: (
molecule = $:molecule
extra_bonds = [ 2 5 ]
)
)
% optimizer object for the molecular geometry
opt<QNewtonOpt>: (
function = $..:mole
update<BFGSUpdate>: ()
convergence<MolEnergyConvergence>: (
cartesian = yes
energy = $..:..:mole
)
)
)
Fixed Coordinate Optimization
This example shows how to selectively fix internal coordinates in an
optimization. Any number of linearly independent coordinates can be
given. These coordinates must remain linearly independent throughout
the optimization, a condition that might not hold since the coordinates
can be nonlinear.
By default, the initial fixed coordinates' values are taken from the
cartesian geometry given by the Molecule object; however, the molecule
will be displaced to the internal coordinate values given with the
fixed internal coordinates if have_fixed_values keyword is set to true,
as shown in this example. In this case, the initial cartesian geometry
should be reasonably close to the desired initial geometry and all of
the variable coordinates will be frozen to their original values during
the initial displacement.
% emacs should use -*- KeyVal -*- mode
% molecule specification
molecule<Molecule>: (
symmetry = CS
{ atoms geometry } = {
H [ 3.04 -0.69 -1.59 ]
H [ 3.04 -0.69 1.59 ]
N [ 2.09 -0.48 -0.00 ]
C [ -0.58 -0.15 0.00 ]
H [ -1.17 1.82 0.00 ]
H [ -1.41 -1.04 -1.64 ]
H [ -1.41 -1.04 1.64 ]
}
)
% basis set specification
basis<GaussianBasisSet>: (
name = '3-21G*'
molecule = $:molecule
)
mpqc: (
checkpoint = no
savestate = no
% molecular coordinates for optimization
coor<SymmMolecularCoor>: (
molecule = $:molecule
generator<IntCoorGen>: (
molecule = $:molecule
)
have_fixed_values = yes
fixed<SetIntCoor>: [
<OutSimpleCo>: ( value = -0.1
label = 'N-inversion'
atoms = [4 3 2 1] )
]
)
% method for computing the molecule's energy
mole<CLHF>: (
molecule = $:molecule
basis = $:basis
coor = $..:coor
memory = 16000000
)
% optimizer object for the molecular geometry
opt<QNewtonOpt>: (
max_iterations = 20
function = $..:mole
update<BFGSUpdate>: ()
convergence<MolEnergyConvergence>: (
cartesian = yes
energy = $..:..:mole
)
)
)
Transition State Optimization
This example shows a transition state optimization of the N-inversion
in $thrm{CH}_3thrm{NH}_2$ using mode following. The initial geometry
was obtained by doing a few fixed coordinate optimizations along the
inversion coordinate.
% emacs should use -*- KeyVal -*- mode
% molecule specification
molecule<Molecule>: (
symmetry = CS
{ atoms geometry } = {
H [ 3.045436 -0.697438 -1.596748 ]
H [ 3.045436 -0.697438 1.596748 ]
N [ 2.098157 -0.482779 -0.000000 ]
C [ -0.582616 -0.151798 0.000000 ]
H [ -1.171620 1.822306 0.000000 ]
H [ -1.417337 -1.042238 -1.647529 ]
H [ -1.417337 -1.042238 1.647529 ]
}
)
% basis set specification
basis<GaussianBasisSet>: (
name = '3-21G*'
molecule = $:molecule
)
mpqc: (
checkpoint = no
savestate = no
% molecular coordinates for optimization
coor<SymmMolecularCoor>: (
molecule = $:molecule
generator<IntCoorGen>: (
molecule = $:molecule
)
followed<OutSimpleCo> = [ 'N-inversion' 4 3 2 1 ]
)
% method for computing the molecule's energy
mole<CLHF>: (
molecule = $:molecule
basis = $:basis
coor = $..:coor
memory = 16000000
)
% optimizer object for the molecular geometry
opt<EFCOpt>: (
transition_state = yes
mode_following = yes
max_iterations = 20
function = $..:mole
update<PowellUpdate>: ()
convergence<MolEnergyConvergence>: (
cartesian = yes
energy = $..:..:mole
)
)
)
Transition State Optimization with a Computed Guess Hessian
This example shows a transition state optimization of the N-inversion
in $thrm{CH}_3thrm{NH}_2$ using mode following. The initial geometry
was obtained by doing a few fixed coordinate optimizations along the
inversion coordinate. An approximate guess Hessian will be computed,
which makes the optimiziation converge much faster in this case.
% emacs should use -*- KeyVal -*- mode
% molecule specification
molecule<Molecule>: (
symmetry = CS
{ atoms geometry } = {
H [ 3.045436 -0.697438 -1.596748 ]
H [ 3.045436 -0.697438 1.596748 ]
N [ 2.098157 -0.482779 -0.000000 ]
C [ -0.582616 -0.151798 0.000000 ]
H [ -1.171620 1.822306 0.000000 ]
H [ -1.417337 -1.042238 -1.647529 ]
H [ -1.417337 -1.042238 1.647529 ]
}
)
% basis set specification
basis<GaussianBasisSet>: (
name = '3-21G*'
molecule = $:molecule
)
mpqc: (
checkpoint = no
savestate = no
% molecular coordinates for optimization
coor<SymmMolecularCoor>: (
molecule = $:molecule
generator<IntCoorGen>: (
molecule = $:molecule
)
followed<OutSimpleCo> = [ 'N-inversion' 4 3 2 1 ]
)
% method for computing the molecule's energy
mole<CLHF>: (
molecule = $:molecule
basis = $:basis
coor = $..:coor
memory = 16000000
guess_hessian<FinDispMolecularHessian>: (
molecule = $:molecule
only_totally_symmetric = yes
eliminate_cubic_terms = no
checkpoint = no
energy<CLHF>: (
molecule = $:molecule
memory = 16000000
basis<GaussianBasisSet>: (
name = '3-21G'
molecule = $:molecule
)
)
)
)
% optimizer object for the molecular geometry
opt<EFCOpt>: (
transition_state = yes
mode_following = yes
max_iterations = 20
function = $..:mole
update<PowellUpdate>: ()
convergence<MolEnergyConvergence>: (
cartesian = yes
energy = $..:..:mole
)
)
)
Hartree-Fock energy with intermediate checkpointing
The following two sections demonstrate how MPQC can be used to save the
mole object periodically. This input will compute the Hartree-Fock
energy of water while saving the mole object every 3 iterations.
% 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 = yes
filename = 'h2o-rhf-STO3G'
checkpoint_freq = 3
savestate = no
% method for computing the molecule's energy
mole<CLHF>: (
molecule = $:molecule
basis = $:basis
memory = 16000000
)
)
The mole object will be saved to files named 'h2o-rhf-
STO3G.wfn.<iter#>.tmp' where <iter#> is the SCF iteration number (3, 6,
etc.). Only the most recent file is kept, files from previous
iterations are removed automatically. Keyword filename here is used to
set the default file name prefix.
MP2-R12 energy with intermediate checkpointing
The following input will compute the MP2-R12 energy of water in
standard approximation A' (MP2-R12/A') while saving the mole object at
intermediate checkpoints.
% 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 = yes
filename = 'h2o-mp2r12ap-vdz-avdz'
savestate = no
% method for computing the molecule's energy
mole<MBPT2_R12>: (
molecule = $:molecule
basis = $:basis
aux_basis = $:abasis
stdapprox = 'A''
nfzc = 1
memory = 16000000
integrals<IntegralCints>:()
% reference wavefunction
reference<CLHF>: (
molecule = $:molecule
basis = $:basis
memory = 16000000
integrals<IntegralCints>:()
)
)
)
The mole object will be saved to a file named h2o-mp2r12ap-vdz-
avdz.wfn". Keyword filename here is used to set the default file name
prefix. Objects of the MBPT2_R12 type are checkpointed after the HF
procedure, after the first integrals (SBS) transformation, and after
the optional second (ABS) transformation.
HF gradient computed from a previously computed HF wave funtion
The following will illustrate how to reuse previously computed
MolecularEnergy objects in subsequent computations. The first input
computes Hartree-Fock energy for water and saves the mole object to
file h2o-rhf-sto3g.wfn.
% 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 = yes
filename = 'h2o-rhf-sto3g'
% method for computing the molecule's energy
mole<CLHF>: (
molecule = $:molecule
basis = $:basis
memory = 16000000
)
)
The second input reuses the mole object from the previous run to
compute the gradient of the Hartree-Fock energy.
% emacs should use -*- KeyVal -*- mode
mpqc: (
checkpoint = no
savestate = no
restart = yes
restart_file = 'h2o-rhf-sto3g.wfn'
do_gradient = yes
)
MP2 Energy computed using precomputed Hartree-Fock wave function
The following input will compute the MP2 energy of water using a saved
Hartree-Fock wave function obtained using the first input from HF
gradient computed from a previously computed HF wave funtion.
% 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
)
% wave function file object specification
wfnfile<BcastStateInBin>:file = 'h2o-rhf-sto3g.wfn'
mpqc: (
checkpoint = no
savestate = no
% method for computing the molecule's energy
mole<MBPT2>: (
molecule = $:molecule
basis = $:basis
memory = 16000000
% reference wavefunction
reference<SavableStateProxy>: (
statein = $:wfnfile
object = 'CLHF'
)
)
)
Note that now object reference is of type SavableStateProxy, rather
than CLHF. SavableStateProxy is a special object type that can be
converted at runtime into the desired type (in this case, CLHF, as
indicated by object).
CLHF energy using a CCA integrals component
The following input will compute the CLHF energy of water using a CCA
integrals component via the IntegralCCA adaptor class.
% 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: (
% path to component libraries
cca_path = /usr/local/lib/cca
% sidl class names of components which will be instantiated
cca_load = MPQC.IntegralEvaluatorFactory
do_cca = yes
checkpoint = no
savestate = no
% method for computing the molecule's energy
mole<CLHF>: (
molecule = $:molecule
basis = $:basis
% cca integrals adaptor class
integrals<IntegralCCA>: (
molecule = $:molecule
% integral buffer type
integral_buffer = opaque
% integral package
integral_package = intv3
% factory component sidl class name
evaluator_factory = MPQC.IntegralEvaluatorFactory
)
)
)
Validating MPQC
After you compile MPQC, you should run the validation suite. You should
also run the validation suite if you upgrade your operating system
software, since this could change shared libraries that are linking
with MPQC and could affect the results. Note that the reference
validation suite has not been verified relative to an independent code,
except for a few spot checks. If you find that MPQC doesn't produce the
same answer as another quantum chemistry program that you trust, then
please promptly notify us and send all the details.
The top-level Makefile has several targets that can be used to check an
MPQC build. MPQC must be built before one of these targets is used:
check
The same as check0 below. This is only available from the top-level
directory and src/bin/mpqc/validate.
check0
Run the smallest MPQC verification suite. It tests basic
functionality. This is only available from the top-level directory
and src/bin/mpqc/validate.
check1
Run the intermediate MPQC verification suite. It runs most of the
tests, only leaving out very expensive runs. This is only available
from the top-level directory and src/bin/mpqc/validate.
check2
Run the complete MPQC verification suite. Depending on the
compilation and runtime environment, tests that are not expected to
work will be omitted. This is only available from the top-level
directory and src/bin/mpqc/validate.
check_clean
Remove MPQC verification suite output files. This is only available
from the top-level directory and src/bin/mpqc/validate.
testbuild
Verify that a variety of small test programs compile. If static
libraries are used, this will require a substantial amount of disk
space.
testrun
Run a variety of small test programs. This will build them if
necessary.
The check targets will run mpqc with the mpqcrun (see mpqcrun) command.
You can give arguments to mpqcrun by setting the MPQCRUN_ARGS variable
on the make command line.
The verification suite is in src/bin/mpqc/validate. After running it,
the output files can be found in src/bin/mpqc/validate/run. The check
targets will compare outputs that your build produced to the reference
files in src/bin/mpqc/validate/ref. The input files can be found with
the reference files. For each comparison, first the status (ok,
missing, or failed) for each file is printed. If both statuses are ok
then an E: is printed followed by the number of digits to which the
energies agree. If they agree to all digits 99 is printed. If a
gradient was computed, then Grad: is printed followed by the number of
digits to which the gradients in least agreement agree. Other
properties checked in this way include frequencies, diagnostics, and
populations.
If two numbers do not agree to the expected accuracy, then an asterisk,
*, is printed after the number of digits in agreement.
Finally, you can do a detailed comparison of the contents of the ref
and run subdirectories by typing make diff.
The input files in the verification suite are divided into several
categories:
h2o
These are simple tests that exercise many of MPQC's features.
h2omp2
Tests that further exercise MP2.
h2ofrq
Tests of H2 O frequencies with a variety of methods.
mbpt
These tests exercise MP2 as well as the open-shell perturbation
theory methods. The various available algorithms are tested as
well.
ckpt
Tests the checkpoint and restart capabilities.
symm1
Tests of point group symmetry.
symm2
More point group symmetry tests. These use basis sets with higher
angular momentum than #symm1#.
symm3
Tests automatic point group determination.
basis1
A variety of basis sets are tested for first row atoms along with
hydrogen and helium.
basis2
Basis sets test for second row atoms.
methods
Basic tests of several of MPQC's methods.
clscf
More tests of methods based on CLSCF.
hsosscf
More tests of methods based on HSOSSCF.
uscf
More tests of methods based on UnrestrictedSCF.
dft
More tests of the CLKS method.
mp2r12
More tests of MP2-R12.
ccaintv3
Tests of embedded CCA integrals components using intv3.
ccacints
Tests of embedded CCA integrals components using cints.
Running Psi 3 from MPQC
Psi 3 is a suite of ab initio 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:
o How the MPQC-Psi interface works
o Environmental Variables
o Preparing an input file
o Psi Execution Environment
o PsiWavefunction specializations
o More examples
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.
Environmental Variables
Several environmental variables are used to control MPQC-Psi
interaction:
PSIBIN
By default, MPQC will try to find Psi binaries under
/usr/local/psi/bin. Use PSIBIN environmental variable to point to
the right location.
The rest of the Psi environment is job specific and specified in the
input file.
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 (mpqc section, mole MolecularEnergy object, etc.). In
addition the following rules apply:
o 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.
o each Psi-specific Wavefunction object has to have a member object
psienv 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.
Psi Execution Environment
Each PsiWavefunction-derived class has to have a member object called
psienv of type PsiExEnv. The following keywords are used by its KeyVal
constructor:
cwd
The directory where to keep Psi input, checkpoint, stdout, stderr,
and other files. Default is /tmp.
fileprefix
The file prefix to use for Psi checkpoint, scratch, and some ASCII
files. Equivalent to keyword name in Psi psi:files:default section.
Defaults to psi.
stdout
The file into which to redirect standard output of Psi modules.
Defaults to psi.stdout.
stderr
The file into which to redirect standard error of Psi modules.
Defaults to psi.stderr.
nscratch
The number of locations over which to stripe Psi binary files.
Equivalent to keyword nvolume in Psi psi:files:default section.
Default is 1.
scratch
The locations over which to stripe Psi binary files. Equivalent to
keyword volumex in Psi psi:files:default section. There's no
default.
Here's an example:
psienv<PsiExEnv>: (
cwd = ./
fileprefix = psi.test
nscratch = 2
scratch = [ '/scratch1/' '/scratch2/' ]
)
PsiWavefunction specializations
Class PsiWavefunction is derived from class Wavefunction, hence its
KeyVal constructor uses all keywords that Wavefunction's KeyVal
constructor uses (basis, molecule, etc.). In addition,
PsiWavefunction's KeyVal constructor looks for the following keywords
in the input file:
psienv
The PsiExEnv object that provides job specific Psi environment.
There's no default.
docc
An optional array of integers that specifies the number of doubly-
occupied orbitals in each irrep.
socc
An optional array of integers that specifies the number of singly-
occupied orbitals in each irrep.
frozen_docc
An optional array of integers that specifies the number of doubly-
occupied orbitals in each irrep frozen in correlated computations.
frozen_uocc
An optional array of integers that specifies the number of
unoccupied orbitals in each irrep frozen in correlated
computations.
total_charge
The total charge of the system. This keyword is queried only if
neither docc nor socc are given.
multiplicity
The spin multiplicity of the system (2*M_S+1). This keyword is
queried only if neither docc nor socc are given.
memory
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).
Note that keywords docc, socc, frozen_docc, frozen_uocc, total_charge,
and multiplicity are used by appropriate specializations of
PsiWavefunctions, i.e. PsiCLHF only checks for docc, etc.
PsiWavefunction specializations PsiCCSD and PsiCCSD_T also look for
keyword reference 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:
%
% 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)'
)
)
%
% 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
)
)
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:
% 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
)
)
CCA Components
Common Component Architecture (CCA) component wrappers, conforming to
interfaces developed for the CCA Chemistry Component Toolkit, have been
created to encapsulate some MPQC functionality. The following
components are provided by MPQC:
o MPQC.Chemistry_QC_ModelFactory
o MPQC.ChemistryOpt_CoordinateModel
o MPQC.IntegralEvaluatorFactory
MPQC.Chemistry_QC_ModelFactory
This is an implementation of the Chemistry.QC.ModelFactory interface.
This factory produces model objects (implementing the
Chemistry.QC.Model interface) based on the MPQC package. The MPQC model
allows calculation of molecular energies and energy derivatives using a
variety of methods.
Provides Ports
o Chemistry.QC.ModelFactory ModelFactory
Uses Ports
o Chemistry.QC.MoleculeFactory MoleculeFactory (required)
Parameters
o theory The method for determining the electronic structure. Defaults
to HF.
o HF Hartree-Fock method.
o B3LYP Density Functional Theory (DFT) with B3LYP functional.
o Use keyval input for other options.
o basis The atomic orbital basis set. Defaults to STO-3G.
o Any basis set defined in the MPQC package.
o Use keyval input for mixed basis sets.
o molecule_filename Path to the molecule file (see cca-chem-generic
documentation for format). No default -- required.
o keyval_filename Path to the keyval input file (see below). No default
-- optional.
Keyval Input
The theory and basis parameters allow very basic calculations to be
performed. More complex calculations will require the use of a keyval
input file. The keyval file format is the same as that used to run MPQC
stand-alone, and any valid MPQC options may be used. The molecular
energy object must be named model. The user-supplied keyval cannot
contain a molecule section; the molecule section will be automatically
inserted by the ModelFactory using the required molecule_filename. This
molecule section should be referred to as $:molecule.
Example keyval input:
model<CLHF>:(
molecule=$:molecule
basis<GaussianBasisSet>:(
name = '6-31G'
molecule = $:molecule
)
)
MPQC.ChemistryOpt_CoordinateModel
This is an implementation of the ChemistryOpt.CoordinateModel interface
based on the MPQC package. It supports molecular structure optimization
in cartesian, symmetrized internal, and redundant internal coordinates.
Hessian approximation is supported.
Provides Ports
o ChemistryOpt.CoordinateModel CoordinateModel
Uses Ports
o Chemistry.QC.ModelFactory ModelFactory (required)
o Chemistry.QC.ModelFactory BackupModelFactory (optional)
o Chemistry.MoleculeViewer MoleculeViewer (optional)
A backup model factory may be supplied. If an error is detected in the
primary model, then a model obtained from the backup factory will be
used. The molecule viewer is currently only used to communicate with
the python viewer, in which case component instantiation and connection
is handled automatically.
Parameters
o grad_rms RMS gradient convergence criteria. Defaults to 0.00030.
o grad_max Max gradient convergence criteria. Defaults to 0.00045.
o disp_rms RMS displacement convergence criteria. Defaults to 0.00120.
o disp_max Max displacement convergence criteria. Defaults to 0.00180.
o coordinate_type Optimization coordinate type. Defaults to
symmetrized.
o cartesian Cartesian coordinates.
o symmetrized Symmetrized internal coordinates.
o redundant Redundant internal coordinates.
o multiple_guess_h Compute new guess Hessian at each call to
guess_hessian_solve() (true) or use guess from first iteration only
(false). Only meaningful in conjunction with solvers supporting use
of dense guess Hessians with limited-memory methods. Defaults to
true.
o use_current_geom If multiple_guess_h is true, either use the current
geometry (true) or the geometry at which the earliest correction pair
used by the solver was determined (false) when computing the guess
Hessian. Defaults to false.
MPQC.IntegralEvaluatorFactory
This is an implementation of the
Chemistry.QC.GaussianBasis.IntegralEvaluatorFactory interface. This
factory produces molecular integral evaluator objects based on the MPQC
package. This code is experimental and does not currently support
derivative integrals.
Provides Ports
o Chemistry.QC.GaussianBasis.IntegralEvaluatorFactory
IntegralEvaluatorFactory
Parameters
o package Integral package, either intv3 or cints. Defaults to intv3.
o integral_buffer Integral buffer type, either opaque or array. The
opaque option uses pointers and is therefore higher performance. The
array option may be used by components implemented in languages which
are not pointer-aware.
MPQC License
MPQC is open-source software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
MPQC Warranty
MPQC is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
Version 2.3.1 Fri Feb 19 2016 mpqc(1)
