1mpqc(1)                              MPQC                              mpqc(1)
2
3
4

NAME

6       mpqc - The Massively Parallel Quantum Chemistry program (MPQC) computes
7       the properties of molecules from first principles.
8
9       This documentation is divided into the following chapters:
10
11       o MPQC Overview
12       o Running MPQC
13       o MPQC Input
14       o Validating MPQC
15       o Running Psi 3 from MPQC
16       o CCA Components
17       o MPQC License
18       o MPQC Warranty

MPQC Overview

20       The Massively Parallel Quantum Chemistry program (MPQC) computes the
21       properties of molecules, ab initio, on a wide variety of computer
22       architectures.
23       MPQC can compute closed shell and general restricted open-shell
24       Hartree-Fock energies and gradients, second order open-shell
25       perturbation theory (OPT2[2]) and Z-averaged perturbation theory
26       (ZAPT2) energies, and second order closed shell Moeller-Plesset
27       perturbation theory energies and gradients. It also includes methods
28       for optimizing molecules in either Cartesian or internal coordinates.
29       MPQC is designed using object-oriented programming techniques and
30       implemented in the C++ programming language.

Running MPQC

32       This chapter explains how to run MPQC in a variety of environments.
33       The first two sections give general information on running MPQC:
34       o Command Line Options
35       o Environmental Variables
36       The final sections given specific information on running MPQC in
37       different environments:
38       o Shared Memory Multiprocessor with SysV IPC
39       o Shared Memory Multiprocessor with POSIX Threads
40       o Shared or Distributed Memory Multiprocessor with MPI
41       o Special Notes for MP2 Gradients
42       o Special Notes for MP2-R12 energies
43       o Special Notes for CCA Components
44   Command Line Options
45       MPQC can be given options followed by an optional input file name. If
46       the input file name is not given, it will default to 'mpqc.in'. The
47       following command line options are recognized:
48       -o  Gives the name of the output file. The default is the console.
49       -i  Convert a simple input file to an object oriented input file and
50           write the result to the ouput. No calculations are done.
51       -messagegrp
52           A ParsedKeyVal specification of a MessageGrp object. The default
53           depends on how MPQC was compiled.
54       -memorygrp
55           A ParsedKeyVal specification of a MemoryGrp object. The default
56           depends on how MPQC was compiled.
57       -threadgrp
58           A ParsedKeyVal specification of a ThreadGrp object. The default
59           depends on how MPQC was compiled.
60       -integral
61           A ParsedKeyVal specification of an Integral object. The default is
62           IntegralV3. Note that some MolecularEnergy specializations require
63           specific choices of Integral specializations and may not work with
64           IntegralV3.
65       -l  Sets a limit on the number of basis functions. The default is zero,
66           which means an unlimited number of basis functions.
67       -W  Sets the working directory. The default is the current directory.
68       -c  Check the input and exit.
69       -v  Print the version number.
70       -w  Print the warranty information (there is no warranty).
71       -d  If a debugger object was given in the input, start the debugger
72           running as soon as MPQC is started.
73       -h  Print a list of options.
74       -f  The name of an object-oriented input file. The default is mpqc.in.
75           This cannot be used if another input file is specified. This option
76           is deprecated, as both input file formats can be read by given the
77           input file name on the command line without any option flags.
78       -cca-path
79           A colon-separated list of directories in which CCA component
80           libraries may be found.
81       -cca-load
82           A colon-separated list of sidl class names for CCA components which
83           will be instantiated from the libraries found in the path given by
84           -cca-path
85       Some MPI environments do not pass the command line to slave programs,
86       but supply it when MPI_Init is called. To make MPQC call MPI_Init with
87       the correct arguments as early as possible use the configure option
88       --enable-always-use-mpi.
89   Environmental Variables
90       MPQC looks at five environmental variables to set up communication,
91       find library files, and specify the default Integral object. Machine
92       specific libraries and utilities to run programs in parallel might look
93       at other environment variables as well. The five that apply on all
94       platforms are:
95       SCLIBDIR
96           The name of the library directory. See the GaussianBasisSet
97           documentation and look below for more information.
98       MESSAGEGRP
99           A ParsedKeyVal specification of a MessageGrp object. The default
100           depends on how MPQC was compiled. See the MessageGrp class
101           documentation for more information.
102       MEMORYGRP
103           A ParsedKeyVal specification of a MemoryGrp object. The default
104           depends on how MPQC was compiled and the MessageGrp in use.
105       THREADGRP
106           A ParsedKeyVal specification of a ThreadGrp object. The default
107           depends on how MPQC was compiled.
108       INTEGRAL
109           A ParsedKeyVal specification of an Integral object. The default is
110           IntegralV3. Note that some MolecularEnergy specializations require
111           specific choices of Integral specializations and may not work with
112           IntegralV3.
113       By default, MPQC tries to find library files first in the lib
114       subdirectory of the installation directory and then the source code
115       directory. If the library files cannot be found, MPQC must be notified
116       of the new location with the environmental variable SCLIBDIR.
117       For example, if you need to run MPQC on a machine that doesn't have the
118       source code distribution in the same place as it was located on the
119       machine on which MPQC is compiled you must do something like the
120       following on the machine with the source code:
121       cd mpqc/lib
122       tar cvf ../sclib.tar basis atominfo.kv
123       Then transfer sclib.tar to the machine on which you want to run MPQC
124       and do something like
125       mkdir ~/sclib
126       cd ~/sclib
127       tar xvf ../sclib.tar
128       setenv SCLIBDIR ~/sclib
129       The setenv command is specific to the C-shell. You will need to do what
130       is appropriate for your shell.
131       The other three keywords specify objects. This is done by giving a mini
132       ParsedKeyVal input in a string. The object is anonymous, that is, no
133       keyword is associated with it. Here is an example:
134       setenv MESSAGEGRP '<ShmMessageGrp>:(n = 4)'
135   Shared Memory Multiprocessor with SysV IPC
136       By default, MPQC will run on only one CPU. To specify more, you can
137       give a ShmMessageGrp object on the command line. The following would
138       run MPQC in four processes:
139       mpqc -messagegrp '<ShmMessageGrp>:(n = 4)' input_file
140       Alternately, the ShmMessageGrp object can be given as an environmental
141       variable:
142       setenv MESSAGEGRP '<ShmMessageGrp>:(n = 4)'
143       mpqc input_file
144       If MPQC should unexpectedly die, shared memory segments and semaphores
145       will be left on the machine. These should be promptly cleaned up or
146       other jobs may be prevented from running successfully. To see if you
147       have any of these resources allocated, use the ipcs command. The output
148       will look something like:
149       IPC status from /dev/kmem as of Wed Mar 13 14:42:18 1996
150       T     ID     KEY        MODE       OWNER    GROUP
151       Message Queues:
152       Shared Memory:
153       m 288800 0x00000000 --rw-------  cljanss     user
154       Semaphores:
155       s    390 0x00000000 --ra-------  cljanss     user
156       s    391 0x00000000 --ra-------  cljanss     user
157       To remove the IPC resources used by cljanss in the above example on
158       IRIX, type:
159       ipcrm -m 288800
160       ipcrm -s 390
161       ipcrm -s 391
162       And on Linux, type:
163       ipcrm shm 288800
164       ipcrm sem 390
165       ipcrm sem 391
166   Shared Memory Multiprocessor with POSIX Threads
167       By default, MPQC will run with only one thread. To specify more, you
168       can give a PthreadThreadGrp object on the command line. MPQC is not
169       parallelized to as large an extent with threads as it is with the more
170       conventional distributed memory model, so you might not get the best
171       performance using this technique. On the other the memory overhead is
172       lower and no interprocess communication is needed.
173       The following would run MPQC in four threads:
174       mpqc -threadgrp '<PthreadThreadGrp>:(num_threads = 4)' input_file
175       Alternately, the PthreadThreadGrp object can be given as an
176       environmental variable:
177       setenv THREADGRP '<PthreadThreadGrp>:(num_threads = 4)'
178       mpqc input_file
179   Shared or Distributed Memory Multiprocessor with MPI
180       A MPIMessageGrp object is used to run using MPI. The number of nodes
181       used is determined by the MPI run-time and is not specified as input
182       data to MPIMessageGrp.
183       mpqc -messagegrp '<MPIMessageGrp>:()' input_file
184       Alternately, the MPIMessageGrp object can be given as an environmental
185       variable:
186       setenv MESSAGEGRP '<MPIMessageGrp>:()'
187       mpqc input_file
188       Usually, a special command is needed to start MPI jobs; typically it is
189       named mpirun.
190   Special Notes for MP2 Gradients
191       The MP2 gradient algorithm uses MemoryGrp object to access distributed
192       shared memory. The MTMPIMemoryGrp class is the most efficient and
193       reliable implementation of MemoryGrp. It requires a multi-thread aware
194       MPI implementation, which is still not common. To run MP2 gradients on
195       a machine with POSIX threads and an multi-thread aware MPI, use:
196       mpqc -messagegrp '<MPIMessageGrp>:()' \
197            -threadgrp '<PthreadThreadGrp>:()' \
198            -memorygrp '<MTMPIMemoryGrp>:()' \
199            input_file
200       or
201       setenv MESSAGEGRP '<MPIMessageGrp>:()'
202       setenv THREADGRP '<PthreadThreadGrp>:()'
203       setenv MEMORYGRP '<MTMPIMemoryGrp>:()'
204       mpqc input_file
205   Special Notes for MP2-R12 energies
206       Distributed Memory
207       The MP2-R12 energy algorithm is similar to the MP2 energy algorithm
208       that uses MemoryGrp object to access distributed memory. Hence the
209       MTMPIMemoryGrp is the recommended implementation of MemoryGrp for such
210       computations (see Special Notes for MP2 Gradients).
211       Disk I/O
212       In contrast to the MP2 energy and gradient algorithms, the MP2-R12
213       energy algorithm may have to use disk to store transformed MO integrals
214       if a single pass through the AO integrals is not possible due to
215       insufficient memory. The best option in such case is to increase the
216       total amount of memory available to the computation by either
217       increasing the number of tasks or the amount of memory per task or
218       both.
219       When increasing memory further is not possible, the user has to specify
220       which type of disk I/O should be used for the MP2-R12 energy algorithm.
221       It is done through the r12ints keyword in input for the MBPT2_R12
222       object. The default choice is to use POSIX I/O on the node on which
223       task 0 resides. This kind of disk I/O is guaranteed to work on all
224       parallel machines, provided there's enough disk space on the node.
225       However, this is hardly most efficient on machines with some sort of
226       parallel I/O available. On machines which have an efficient
227       implementation of MPI-IO the r12ints should be set instead to mpi-mem.
228       This will force the MBPT2_R12 object to use MPI-IO for disk I/O. It is
229       user's responsibility to make sure that the MO integrals file resides
230       on an MPI-IO-compatible file system. Hence the r12ints_file keyword,
231       which specifies the name of the MO integrals file, should be set to a
232       location which is guaranteed to work properly with MPI-IO. For example,
233       on IBM SP and other IBM machines which have General Parallel File
234       System (GPFS), the user should set r12ints = mpi-mem and r12ints_file
235       to a file on a GPFS file system.
236       Integral object
237       At the moment, MBPT2_R12 objects require specific specialization of
238       Integral, IntegralCints. Thus in order to compute MP2-R12 energies,
239       your version of MPQC needs to be compiled with support for
240       IntegralCints. A free, open-source library called libint is a
241       prerequisite for IntegralCintsIn order to use IntegralCints as the
242       default Integral object, add -integral '<IntegralCints>:()' to the
243       command line, or set environmental variable INTEGRAL to
244       '<IntegralCints>:()'.
245   Special Notes for CCA Components
246       Common Component Architecture (CCA)
247       Portions of MPQC functionality are being packaged into CCA components.
248       For general overviews of CCA technology and framework usage, please see
249       www.cca-forum.org (the tutorial in particular) and the cca-chem-apps
250       documentation. MPQC components may be utilized directly within the
251       ccaffeine framework, while some components may be instantiated and used
252       within MPQC itself, making use of an embedded CCA framework.
253       CCA Runtime Environment
254       For MPQC runs utilizing embedded components, the runtime environment
255       for the CCA framework must be specified. The colon-separated path used
256       to locate component libraries must be specified either using the -cca-
257       path command-line option or using the cca_path key within the mpqc
258       section of a keyval input. The colon-separated list of component sidl
259       class names which will be referenced within the input must be specified
260       using either the -cca-load command-line option or using the cca_load
261       key within the mpqc section of a keyval input. If defaults for the cca-
262       path and cca-load options are desired, do_cca must be set to yes in the
263       keyval input.

