mpqc(1) MPQC mpqc(1) NAME mpqc - The Massively Parallel Quantum Chemistry program (MPQC) computes the properties of molecules from first principles. This documentation is divided into the following chapters: o MPQC Overview o Running MPQC o MPQC Input o Validating MPQC o Running Psi 3 from MPQC o CCA Components o MPQC License o MPQC Warranty MPQC Overview The Massively Parallel Quantum Chemistry program (MPQC) computes the prop- erties of molecules, ab initio, on a wide variety of computer architec- tures. MPQC can compute closed shell and general restricted open-shell Hartree- Fock energies and gradients, second order open-shell perturbation theory (OPT2[2]) and Z-averaged perturbation theory (ZAPT2) energies, and second order closed shell Moeller-Plesset perturbation theory energies and gradi- ents. It also includes methods for optimizing molecules in either Cartesian or internal coordinates. MPQC is designed using object-oriented programming techniques and imple- mented in the C++ programming language. Running MPQC This chapter explains how to run MPQC in a variety of environments. The first two sections give general information on running MPQC: o Command Line Options o Environmental Variables The final sections given specific information on running MPQC in different environments: o Shared Memory Multiprocessor with SysV IPC o Shared Memory Multiprocessor with POSIX Threads o Shared or Distributed Memory Multiprocessor with MPI o Special Notes for MP2 Gradients o Special Notes for MP2-R12 energies o Special Notes for CCA Components Command Line Options MPQC can be given options followed by an optional input file name. If the input file name is not given, it will default to 'mpqc.in'. The following command line options are recognized: -o Gives the name of the output file. The default is the console. -i Convert a simple input file to an object oriented input file and write the result to the ouput. No calculations are done. -messagegrp A ParsedKeyVal specification of a MessageGrp object. The default de- pends on how MPQC was compiled. -memorygrp A ParsedKeyVal specification of a MemoryGrp object. The default depends on how MPQC was compiled. -threadgrp A ParsedKeyVal specification of a ThreadGrp object. The default depends on how MPQC was compiled. -integral A ParsedKeyVal specification of an Integral object. The default is In- tegralV3. Note that some MolecularEnergy specializations require spe- cific choices of Integral specializations and may not work with Inte- gralV3. -l Sets a limit on the number of basis functions. The default is zero, which means an unlimited number of basis functions. -W Sets the working directory. The default is the current directory. -c Check the input and exit. -v Print the version number. -w Print the warranty information (there is no warranty). -d If a debugger object was given in the input, start the debugger running as soon as MPQC is started. -h Print a list of options. -f The name of an object-oriented input file. The default is mpqc.in. This cannot be used if another input file is specified. This option is dep- recated, as both input file formats can be read by given the input file name on the command line without any option flags. -cca-path A colon-separated list of directories in which CCA component libraries may be found. -cca-load A colon-separated list of sidl class names for CCA components which will be instantiated from the libraries found in the path given by -cca-path Some MPI environments do not pass the command line to slave programs, but supply it when MPI_Init is called. To make MPQC call MPI_Init with the cor- rect arguments as early as possible use the configure option --enable-al- ways-use-mpi. Environmental Variables MPQC looks at five environmental variables to set up communication, find library files, and specify the default Integral object. Machine specific libraries and utilities to run programs in parallel might look at other en- vironment variables as well. The five that apply on all platforms are: SCLIBDIR The name of the library directory. See the GaussianBasisSet documenta- tion and look below for more information. MESSAGEGRP A ParsedKeyVal specification of a MessageGrp object. The default de- pends on how MPQC was compiled. See the MessageGrp class documentation for more information. MEMORYGRP A ParsedKeyVal specification of a MemoryGrp object. The default depends on how MPQC was compiled and the MessageGrp in use. THREADGRP A ParsedKeyVal specification of a ThreadGrp object. The default depends on how MPQC was compiled. INTEGRAL A ParsedKeyVal specification of an Integral object. The default is In- tegralV3. Note that some MolecularEnergy specializations require spe- cific choices of Integral specializations and may not work with Inte- gralV3. By default, MPQC tries to find library files first in the lib subdirectory of the installation directory and then the source code directory. If the library files cannot be found, MPQC must be notified of the new location with the environmental variable SCLIBDIR. For example, if you need to run MPQC on a machine that doesn't have the source code distribution in the same place as it was located on the machine on which MPQC is compiled you must do something like the following on the machine with the source code: cd mpqc/lib tar cvf ../sclib.tar basis atominfo.kv Then transfer sclib.tar to the machine on which you want to run MPQC and do something like mkdir ~/sclib cd ~/sclib tar xvf ../sclib.tar setenv SCLIBDIR ~/sclib The setenv command is specific to the C-shell. You will need to do what is appropriate for your shell. The other three keywords specify objects. This is done by giving a mini ParsedKeyVal input in a string. The object is anonymous, that is, no key- word is associated with it. Here is an example: setenv MESSAGEGRP '<ShmMessageGrp>:(n = 4)' Shared Memory Multiprocessor with SysV IPC By default, MPQC will run on only one CPU. To specify more, you can give a ShmMessageGrp object on the command line. The following would run MPQC in four processes: mpqc -messagegrp '<ShmMessageGrp>:(n = 4)' input_file Alternately, the ShmMessageGrp object can be given as an environmental variable: setenv MESSAGEGRP '<ShmMessageGrp>:(n = 4)' mpqc input_file If MPQC should unexpectedly die, shared memory segments and semaphores will be left on the machine. These should be promptly cleaned up or other jobs may be prevented from running successfully. To see if you have any of these resources allocated, use the ipcs command. The output will look something like: IPC status from /dev/kmem as of Wed Mar 13 14:42:18 1996 T ID KEY MODE OWNER GROUP Message Queues: Shared Memory: m 288800 0x00000000 --rw------- cljanss user Semaphores: s 390 0x00000000 --ra------- cljanss user s 391 0x00000000 --ra------- cljanss user To remove the IPC resources used by cljanss in the above example on IRIX, type: ipcrm -m 288800 ipcrm -s 390 ipcrm -s 391 And on Linux, type: ipcrm shm 288800 ipcrm sem 390 ipcrm sem 391 Shared Memory Multiprocessor with POSIX Threads By default, MPQC will run with only one thread. To specify more, you can give a PthreadThreadGrp object on the command line. MPQC is not paral- lelized to as large an extent with threads as it is with the more conven- tional distributed memory model, so you might not get the best performance using this technique. On the other the memory overhead is lower and no in- terprocess communication is needed. The following would run MPQC in four threads: mpqc -threadgrp '<PthreadThreadGrp>:(num_threads = 4)' input_file Alternately, the PthreadThreadGrp object can be given as an environmental variable: setenv THREADGRP '<PthreadThreadGrp>:(num_threads = 4)' mpqc input_file Shared or Distributed Memory Multiprocessor with MPI A MPIMessageGrp object is used to run using MPI. The number of nodes used is determined by the MPI run-time and is not specified as input data to MPIMessageGrp. mpqc -messagegrp '<MPIMessageGrp>:()' input_file Alternately, the MPIMessageGrp object can be given as an environmental variable: setenv MESSAGEGRP '<MPIMessageGrp>:()' mpqc input_file Usually, a special command is needed to start MPI jobs; typically it is named mpirun. Special Notes for MP2 Gradients The MP2 gradient algorithm uses MemoryGrp object to access distributed shared memory. The MTMPIMemoryGrp class is the most efficient and reliable implementation of MemoryGrp. It requires a multi-thread aware MPI implemen- tation, which is still not common. To run MP2 gradients on a machine with POSIX threads and an multi-thread aware MPI, use: mpqc -messagegrp '<MPIMessageGrp>:()' \ -threadgrp '<PthreadThreadGrp>:()' \ -memorygrp '<MTMPIMemoryGrp>:()' \ input_file or setenv MESSAGEGRP '<MPIMessageGrp>:()' setenv THREADGRP '<PthreadThreadGrp>:()' setenv MEMORYGRP '<MTMPIMemoryGrp>:()' mpqc input_file Special Notes for MP2-R12 energies Distributed Memory The MP2-R12 energy algorithm is similar to the MP2 energy algorithm that uses MemoryGrp object to access distributed memory. Hence the MTMPIMemory- Grp is the recommended implementation of MemoryGrp for such computations (see Special Notes for MP2 Gradients). Disk I/O In contrast to the MP2 energy and gradient algorithms, the MP2-R12 energy algorithm may have to use disk to store transformed MO integrals if a sin- gle pass through the AO integrals is not possible due to insufficient mem- ory. The best option in such case is to increase the total amount of memory available to the computation by either increasing the number of tasks or the amount of memory per task or both. When increasing memory further is not possible, the user has to specify which type of disk I/O should be used for the MP2-R12 energy algorithm. It is done through the r12ints keyword in input for the MBPT2_R12 object. The default choice is to use POSIX I/O on the node on which task 0 resides. This kind of disk I/O is guaranteed to work on all parallel machines, pro- vided there's enough disk space on the node. However, this is hardly most efficient on machines with some sort of parallel I/O available. On machines which have an efficient implementation of MPI-IO the r12ints should be set instead to mpi-mem. This will force the MBPT2_R12 object to use MPI-IO for disk I/O. It is user's responsibility to make sure that the MO integrals file resides on an MPI-IO-compatible file system. Hence the r12ints_file keyword, which specifies the name of the MO integrals file, should be set to a location which is guaranteed to work properly with MPI-IO. For exam- ple, on IBM SP and other IBM machines which have General Parallel File Sys- tem (GPFS), the user should set r12ints = mpi-mem and r12ints_file to a file on a GPFS file system. Integral object At the moment, MBPT2_R12 objects require specific specialization of Inte- gral, IntegralCints. Thus in order to compute MP2-R12 energies, your ver- sion of MPQC needs to be compiled with support for IntegralCints. A free, open-source library called libint is a prerequisite for IntegralCintsIn or- der to use IntegralCints as the default Integral object, add -integral '<IntegralCints>:()' to the command line, or set environmental variable IN- TEGRAL to '<IntegralCints>:()'. Special Notes for CCA Components Common Component Architecture (CCA) Portions of MPQC functionality are being packaged into CCA components. For general overviews of CCA technology and framework usage, please see www.cca-forum.org (the tutorial in particular) and the cca-chem-apps docu- mentation. MPQC components may be utilized directly within the ccaffeine framework, while some components may be instantiated and used within MPQC itself, making use of an embedded CCA framework. CCA Runtime Environment For MPQC runs utilizing embedded components, the runtime environment for the CCA framework must be specified. The colon-separated path used to lo- cate component libraries must be specified either using the -cca-path com- mand-line option or using the cca_path key within the mpqc section of a keyval input. The colon-separated list of component sidl class names which will be referenced within the input must be specified using either the -cca-load command-line option or using the cca_load key within the mpqc section of a keyval input. If defaults for the cca-path and cca-load op- tions are desired, do_cca must be set to yes in the keyval input. MPQC Input MPQC supports two input formats. The primary input is an object oriented format which gives users access to all of MPQC's options. The second format allows access to a subset of MPQC's capabilities, but is more intuitive and easier to learn. New users are advised to start with the simplified format. MPQC can be used to convert the simplified format to the full object-ori- ented format with the -i option. Each of these input formats is described in the following two chapters: o Simple Input o Object-Oriented Input Simple Input The simple input format consists of keywords followed by a ':' followed by a value. The keywords are case sensitive. The values might be modified by options found in parenthesis. For example, the following input performs an optimization of water using density functional theory with the B3LYP ex- change-correlation functional: % B3LYP optimization of water optimize: yes method: KS (xc = B3LYP) basis: 3-21G* molecule: (angstrom) O 0.172 0.000 0.000 H 0.745 0.000 0.754 H 0.745 0.000 -0.754 Comments begin with a % and continue to the end of the line. Basis set names containing special characters, such as a space or parentheses, must be quoted inside a pair of double quotes. The accepted keywords are: molecule Gives the atoms types and coordinates. The following options can be used bohr The coordinates are given in Bohr. angstrom The coordinates are given in Angstroms (the default). charge This option can be given after an 'element x y z' quadruple. This will override the charge on the atom. For example, (charge = 0) can be given for the ghost atoms in a counterpoise correction calculation. multiplicity Gives the multiplicity of the molecule. The default is 1. optimize If yes, then an optimization will be performed. The default is no. The following options can be given. cartesian Use Cartesian coordinates. internal Use internal coordinates. redundant Use redundant internal coordinates. gradient If yes, then a gradient calculation will be performed. The default is no. frequencies If yes, then the frequencies will be obtained. The default is no. charge Specificies the charge on the molecule. The default is 0. method Specifices the method. There is no default and the possible values are: HF Hartree-Fock. Unrestricted HF is used if multiplicity > 1 RHF Restricted Hartree-Fock. UHF Unrestricted Hartree-Fock. KS Kohn-Sham. Unrestricted KS is used if multiplicity > 1 RKS Restricted Kohn-Sham. UKS Unrestricted Kohn-Sham. MP2 Second order Moeller-Plesset perturbation theory. Only available for multiplicity = 1. MP2-R12/A The A version of MP2-R12. Only available for multiplicity = 1. An aux- iliary basis may be specified. No gradient, optimization, or frequen- cies are possible. MP2-R12/A' The A' version of MP2-R12. Only available for multiplicity = 1. An aux- iliary basis may be specified. No gradient, optimization, or frequen- cies are possible. ZAPT2 Z-averaged perturbation theory. Only available for multiplicity > 1. No gradient, optimization, or frequencies are possible. The following options are valid with the KS, RKS, and UKS methods: grid Specifies the grid to be used for numerical integrations. The following values can be given: xcoarse coarse medium fine xfine ultrafine xc Specifies the exchange-correlation functional. There is no default. See the table in the StdDenFunctional class documentation for the possible values. The following options are valid with the MP2-R12/A and MP2-R12/A' methods. These options are mutually exclusive: abs Use the standard Auxiliary Basis Set method. abs+ Use the standard Auxiliary Basis Set method, but use the union of the orbital and the given auxiliary basis as the actual auxiliary basis set used. cabs Use the Complementary Auxiliary Basis Set method. cabs+ Use the Complementary Auxiliary Basis Set method, but use the union of the orbital and the given auxiliary basis as the actual auxiliary basis set used. The following options are valid with the MP2-R12/A' method: ebc Assume the Extended Brillion Condition to hold. This is the default. gbc Assume the Generalized Brillion Condition to hold. This is the default. !ebc Do not assume the Extended Brillion Condition to hold. !gbc Do not assume the Generalized Brillion Condition to hold. basis Specifies the basis set. There is no default. See the table in the GaussianBasisSet class documentation for the available basis sets. auxbasis Specifies the auxiliary basis set for MP2-R12 methods. There is no de- fault. See the table in the GaussianBasisSet class documentation for the available basis sets. restart Set to yes to restart an optimization. The default is no. checkpoint Set to no to not save checkpoint files during an optimization. The de- fault is yes. symmetry Specifices the Schoenflies symbol of the point group of the molecule. The default is auto, which will cause to program to find the highest order Abelian subgroup of the molecule. docc Gives the number of doubly occupied orbitals in each each irreducible representation in a parenthesized list. The symmetry must be specified and not be auto. The method must be restricted. socc Gives the number of single occupied orbitals in each each irreducible representation in a parenthesized list. The symmetry must be specified and not be auto. The method must be restricted. alpha Gives the number of alpha occupied orbitals in each each irreducible representation in a parenthesized list. The symmetry must be specified and not be auto. The method must be unrestricted. beta Gives the number of beta occupied orbitals in each each irreducible representation in a parenthesized list. The symmetry must be specified and not be auto. The method must be unrestricted. frozen_docc Gives the number of frozen core orbitals. Can be either a single inte- ger or a parenthesized list giving the frozen core orbitals in each ir- reducible representation. In the latter case the symmetry must be given and not be auto. frozen_uocc Gives the number of frozen virtual orbitals. Can be either a single in- teger or a parenthesized list giving the frozen virtual orbitals in each irreducible representation. In the latter case the symmetry must be given and not be auto. memory Gives a hint for the amount of memory in bytes that can be used. This is typically a lower bound, more memory will be used in practice and the exact amount cannot be precisely controlled. The format is a fixed or floating point number optionally followed (without spaces) by one of the following suffixes: KB, MB, GB, KIB, MIB, or GIB. Object-Oriented Input MPQC is an object-oriented program that directly allows the user to specify objects that MPQC then manipulates to obtain energies, properties, etc. This makes the input very flexible, but very complex. However, most calcu- lations should be quite similar to the one of the examples given later in this chapter. The best way to get started is to use one of the example in- put files and modify it to meet your needs. The object-oriented input format is described in the following sections: o Overview of the Object-Oriented Input o A Walk-Through of an Object-Oriented Input File o Sample Object-Oriented Input Files Overview of the Object-Oriented Input MPQC starts off by creating a ParsedKeyVal object that parses the input file specified on the command line. The format of the input file is docu- mented in the KeyVal documentation . It is basically a free format input that associates keywords and logical groupings of keywords with values. The values can be scalars, arrays, or objects. The keywords recognized by MPQC begin with the mpqc prefix. That is, they must be nested between an mpqc:( and a ). Alternately, each keyword can be individually prefixed by mpqc:. The primary keywords are given below. Some of the keywords specify objects, in which case the object will require more ParsedKeyVal input. These objects are created from the input by using their ParsedKeyVal constructors. These constructors are documented with the source code documentation for the class. mole This is the most important keyword for MPQC. It specifies the Molecu- larEnergy object. This is an object that knows how to compute the en- ergy of a molecule. The specializations of MolecularEnergy that are most commonly used are CLKS, HSOSKS, UKS, CLHF, HSOSHF, UHF, and MBPT2. opt This keyword must be specified for optimizations. It specifies an Opti- mize object. Usually, QNewtonOpt is best for finding minima and EFCOpt is best for transition states. freq This keyword must be specified to compute frequencies. It specifies a MolecularFrequencies object. thread This specifies an object of type ThreadGrp that can be used to advan- tage on shared-memory multiprocessor machines for certain types of cal- culations. This keyword can be overridden by giving the ThreadGrp in the environment or command line. See the section on running MPQC for more information. integrals This specifies an object of type Integral that will be used as the de- fault integral evaluator. If MP2-R12 is used, then this should be set to use IntegralCints with a line like integrals<IntegralCints>: (). checkpoint The value of this keyword is boolean. <ul> <li><tt>true</tt> and optimization is to be performed <br> <tt>opt</tt> object will be checkpointed after each iteration. The checkpoint file suffix is '.ckpt'. <li><tt>true</tt> and optimization is not performed <br> <tt>mole</tt> object will be checkpointed at intermediate points. The manner in which <tt>mole</tt> will be checkpointed depends on its particular type. The checkpoint file suffix is usually '.wfn', however in general it will depend on the particular specialization of <tt>MolecularEnergy</tt>. </ul> The default is to not checkpoint. </dd> checkpoint_freq This specifies how often to checkpoint certain MolecularEnergy special- izations which compute iteratively. Currently, mole objects of SCF type can use this keyword. The default is 1, which means to checkpoint after every iteration. savestate The value of this keyword is boolean. If true, then the states of the Optimize and MolecularEnergy objects will be saved after the calcula- tion completes. The output file suffixes are '.ckpt' and '.wfn', re- spectively. The default is to save state. restart The value of this keyword is boolean. If true, mpqc will attempt to restart the calculation. If the checkpoint file is not found, the cal- culation will continue as if the value were false. The default is true. restart_file This gives the name of a file from which restart information is read. If the file name ends with '.wfn' then MPQC will try to restore a Mole- cularEnergy object from it and query for the opt object in the input file. If the file name ends with '.ckpt' MPQC will try to restore an Optimize object from this file. The default file name is formed by ap- pending '.ckpt' to the input file name with the extension removed. do_energy The value of this keyword is boolean. If true a single point energy calculation will be done for the MolecularEnergy object given with the mole keyword. The default is true. do_gradient The value of this keyword is boolean. If true a single point gradient calculation will be done for the MolecularEnergy object given with the mole keyword. The default is false. do_cca The value of this keywork is boolean. If true the cca embedded frame- work will be initialized. The default is false. cca_path The value of this keyword is a string that provides a colon-separated list of directories in which CCA component libraries may be found. cca_load The value of this keyword is a string that provides a colon-separated list of sidl class names for CCA components which will be instantiated from the libraries found in the path given by cca_path. optimize The value of this keyword is boolean. If true and the opt keyword was set to a valid value, then an optimization will be performed. The de- fault is true. write_pdb The value of this keyword is boolean. If true a PDB file with the mole- cular coordinates will be written. filename The value of this keyword is a string that gives a name from which checkpoint and other filenames are constructed. The default is the basename of the input file. print_timings If this is true, timing information is printed at the end of the run. The default is true. There are also some utility keywords that tell mpqc some technical details about how to do the calculation: debug This optional keyword gives a Debugger object which can be used to help find the problem if MPQC encounters a catastrophic error. matrixkit This optional keyword gives a SCMatrixKit specialization which is used to produce matrices of the desired type. The default is a ReplSCMa- trixKit which replicates matrices on all of the nodes. Other choices are not thoroughly tested. A Walk-Through of an Object-Oriented Input File This example input does a Hartree-Fock calculation on water. Following is the entire input, followed by a breakdown with descriptions. % This input does a Hartree-Fock calculation on water. molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) mpqc: ( mole<CLHF>: ( molecule = $:molecule basis = $:basis ) ) We start with a descriptive comment. Comments begin with a %. Everything from the % to the end of the line is ignored. % This input does a Hartree-Fock calculation on water. Now lets set up a Molecule object. The name of the object comes first, it is molecule. Then, in angle brackets, comes the type of the molecule, which is the class Molecule. The keyword and class name are followed by a : and then several pieces of input grouped between a pair of matching parenthe- ses. These parentheses contain the information that will be given to Mole- cule KeyVal constructor. molecule<Molecule>: ( The point group of the molecule is needed. This is done by assigning symme- try to a case insensitive Schoenflies symbol that is used to initialize a PointGroup object. An Abelian point group should be used. symmetry = C2V The default unit for the Cartesian coordinates is Bohr. You can specify other units by assigned unit to a string that will be used to initialize a Units object. unit = angstrom Finally, the atoms and coordinates are given. This can be given in the shorthand table syntax shown below. The headings of the table are the key- words between the first pair of brackets. These are followed by an = and another pair of brackets that contain the data. The first datum is assigned to the first element of the array that corresponds to the first heading, atom. The second datum is assigned to the first element of the array asso- ciated with the second heading, geometry, and so on. Here the second datum is actually a vector: the x, y and z coordinates of the first atom. { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) Next, a basis set object is given. basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) Now we will give the main body of input. All the subsequent keywords will be grouped in the mpqc section of the input (that is, each keyword will be prefixed with mpqc:). mpqc: ( Next we give the mole keyword which provides a specialization of the Molec- ularEnergy class. In this case we will do a closed-shell Hartree-Fock cal- culation. That is done with an object of type CLHF. The keywords that CLHF accepts are given with the documentation for the CLHF class, usually in the description of the const RefKeyVal& constructor for the class. Also with the CLHF documentation is a list of parent classes. Each of the parent classes may also have input. This input is included with the rest of the input for the child class. mole<CLHF>: ( The next line specifies the molecule to be used. There are two things to note, first that this is actually a reference to complete molecule specifi- cation elsewhere in the input file. The $ indicates that this is a refer- ence and the keyword following the $ is the actual location of the mole- cule. The : in front of the keyword means that the keyword is not relative to the current location in the input, but rather relative to the root of the tree of keywords. Thus, this line grabs the molecule that was specified above. The molecule object could have been placed here, but frequently it is necessary that several objects refer to the exact same object and this can only be done using references. The second point is that if you look at the documentation for CLHF, you will see that it doesn't read molecule keyword. However, if you follow its parent classes up to MolecularEnergy, you'll find that molecule is indeed read. molecule = $:molecule Just as we gave molecule, specify the basis set with the basis keyword as follows: basis = $:basis Now we close off the parentheses we opened above and we are finished. ) ) Sample Object-Oriented Input Files The easiest way to get started with mpqc is to start with one of sample in- puts that most nearly matches your problem. The src/bin/mpqc/samples con- tains all of the sample inputs below: o Hartree-Fock Energy o MP2 Energy o MP2-R12 energy o Hartree-Fock Optimization o Optimization with a Computed Guess Hessian o Optimization Using Newton's Method o Hartree-Fock Frequencies o Giving Coordinates and a Guess Hessian o Optimization with a Hydrogen Bond o Fixed Coordinate Optimization o Transition State Optimization o Transition State Optimization with a Computed Guess Hessian o Hartree-Fock energy with intermediate checkpointing o MP2-R12 energy with intermediate checkpointing o HF gradient computed from a previously computed HF wave funtion o MP2 Energy computed using precomputed Hartree-Fock wave function o CLHF energy using a CCA integrals component Hartree-Fock Energy The following input will compute the Hartree-Fock energy of water. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis memory = 16000000 ) ) MP2 Energy The following input will compute the MP2 energy of water. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % method for computing the molecule's energy mole<MBPT2>: ( molecule = $:molecule basis = $:basis memory = 16000000 % reference wavefunction reference<CLHF>: ( molecule = $:molecule basis = $:basis memory = 16000000 ) ) ) MP2-R12 energy The following will compute the MP2-R12 energy of water in standard approxi- mation A' (MP2-R12/A'). % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = 'cc-pVDZ' molecule = $:molecule ) % auxiliary basis set specification abasis<GaussianBasisSet>: ( name = 'aug-cc-pVDZ' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % method for computing the molecule's energy mole<MBPT2_R12>: ( molecule = $:molecule basis = $:basis aux_basis = $:abasis stdapprox = 'A'' nfzc = 1 memory = 16000000 integrals<IntegralCints>:() % reference wavefunction reference<CLHF>: ( molecule = $:molecule basis = $:basis memory = 16000000 integrals<IntegralCints>:() ) ) ) Hartree-Fock Optimization The following input will optimize the geometry of water using the quasi- Newton method. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = '6-31G*' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % molecular coordinates for optimization coor<SymmMolecularCoor>: ( molecule = $:molecule generator<IntCoorGen>: ( molecule = $:molecule ) ) % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis coor = $..:coor memory = 16000000 ) % optimizer object for the molecular geometry opt<QNewtonOpt>: ( function = $..:mole update<BFGSUpdate>: () convergence<MolEnergyConvergence>: ( cartesian = yes energy = $..:..:mole ) ) ) Optimization with a Computed Guess Hessian The following input will optimize the geometry of water using the quasi- Newton method. The guess Hessian will be computed at a lower level of the- ory. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = '6-31G*' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % molecular coordinates for optimization coor<SymmMolecularCoor>: ( molecule = $:molecule generator<IntCoorGen>: ( molecule = $:molecule ) ) % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis coor = $..:coor memory = 16000000 guess_hessian<FinDispMolecularHessian>: ( molecule = $:molecule only_totally_symmetric = yes eliminate_cubic_terms = no checkpoint = no energy<CLHF>: ( molecule = $:molecule memory = 16000000 basis<GaussianBasisSet>: ( name = '3-21G' molecule = $:molecule ) ) ) ) % optimizer object for the molecular geometry opt<QNewtonOpt>: ( function = $..:mole update<BFGSUpdate>: () convergence<MolEnergyConvergence>: ( cartesian = yes energy = $..:..:mole ) ) ) Optimization Using Newton's Method The following input will optimize the geometry of water using the Newton's method. The Hessian will be computed at each step in the optimization. How- ever, Hessian recomputation is usually not worth the cost; try using the computed Hessian as a guess Hessian for a quasi-Newton method before re- sorting to a Newton optimization. % Emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = c2v unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.36937294 ] H [ 0.78397590 0.00000000 -0.18468647 ] H [ -0.78397590 0.00000000 -0.18468647 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = '3-21G' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no restart = no % molecular coordinates for optimization coor<SymmMolecularCoor>: ( molecule = $:molecule generator<IntCoorGen>: ( molecule = $:molecule ) ) do_energy = no do_gradient = no % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis memory = 16000000 coor = $..:coor guess_wavefunction<CLHF>: ( molecule = $:molecule total_charge = 0 basis<GaussianBasisSet>: ( molecule = $:molecule name = 'STO-3G' ) memory = 16000000 ) hessian<FinDispMolecularHessian>: ( only_totally_symmetric = yes eliminate_cubic_terms = no checkpoint = no ) ) optimize = yes % optimizer object for the molecular geometry opt<NewtonOpt>: ( print_hessian = yes max_iterations = 20 function = $..:mole convergence<MolEnergyConvergence>: ( cartesian = yes energy = $..:..:mole ) ) ) Hartree-Fock Frequencies The following input will compute Hartree-Fock frequencies by finite dis- placements. A thermodynamic analysis will also be performed. If optimiza- tion input is also provided, then the optimization will be run first, then the frequencies. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = C1 { atoms geometry } = { O [ 0.0000000000 0.0000000000 0.8072934188 ] H [ 1.4325589285 0.0000000000 -0.3941980761 ] H [ -1.4325589285 0.0000000000 -0.3941980761 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis memory = 16000000 ) % vibrational frequency input freq<MolecularFrequencies>: ( molecule = $:molecule ) ) Giving Coordinates and a Guess Hessian The following example shows several features that are really independent. The variable coordinates are explicitly given, rather than generated auto- matically. This is especially useful when a guess Hessian is to be pro- vided, as it is here. This Hessian, as given by the user, is not complete and the QNewtonOpt object will fill in the missing values using a guess the Hessian provided by the MolecularEnergy object. Also, fixed coordinates are given in this sample input. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = C1 { atoms geometry } = { H [ 0.088 2.006 1.438 ] O [ 0.123 3.193 0.000 ] H [ 0.088 2.006 -1.438 ] O [ 4.502 5.955 -0.000 ] H [ 2.917 4.963 -0.000 ] H [ 3.812 7.691 -0.000 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis coor = $..:coor memory = 16000000 ) % molecular coordinates for optimization coor<SymmMolecularCoor>: ( molecule = $:molecule generator<IntCoorGen>: ( molecule = $:molecule extra_bonds = [ 2 5 ] ) % use these instead of generated coordinates variable<SetIntCoor>: [ <StreSimpleCo>:( atoms = [ 2 5 ] ) <BendSimpleCo>:( atoms = [ 2 5 4 ] ) <OutSimpleCo>: ( atoms = [ 5 2 1 3 ] ) <SumIntCoor>: ( coor: [ <StreSimpleCo>:( atoms = [ 1 2 ] ) <StreSimpleCo>:( atoms = [ 2 3 ] ) ] coef = [ 1.0 1.0 ] ) <SumIntCoor>: ( coor: [ <StreSimpleCo>:( atoms = [ 4 5 ] ) <StreSimpleCo>:( atoms = [ 4 6 ] ) ] coef = [ 1.0 1.0 ] ) <BendSimpleCo>:( atoms = [ 1 2 3 ] ) <BendSimpleCo>:( atoms = [ 5 4 6 ] ) ] % these are fixed by symmetry anyway, fixed<SetIntCoor>: [ <SumIntCoor>: ( coor: [ <StreSimpleCo>:( atoms = [ 1 2 ] ) <StreSimpleCo>:( atoms = [ 2 3 ] ) ] coef = [ 1.0 -1.0 ] ) <SumIntCoor>: ( coor: [ <StreSimpleCo>:( atoms = [ 4 5 ] ) <StreSimpleCo>:( atoms = [ 4 6 ] ) ] coef = [ 1.0 -1.0 ] ) <TorsSimpleCo>:( atoms = [ 2 5 4 6] ) <OutSimpleCo>:( atoms = [ 3 2 6 4 ] ) <OutSimpleCo>:( atoms = [ 1 2 6 4 ] ) ] ) % optimizer object for the molecular geometry opt<QNewtonOpt>: ( function = $..:mole update<BFGSUpdate>: () convergence<MolEnergyConvergence>: ( cartesian = yes energy = $..:..:mole ) % give a partial guess hessian in internal coordinates % the missing elements will be filled in automatically hessian = [ [ 0.0109261670 ] [ -0.0004214845 0.0102746106 ] [ -0.0008600592 0.0030051330 0.0043149957 ] [ 0.0 0.0 0.0 ] [ 0.0 0.0 0.0 ] [ 0.0 0.0 0.0 ] [ 0.0 0.0 0.0 ] ] ) ) Optimization with a Hydrogen Bond The automatic internal coordinate generator will fail if it cannot find enough redundant internal coordinates. In this case, the internal coordi- nate generator must be explicitly created in the input and given extra con- nectivity information, as is shown below. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = C1 { atoms geometry } = { H [ 0.088 2.006 1.438 ] O [ 0.123 3.193 0.000 ] H [ 0.088 2.006 -1.438 ] O [ 4.502 5.955 -0.000 ] H [ 2.917 4.963 -0.000 ] H [ 3.812 7.691 -0.000 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis coor = $..:coor memory = 16000000 ) % molecular coordinates for optimization coor<SymmMolecularCoor>: ( molecule = $:molecule % give an internal coordinate generator that knows about the % hydrogen bond between atoms 2 and 5 generator<IntCoorGen>: ( molecule = $:molecule extra_bonds = [ 2 5 ] ) ) % optimizer object for the molecular geometry opt<QNewtonOpt>: ( function = $..:mole update<BFGSUpdate>: () convergence<MolEnergyConvergence>: ( cartesian = yes energy = $..:..:mole ) ) ) Fixed Coordinate Optimization This example shows how to selectively fix internal coordinates in an opti- mization. Any number of linearly independent coordinates can be given. These coordinates must remain linearly independent throughout the optimiza- tion, a condition that might not hold since the coordinates can be nonlin- ear. By default, the initial fixed coordinates' values are taken from the carte- sian geometry given by the Molecule object; however, the molecule will be displaced to the internal coordinate values given with the fixed internal coordinates if have_fixed_values keyword is set to true, as shown in this example. In this case, the initial cartesian geometry should be reasonably close to the desired initial geometry and all of the variable coordinates will be frozen to their original values during the initial displacement. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = CS { atoms geometry } = { H [ 3.04 -0.69 -1.59 ] H [ 3.04 -0.69 1.59 ] N [ 2.09 -0.48 -0.00 ] C [ -0.58 -0.15 0.00 ] H [ -1.17 1.82 0.00 ] H [ -1.41 -1.04 -1.64 ] H [ -1.41 -1.04 1.64 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = '3-21G*' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % molecular coordinates for optimization coor<SymmMolecularCoor>: ( molecule = $:molecule generator<IntCoorGen>: ( molecule = $:molecule ) have_fixed_values = yes fixed<SetIntCoor>: [ <OutSimpleCo>: ( value = -0.1 label = 'N-inversion' atoms = [4 3 2 1] ) ] ) % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis coor = $..:coor memory = 16000000 ) % optimizer object for the molecular geometry opt<QNewtonOpt>: ( max_iterations = 20 function = $..:mole update<BFGSUpdate>: () convergence<MolEnergyConvergence>: ( cartesian = yes energy = $..:..:mole ) ) ) Transition State Optimization This example shows a transition state optimization of the N-inversion in $thrm{CH}_3thrm{NH}_2$ using mode following. The initial geometry was ob- tained by doing a few fixed coordinate optimizations along the inversion coordinate. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = CS { atoms geometry } = { H [ 3.045436 -0.697438 -1.596748 ] H [ 3.045436 -0.697438 1.596748 ] N [ 2.098157 -0.482779 -0.000000 ] C [ -0.582616 -0.151798 0.000000 ] H [ -1.171620 1.822306 0.000000 ] H [ -1.417337 -1.042238 -1.647529 ] H [ -1.417337 -1.042238 1.647529 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = '3-21G*' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % molecular coordinates for optimization coor<SymmMolecularCoor>: ( molecule = $:molecule generator<IntCoorGen>: ( molecule = $:molecule ) followed<OutSimpleCo> = [ 'N-inversion' 4 3 2 1 ] ) % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis coor = $..:coor memory = 16000000 ) % optimizer object for the molecular geometry opt<EFCOpt>: ( transition_state = yes mode_following = yes max_iterations = 20 function = $..:mole update<PowellUpdate>: () convergence<MolEnergyConvergence>: ( cartesian = yes energy = $..:..:mole ) ) ) Transition State Optimization with a Computed Guess Hessian This example shows a transition state optimization of the N-inversion in $thrm{CH}_3thrm{NH}_2$ using mode following. The initial geometry was ob- tained by doing a few fixed coordinate optimizations along the inversion coordinate. An approximate guess Hessian will be computed, which makes the optimiziation converge much faster in this case. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = CS { atoms geometry } = { H [ 3.045436 -0.697438 -1.596748 ] H [ 3.045436 -0.697438 1.596748 ] N [ 2.098157 -0.482779 -0.000000 ] C [ -0.582616 -0.151798 0.000000 ] H [ -1.171620 1.822306 0.000000 ] H [ -1.417337 -1.042238 -1.647529 ] H [ -1.417337 -1.042238 1.647529 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = '3-21G*' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = no % molecular coordinates for optimization coor<SymmMolecularCoor>: ( molecule = $:molecule generator<IntCoorGen>: ( molecule = $:molecule ) followed<OutSimpleCo> = [ 'N-inversion' 4 3 2 1 ] ) % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis coor = $..:coor memory = 16000000 guess_hessian<FinDispMolecularHessian>: ( molecule = $:molecule only_totally_symmetric = yes eliminate_cubic_terms = no checkpoint = no energy<CLHF>: ( molecule = $:molecule memory = 16000000 basis<GaussianBasisSet>: ( name = '3-21G' molecule = $:molecule ) ) ) ) % optimizer object for the molecular geometry opt<EFCOpt>: ( transition_state = yes mode_following = yes max_iterations = 20 function = $..:mole update<PowellUpdate>: () convergence<MolEnergyConvergence>: ( cartesian = yes energy = $..:..:mole ) ) ) Hartree-Fock energy with intermediate checkpointing The following two sections demonstrate how MPQC can be used to save the mole object periodically. This input will compute the Hartree-Fock energy of water while saving the mole object every 3 iterations. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) mpqc: ( checkpoint = yes filename = 'h2o-rhf-STO3G' checkpoint_freq = 3 savestate = no % method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis memory = 16000000 ) ) The mole object will be saved to files named 'h2o-rhf- STO3G.wfn.<iter#>.tmp' where <iter#> is the SCF iteration number (3, 6, etc.). Only the most recent file is kept, files from previous iterations are removed automatically. Keyword filename here is used to set the default file name prefix. MP2-R12 energy with intermediate checkpointing The following input will compute the MP2-R12 energy of water in standard approximation A' (MP2-R12/A') while saving the mole object at intermediate checkpoints. % emacs should use -*- KeyVal -*- mode % molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) % basis set specification basis<GaussianBasisSet>: ( name = 'cc-pVDZ' molecule = $:molecule ) % auxiliary basis set specification abasis<GaussianBasisSet>: ( name = 'aug-cc-pVDZ' molecule = $:molecule ) mpqc: ( checkpoint = yes filename = 'h2o-mp2r12ap-vdz-avdz' savestate = no % method for computing the molecule's energy mole<MBPT2_R12>: ( molecule = $:molecule basis = $:basis aux_basis = $:abasis stdapprox = 'A'' nfzc = 1 memory = 16000000 integrals<IntegralCints>:() % reference wavefunction reference<CLHF>: ( molecule = $:molecule basis = $:basis memory = 16000000 integrals<IntegralCints>:() ) ) ) The mole object will be saved to a file named h2o-mp2r12ap-vdz- avdz.wfn'</tt>. Keyword <tt>filename</tt> here is used to set the default file name prefix. Objects of the <tt>MBPT2_R12</tt> type are checkpointed after the HF procedure, after the first integrals (SBS) transformation, and after the optional second (ABS) transformation. @subsubsection mpqcoosamphfgradfromwfn HF gradient computed from a previ- ously computed HF wave funtion The following will illustrate how to reuse previously computed <tt>Molecu- larEnergy</tt> objects in subsequent computations. The first input computes Hartree-Fock energy for water and saves the <tt>mole</tt> object to file <tt>h2o-rhf-sto3g.wfn</tt>. <pre> \% emacs should use -*- KeyVal -*- mode \% molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) \% basis set specification basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) mpqc: ( checkpoint = no savestate = yes filename = 'h2o-rhf-sto3g' \% method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis memory = 16000000 ) ) </pre> <br> The second input reuses the <tt>mole</tt> object from the previous run to compute the gradient of the Hartree-Fock energy. <pre> \% emacs should use -*- KeyVal -*- mode mpqc: ( checkpoint = no savestate = no restart = yes restart_file = 'h2o-rhf-sto3g.wfn' do_gradient = yes ) </pre> <br> @subsubsection mpqcoosampmp2usinghfwfn MP2 Energy computed using precom- puted Hartree-Fock wave function The following input will compute the MP2 energy of water using a saved Hartree-Fock wave function obtained using the first input from \ref mpq- coosamphfgradfromwfn. <pre> \% emacs should use -*- KeyVal -*- mode \% molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) \% basis set specification basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) \% wave function file object specification wfn- file<BcastStateInBin>:file = 'h2o-rhf-sto3g.wfn' mpqc: ( checkpoint = no savestate = no \% method for computing the molecule's energy mole<MBPT2>: ( molecule = $:molecule basis = $:basis memory = 16000000 \% reference wavefunction reference<SavableStateProxy>: ( statein = $:wfnfile object = 'CLHF' ) ) ) </pre> <br> Note that now object <tt>reference</tt> is of type <tt>Sav- ableStateProxy</tt>, rather than <tt>CLHF</tt>. <tt>SavableStateProxy</tt> is a special object type that can be converted at runtime into the desired type (in this case, <tt>CLHF</tt>, as indicated by <tt>object</tt>). @subsubsection mpqcoosamphfusingcca CLHF energy using a CCA integrals com- ponent The following input will compute the CLHF energy of water using a CCA inte- grals component via the IntegralCCA adaptor class. <pre> \% emacs should use -*- KeyVal -*- mode \% molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.00000000 0.00000000 0.37000000 ] H [ 0.78000000 0.00000000 -0.18000000 ] H [ -0.78000000 0.00000000 -0.18000000 ] } ) \% basis set specification basis<GaussianBasisSet>: ( name = 'STO-3G' molecule = $:molecule ) mpqc: ( \% path to component libraries cca_path = /usr/local/lib/cca \% sidl class names of components which will be instantiated cca_load = MPQC.IntegralEvaluatorFactory do_cca = yes checkpoint = no savestate = no \% method for computing the molecule's energy mole<CLHF>: ( molecule = $:molecule basis = $:basis \% cca integrals adaptor class integrals<IntegralCCA>: ( molecule = $:molecule \% integral buffer type integral_buffer = opaque \% integral package integral_package = intv3 \% factory component sidl class name evaluator_factory = MPQC.IntegralEvaluatorFactory ) ) ) </pre> <br> <br> @section mpqcval Validating MPQC After you compile MPQC, you should run the validation suite. You should also run the validation suite if you upgrade your operating system soft- ware, since this could change shared libraries that are linking with MPQC and could affect the results. Note that the reference validation suite has not been verified relative to an independent code, except for a few spot checks. If you find that MPQC doesn't produce the same answer as another quantum chemistry program that you trust, then please promptly notify us and send all the details. The top-level Makefile has several targets that can be used to check an MPQC build. MPQC must be built before one of these targets is used: <dl> <dt><tt>check</tt><dd>The same as <tt>check0</tt> below. This is only available from the top-level directory and <tt>src/bin/mpqc/validate</tt>. <dt><tt>check0</tt><dd>Run the smallest MPQC verification suite. It tests basic functionality. This is only available from the top-level directory and <tt>src/bin/mpqc/validate</tt>. <dt><tt>check1</tt><dd>Run the intermediate MPQC verification suite. It runs most of the tests, only leaving out very expensive runs. This is only available from the top-level directory and <tt>src/bin/mpqc/validate</tt>. <dt><tt>check2</tt><dd>Run the complete MPQC verification suite. Depending on the compilation and runtime environment, tests that are not expected to work will be omitted. This is only available from the top-level directory and <tt>src/bin/mpqc/validate</tt>. <dt><tt>check_clean</tt><dd>Remove MPQC verification suite output files. This is only available from the top-level directory and <tt>src/bin/mpqc/validate</tt>. <dt><tt>testbuild</tt><dd>Verify that a variety of small test programs compile. If static libraries are used, this will require a substantial amount of disk space. <dt><tt>testrun</tt><dd>Run a variety of small test programs. This will build them if necessary. </dl> The check targets will run mpqc with the mpqcrun (see \ref mpqcrun) com- mand. You can give arguments to mpqcrun by setting the <tt>MPQCRUN_ARGS</tt> variable on the make command line. The verification suite is in <tt>src/bin/mpqc/validate</tt>. After running it, the output files can be found in <tt>src/bin/mpqc/validate/run</tt>. The check targets will compare outputs that your build produced to the ref- erence files in <tt>src/bin/mpqc/validate/ref</tt>. The input files can be found with the reference files. For each comparison, first the status (<tt>ok</tt>, <tt>missing</tt>, or <tt>failed</tt>) for each file is printed. If both statuses are <tt>ok</tt> then an <tt>E:</tt> is printed followed by the number of digits to which the energies agree. If they agree to all digits <tt>99</tt> is printed. If a gradient was computed, then <tt>Grad:</tt> is printed followed by the number of digits to which the gradients in least agreement agree. Other properties checked in this way include frequencies, diagnostics, and populations. If two numbers do not agree to the expected accuracy, then an asterisk, <tt>*</tt>, is printed after the number of digits in agreement. Finally, you can do a detailed comparison of the contents of the <tt>ref</tt> and <tt>run</tt> subdirectories by typing <tt>make diff</tt>. The input files in the verification suite are divided into several cate- gories: <dl> <dt><tt>h2o</tt><dd>These are simple tests that exercise many of MPQC's features. <dt><tt>h2omp2</tt><dd>Tests that further exercise MP2. <dt><tt>h2ofrq</tt><dd>Tests of H<sub>2</sub>O frequencies with a variety of methods. <dt><tt>mbpt</tt><dd>These tests exercise MP2 as well as the open-shell perturbation theory methods. The various available algorithms are tested as well. <dt><tt>ckpt</tt><dd>Tests the checkpoint and restart capabilities. <dt><tt>symm1</tt><dd>Tests of point group symmetry. <dt><tt>symm2</tt><dd>More point group symmetry tests. These use basis sets with higher angular momentum than #symm1#. <dt><tt>symm3</tt><dd>Tests automatic point group determination. <dt><tt>basis1</tt><dd>A variety of basis sets are tested for first row atoms along with hydrogen and helium. <dt><tt>basis2</tt><dd>Basis sets test for second row atoms. <dt><tt>methods</tt><dd>Basic tests of several of MPQC's methods. <dt><tt>clscf</tt><dd>More tests of methods based on CLSCF. <dt><tt>hsosscf</tt><dd>More tests of methods based on HSOSSCF. <dt><tt>uscf</tt><dd>More tests of methods based on UnrestrictedSCF. <dt><tt>dft</tt><dd>More tests of the CLKS method. <dt><tt>mp2r12</tt><dd>More tests of MP2-R12. <dt><tt>ccaintv3</tt><dd>Tests of embedded CCA integrals components using <tt>intv3</tt>. <dt><tt>ccacints</tt><dd>Tests of embedded CCA integrals components using <tt>cints</tt>. </dl> <br> @section mpqcpsi Running Psi 3 from MPQC <a href='http://www.psicode.org/'>Psi 3</a> is a suite of <i>ab initio</i> codes related to the original Psi package started in Prof. Fritz Schaefer's group at UC Berkeley. Current version of MPQC works with stable versions of Psi 3 starting with 3.2.0. From now on we will refer to Psi 3 as simply Psi. Psi is written primarily in C and executes in serial mode only. The interface between Psi and MPQC is intended mainly for Psi users who wish to exploit MPQC's geometry optimization and frequency analyses capabilities with Psi energies and gradients. The following sections explain how to use Psi from MPQC: <ul> <li> \ref psiworks <li> \ref psienv <li> \ref psiinp <li> \ref psiexenv <li> \ref psiwfn <li> \ref examples </ul> @subsection psiworks How the MPQC-Psi interface works The current version of the interface is rather slim. It is only possible to import energies and gradients computed with Psi into MPQC, i.e. wave func- tions cannot be imported. All MPQC-Psi interaction happens via text files and system calls. MPQC generates input file for Psi, calls appropriate Psi modules, and then parses the output files for energies and gradients. @subsection psienv Environmental Variables Several environmental variables are used to control MPQC-Psi interaction: <dl> <dt><tt>PSIBIN</tt><dd> By default, MPQC will try to find Psi binaries under <tt>/usr/local/psi/bin</tt>. Use <tt>PSIBIN</tt> environmental vari- able to point to the right location. </dl> The rest of the Psi environment is job specific and specified in the input file. @subsection psiinp Preparing an input file As noted above, MPQC parses the input file, and as such the input file has to be in the MPQC OO input format. All features of usual MPQC input files are there (<tt>mpqc</tt> section, <tt>mole</tt> MolecularEnergy object, etc.). In addition the following rules apply: <ul> <li> instead of using MPQC Wavefunction objects (CLHF, MBPT2, etc.), the Psi specific Wavefunction types (i.e. specializations of PsiWavefunction) have to be used. Presently the following specializations are supported: PsiCLHF, PsiHSOSHF, PsiUHF, PsiCCSD, PsiCCSD_T . The first three are di- rectly analogous to MPQC Wavefunction types CLHF, HSOSHF, and UHF. The lat- ter two do not have MPQC analogs yet. See appropriate class documentation on how to specify them properly. <li> each Psi-specific Wavefunction object has to have a member object <tt>psienv</tt> of type PsiExEnv. PsiExEnv contains job specific informa- tion, such as the directory in which Psi input, output, and checkpoint files will be kept, filename prefix, scratch directories, etc. It makes sense to define one such object and simply refer to it from all PsiWave- function objects. See PsiExEnv class documentation for more info. </ul> @subsection psiexenv Psi Execution Environment Each PsiWavefunction-derived class has to have a member object called <tt>psienv</tt> of type PsiExEnv. The following keywords are used by its KeyVal constructor: <dl> <dt><tt>cwd</tt><dd> The directory where to keep Psi input, checkpoint, stdout, stderr, and other files. Default is <tt>/tmp</tt>. <dt><tt>fileprefix</tt><dd> The file prefix to use for Psi checkpoint, scratch, and some ASCII files. Equivalent to keyword <tt>name</tt> in Psi <tt>psi:files:default</tt> section. Defaults to <tt>psi</tt>. <dt><tt>stdout</tt><dd> The file into which to redirect standard output of Psi modules. Defaults to <tt>psi.stdout</tt>. <dt><tt>stderr</tt><dd> The file into which to redirect standard error of Psi modules. Defaults to <tt>psi.stderr</tt>. <dt><tt>nscratch</tt><dd> The number of locations over which to stripe Psi binary files. Equivalent to keyword <tt>nvolume</tt> in Psi <tt>psi:files:default</tt> section. De- fault is 1. <dt><tt>scratch</tt><dd> The locations over which to stripe Psi binary files. Equivalent to keyword <tt>volume<i>x</i></tt> in Psi <tt>psi:files:default</tt> section. There's no default. </dl> Here's an example: <pre> psienv<PsiExEnv>: ( cwd = ./ fileprefix = psi.test nscratch = 2 scratch = [ '/scratch1/' '/scratch2/' ] ) </pre> <br> @subsection psiwfn PsiWavefunction specializations Class PsiWavefunction is derived from class Wavefunction, hence its KeyVal constructor uses all keywords that Wavefunction's KeyVal constructor uses (<tt>basis</tt>, <tt>molecule</tt>, etc.). In addition, PsiWavefunction's KeyVal constructor looks for the following keywords in the input file: <dl> <dt><tt>psienv</tt><dd> The PsiExEnv object that provides job specific Psi environment. There's no default. <dt><tt>docc</tt><dd> An optional array of integers that specifies the number of doubly-occupied orbitals in each irrep. <dt><tt>socc</tt><dd> An optional array of integers that specifies the number of singly-occupied orbitals in each irrep. <dt><tt>frozen_docc</tt><dd> An optional array of integers that specifies the number of doubly-occupied orbitals in each irrep frozen in correlated computations. <dt><tt>frozen_uocc</tt><dd> An optional array of integers that specifies the number of unoccupied orbitals in each irrep frozen in correlated computations. <dt><tt>total_charge</tt><dd> The total charge of the system. This keyword is queried only if neither <tt>docc</tt> nor <tt>socc</tt> are given. <dt><tt>multiplicity</tt><dd> The spin multiplic- ity of the system (2*M_S+1). This keyword is queried only if neither <tt>docc</tt> nor <tt>socc</tt> are given. <dt><tt>memory</tt><dd> The number of bytes of memory Psi modules associated with this PsiWavefunction are allowed to use. Default is 2000000 (2 million bytes, approximately 2 MB). </dl> Note that keywords <tt>docc</tt>, <tt>socc</tt>, <tt>frozen_docc</tt>, <tt>frozen_uocc</tt>, <tt>total_charge</tt>, and <tt>multiplicity</tt> are used by appropriate specializations of PsiWave- functions, i.e. PsiCLHF only checks for <tt>docc</tt>, etc. PsiWavefunction specializations PsiCCSD and PsiCCSD_T also look for keyword <tt>reference</tt> which specifies the reference wave function (an object of type PsiSCF). All classes for correlated Psi wave functions will require such an object. Here are a few examples of PsiWavefunctions: <pre> \% \% ROHF DZ on F atom \% mole<PsiHSOSHF>: ( docc = [ 2 0 0 0 0 1 1 0 ] socc = [ 0 0 0 0 0 0 0 1] memory = 10000000 \% Psi Environment data psienv<PsiExEnv>: ( cwd = ./ fileprefix = f.dz.test stdout = f.dz.test.stdout stderr = f.dz.test.stderr nscratch = 1 scratch = [ '/scratch/mpqc/' ] ) \% MolecularEnergy input molecule<Molecule>: ( {atoms geometry} = { F [ 0.0 0.0 0.0 ] } ) \% Basis input basis<GaussianBasisSet>: ( molecule = $..:molecule name = 'DZ (Dunning)' ) ) </pre> <br> <pre> \% \% RHF CCSD/cc-pVDZ on water \% mole<PsiCCSD>: ( frozen_docc = [1 0 0 0] memory = 40000000 \% Psi Environment data psienv<PsiExEnv>: ( cwd = ./ fileprefix = h2o.ccpvdz.ccsd.test nscratch = 1 scratch = [ '/tmp/' ] ) \% MolecularEnergy input molecule<Molecule>: ( {atoms geometry} = { H [ -1.5 0.0 -0.3 ] H [ 1.5 0.0 -0.3 ] O [ 0.0 0.0 1.0 ] } ) \% Basis input basis<GaussianBasisSet>: ( molecule = $..:molecule name = 'cc-pVDZ' ) reference<PsiCLHF>: ( psienv = $..:psienv molecule = $..:molecule basis = $..:basis total_charge = 0 multiplicity = 1 ) ) </pre> <br> @subsection examples More examples This section contains some examples of complete inputs that specify an MPQC/Psi computations. Here's an optimization + subsequent frequency analysis on water molecule at the RHF CCSD 6-311G** level: <pre> \% Emacs should use -*- KeyVal -*- mode \% this file was automatically generated \% label: water test series \% molecule specification molecule<Molecule>: ( symmetry = C2V unit = angstrom { atoms geometry } = { O [ 0.000000000000 0.000000000000 0.369372944000 ] H [ 0.783975899000 0.000000000000 -0.184686472000 ] H [ -0.783975899000 0.000000000000 -0.184686472000 ] } ) \% basis set specification basis<GaussianBasisSet>: ( name = '6-311G**' molecule = $:molecule ) \% Psi environment specification psienv<PsiEx- Env>: ( cwd = ./ fileprefix = mpqcpsi stdout = mpqcpsi.stdout stderr = mpqcpsi.stderr nscratch = 1 scratch = [ '/scratch/evaleev/' ] ) mpqc: ( checkpoint = no savestate = no restart = no coor<SymmMolecularCoor>: ( molecule = $:molecule generator<IntCoorGen>: ( molecule = $:molecule ) ) \% molecular coordinates for optimization do_energy = yes do_gradient = no \% method for computing the molecule's energy mole<PsiCCSD>: ( molecule = $:molecule basis = $:basis coor = $..:coor psienv = $:psienv memory = 32000000 reference<PsiCLHF>: ( psienv = $:psienv molecule = $:molecule total_charge = 0 multiplicity = 1 basis = $:basis memory = 32000000 ) hessian<FinDispMolecularHessian>: ( point_group<PointGroup>: symmetry = C2V checkpoint = no restart = no ) ) optimize = yes \% optimizer object for the molecular geometry opt<QNewtonOpt>: ( max_iterations = 20 function = $..:mole update<BFGSUpdate>: () convergence<MolEnergyConvergence>: ( cartesian = yes energy = $..:..:mole ) ) \% vibrational frequency input freq<MolecularFrequencies>: ( point_group<PointGroup>: symmetry = C2V molecule = $:molecule ) ) </pre> <br> <br> @section mpqccomponents CCA Components Common Component Architecture (CCA) component wrappers, conforming to in- terfaces developed for the <a href='http://www.cca-forum.org/~cca-chem'>CCA Chemistry Component Toolkit</a>, have been created to encapsulate some MPQC functionality. The following components are provided by MPQC: <ul> <li> \ref modelfac <li> \ref coormodel <li> \ref evalfac </ul> @subsection modelfac MPQC.Chemistry_QC_ModelFactory This is an implementation of the Chemistry.QC.ModelFactory interface. This factory produces model objects (implementing the Chemistry.QC.Model inter- face) based on the MPQC package. The MPQC model allows calculation of mol- ecular energies and energy derivatives using a variety of methods. @subsubsection modelfacpp Provides Ports <ul> <li>Chemistry.QC.ModelFactory <em>ModelFactory</em> </ul> @subsubsection modelfacup Uses Ports <ul> <li>Chemistry.QC.MoleculeFactory <em>MoleculeFactory</em> (required) </ul> @subsubsection modelfacparam Parameters <ul> <li><b>theory</b> The method for determining the electronic structure. Defaults to HF. <ul> <li> <em>HF</em> Hartree-Fock method. <li> <em>B3LYP</em> Density Functional Theory (DFT) with B3LYP functional. <li> Use keyval input for other options. </ul> <li><b>basis</b> The atomic orbital basis set. Defaults to <em>STO-3G</em>. <ul> <li> Any basis set defined in the MPQC package. <li> Use keyval input for mixed basis sets. </ul> <li><b>molecule_filename</b> Path to the molecule file (see cca-chem- generic documentation for format). No default – required. <li><b>keyval_filename</b> Path to the keyval input file (see below). No default – optional. </ul> @subsubsection modelfackeyval Keyval Input The <b>theory</b> and <b>ba- sis</b> parameters allow very basic calculations to be performed. More complex calculations will require the use of a keyval input file. The key- val file format is the same as that used to run MPQC stand-alone, and any valid MPQC options may be used. The molecular energy object must be named <tt>model</tt>. The user-supplied keyval cannot contain a molecule sec- tion; the molecule section will be automatically inserted by the ModelFac- tory using the required <b>molecule_filename</b>. This molecule section should be referred to as <tt>$:molecule</tt>. Example keyval input: <pre> model<CLHF>:( molecule=$:molecule basis<GaussianBasisSet>:( name = '6-31G" molecule = $:molecule ) ) MPQC.ChemistryOpt_CoordinateModel This is an implementation of the ChemistryOpt.CoordinateModel interface based on the MPQC package. It supports molecular structure optimization in cartesian, symmetrized internal, and redundant internal coordinates. Hess- ian approximation is supported. Provides Ports o ChemistryOpt.CoordinateModel CoordinateModel Uses Ports o Chemistry.QC.ModelFactory ModelFactory (required) o Chemistry.QC.ModelFactory BackupModelFactory (optional) o Chemistry.MoleculeViewer MoleculeViewer (optional) A backup model factory may be supplied. If an error is detected in the pri- mary model, then a model obtained from the backup factory will be used. The molecule viewer is currently only used to communicate with the python viewer, in which case component instantiation and connection is handled au- tomatically. Parameters o grad_rms RMS gradient convergence criteria. Defaults to 0.00030. o grad_max Max gradient convergence criteria. Defaults to 0.00045. o disp_rms RMS displacement convergence criteria. Defaults to 0.00120. o disp_max Max displacement convergence criteria. Defaults to 0.00180. o coordinate_type Optimization coordinate type. Defaults to symmetrized. o cartesian Cartesian coordinates. o symmetrized Symmetrized internal coordinates. o redundant Redundant internal coordinates. o multiple_guess_h Compute new guess Hessian at each call to guess_hess- ian_solve() (true) or use guess from first iteration only (false). Only meaningful in conjunction with solvers supporting use of dense guess Hes- sians with limited-memory methods. Defaults to true. o use_current_geom If multiple_guess_h is true, either use the current geometry (true) or the geometry at which the earliest correction pair used by the solver was determined (false) when computing the guess Hess- ian. Defaults to false. MPQC.IntegralEvaluatorFactory This is an implementation of the Chemistry.QC.GaussianBasis.IntegralEvalu- atorFactory interface. This factory produces molecular integral evaluator objects based on the MPQC package. This code is experimental and does not currently support derivative integrals. Provides Ports o Chemistry.QC.GaussianBasis.IntegralEvaluatorFactory IntegralEvaluatorFac- tory Parameters o package Integral package, either intv3 or cints. Defaults to intv3. o integral_buffer Integral buffer type, either opaque or array. The opaque option uses pointers and is therefore higher performance. The array op- tion may be used by components implemented in languages which are not pointer-aware. MPQC License MPQC is open-source software; you can redistribute it and/or modify it un- der the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. MPQC Warranty MPQC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more de- tails. Version 2.3.1 Thu Sep 3 2026 mpqc(1)
NAME | MPQC Overview | Running MPQC | MPQC Input | Simple Input | Object-Oriented Input | MPQC License | MPQC Warranty
Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=mpqc&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>