MPQC Input

265       MPQC supports two input formats. The primary input is an object
266       oriented format which gives users access to all of MPQC's options. The
267       second format allows access to a subset of MPQC's capabilities, but is
268       more intuitive and easier to learn. New users are advised to start with
269       the simplified format. MPQC can be used to convert the simplified
270       format to the full object-oriented format with the -i option.
271       Each of these input formats is described in the following two chapters:
272       o Simple Input
273       o Object-Oriented Input

Simple Input

275       The simple input format consists of keywords followed by a ':' followed
276       by a value. The keywords are case sensitive. The values might be
277       modified by options found in parenthesis. For example, the following
278       input performs an optimization of water using density functional theory
279       with the B3LYP exchange-correlation functional:
280       % B3LYP optimization of water
281       optimize: yes
282       method: KS (xc = B3LYP)
283       basis: 3-21G*
284       molecule: (angstrom)
285           O    0.172   0.000   0.000
286           H    0.745   0.000   0.754
287           H    0.745   0.000  -0.754
288       Comments begin with a % and continue to the end of the line. Basis set
289       names containing special characters, such as a space or parentheses,
290       must be quoted inside a pair of double quotes. The accepted keywords
291       are:
292       molecule
293           Gives the atoms types and coordinates. The following options can be
294           used
295       bohr
296           The coordinates are given in Bohr.
297       angstrom
298           The coordinates are given in Angstroms (the default).
299       charge
300           This option can be given after an 'element x y z' quadruple. This
301           will override the charge on the atom. For example, (charge = 0) can
302           be given for the ghost atoms in a counterpoise correction
303           calculation.
304       multiplicity
305           Gives the multiplicity of the molecule. The default is 1.
306       optimize
307           If yes, then an optimization will be performed. The default is no.
308           The following options can be given.
309       cartesian
310           Use Cartesian coordinates.
311       internal
312           Use internal coordinates.
313       redundant
314           Use redundant internal coordinates.
315       gradient
316           If yes, then a gradient calculation will be performed. The default
317           is no.
318       frequencies
319           If yes, then the frequencies will be obtained. The default is no.
320       charge
321           Specificies the charge on the molecule. The default is 0.
322       method
323           Specifices the method. There is no default and the possible values
324           are:
325       HF  Hartree-Fock. Unrestricted HF is used if multiplicity > 1
326       RHF
327           Restricted Hartree-Fock.
328       UHF
329           Unrestricted Hartree-Fock.
330       KS  Kohn-Sham. Unrestricted KS is used if multiplicity > 1
331       RKS
332           Restricted Kohn-Sham.
333       UKS
334           Unrestricted Kohn-Sham.
335       MP2
336           Second order Moeller-Plesset perturbation theory. Only available
337           for multiplicity = 1.
338       MP2-R12/A
339           The A version of MP2-R12. Only available for multiplicity = 1. An
340           auxiliary basis may be specified. No gradient, optimization, or
341           frequencies are possible.
342       MP2-R12/A'
343           The A' version of MP2-R12. Only available for multiplicity = 1. An
344           auxiliary basis may be specified. No gradient, optimization, or
345           frequencies are possible.
346       ZAPT2
347           Z-averaged perturbation theory. Only available for multiplicity >
348           1. No gradient, optimization, or frequencies are possible.
349       The following options are valid with the KS, RKS, and UKS methods:
350       grid
351           Specifies the grid to be used for numerical integrations. The
352           following values can be given:
353       xcoarse
354       coarse
355       medium
356       fine
357       xfine
358       ultrafine
359       xc  Specifies the exchange-correlation functional. There is no default.
360           See the table in the StdDenFunctional class documentation for the
361           possible values.
362       The following options are valid with the MP2-R12/A and MP2-R12/A'
363       methods. These options are mutually exclusive:
364       abs
365           Use the standard Auxiliary Basis Set method.
366       abs+
367           Use the standard Auxiliary Basis Set method, but use the union of
368           the orbital and the given auxiliary basis as the actual auxiliary
369           basis set used.
370       cabs
371           Use the Complementary Auxiliary Basis Set method.
372       cabs+
373           Use the Complementary Auxiliary Basis Set method, but use the union
374           of the orbital and the given auxiliary basis as the actual
375           auxiliary basis set used.
376       The following options are valid with the MP2-R12/A' method:
377       ebc
378           Assume the Extended Brillion Condition to hold. This is the
379           default.
380       gbc
381           Assume the Generalized Brillion Condition to hold. This is the
382           default.
383       !ebc
384           Do not assume the Extended Brillion Condition to hold.
385       !gbc
386           Do not assume the Generalized Brillion Condition to hold.
387       basis
388           Specifies the basis set. There is no default. See the table in the
389           GaussianBasisSet class documentation for the available basis sets.
390       auxbasis
391           Specifies the auxiliary basis set for MP2-R12 methods. There is no
392           default. See the table in the GaussianBasisSet class documentation
393           for the available basis sets.
394       restart
395           Set to yes to restart an optimization. The default is no.
396       checkpoint
397           Set to no to not save checkpoint files during an optimization. The
398           default is yes.
399       symmetry
400           Specifices the Schoenflies symbol of the point group of the
401           molecule. The default is auto, which will cause to program to find
402           the highest order Abelian subgroup of the molecule.
403       docc
404           Gives the number of doubly occupied orbitals in each each
405           irreducible representation in a parenthesized list. The symmetry
406           must be specified and not be auto. The method must be restricted.
407       socc
408           Gives the number of single occupied orbitals in each each
409           irreducible representation in a parenthesized list. The symmetry
410           must be specified and not be auto. The method must be restricted.
411       alpha
412           Gives the number of alpha occupied orbitals in each each
413           irreducible representation in a parenthesized list. The symmetry
414           must be specified and not be auto. The method must be unrestricted.
415       beta
416           Gives the number of beta occupied orbitals in each each irreducible
417           representation in a parenthesized list. The symmetry must be
418           specified and not be auto. The method must be unrestricted.
419       frozen_docc
420           Gives the number of frozen core orbitals. Can be either a single
421           integer or a parenthesized list giving the frozen core orbitals in
422           each irreducible representation. In the latter case the symmetry
423           must be given and not be auto.
424       frozen_uocc
425           Gives the number of frozen virtual orbitals. Can be either a single
426           integer or a parenthesized list giving the frozen virtual orbitals
427           in each irreducible representation. In the latter case the symmetry
428           must be given and not be auto.
429       memory
430           Gives a hint for the amount of memory in bytes that can be used.
431           This is typically a lower bound, more memory will be used in
432           practice and the exact amount cannot be precisely controlled. The
433           format is a fixed or floating point number optionally followed
434           (without spaces) by one of the following suffixes: KB, MB, GB, KIB,
435           MIB, or GIB.

Object-Oriented Input

437       MPQC is an object-oriented program that directly allows the user to
438       specify objects that MPQC then manipulates to obtain energies,
439       properties, etc. This makes the input very flexible, but very complex.
440       However, most calculations should be quite similar to the one of the
441       examples given later in this chapter. The best way to get started is to
442       use one of the example input files and modify it to meet your needs.
443       The object-oriented input format is described in the following
444       sections:
445       o Overview of the Object-Oriented Input
446       o A Walk-Through of an Object-Oriented Input File
447       o Sample Object-Oriented Input Files
448   Overview of the Object-Oriented Input
449       MPQC starts off by creating a ParsedKeyVal object that parses the input
450       file specified on the command line. The format of the input file is
451       documented in the KeyVal documentation . It is basically a free format
452       input that associates keywords and logical groupings of keywords with
453       values. The values can be scalars, arrays, or objects.
454       The keywords recognized by MPQC begin with the mpqc prefix. That is,
455       they must be nested between an mpqc:( and a ). Alternately, each
456       keyword can be individually prefixed by mpqc:. The primary keywords are
457       given below. Some of the keywords specify objects, in which case the
458       object will require more ParsedKeyVal input. These objects are created
459       from the input by using their ParsedKeyVal constructors. These
460       constructors are documented with the source code documentation for the
461       class.
462       mole
463           This is the most important keyword for MPQC. It specifies the
464           MolecularEnergy object. This is an object that knows how to compute
465           the energy of a molecule. The specializations of MolecularEnergy
466           that are most commonly used are CLKS, HSOSKS, UKS, CLHF, HSOSHF,
467           UHF, and MBPT2.
468       opt
469           This keyword must be specified for optimizations. It specifies an
470           Optimize object. Usually, QNewtonOpt is best for finding minima and
471           EFCOpt is best for transition states.
472       freq
473           This keyword must be specified to compute frequencies. It specifies
474           a MolecularFrequencies object.
475       thread
476           This specifies an object of type ThreadGrp that can be used to
477           advantage on shared-memory multiprocessor machines for certain
478           types of calculations. This keyword can be overridden by giving the
479           ThreadGrp in the environment or command line. See the section on
480           running MPQC for more information.
481       integrals
482           This specifies an object of type Integral that will be used as the
483           default integral evaluator. If MP2-R12 is used, then this should be
484           set to use IntegralCints with a line like integrals<IntegralCints>:
485           ().
486       checkpoint
487           The value of this keyword is boolean.
488           <ul>
489
490           <li><tt>true</tt> and optimization is to be performed <br>
491
492           <tt>opt</tt> object will be checkpointed after each iteration.
493           The checkpoint file suffix is '.ckpt'.
494
495           <li><tt>true</tt> and optimization is not performed <br>
496
497           <tt>mole</tt> object will be checkpointed at intermediate points.
498           The manner in which
499           <tt>mole</tt> will be checkpointed depends on its particular type.
500           The checkpoint file suffix is usually '.wfn', however
501           in general it will depend on the particular specialization of
502           <tt>MolecularEnergy</tt>.
503
504           </ul>
505
506           The default is to not checkpoint.
507           </dd>
508
509       checkpoint_freq
510           This specifies how often to checkpoint certain MolecularEnergy
511           specializations which compute iteratively. Currently, mole objects
512           of SCF type can use this keyword. The default is 1, which means to
513           checkpoint after every iteration.
514       savestate
515           The value of this keyword is boolean. If true, then the states of
516           the Optimize and MolecularEnergy objects will be saved after the
517           calculation completes. The output file suffixes are '.ckpt' and
518           '.wfn', respectively. The default is to save state.
519       restart
520           The value of this keyword is boolean. If true, mpqc will attempt to
521           restart the calculation. If the checkpoint file is not found, the
522           calculation will continue as if the value were false. The default
523           is true.
524       restart_file
525           This gives the name of a file from which restart information is
526           read. If the file name ends with '.wfn' then MPQC will try to
527           restore a MolecularEnergy object from it and query for the opt
528           object in the input file. If the file name ends with '.ckpt' MPQC
529           will try to restore an Optimize object from this file. The default
530           file name is formed by appending '.ckpt' to the input file name
531           with the extension removed.
532       do_energy
533           The value of this keyword is boolean. If true a single point energy
534           calculation will be done for the MolecularEnergy object given with
535           the mole keyword. The default is true.
536       do_gradient
537           The value of this keyword is boolean. If true a single point
538           gradient calculation will be done for the MolecularEnergy object
539           given with the mole keyword. The default is false.
540       do_cca
541           The value of this keywork is boolean. If true the cca embedded
542           framework will be initialized. The default is false.
543       cca_path
544           The value of this keyword is a string that provides a colon-
545           separated list of directories in which CCA component libraries may
546           be found.
547       cca_load
548           The value of this keyword is a string that provides a colon-
549           separated list of sidl class names for CCA components which will be
550           instantiated from the libraries found in the path given by
551           cca_path.
552       optimize
553           The value of this keyword is boolean. If true and the opt keyword
554           was set to a valid value, then an optimization will be performed.
555           The default is true.
556       write_pdb
557           The value of this keyword is boolean. If true a PDB file with the
558           molecular coordinates will be written.
559       filename
560           The value of this keyword is a string that gives a name from which
561           checkpoint and other filenames are constructed. The default is the
562           basename of the input file.
563       print_timings
564           If this is true, timing information is printed at the end of the
565           run. The default is true.
566       There are also some utility keywords that tell mpqc some technical
567       details about how to do the calculation:
568       debug
569           This optional keyword gives a Debugger object which can be used to
570           help find the problem if MPQC encounters a catastrophic error.
571       matrixkit
572           This optional keyword gives a SCMatrixKit specialization which is
573           used to produce matrices of the desired type. The default is a
574           ReplSCMatrixKit which replicates matrices on all of the nodes.
575           Other choices are not thoroughly tested.
576   A Walk-Through of an Object-Oriented Input File
577       This example input does a Hartree-Fock calculation on water. Following
578       is the entire input, followed by a breakdown with descriptions.
579       % This input does a Hartree-Fock calculation on water.
580       molecule<Molecule>: (
581         symmetry = C2V
582         unit = angstrom
583         { atoms geometry } = {
584           O     [     0.00000000     0.00000000     0.37000000 ]
585           H     [     0.78000000     0.00000000    -0.18000000 ]
586           H     [    -0.78000000     0.00000000    -0.18000000 ]
587         }
588       )
589       basis<GaussianBasisSet>: (
590         name = 'STO-3G'
591         molecule = $:molecule
592       )
593       mpqc: (
594         mole<CLHF>: (
595           molecule = $:molecule
596           basis = $:basis
597         )
598       )
599       We start with a descriptive comment. Comments begin with a %.
600       Everything from the % to the end of the line is ignored.
601       % This input does a Hartree-Fock calculation on water.
602       Now lets set up a Molecule object. The name of the object comes first,
603       it is molecule. Then, in angle brackets, comes the type of the
604       molecule, which is the class Molecule. The keyword and class name are
605       followed by a : and then several pieces of input grouped between a pair
606       of matching parentheses. These parentheses contain the information that
607       will be given to Molecule KeyVal constructor.
608       molecule<Molecule>: (
609       The point group of the molecule is needed. This is done by assigning
610       symmetry to a case insensitive Schoenflies symbol that is used to
611       initialize a PointGroup object. An Abelian point group should be used.
612         symmetry = C2V
613       The default unit for the Cartesian coordinates is Bohr. You can specify
614       other units by assigned unit to a string that will be used to
615       initialize a Units object.
616         unit = angstrom
617       Finally, the atoms and coordinates are given. This can be given in the
618       shorthand table syntax shown below. The headings of the table are the
619       keywords between the first pair of brackets. These are followed by an =
620       and another pair of brackets that contain the data. The first datum is
621       assigned to the first element of the array that corresponds to the
622       first heading, atom. The second datum is assigned to the first element
623       of the array associated with the second heading, geometry, and so on.
624       Here the second datum is actually a vector: the x, y and z coordinates
625       of the first atom.
626         { atoms                       geometry                   } = {
627           O     [     0.00000000     0.00000000     0.37000000 ]
628           H     [     0.78000000     0.00000000    -0.18000000 ]
629           H     [    -0.78000000     0.00000000    -0.18000000 ]
630         }
631       )
632       Next, a basis set object is given.
633       basis<GaussianBasisSet>: (
634         name = 'STO-3G'
635         molecule = $:molecule
636       )
637       Now we will give the main body of input. All the subsequent keywords
638       will be grouped in the mpqc section of the input (that is, each keyword
639       will be prefixed with mpqc:).
640       mpqc: (
641       Next we give the mole keyword which provides a specialization of the
642       MolecularEnergy class. In this case we will do a closed-shell Hartree-
643       Fock calculation. That is done with an object of type CLHF. The
644       keywords that CLHF accepts are given with the documentation for the
645       CLHF class, usually in the description of the const RefKeyVal&
646       constructor for the class. Also with the CLHF documentation is a list
647       of parent classes. Each of the parent classes may also have input. This
648       input is included with the rest of the input for the child class.
649         mole<CLHF>: (
650       The next line specifies the molecule to be used. There are two things
651       to note, first that this is actually a reference to complete molecule
652       specification elsewhere in the input file. The $ indicates that this is
653       a reference and the keyword following the $ is the actual location of
654       the molecule. The : in front of the keyword means that the keyword is
655       not relative to the current location in the input, but rather relative
656       to the root of the tree of keywords. Thus, this line grabs the molecule
657       that was specified above. The molecule object could have been placed
658       here, but frequently it is necessary that several objects refer to the
659       exact same object and this can only be done using references.
660       The second point is that if you look at the documentation for CLHF, you
661       will see that it doesn't read molecule keyword. However, if you follow
662       its parent classes up to MolecularEnergy, you'll find that molecule is
663       indeed read.
664           molecule = $:molecule
665       Just as we gave molecule, specify the basis set with the basis keyword
666       as follows:
667           basis = $:basis
668       Now we close off the parentheses we opened above and we are finished.
669         )
670       )
671   Sample Object-Oriented Input Files
672       The easiest way to get started with mpqc is to start with one of sample
673       inputs that most nearly matches your problem. The src/bin/mpqc/samples
674       contains all of the sample inputs below:
675       o Hartree-Fock Energy
676       o MP2 Energy
677       o MP2-R12 energy
678       o Hartree-Fock Optimization
679       o Optimization with a Computed Guess Hessian
680       o Optimization Using Newton's Method
681       o Hartree-Fock Frequencies
682       o Giving Coordinates and a Guess Hessian
683       o Optimization with a Hydrogen Bond
684       o Fixed Coordinate Optimization
685       o Transition State Optimization
686       o Transition State Optimization with a Computed Guess Hessian
687       o Hartree-Fock energy with intermediate checkpointing
688       o MP2-R12 energy with intermediate checkpointing
689       o HF gradient computed from a previously computed HF wave funtion
690       o MP2 Energy computed using precomputed Hartree-Fock wave function
691       o CLHF energy using a CCA integrals component
692   Hartree-Fock Energy
693       The following input will compute the Hartree-Fock energy of water.
694       % emacs should use -*- KeyVal -*- mode
695       % molecule specification
696       molecule<Molecule>: (
697         symmetry = C2V
698         unit = angstrom
699         { atoms geometry } = {
700           O     [     0.00000000     0.00000000     0.37000000 ]
701           H     [     0.78000000     0.00000000    -0.18000000 ]
702           H     [    -0.78000000     0.00000000    -0.18000000 ]
703         }
704       )
705       % basis set specification
706       basis<GaussianBasisSet>: (
707         name = 'STO-3G'
708         molecule = $:molecule
709       )
710       mpqc: (
711         checkpoint = no
712         savestate = no
713         % method for computing the molecule's energy
714         mole<CLHF>: (
715           molecule = $:molecule
716           basis = $:basis
717           memory = 16000000
718         )
719       )
720   MP2 Energy
721       The following input will compute the MP2 energy of water.
722       % emacs should use -*- KeyVal -*- mode
723       % molecule specification
724       molecule<Molecule>: (
725         symmetry = C2V
726         unit = angstrom
727         { atoms geometry } = {
728           O     [     0.00000000     0.00000000     0.37000000 ]
729           H     [     0.78000000     0.00000000    -0.18000000 ]
730           H     [    -0.78000000     0.00000000    -0.18000000 ]
731         }
732       )
733       % basis set specification
734       basis<GaussianBasisSet>: (
735         name = 'STO-3G'
736         molecule = $:molecule
737       )
738       mpqc: (
739         checkpoint = no
740         savestate = no
741         % method for computing the molecule's energy
742         mole<MBPT2>: (
743           molecule = $:molecule
744           basis = $:basis
745           memory = 16000000
746           % reference wavefunction
747           reference<CLHF>: (
748             molecule = $:molecule
749             basis = $:basis
750             memory = 16000000
751           )
752         )
753       )
754   MP2-R12 energy
755       The following will compute the MP2-R12 energy of water in standard
756       approximation A' (MP2-R12/A').
757       % emacs should use -*- KeyVal -*- mode
758       % molecule specification
759       molecule<Molecule>: (
760         symmetry = C2V
761         unit = angstrom
762         { atoms geometry } = {
763           O     [     0.00000000     0.00000000     0.37000000 ]
764           H     [     0.78000000     0.00000000    -0.18000000 ]
765           H     [    -0.78000000     0.00000000    -0.18000000 ]
766         }
767       )
768       % basis set specification
769       basis<GaussianBasisSet>: (
770         name = 'cc-pVDZ'
771         molecule = $:molecule
772       )
773       % auxiliary basis set specification
774       abasis<GaussianBasisSet>: (
775         name = 'aug-cc-pVDZ'
776         molecule = $:molecule
777       )
778       mpqc: (
779         checkpoint = no
780         savestate = no
781         % method for computing the molecule's energy
782         mole<MBPT2_R12>: (
783           molecule = $:molecule
784           basis = $:basis
785           aux_basis = $:abasis
786           stdapprox = 'A''
787           nfzc = 1
788           memory = 16000000
789           integrals<IntegralCints>:()
790           % reference wavefunction
791           reference<CLHF>: (
792             molecule = $:molecule
793             basis = $:basis
794             memory = 16000000
795             integrals<IntegralCints>:()
796           )
797         )
798       )
799   Hartree-Fock Optimization
800       The following input will optimize the geometry of water using the
801       quasi-Newton method.
802       % emacs should use -*- KeyVal -*- mode
803       % molecule specification
804       molecule<Molecule>: (
805         symmetry = C2V
806         unit = angstrom
807         { atoms geometry } = {
808           O     [     0.00000000     0.00000000     0.37000000 ]
809           H     [     0.78000000     0.00000000    -0.18000000 ]
810           H     [    -0.78000000     0.00000000    -0.18000000 ]
811         }
812       )
813       % basis set specification
814       basis<GaussianBasisSet>: (
815         name = '6-31G*'
816         molecule = $:molecule
817       )
818       mpqc: (
819         checkpoint = no
820         savestate = no
821         % molecular coordinates for optimization
822         coor<SymmMolecularCoor>: (
823           molecule = $:molecule
824           generator<IntCoorGen>: (
825             molecule = $:molecule
826           )
827         )
828         % method for computing the molecule's energy
829         mole<CLHF>: (
830           molecule = $:molecule
831           basis = $:basis
832           coor = $..:coor
833           memory = 16000000
834         )
835         % optimizer object for the molecular geometry
836         opt<QNewtonOpt>: (
837           function = $..:mole
838           update<BFGSUpdate>: ()
839           convergence<MolEnergyConvergence>: (
840             cartesian = yes
841             energy = $..:..:mole
842           )
843         )
844       )
845   Optimization with a Computed Guess Hessian
846       The following input will optimize the geometry of water using the
847       quasi-Newton method. The guess Hessian will be computed at a lower
848       level of theory.
849       % emacs should use -*- KeyVal -*- mode
850       % molecule specification
851       molecule<Molecule>: (
852         symmetry = C2V
853         unit = angstrom
854         { atoms geometry } = {
855           O     [     0.00000000     0.00000000     0.37000000 ]
856           H     [     0.78000000     0.00000000    -0.18000000 ]
857           H     [    -0.78000000     0.00000000    -0.18000000 ]
858         }
859       )
860       % basis set specification
861       basis<GaussianBasisSet>: (
862         name = '6-31G*'
863         molecule = $:molecule
864       )
865       mpqc: (
866         checkpoint = no
867         savestate = no
868         % molecular coordinates for optimization
869         coor<SymmMolecularCoor>: (
870           molecule = $:molecule
871           generator<IntCoorGen>: (
872             molecule = $:molecule
873           )
874         )
875         % method for computing the molecule's energy
876         mole<CLHF>: (
877           molecule = $:molecule
878           basis = $:basis
879           coor = $..:coor
880           memory = 16000000
881           guess_hessian<FinDispMolecularHessian>: (
882             molecule = $:molecule
883             only_totally_symmetric = yes
884             eliminate_cubic_terms = no
885             checkpoint = no
886             energy<CLHF>: (
887               molecule = $:molecule
888               memory = 16000000
889               basis<GaussianBasisSet>: (
890                 name = '3-21G'
891                 molecule = $:molecule
892               )
893             )
894           )
895         )
896         % optimizer object for the molecular geometry
897         opt<QNewtonOpt>: (
898           function = $..:mole
899           update<BFGSUpdate>: ()
900           convergence<MolEnergyConvergence>: (
901             cartesian = yes
902             energy = $..:..:mole
903           )
904         )
905       )
906   Optimization Using Newton's Method
907       The following input will optimize the geometry of water using the
908       Newton's method. The Hessian will be computed at each step in the
909       optimization. However, Hessian recomputation is usually not worth the
910       cost; try using the computed Hessian as a guess Hessian for a quasi-
911       Newton method before resorting to a Newton optimization.
912       % Emacs should use -*- KeyVal -*- mode
913       % molecule specification
914       molecule<Molecule>: (
915         symmetry = c2v
916         unit = angstrom
917         { atoms geometry } = {
918            O     [     0.00000000     0.00000000     0.36937294 ]
919            H     [     0.78397590     0.00000000    -0.18468647 ]
920            H     [    -0.78397590     0.00000000    -0.18468647 ]
921         }
922       )
923       % basis set specification
924       basis<GaussianBasisSet>: (
925         name = '3-21G'
926         molecule = $:molecule
927       )
928       mpqc: (
929         checkpoint = no
930         savestate = no
931         restart = no
932         % molecular coordinates for optimization
933         coor<SymmMolecularCoor>: (
934           molecule = $:molecule
935           generator<IntCoorGen>: (
936             molecule = $:molecule
937           )
938         )
939         do_energy = no
940         do_gradient = no
941         % method for computing the molecule's energy
942         mole<CLHF>: (
943           molecule = $:molecule
944           basis = $:basis
945           memory = 16000000
946           coor = $..:coor
947           guess_wavefunction<CLHF>: (
948             molecule = $:molecule
949             total_charge = 0
950             basis<GaussianBasisSet>: (
951               molecule = $:molecule
952               name = 'STO-3G'
953             )
954             memory = 16000000
955           )
956           hessian<FinDispMolecularHessian>: (
957             only_totally_symmetric = yes
958             eliminate_cubic_terms = no
959             checkpoint = no
960           )
961         )
962         optimize = yes
963         % optimizer object for the molecular geometry
964         opt<NewtonOpt>: (
965           print_hessian = yes
966           max_iterations = 20
967           function = $..:mole
968           convergence<MolEnergyConvergence>: (
969             cartesian = yes
970             energy = $..:..:mole
971           )
972         )
973       )
974   Hartree-Fock Frequencies
975       The following input will compute Hartree-Fock frequencies by finite
976       displacements. A thermodynamic analysis will also be performed. If
977       optimization input is also provided, then the optimization will be run
978       first, then the frequencies.
979       % emacs should use -*- KeyVal -*- mode
980       % molecule specification
981       molecule<Molecule>: (
982         symmetry = C1
983         { atoms geometry } = {
984           O     [  0.0000000000    0.0000000000    0.8072934188 ]
985           H     [  1.4325589285    0.0000000000   -0.3941980761 ]
986           H     [ -1.4325589285    0.0000000000   -0.3941980761 ]
987         }
988       )
989       % basis set specification
990       basis<GaussianBasisSet>: (
991         name = 'STO-3G'
992         molecule = $:molecule
993       )
994       mpqc: (
995         checkpoint = no
996         savestate = no
997         % method for computing the molecule's energy
998         mole<CLHF>: (
999           molecule = $:molecule
1000           basis = $:basis
1001           memory = 16000000
1002         )
1003       % vibrational frequency input
1004         freq<MolecularFrequencies>: (
1005           molecule = $:molecule
1006         )
1007       )
1008   Giving Coordinates and a Guess Hessian
1009       The following example shows several features that are really
1010       independent. The variable coordinates are explicitly given, rather than
1011       generated automatically. This is especially useful when a guess Hessian
1012       is to be provided, as it is here. This Hessian, as given by the user,
1013       is not complete and the QNewtonOpt object will fill in the missing
1014       values using a guess the Hessian provided by the MolecularEnergy
1015       object. Also, fixed coordinates are given in this sample input.
1016       % emacs should use -*- KeyVal -*- mode
1017       % molecule specification
1018       molecule<Molecule>: (
1019         symmetry = C1
1020         { atoms geometry } = {
1021             H    [ 0.088    2.006    1.438 ]
1022             O    [ 0.123    3.193    0.000 ]
1023             H    [ 0.088    2.006   -1.438 ]
1024             O    [ 4.502    5.955   -0.000 ]
1025             H    [ 2.917    4.963   -0.000 ]
1026             H    [ 3.812    7.691   -0.000 ]
1027         }
1028       )
1029       % basis set specification
1030       basis<GaussianBasisSet>: (
1031         name = 'STO-3G'
1032         molecule = $:molecule
1033       )
1034       mpqc: (
1035         checkpoint = no
1036         savestate = no
1037         % method for computing the molecule's energy
1038         mole<CLHF>: (
1039           molecule = $:molecule
1040           basis = $:basis
1041           coor = $..:coor
1042           memory = 16000000
1043         )
1044         % molecular coordinates for optimization
1045         coor<SymmMolecularCoor>: (
1046           molecule = $:molecule
1047           generator<IntCoorGen>: (
1048             molecule = $:molecule
1049             extra_bonds = [ 2 5 ]
1050           )
1051           % use these instead of generated coordinates
1052           variable<SetIntCoor>: [
1053             <StreSimpleCo>:( atoms = [ 2 5 ] )
1054             <BendSimpleCo>:( atoms = [ 2 5 4 ] )
1055             <OutSimpleCo>: ( atoms = [ 5 2 1 3 ] )
1056             <SumIntCoor>: (
1057               coor: [
1058                 <StreSimpleCo>:( atoms = [ 1 2 ] )
1059                 <StreSimpleCo>:( atoms = [ 2 3 ] )
1060                 ]
1061               coef = [ 1.0 1.0 ]
1062               )
1063             <SumIntCoor>: (
1064               coor: [
1065                 <StreSimpleCo>:( atoms = [ 4 5 ] )
1066                 <StreSimpleCo>:( atoms = [ 4 6 ] )
1067                 ]
1068               coef = [ 1.0 1.0 ]
1069               )
1070             <BendSimpleCo>:( atoms = [ 1 2 3 ] )
1071             <BendSimpleCo>:( atoms = [ 5 4 6 ] )
1072           ]
1073           % these are fixed by symmetry anyway,
1074           fixed<SetIntCoor>: [
1075             <SumIntCoor>: (
1076               coor: [
1077                 <StreSimpleCo>:( atoms = [ 1 2 ] )
1078                 <StreSimpleCo>:( atoms = [ 2 3 ] )
1079                 ]
1080               coef = [ 1.0 -1.0 ]
1081               )
1082             <SumIntCoor>: (
1083               coor: [
1084                 <StreSimpleCo>:( atoms = [ 4 5 ] )
1085                 <StreSimpleCo>:( atoms = [ 4 6 ] )
1086                 ]
1087               coef = [ 1.0 -1.0 ]
1088               )
1089             <TorsSimpleCo>:( atoms = [ 2 5 4 6] )
1090             <OutSimpleCo>:( atoms = [ 3 2 6 4 ] )
1091             <OutSimpleCo>:( atoms = [ 1 2 6 4 ] )
1092           ]
1093         )
1094         % optimizer object for the molecular geometry
1095         opt<QNewtonOpt>: (
1096           function = $..:mole
1097           update<BFGSUpdate>: ()
1098           convergence<MolEnergyConvergence>: (
1099             cartesian = yes
1100             energy = $..:..:mole
1101           )
1102           % give a partial guess hessian in internal coordinates
1103           % the missing elements will be filled in automatically
1104           hessian = [
1105               [  0.0109261670 ]
1106               [ -0.0004214845    0.0102746106  ]
1107               [ -0.0008600592    0.0030051330    0.0043149957 ]
1108               [  0.0             0.0             0.0          ]
1109               [  0.0             0.0             0.0          ]
1110               [  0.0             0.0             0.0          ]
1111               [  0.0             0.0             0.0          ]
1112            ]
1113         )
1114       )
1115   Optimization with a Hydrogen Bond
1116       The automatic internal coordinate generator will fail if it cannot find
1117       enough redundant internal coordinates. In this case, the internal
1118       coordinate generator must be explicitly created in the input and given
1119       extra connectivity information, as is shown below.
1120       % emacs should use -*- KeyVal -*- mode
1121       % molecule specification
1122       molecule<Molecule>: (
1123         symmetry = C1
1124         { atoms geometry } = {
1125             H    [ 0.088    2.006    1.438 ]
1126             O    [ 0.123    3.193    0.000 ]
1127             H    [ 0.088    2.006   -1.438 ]
1128             O    [ 4.502    5.955   -0.000 ]
1129             H    [ 2.917    4.963   -0.000 ]
1130             H    [ 3.812    7.691   -0.000 ]
1131         }
1132       )
1133       % basis set specification
1134       basis<GaussianBasisSet>: (
1135         name = 'STO-3G'
1136         molecule = $:molecule
1137       )
1138       mpqc: (
1139         checkpoint = no
1140         savestate = no
1141         % method for computing the molecule's energy
1142         mole<CLHF>: (
1143           molecule = $:molecule
1144           basis = $:basis
1145           coor = $..:coor
1146           memory = 16000000
1147         )
1148         % molecular coordinates for optimization
1149         coor<SymmMolecularCoor>: (
1150           molecule = $:molecule
1151           % give an internal coordinate generator that knows about the
1152           % hydrogen bond between atoms 2 and 5
1153           generator<IntCoorGen>: (
1154             molecule = $:molecule
1155             extra_bonds = [ 2 5 ]
1156           )
1157         )
1158         % optimizer object for the molecular geometry
1159         opt<QNewtonOpt>: (
1160           function = $..:mole
1161           update<BFGSUpdate>: ()
1162           convergence<MolEnergyConvergence>: (
1163             cartesian = yes
1164             energy = $..:..:mole
1165           )
1166         )
1167       )
1168   Fixed Coordinate Optimization
1169       This example shows how to selectively fix internal coordinates in an
1170       optimization. Any number of linearly independent coordinates can be
1171       given. These coordinates must remain linearly independent throughout
1172       the optimization, a condition that might not hold since the coordinates
1173       can be nonlinear.
1174       By default, the initial fixed coordinates' values are taken from the
1175       cartesian geometry given by the Molecule object; however, the molecule
1176       will be displaced to the internal coordinate values given with the
1177       fixed internal coordinates if have_fixed_values keyword is set to true,
1178       as shown in this example. In this case, the initial cartesian geometry
1179       should be reasonably close to the desired initial geometry and all of
1180       the variable coordinates will be frozen to their original values during
1181       the initial displacement.
1182       % emacs should use -*- KeyVal -*- mode
1183       % molecule specification
1184       molecule<Molecule>: (
1185         symmetry = CS
1186         { atoms geometry } = {
1187           H [  3.04 -0.69 -1.59 ]
1188           H [  3.04 -0.69  1.59 ]
1189           N [  2.09 -0.48 -0.00 ]
1190           C [ -0.58 -0.15  0.00 ]
1191           H [ -1.17  1.82  0.00 ]
1192           H [ -1.41 -1.04 -1.64 ]
1193           H [ -1.41 -1.04  1.64 ]
1194         }
1195       )
1196       % basis set specification
1197       basis<GaussianBasisSet>: (
1198         name = '3-21G*'
1199         molecule = $:molecule
1200       )
1201       mpqc: (
1202         checkpoint = no
1203         savestate = no
1204         % molecular coordinates for optimization
1205         coor<SymmMolecularCoor>: (
1206           molecule = $:molecule
1207           generator<IntCoorGen>: (
1208             molecule = $:molecule
1209           )
1210           have_fixed_values = yes
1211           fixed<SetIntCoor>: [
1212             <OutSimpleCo>: ( value = -0.1
1213                              label = 'N-inversion'
1214                              atoms = [4 3 2 1] )
1215             ]
1216         )
1217         % method for computing the molecule's energy
1218         mole<CLHF>: (
1219           molecule = $:molecule
1220           basis = $:basis
1221           coor = $..:coor
1222           memory = 16000000
1223         )
1224         % optimizer object for the molecular geometry
1225         opt<QNewtonOpt>: (
1226           max_iterations = 20
1227           function = $..:mole
1228           update<BFGSUpdate>: ()
1229           convergence<MolEnergyConvergence>: (
1230             cartesian = yes
1231             energy = $..:..:mole
1232           )
1233         )
1234       )
1235   Transition State Optimization
1236       This example shows a transition state optimization of the N-inversion
1237       in $thrm{CH}_3thrm{NH}_2$ using mode following. The initial geometry
1238       was obtained by doing a few fixed coordinate optimizations along the
1239       inversion coordinate.
1240       % emacs should use -*- KeyVal -*- mode
1241       % molecule specification
1242       molecule<Molecule>: (
1243         symmetry = CS
1244         { atoms geometry } = {
1245           H [  3.045436 -0.697438 -1.596748 ]
1246           H [  3.045436 -0.697438  1.596748 ]
1247           N [  2.098157 -0.482779 -0.000000 ]
1248           C [ -0.582616 -0.151798  0.000000 ]
1249           H [ -1.171620  1.822306  0.000000 ]
1250           H [ -1.417337 -1.042238 -1.647529 ]
1251           H [ -1.417337 -1.042238  1.647529 ]
1252         }
1253       )
1254       % basis set specification
1255       basis<GaussianBasisSet>: (
1256         name = '3-21G*'
1257         molecule = $:molecule
1258       )
1259       mpqc: (
1260         checkpoint = no
1261         savestate = no
1262         % molecular coordinates for optimization
1263         coor<SymmMolecularCoor>: (
1264           molecule = $:molecule
1265           generator<IntCoorGen>: (
1266             molecule = $:molecule
1267           )
1268           followed<OutSimpleCo> = [ 'N-inversion' 4 3 2 1 ]
1269         )
1270         % method for computing the molecule's energy
1271         mole<CLHF>: (
1272           molecule = $:molecule
1273           basis = $:basis
1274           coor = $..:coor
1275           memory = 16000000
1276         )
1277         % optimizer object for the molecular geometry
1278         opt<EFCOpt>: (
1279           transition_state = yes
1280           mode_following = yes
1281           max_iterations = 20
1282           function = $..:mole
1283           update<PowellUpdate>: ()
1284           convergence<MolEnergyConvergence>: (
1285             cartesian = yes
1286             energy = $..:..:mole
1287           )
1288         )
1289       )
1290   Transition State Optimization with a Computed Guess Hessian
1291       This example shows a transition state optimization of the N-inversion
1292       in $thrm{CH}_3thrm{NH}_2$ using mode following. The initial geometry
1293       was obtained by doing a few fixed coordinate optimizations along the
1294       inversion coordinate. An approximate guess Hessian will be computed,
1295       which makes the optimiziation converge much faster in this case.
1296       % emacs should use -*- KeyVal -*- mode
1297       % molecule specification
1298       molecule<Molecule>: (
1299         symmetry = CS
1300         { atoms geometry } = {
1301           H [  3.045436 -0.697438 -1.596748 ]
1302           H [  3.045436 -0.697438  1.596748 ]
1303           N [  2.098157 -0.482779 -0.000000 ]
1304           C [ -0.582616 -0.151798  0.000000 ]
1305           H [ -1.171620  1.822306  0.000000 ]
1306           H [ -1.417337 -1.042238 -1.647529 ]
1307           H [ -1.417337 -1.042238  1.647529 ]
1308         }
1309       )
1310       % basis set specification
1311       basis<GaussianBasisSet>: (
1312         name = '3-21G*'
1313         molecule = $:molecule
1314       )
1315       mpqc: (
1316         checkpoint = no
1317         savestate = no
1318         % molecular coordinates for optimization
1319         coor<SymmMolecularCoor>: (
1320           molecule = $:molecule
1321           generator<IntCoorGen>: (
1322             molecule = $:molecule
1323           )
1324           followed<OutSimpleCo> = [ 'N-inversion' 4 3 2 1 ]
1325         )
1326         % method for computing the molecule's energy
1327         mole<CLHF>: (
1328           molecule = $:molecule
1329           basis = $:basis
1330           coor = $..:coor
1331           memory = 16000000
1332           guess_hessian<FinDispMolecularHessian>: (
1333             molecule = $:molecule
1334             only_totally_symmetric = yes
1335             eliminate_cubic_terms = no
1336             checkpoint = no
1337             energy<CLHF>: (
1338               molecule = $:molecule
1339               memory = 16000000
1340               basis<GaussianBasisSet>: (
1341                 name = '3-21G'
1342                 molecule = $:molecule
1343               )
1344             )
1345           )
1346         )
1347         % optimizer object for the molecular geometry
1348         opt<EFCOpt>: (
1349           transition_state = yes
1350           mode_following = yes
1351           max_iterations = 20
1352           function = $..:mole
1353           update<PowellUpdate>: ()
1354           convergence<MolEnergyConvergence>: (
1355             cartesian = yes
1356             energy = $..:..:mole
1357           )
1358         )
1359       )
1360   Hartree-Fock energy with intermediate checkpointing
1361       The following two sections demonstrate how MPQC can be used to save the
1362       mole object periodically. This input will compute the Hartree-Fock
1363       energy of water while saving the mole object every 3 iterations.
1364       % emacs should use -*- KeyVal -*- mode
1365       % molecule specification
1366       molecule<Molecule>: (
1367         symmetry = C2V
1368         unit = angstrom
1369         { atoms geometry } = {
1370           O     [     0.00000000     0.00000000     0.37000000 ]
1371           H     [     0.78000000     0.00000000    -0.18000000 ]
1372           H     [    -0.78000000     0.00000000    -0.18000000 ]
1373         }
1374       )
1375       % basis set specification
1376       basis<GaussianBasisSet>: (
1377         name = 'STO-3G'
1378         molecule = $:molecule
1379       )
1380       mpqc: (
1381         checkpoint = yes
1382         filename = 'h2o-rhf-STO3G'
1383         checkpoint_freq = 3
1384         savestate = no
1385         % method for computing the molecule's energy
1386         mole<CLHF>: (
1387           molecule = $:molecule
1388           basis = $:basis
1389           memory = 16000000
1390         )
1391       )
1392       The mole object will be saved to files named 'h2o-rhf-
1393       STO3G.wfn.<iter#>.tmp' where <iter#> is the SCF iteration number (3, 6,
1394       etc.). Only the most recent file is kept, files from previous
1395       iterations are removed automatically. Keyword filename here is used to
1396       set the default file name prefix.
1397   MP2-R12 energy with intermediate checkpointing
1398       The following input will compute the MP2-R12 energy of water in
1399       standard approximation A' (MP2-R12/A') while saving the mole object at
1400       intermediate checkpoints.
1401       % emacs should use -*- KeyVal -*- mode
1402       % molecule specification
1403       molecule<Molecule>: (
1404         symmetry = C2V
1405         unit = angstrom
1406         { atoms geometry } = {
1407           O     [     0.00000000     0.00000000     0.37000000 ]
1408           H     [     0.78000000     0.00000000    -0.18000000 ]
1409           H     [    -0.78000000     0.00000000    -0.18000000 ]
1410         }
1411       )
1412       % basis set specification
1413       basis<GaussianBasisSet>: (
1414         name = 'cc-pVDZ'
1415         molecule = $:molecule
1416       )
1417       % auxiliary basis set specification
1418       abasis<GaussianBasisSet>: (
1419         name = 'aug-cc-pVDZ'
1420         molecule = $:molecule
1421       )
1422       mpqc: (
1423         checkpoint = yes
1424         filename = 'h2o-mp2r12ap-vdz-avdz'
1425         savestate = no
1426         % method for computing the molecule's energy
1427         mole<MBPT2_R12>: (
1428           molecule = $:molecule
1429           basis = $:basis
1430           aux_basis = $:abasis
1431           stdapprox = 'A''
1432           nfzc = 1
1433           memory = 16000000
1434           integrals<IntegralCints>:()
1435           % reference wavefunction
1436           reference<CLHF>: (
1437             molecule = $:molecule
1438             basis = $:basis
1439             memory = 16000000
1440             integrals<IntegralCints>:()
1441           )
1442         )
1443       )
1444       The mole object will be saved to a file named h2o-mp2r12ap-vdz-
1445       avdz.wfn'</tt>.  Keyword <tt>filename</tt> here is used to set the
1446       default file name prefix.  Objects of the <tt>MBPT2_R12</tt> type are
1447       checkpointed after the HF procedure, after the first integrals (SBS)
1448       transformation, and after the optional second (ABS) transformation.
1449
1450       @subsubsection mpqcoosamphfgradfromwfn HF gradient computed from a
1451       previously computed HF wave funtion
1452
1453       The following will illustrate how to reuse previously computed
1454       <tt>MolecularEnergy</tt> objects in subsequent computations. The first
1455       input computes Hartree-Fock energy for water and saves the
1456       <tt>mole</tt> object to file <tt>h2o-rhf-sto3g.wfn</tt>.
1457
1458       <pre> \% emacs should use -*- KeyVal -*- mode \% molecule specification
1459       molecule<Molecule>: (
1460         symmetry = C2V
1461         unit = angstrom
1462         { atoms geometry } = {
1463           O     [     0.00000000     0.00000000     0.37000000 ]
1464           H     [     0.78000000     0.00000000    -0.18000000 ]
1465           H     [    -0.78000000     0.00000000    -0.18000000 ]
1466         } ) \% basis set specification basis<GaussianBasisSet>: (
1467         name = 'STO-3G'
1468         molecule = $:molecule ) mpqc: (
1469         checkpoint = no
1470         savestate = yes
1471         filename = 'h2o-rhf-sto3g'
1472         \% method for computing the molecule's energy
1473         mole<CLHF>: (
1474           molecule = $:molecule
1475           basis = $:basis
1476           memory = 16000000
1477         ) ) </pre> <br>
1478
1479       The second input reuses the <tt>mole</tt> object from the previous run
1480       to compute the gradient of the Hartree-Fock energy.
1481
1482       <pre> \% emacs should use -*- KeyVal -*- mode mpqc: (
1483         checkpoint = no
1484         savestate = no
1485         restart = yes
1486         restart_file = 'h2o-rhf-sto3g.wfn'
1487         do_gradient = yes ) </pre> <br>
1488
1489       @subsubsection mpqcoosampmp2usinghfwfn MP2 Energy computed using
1490       precomputed Hartree-Fock wave function
1491
1492       The following input will compute the MP2 energy of water using a saved
1493       Hartree-Fock wave function obtained using the first input from \ref
1494       mpqcoosamphfgradfromwfn.
1495
1496       <pre> \% emacs should use -*- KeyVal -*- mode \% molecule specification
1497       molecule<Molecule>: (
1498         symmetry = C2V
1499         unit = angstrom
1500         { atoms geometry } = {
1501           O     [     0.00000000     0.00000000     0.37000000 ]
1502           H     [     0.78000000     0.00000000    -0.18000000 ]
1503           H     [    -0.78000000     0.00000000    -0.18000000 ]
1504         } ) \% basis set specification basis<GaussianBasisSet>: (
1505         name = 'STO-3G'
1506         molecule = $:molecule ) \% wave function file object specification
1507       wfnfile<BcastStateInBin>:file = 'h2o-rhf-sto3g.wfn' mpqc: (
1508         checkpoint = no
1509         savestate = no
1510         \% method for computing the molecule's energy
1511         mole<MBPT2>: (
1512           molecule = $:molecule
1513           basis = $:basis
1514           memory = 16000000
1515           \% reference wavefunction
1516           reference<SavableStateProxy>: (
1517             statein = $:wfnfile
1518             object = 'CLHF'
1519           )
1520         ) ) </pre> <br>
1521
1522       Note that now object <tt>reference</tt> is of type
1523       <tt>SavableStateProxy</tt>, rather than <tt>CLHF</tt>.
1524       <tt>SavableStateProxy</tt> is a special object type that can be
1525       converted at runtime into the desired type (in this case,
1526       <tt>CLHF</tt>, as indicated by <tt>object</tt>).
1527
1528       @subsubsection mpqcoosamphfusingcca CLHF energy using a CCA integrals
1529       component
1530
1531       The following input will compute the CLHF energy of water using a CCA
1532       integrals component via the IntegralCCA adaptor class.
1533
1534       <pre> \% emacs should use -*- KeyVal -*- mode \% molecule specification
1535       molecule<Molecule>: (
1536         symmetry = C2V
1537         unit = angstrom
1538         { atoms geometry } = {
1539           O     [     0.00000000     0.00000000     0.37000000 ]
1540           H     [     0.78000000     0.00000000    -0.18000000 ]
1541           H     [    -0.78000000     0.00000000    -0.18000000 ]
1542         } ) \% basis set specification basis<GaussianBasisSet>: (
1543         name = 'STO-3G'
1544         molecule = $:molecule ) mpqc: (
1545         \% path to component libraries
1546         cca_path = /usr/local/lib/cca
1547         \% sidl class names of components which will be instantiated
1548         cca_load = MPQC.IntegralEvaluatorFactory
1549         do_cca = yes
1550         checkpoint = no
1551         savestate = no
1552         \% method for computing the molecule's energy
1553         mole<CLHF>: (
1554           molecule = $:molecule
1555           basis = $:basis
1556           \% cca integrals adaptor class
1557           integrals<IntegralCCA>: (
1558             molecule = $:molecule
1559             \% integral buffer type
1560             integral_buffer = opaque
1561             \% integral package
1562             integral_package = intv3
1563             \% factory component sidl class name
1564             evaluator_factory = MPQC.IntegralEvaluatorFactory
1565           )
1566         ) ) </pre> <br>
1567
1568       <br> @section mpqcval Validating MPQC
1569
1570        After you compile MPQC, you should run the validation suite.  You
1571       should also run the validation suite if you upgrade your operating
1572       system software, since this could change shared libraries that are
1573       linking with MPQC and could affect the results.  Note that the
1574       reference validation suite has not been verified relative to an
1575       independent code, except for a few spot checks.  If you find that MPQC
1576       doesn't produce the same answer as another quantum chemistry program
1577       that you trust, then please promptly notify us and send all the
1578       details.
1579
1580        The top-level Makefile has several targets that can be used to check
1581       an MPQC build.  MPQC must be built before one of these targets is used:
1582       <dl>
1583         <dt><tt>check</tt><dd>The same as <tt>check0</tt> below.  This
1584                               is only available from the top-level directory
1585                               and <tt>src/bin/mpqc/validate</tt>.
1586         <dt><tt>check0</tt><dd>Run the smallest MPQC verification suite.
1587                               It tests basic functionality.  This
1588                               is only available from the top-level directory
1589                               and <tt>src/bin/mpqc/validate</tt>.
1590         <dt><tt>check1</tt><dd>Run the intermediate MPQC verification suite.
1591                               It runs most of the tests, only leaving out
1592                               very expensive runs.  This
1593                               is only available from the top-level directory
1594                               and <tt>src/bin/mpqc/validate</tt>.
1595         <dt><tt>check2</tt><dd>Run the complete MPQC verification suite.
1596                               Depending on the compilation and runtime
1597                               environment, tests that are not expected
1598                               to work will be omitted.  This
1599                               is only available from the top-level directory
1600                               and <tt>src/bin/mpqc/validate</tt>.
1601         <dt><tt>check_clean</tt><dd>Remove MPQC verification suite output
1602       files.
1603                               This is only available from the top-level
1604       directory
1605                               and <tt>src/bin/mpqc/validate</tt>.
1606         <dt><tt>testbuild</tt><dd>Verify that a variety of small test
1607       programs
1608                               compile.  If static libraries are used, this
1609                               will require a substantial amount of disk
1610       space.
1611         <dt><tt>testrun</tt><dd>Run a variety of small test programs.  This
1612                               will build them if necessary.  </dl>
1613
1614       The check targets will run mpqc with the mpqcrun (see \ref mpqcrun)
1615       command.  You can give arguments to mpqcrun by setting the
1616       <tt>MPQCRUN_ARGS</tt> variable on the make command line.
1617
1618       The verification suite is in <tt>src/bin/mpqc/validate</tt>.  After
1619       running it, the output files can be found in
1620       <tt>src/bin/mpqc/validate/run</tt>.  The check targets will compare
1621       outputs that your build produced to the reference files in
1622       <tt>src/bin/mpqc/validate/ref</tt>.  The input files can be found with
1623       the reference files.  For each comparison, first the status
1624       (<tt>ok</tt>, <tt>missing</tt>, or <tt>failed</tt>) for each file is
1625       printed.  If both statuses are <tt>ok</tt> then an <tt>E:</tt> is
1626       printed followed by the number of digits to which the energies agree.
1627       If they agree to all digits <tt>99</tt> is printed.  If a gradient was
1628       computed, then <tt>Grad:</tt> is printed followed by the number of
1629       digits to which the gradients in least agreement agree.  Other
1630       properties checked in this way include frequencies, diagnostics, and
1631       populations.
1632
1633         If two numbers do not agree to the expected accuracy, then an
1634       asterisk, <tt>*</tt>, is printed after the number of digits in
1635       agreement.
1636
1637         Finally, you can do a detailed comparison of the contents of the
1638       <tt>ref</tt> and <tt>run</tt> subdirectories by typing <tt>make
1639       diff</tt>.
1640
1641       The input files in the verification suite are divided into several
1642       categories: <dl>
1643         <dt><tt>h2o</tt><dd>These are simple tests that exercise many of
1644       MPQC's
1645               features.
1646
1647         <dt><tt>h2omp2</tt><dd>Tests that further exercise MP2.
1648
1649         <dt><tt>h2ofrq</tt><dd>Tests of H<sub>2</sub>O frequencies with a
1650       variety
1651               of methods.
1652
1653         <dt><tt>mbpt</tt><dd>These tests exercise MP2 as well as the open-
1654       shell
1655               perturbation theory methods.  The various available
1656               algorithms are tested as well.
1657
1658         <dt><tt>ckpt</tt><dd>Tests the checkpoint and restart capabilities.
1659
1660         <dt><tt>symm1</tt><dd>Tests of point group symmetry.
1661
1662         <dt><tt>symm2</tt><dd>More point group symmetry tests.  These use
1663       basis
1664               sets with higher angular momentum than #symm1#.
1665
1666         <dt><tt>symm3</tt><dd>Tests automatic point group determination.
1667
1668         <dt><tt>basis1</tt><dd>A variety of basis sets are tested for first
1669       row
1670               atoms along with hydrogen and helium.
1671
1672         <dt><tt>basis2</tt><dd>Basis sets test for second row atoms.
1673
1674         <dt><tt>methods</tt><dd>Basic tests of several of MPQC's methods.
1675
1676         <dt><tt>clscf</tt><dd>More tests of methods based on CLSCF.
1677
1678         <dt><tt>hsosscf</tt><dd>More tests of methods based on HSOSSCF.
1679
1680         <dt><tt>uscf</tt><dd>More tests of methods based on UnrestrictedSCF.
1681
1682         <dt><tt>dft</tt><dd>More tests of the CLKS method.
1683
1684         <dt><tt>mp2r12</tt><dd>More tests of MP2-R12.
1685
1686         <dt><tt>ccaintv3</tt><dd>Tests of embedded CCA integrals components
1687       using <tt>intv3</tt>.
1688
1689         <dt><tt>ccacints</tt><dd>Tests of embedded CCA integrals components
1690       using <tt>cints</tt>.
1691
1692       </dl>
1693
1694       <br>
1695
1696       @section mpqcpsi Running Psi 3 from MPQC
1697
1698       <a href='http://www.psicode.org/'>Psi 3</a> is a suite of <i>ab
1699       initio</i> codes related to the original Psi package started in Prof.
1700       Fritz Schaefer's group at UC Berkeley. Current version of MPQC works
1701       with stable versions of Psi 3 starting with 3.2.0.  From now on we will
1702       refer to Psi 3 as simply Psi.  Psi is written primarily in C and
1703       executes in serial mode only.  The interface between Psi and MPQC is
1704       intended mainly for Psi users who wish to exploit MPQC's geometry
1705       optimization and frequency analyses capabilities with Psi energies and
1706       gradients.
1707
1708       The following sections explain how to use Psi from MPQC:
1709
1710       <ul>
1711         <li> \ref psiworks
1712         <li> \ref psienv
1713         <li> \ref psiinp
1714         <li> \ref psiexenv
1715         <li> \ref psiwfn
1716         <li> \ref examples </ul>
1717
1718       @subsection psiworks How the MPQC-Psi interface works
1719
1720       The current version of the interface is rather slim. It is only
1721       possible to import energies and gradients computed with Psi into MPQC,
1722       i.e. wave functions cannot be imported. All MPQC-Psi interaction
1723       happens via text files and system calls.  MPQC generates input file for
1724       Psi, calls appropriate Psi modules, and then parses the output files
1725       for energies and gradients.
1726
1727
1728       @subsection psienv Environmental Variables
1729
1730       Several environmental variables are used to control MPQC-Psi
1731       interaction: <dl> <dt><tt>PSIBIN</tt><dd> By default, MPQC will try to
1732       find Psi binaries under <tt>/usr/local/psi/bin</tt>.  Use
1733       <tt>PSIBIN</tt> environmental variable to point to the right location.
1734       </dl> The rest of the Psi environment is job specific and specified in
1735       the input file.
1736
1737
1738       @subsection psiinp Preparing an input file
1739
1740       As noted above, MPQC parses the input file, and as such the input file
1741       has to be in the MPQC OO input format. All features of usual MPQC input
1742       files are there (<tt>mpqc</tt> section, <tt>mole</tt> MolecularEnergy
1743       object, etc.).  In addition the following rules apply: <ul>
1744         <li> instead of using MPQC Wavefunction objects (CLHF, MBPT2, etc.),
1745       the Psi specific Wavefunction types (i.e. specializations of
1746       PsiWavefunction) have to be used.  Presently the following
1747       specializations are supported: PsiCLHF, PsiHSOSHF, PsiUHF, PsiCCSD,
1748       PsiCCSD_T . The first three are directly analogous to MPQC Wavefunction
1749       types CLHF, HSOSHF, and UHF. The latter two do not have MPQC analogs
1750       yet. See appropriate class documentation on how to specify them
1751       properly.
1752         <li> each Psi-specific Wavefunction object has to have a member
1753       object <tt>psienv</tt> of type PsiExEnv. PsiExEnv contains job specific
1754       information, such as the directory in which Psi input, output, and
1755       checkpoint files will be kept, filename prefix, scratch directories,
1756       etc.  It makes sense to define one such object and simply refer to it
1757       from all PsiWavefunction objects. See PsiExEnv class documentation for
1758       more info.  </ul>
1759
1760       @subsection psiexenv Psi Execution Environment
1761
1762       Each PsiWavefunction-derived class has to have a member object called
1763       <tt>psienv</tt> of type PsiExEnv. The following keywords are used by
1764       its KeyVal constructor: <dl> <dt><tt>cwd</tt><dd> The directory where
1765       to keep Psi input, checkpoint, stdout, stderr, and other files. Default
1766       is <tt>/tmp</tt>.  <dt><tt>fileprefix</tt><dd> The file prefix to use
1767       for Psi checkpoint, scratch, and some ASCII files.  Equivalent to
1768       keyword <tt>name</tt> in Psi <tt>psi:files:default</tt> section.
1769       Defaults to <tt>psi</tt>.  <dt><tt>stdout</tt><dd> The file into which
1770       to redirect standard output of Psi modules.  Defaults to
1771       <tt>psi.stdout</tt>.  <dt><tt>stderr</tt><dd> The file into which to
1772       redirect standard error of Psi modules.  Defaults to
1773       <tt>psi.stderr</tt>.  <dt><tt>nscratch</tt><dd> The number of locations
1774       over which to stripe Psi binary files. Equivalent to keyword
1775       <tt>nvolume</tt> in Psi <tt>psi:files:default</tt> section.  Default is
1776       1.  <dt><tt>scratch</tt><dd> The locations over which to stripe Psi
1777       binary files. Equivalent to keyword <tt>volume<i>x</i></tt> in Psi
1778       <tt>psi:files:default</tt> section.  There's no default.  </dl>
1779
1780       Here's an example: <pre>
1781         psienv<PsiExEnv>: (
1782           cwd = ./
1783           fileprefix = psi.test
1784           nscratch = 2
1785           scratch = [ '/scratch1/' '/scratch2/' ]
1786         ) </pre> <br>
1787
1788
1789       @subsection psiwfn PsiWavefunction specializations
1790
1791       Class PsiWavefunction is derived from class Wavefunction, hence its
1792       KeyVal constructor uses all keywords that Wavefunction's KeyVal
1793       constructor uses (<tt>basis</tt>, <tt>molecule</tt>, etc.).  In
1794       addition, PsiWavefunction's KeyVal constructor looks for the following
1795       keywords in the input file: <dl> <dt><tt>psienv</tt><dd> The PsiExEnv
1796       object that provides job specific Psi environment. There's no default.
1797       <dt><tt>docc</tt><dd> An optional array of integers that specifies the
1798       number of doubly-occupied orbitals in each irrep.
1799       <dt><tt>socc</tt><dd> An optional array of integers that specifies the
1800       number of singly-occupied orbitals in each irrep.
1801       <dt><tt>frozen_docc</tt><dd> An optional array of integers that
1802       specifies the number of doubly-occupied orbitals in each irrep frozen
1803       in correlated computations.  <dt><tt>frozen_uocc</tt><dd> An optional
1804       array of integers that specifies the number of unoccupied orbitals in
1805       each irrep frozen in correlated computations.
1806       <dt><tt>total_charge</tt><dd> The total charge of the system. This
1807       keyword is queried only if neither <tt>docc</tt> nor <tt>socc</tt> are
1808       given.  <dt><tt>multiplicity</tt><dd> The spin multiplicity of the
1809       system (2*M_S+1).  This keyword is queried only if neither
1810       <tt>docc</tt> nor <tt>socc</tt> are given.  <dt><tt>memory</tt><dd> The
1811       number of bytes of memory Psi modules associated with this
1812       PsiWavefunction are allowed to use. Default is 2000000 (2 million
1813       bytes, approximately 2 MB).  </dl> Note that keywords <tt>docc</tt>,
1814       <tt>socc</tt>, <tt>frozen_docc</tt>, <tt>frozen_uocc</tt>,
1815       <tt>total_charge</tt>, and <tt>multiplicity</tt> are used by
1816       appropriate specializations of PsiWavefunctions, i.e. PsiCLHF only
1817       checks for <tt>docc</tt>, etc.
1818
1819       PsiWavefunction specializations PsiCCSD and PsiCCSD_T also look for
1820       keyword <tt>reference</tt> which specifies the reference wave function
1821       (an object of type PsiSCF). All classes for correlated Psi wave
1822       functions will require such an object.
1823
1824       Here are a few examples of PsiWavefunctions: <pre>
1825         \%
1826         \% ROHF DZ on F atom
1827         \%
1828         mole<PsiHSOSHF>: (
1829           docc = [ 2 0 0 0 0 1 1 0 ] socc = [ 0 0 0 0 0 0 0 1]
1830           memory = 10000000
1831
1832           \% Psi Environment data
1833           psienv<PsiExEnv>: (
1834             cwd = ./
1835             fileprefix = f.dz.test
1836             stdout = f.dz.test.stdout
1837             stderr = f.dz.test.stderr
1838             nscratch = 1
1839             scratch = [ '/scratch/mpqc/' ]
1840           )
1841
1842           \% MolecularEnergy input
1843           molecule<Molecule>: (
1844               {atoms geometry} = {
1845                 F  [   0.0  0.0   0.0 ]
1846                }
1847             )
1848
1849           \% Basis input
1850           basis<GaussianBasisSet>: (
1851               molecule = $..:molecule
1852               name = 'DZ (Dunning)'
1853             )
1854
1855         ) </pre> <br>
1856
1857       <pre>
1858         \%
1859         \% RHF CCSD/cc-pVDZ on water
1860         \%
1861         mole<PsiCCSD>: (
1862           frozen_docc = [1 0 0 0]
1863           memory = 40000000
1864
1865           \% Psi Environment data
1866           psienv<PsiExEnv>: (
1867             cwd = ./
1868             fileprefix = h2o.ccpvdz.ccsd.test
1869             nscratch = 1
1870             scratch = [ '/tmp/' ]
1871           )
1872
1873           \% MolecularEnergy input
1874           molecule<Molecule>: (
1875               {atoms geometry} = {
1876                 H  [  -1.5  0.0  -0.3 ]
1877                 H  [   1.5  0.0  -0.3 ]
1878                 O  [   0.0  0.0   1.0 ]
1879                }
1880             )
1881
1882           \% Basis input
1883           basis<GaussianBasisSet>: (
1884               molecule = $..:molecule
1885               name = 'cc-pVDZ'
1886             )
1887
1888           reference<PsiCLHF>: (
1889             psienv = $..:psienv
1890             molecule = $..:molecule
1891             basis = $..:basis
1892             total_charge = 0
1893             multiplicity = 1
1894           )
1895         ) </pre> <br>
1896
1897
1898       @subsection examples More examples
1899
1900       This section contains some examples of complete inputs that specify an
1901       MPQC/Psi computations.
1902
1903       Here's an optimization + subsequent frequency analysis on water
1904       molecule at the RHF CCSD 6-311G** level: <pre> \% Emacs should use -*-
1905       KeyVal -*- mode \% this file was automatically generated \% label:
1906       water test series \% molecule specification molecule<Molecule>: (
1907         symmetry = C2V
1908         unit = angstrom
1909         { atoms geometry } = {
1910            O     [     0.000000000000     0.000000000000     0.369372944000 ]
1911            H     [     0.783975899000     0.000000000000    -0.184686472000 ]
1912            H     [    -0.783975899000     0.000000000000    -0.184686472000 ]
1913         } ) \% basis set specification basis<GaussianBasisSet>: (
1914         name = '6-311G**'
1915         molecule = $:molecule ) \% Psi environment specification
1916       psienv<PsiExEnv>: (
1917             cwd = ./
1918             fileprefix = mpqcpsi
1919             stdout = mpqcpsi.stdout
1920             stderr = mpqcpsi.stderr
1921             nscratch = 1
1922             scratch = [ '/scratch/evaleev/' ] )
1923
1924       mpqc: (
1925         checkpoint = no
1926         savestate = no
1927         restart = no
1928         coor<SymmMolecularCoor>: (
1929           molecule = $:molecule
1930           generator<IntCoorGen>: (
1931             molecule = $:molecule
1932           )
1933         )
1934         \% molecular coordinates for optimization  do_energy = yes
1935         do_gradient = no
1936         \% method for computing the molecule's energy
1937         mole<PsiCCSD>: (
1938           molecule = $:molecule
1939           basis = $:basis
1940           coor = $..:coor
1941           psienv = $:psienv
1942           memory = 32000000
1943           reference<PsiCLHF>: (
1944             psienv = $:psienv
1945             molecule = $:molecule
1946             total_charge = 0
1947             multiplicity = 1
1948             basis = $:basis
1949             memory = 32000000
1950           )
1951           hessian<FinDispMolecularHessian>: (
1952             point_group<PointGroup>: symmetry = C2V
1953             checkpoint = no
1954             restart = no
1955           )
1956         )
1957         optimize = yes
1958         \% optimizer object for the molecular geometry
1959         opt<QNewtonOpt>: (
1960           max_iterations = 20
1961           function = $..:mole
1962           update<BFGSUpdate>: ()
1963           convergence<MolEnergyConvergence>: (
1964             cartesian = yes
1965             energy = $..:..:mole
1966           )
1967         ) \% vibrational frequency input
1968         freq<MolecularFrequencies>: (
1969           point_group<PointGroup>: symmetry = C2V
1970           molecule = $:molecule
1971         ) ) </pre> <br>
1972
1973       <br>
1974
1975       @section mpqccomponents CCA Components
1976
1977       Common Component Architecture (CCA) component wrappers, conforming to
1978       interfaces developed for the <a href='http://www.cca-forum.org/~cca-
1979       chem'>CCA Chemistry Component Toolkit</a>, have been created to
1980       encapsulate some MPQC functionality.  The following components are
1981       provided by MPQC:
1982
1983
1984       <ul>
1985         <li> \ref modelfac
1986         <li> \ref coormodel
1987         <li> \ref evalfac </ul>
1988
1989       @subsection modelfac MPQC.Chemistry_QC_ModelFactory
1990
1991       This is an implementation of the Chemistry.QC.ModelFactory interface.
1992       This factory produces model objects (implementing the
1993       Chemistry.QC.Model interface) based on the MPQC package.  The MPQC
1994       model allows calculation of molecular energies and energy derivatives
1995       using a variety of methods.
1996
1997       @subsubsection modelfacpp Provides Ports <ul>
1998         <li>Chemistry.QC.ModelFactory <em>ModelFactory</em> </ul>
1999
2000       @subsubsection modelfacup Uses Ports <ul>
2001         <li>Chemistry.QC.MoleculeFactory <em>MoleculeFactory</em> (required)
2002       </ul>
2003
2004       @subsubsection modelfacparam Parameters <ul>
2005         <li><b>theory</b> The method for determining the electronic
2006       structure.
2007             Defaults to HF.
2008             <ul>
2009                <li> <em>HF</em>  Hartree-Fock method.
2010                <li> <em>B3LYP</em> Density Functional Theory (DFT) with
2011                     B3LYP functional.
2012                <li> Use keyval input for other options.
2013             </ul>
2014         <li><b>basis</b> The atomic orbital basis set.  Defaults to
2015       <em>STO-3G</em>.
2016             <ul>
2017                <li> Any basis set defined in the MPQC package.
2018                <li> Use keyval input for mixed basis sets.
2019             </ul>
2020          <li><b>molecule_filename</b> Path to the molecule file (see cca-
2021       chem-generic
2022              documentation for format).  No default &ndash; required.
2023          <li><b>keyval_filename</b> Path to the keyval input file (see
2024       below).
2025              No default &ndash; optional.  </ul>
2026
2027       @subsubsection modelfackeyval Keyval Input The <b>theory</b> and
2028       <b>basis</b> parameters allow very basic calculations to be performed.
2029       More complex calculations will require the use of a keyval input file.
2030       The keyval file format is the same as that used to run MPQC stand-
2031       alone, and any valid MPQC options may be used.  The molecular energy
2032       object must be named <tt>model</tt>.  The user-supplied keyval cannot
2033       contain a molecule section; the molecule section will be automatically
2034       inserted by the ModelFactory using the required
2035       <b>molecule_filename</b>.  This molecule section should be referred to
2036       as <tt>$:molecule</tt>.
2037
2038       Example keyval input: <pre>
2039         model<CLHF>:(
2040           molecule=$:molecule
2041           basis<GaussianBasisSet>:(
2042             name = '6-31G" molecule = $:molecule ) )
2043
2044   MPQC.ChemistryOpt_CoordinateModel
2045        This is an implementation of the ChemistryOpt.CoordinateModel
2046       interface based on the MPQC package. It supports molecular structure
2047       optimization in cartesian, symmetrized internal, and redundant internal
2048       coordinates. Hessian approximation is supported.
2049
2050   Provides Ports
2051
2052
2053       o ChemistryOpt.CoordinateModel CoordinateModel
2054
2055
2056   Uses Ports
2057
2058
2059       o Chemistry.QC.ModelFactory ModelFactory (required)
2060       o Chemistry.QC.ModelFactory BackupModelFactory (optional)
2061       o Chemistry.MoleculeViewer MoleculeViewer (optional)
2062
2063       A backup model factory may be supplied. If an error is detected in the
2064       primary model, then a model obtained from the backup factory will be
2065       used. The molecule viewer is currently only used to communicate with
2066       the python viewer, in which case component instantiation and connection
2067       is handled automatically.
2068
2069   Parameters
2070
2071
2072       o grad_rms RMS gradient convergence criteria. Defaults to 0.00030.
2073       o grad_max Max gradient convergence criteria. Defaults to 0.00045.
2074       o disp_rms RMS displacement convergence criteria. Defaults to 0.00120.
2075       o disp_max Max displacement convergence criteria. Defaults to 0.00180.
2076       o coordinate_type Optimization coordinate type. Defaults to
2077         symmetrized.
2078
2079         o cartesian Cartesian coordinates.
2080         o symmetrized Symmetrized internal coordinates.
2081         o redundant Redundant internal coordinates.
2082       o multiple_guess_h Compute new guess Hessian at each call to
2083         guess_hessian_solve() (true) or use guess from first iteration only
2084         (false). Only meaningful in conjunction with solvers supporting use
2085         of dense guess Hessians with limited-memory methods. Defaults to
2086         true.
2087       o use_current_geom If multiple_guess_h is true, either use the current
2088         geometry (true) or the geometry at which the earliest correction pair
2089         used by the solver was determined (false) when computing the guess
2090         Hessian. Defaults to false.
2091
2092
2093   MPQC.IntegralEvaluatorFactory
2094        This is an implementation of the
2095       Chemistry.QC.GaussianBasis.IntegralEvaluatorFactory interface. This
2096       factory produces molecular integral evaluator objects based on the MPQC
2097       package. This code is experimental and does not currently support
2098       derivative integrals.
2099
2100   Provides Ports
2101
2102
2103       o Chemistry.QC.GaussianBasis.IntegralEvaluatorFactory
2104         IntegralEvaluatorFactory
2105
2106
2107   Parameters
2108
2109
2110       o package Integral package, either intv3 or cints. Defaults to intv3.
2111       o integral_buffer Integral buffer type, either opaque or array. The
2112         opaque option uses pointers and is therefore higher performance. The
2113         array option may be used by components implemented in languages which
2114         are not pointer-aware.
2115
2116
2117

MPQC License

2119        MPQC is open-source software; you can redistribute it and/or modify it
2120       under the terms of the GNU General Public License as published by the
2121       Free Software Foundation; either version 2 of the License, or (at your
2122       option) any later version.
2123
2124

MPQC Warranty

2126        MPQC is distributed in the hope that it will be useful, but WITHOUT
2127       ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
2128       FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
2129       for more details.
2130
2131
2132
2133
2134
2135Version 2.3.1                   Thu Jan 19 2023                        mpqc(1)
Impressum