Provided by: mpqc_2.3.1-16ubuntu5_amd64 bug

NAME

       mpqc - The Massively Parallel Quantum Chemistry program (MPQC)

SYNOPSIS

       mpqc [options] [filename]

DESCRIPTION

       MPQC computes the properties of molecules, ab initio, on a wide variety of computer
       architectures.

       It can compute closed shell and general restricted openshell HartreeFock energies and
       gradients, second order openshell perturbation theory (OPT2[2]) and Zaveraged perturbation
       theory (ZAPT2) energies, and second order closed shell MoellerPlesset perturbation theory
       energies and gradients. It also includes methods for optimizing molecules in either
       Cartesian or internal coordinates.

       MPQC is designed using objectoriented programming techniques and implemented in the C++
       programming language.

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 output. No calculations are done.

       -messagegrp
               A ParsedKeyVal specification of a MessageGrp object. The default depends on how
               MPQC was compiled.

       -memorygrp
               A ParsedKeyVal specification of a MemoryGrp object. The default depends on how
               MPQC was compiled.

       -threadgrp
               A ParsedKeyVal specification of a ThreadGrp object. The default depends on how
               MPQC was compiled.

       -l      Sets a limit on the number of basis functions. The default is zero, which means an
               unlimited number of basis functions.

       -W      Sets the working directory. The default is the current directory.

       -c      Check the input and exit.

       -v      Print the version number.

       -w      Print the warranty information (there is no warranty).

       -d      If a debugger object was given in the input, start the debugger running as soon as
               MPQC is started.

       -h      Print a list of options.

       -f      The name of an object-oriented input file. The default is mpqc.in. This cannot be
               used if another input file is specified. This option is deprecated, as both input
               file formats can be read by given the input file name on the command line without
               any option flags.

       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 on start-up, instead of when an
       MPIMessageGrp is created, name the executable mpqc-mpi.

ENVIRONMENTAL VARIABLES

       MPQC looks at four environmental variables to set up communication and find library files.
       Machine specific libraries and utilities to run programs in parallel might look at other
       environment variables as well. The four that apply on all platforms are:

       SCLIBDIR
               The name of the library directory.

       MESSAGEGRP
               A ParsedKeyVal specification of a MessageGrp object. The default depends on how
               MPQC was compiled. See the MessageGrp class documentation for more information.

       MEMORYGRP
               A ParsedKeyVal specification of a MemoryGrp object. The default depends on how
               MPQC was compiled and the MessageGrp in use.

       THREADGRP
               A ParsedKeyVal specification of a ThreadGrp object. The default depends on how
               MPQC was compiled.

       By default, MPQC tries to find library files first in the lib sub-directory 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.

       The other three keywords specify objects. This is done by giving a mini ParsedKeyVal input
       in a string. The object is anonymous, that is, no keyword is associated with it. Here is
       an example:

       setenv MESSAGEGRP '<ShmMessageGrp>:(n = 4)'

SHARED MEMORY MULTIPROCESSOR WITH SYSV IPC

       By default, MPQC will run on only one CPU. To specify more, you can give a ShmMessageGrp
       object on the command line. The following would run mpqc in four processes:

       mpqc -messagegrp '<ShmMessageGrp>:(n = 4)' input_file

       Alternately, the ShmMessageGrp object can be given as an environmental variable:

       setenv MESSAGEGRP '<ShmMessageGrp>:(n = 4)'
       mpqc input_file

       If MPQC should unexpectedly die, shared memory segments and semaphores will be left on the
       machine. These should be promptly cleaned up or other jobs may be prevented from running
       successfully. To see if you have any of these resources allocated, use the ipcs command.
       The output will look something like:

       IPC status from /dev/kmem as of Wed Mar 13 14:42:18 1996
       T     ID     KEY        MODE       OWNER    GROUP
       Message Queues:
       Shared Memory:
       m 288800 0x00000000 --rw-------  cljanss     user
       Semaphores:
       s    390 0x00000000 --ra-------  cljanss     user
       s    391 0x00000000 --ra-------  cljanss     user

       To remove the IPC resources used by cljanss in the above example on IRIX, type:

       ipcrm -m 288800
       ipcrm -s 390
       ipcrm -s 391

       And on Linux, type:

       ipcrm shm 288800
       ipcrm sem 390
       ipcrm sem 391

SHARED MEMORY MULTIPROCESSOR WITH POSIX THREADS

       By default, MPQC will run with only one thread. To specify more, you can give a
       PthreadThreadGrp object on the command line. MPQC is not parallelized to as large an
       extent with threads as it is with the more conventional distributed memory model, so you
       might not get the best performance using this technique. On the other the memory overhead
       is lower and no interprocess communication is needed.

       The following would run MPQC in four threads:

       mpqc -threadgrp '<PthreadThreadGrp>:(num_threads = 4)' input_file

       Alternately, the PthreadThreadGrp object can be given as an environmental variable:

       setenv THREADGRP '<PthreadThreadGrp>:(n = 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.

INPUT

       MPQC supports two input formats. The primary input is an object oriented format which
       gives users access to all of MPQCs options. The second format allows access to a subset of
       MPQCs capabilities, but is more intuitive and easier to learn. New users are advised to
       start with the simplified format. MPQC can be used to convert the simplified format to the
       full object-oriented format with the -i option.

Simple Input

       The simple input format consists of keywords followed by a ':' followed by a value. The
       keywords are case sensitive. The values might be modified by options found in parenthesis.
       For example, the following input performs an optimization of water using density
       functional theory with the B3LYP exchange-correlation functional:

       % B3LYP optimization of water
       optimize: yes
       method: KS (xc = B3LYP)
       basis: 3-21G*
       molecule:
           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.

       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
            Specifies the charge on the molecule. The default is 0.

       method
            Specif ices 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.

       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.

       basis
            Specifies the basis set. There is no default. See the table in the GaussianBasisSet
           class documentation for the available basis sets.

       restart
            Set to yes to restart an optimization. The default is no.

       checkpoint
            Set to no to not save checkpoint files during an optimization. The default is yes.

       symmetry
            Specif ices the Schoenflies symbol of the point group of the molecule. The default is
           auto, which will cause to program to find the highest order Abelian subgroup of the
           molecule.

       docc
            Gives the number of doubly occupied orbitals in each each irreducible representation
           in a parenthesized list. The symmetry must be specified and not be auto. The method
           must be restricted.

       socc
            Gives the number of single occupied orbitals in each each irreducible representation
           in a parenthesized list. The symmetry must be specified and not be auto. The method
           must be restricted.

       alpha
            Gives the number of alpha occupied orbitals in each each irreducible representation
           in a parenthesized list. The symmetry must be specified and not be auto. The method
           must be unrestricted.

       beta
            Gives the number of beta occupied orbitals in each each irreducible representation in
           a parenthesized list. The symmetry must be specified and not be auto. The method must
           be unrestricted.

       frozen_docc
            Gives the number of frozen core orbitals. Can be either a single integer or a
           parenthesized list giving the frozen core orbitals in each irreducible representation.
           In the latter case the symmetry must be given and not be auto.

       frozen_uocc
            Gives the number of frozen virtual orbitals. Can be either a single integer or a
           parenthesized list giving the frozen virtual orbitals in each irreducible
           representation. In the latter case the symmetry must be given and not be auto.

Object-Oriented Input

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

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

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

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

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

       freq
            This keyword must be specified to compute frequencies. It specifies a
           MolecularFrequencies object.

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

       checkpoint
            The value of this keyword is Boolean. If true, then optimizations will be
           checkpointed after each iteration. The checkpoint file suffice is .ckpt. The default
           is to checkpoint.

       savestate
            The value of this keyword is Boolean. If true, then the states of the optimizer and
           wavefunction objects will be saved after the calculation completes. The output file
           suffix is .wfn. The default is to save state.

       restart
            The value of this keyword is Boolean. If true, mpqc will attempt to restart the
           calculation. If the checkpoint file is not found, the calculation will continue as if
           the value were false. The default is true.

       restart_file
            This gives the name of a file from which restart information is read. If the file
           name ends in .wfn the MolecularEnergy object will be restored. Otherwise, the Optimize
           object will be restored. The default file name is formed by appending .ckpt to the
           input file name with the extension removed.

       do_energy
            The value of this keyword is Boolean. If true a single point energy calculation will
           be done for the MolecularEnergy object given with the mole keyword. The default is
           true.

       do_gradient
            The value of this keyword is Boolean. If true a single point gradient calculation
           will be done for the MolecularEnergy object given with the mole keyword. The default
           is false.

       optimize
            The value of this keyword is Boolean. If true and the opt keyword was set to a valid
           value, then an optimization will be performed. The default is true.

       write_pdb
            The value of this keyword is Boolean. If true a PDB file with the molecular
           coordinates will be written.

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

       print_timings
            If this is true, timing information is printed at the end of the run. The default is
           true.

       There are also some utility keywords that tell mpqc some technical details about how to do
       the calculation:

       debug
            This optional keyword gives a Debugger object which can used to help find the problem
           if MPQC encounters a catastrophic error.

       matrixkit
            This optional keyword gives a SCMatrixKit specialization which is used to produce
           matrices of the desired type. The default is a ReplSCMatrixKit which replicates
           matrices on all of the nodes. Other choices are not thoroughly tested.

EXAMPLES

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

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

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

       % This input does a Hartree-Fock calculation on water.

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

       molecule<Molecule>: (

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

         symmetry = C2V

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

         unit = angstrom

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

         { atoms                       geometry                   } = {
           O     [     0.00000000     0.00000000     0.37000000 ]
           H     [     0.78000000     0.00000000    -0.18000000 ]
           H     [    -0.78000000     0.00000000    -0.18000000 ]
         }
       )

       Next, a basis set object is given.

       basis<GaussianBasisSet>: (
         name = 'STO-3G'
         molecule = $:molecule
       )

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

       mpqc: (

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

         mole<CLHF>: (

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

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

           molecule = $:molecule

       Just as we gave molecule, specify the basis set with the basis keyword as follows:

           basis = $:basis

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

         )
       )

Sample Object-Oriented Input Files

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

   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
           )
         )
       )

   Hartree-Fock Optimization
       The following input will optimize the geometry of water using the quasi-Newton method.

       % emacs should use -*- KeyVal -*- mode
       % molecule specification
       molecule<Molecule>: (
         symmetry = C2V
         unit = angstrom
         { atoms geometry } = {
           O     [     0.00000000     0.00000000     0.37000000 ]
           H     [     0.78000000     0.00000000    -0.18000000 ]
           H     [    -0.78000000     0.00000000    -0.18000000 ]
         }
       )
       % basis set specification
       basis<GaussianBasisSet>: (
         name = '6-31G*'
         molecule = $:molecule
       )
       mpqc: (
         checkpoint = no
         savestate = no
         % molecular coordinates for optimization
         coor<SymmMolecularCoor>: (
           molecule = $:molecule
           generator<IntCoorGen>: (
             molecule = $:molecule
           )
         )
         % method for computing the molecule's energy
         mole<CLHF>: (
           molecule = $:molecule
           basis = $:basis
           coor = $..:coor
           memory = 16000000
         )
         % optimizer object for the molecular geometry
         opt<QNewtonOpt>: (
           function = $..:mole
           update<BFGSUpdate>: ()
           convergence<MolEnergyConvergence>: (
             cartesian = yes
             energy = $..:..:mole
           )
         )
       )

   Optimization with a Computed Guess Hessian
       The following input will optimize the geometry of water using the quasi-Newton method. The
       guess Hessian will be computed at a lower level of theory.

       % emacs should use -*- KeyVal -*- mode
       % molecule specification
       molecule<Molecule>: (
         symmetry = C2V
         unit = angstrom
         { atoms geometry } = {
           O     [     0.00000000     0.00000000     0.37000000 ]
           H     [     0.78000000     0.00000000    -0.18000000 ]
           H     [    -0.78000000     0.00000000    -0.18000000 ]
         }
       )
       % basis set specification
       basis<GaussianBasisSet>: (
         name = '6-31G*'
         molecule = $:molecule
       )
       mpqc: (
         checkpoint = no
         savestate = no
         % molecular coordinates for optimization
         coor<SymmMolecularCoor>: (
           molecule = $:molecule
           generator<IntCoorGen>: (
             molecule = $:molecule
           )
         )
         % method for computing the molecule's energy
         mole<CLHF>: (
           molecule = $:molecule
           basis = $:basis
           coor = $..:coor
           memory = 16000000
           guess_hessian<FinDispMolecularHessian>: (
             molecule = $:molecule
             only_totally_symmetric = yes
             eliminate_cubic_terms = no
             checkpoint = no
             energy<CLHF>: (
               molecule = $:molecule
               memory = 16000000
               basis<GaussianBasisSet>: (
                 name = '3-21G'
                 molecule = $:molecule
               )
             )
           )
         )
         % optimizer object for the molecular geometry
         opt<QNewtonOpt>: (
           function = $..:mole
           update<BFGSUpdate>: ()
           convergence<MolEnergyConvergence>: (
             cartesian = yes
             energy = $..:..:mole
           )
         )
       )

   Optimization Using Newton's Method
       The following input will optimize the geometry of water using the Newton's method. The
       Hessian will be computed at each step in the optimization. However, Hessian recomputation
       is usually not worth the cost; try using the computed Hessian as a guess Hessian for a
       quasi-Newton method before resorting to a Newton optimization.

       % Emacs should use -*- KeyVal -*- mode
       % molecule specification
       molecule<Molecule>: (
         symmetry = c2v
         unit = angstrom
         { atoms geometry } = {
            O     [     0.00000000     0.00000000     0.36937294 ]
            H     [     0.78397590     0.00000000    -0.18468647 ]
            H     [    -0.78397590     0.00000000    -0.18468647 ]
         }
       )
       % basis set specification
       basis<GaussianBasisSet>: (
         name = '3-21G'
         molecule = $:molecule
       )
       mpqc: (
         checkpoint = no
         savestate = no
         restart = no
         % molecular coordinates for optimization
         coor<SymmMolecularCoor>: (
           molecule = $:molecule
           generator<IntCoorGen>: (
             molecule = $:molecule
           )
         )
         do_energy = no
         do_gradient = no
         % method for computing the molecule's energy
         mole<CLHF>: (
           molecule = $:molecule
           basis = $:basis
           memory = 16000000
           coor = $..:coor
           guess_wavefunction<CLHF>: (
             molecule = $:molecule
             total_charge = 0
             basis<GaussianBasisSet>: (
               molecule = $:molecule
               name = 'STO-3G'
             )
             memory = 16000000
           )
           hessian<FinDispMolecularHessian>: (
             only_totally_symmetric = yes
             eliminate_cubic_terms = no
             checkpoint = no
           )
         )
         optimize = yes
         % optimizer object for the molecular geometry
         opt<NewtonOpt>: (
           print_hessian = yes
           max_iterations = 20
           function = $..:mole
           convergence<MolEnergyConvergence>: (
             cartesian = yes
             energy = $..:..:mole
           )
         )
       )

   Hartree-Fock Frequencies
       The following input will compute Hartree-Fock frequencies by finite displacements. A
       thermodynamic analysis will also be performed. If optimization input is also provided,
       then the optimization will be run first, then the frequencies.

       % emacs should use -*- KeyVal -*- mode
       % molecule specification
       molecule<Molecule>: (
         symmetry = C1
         { atoms geometry } = {
           O     [  0.0000000000    0.0000000000    0.8072934188 ]
           H     [  1.4325589285    0.0000000000   -0.3941980761 ]
           H     [ -1.4325589285    0.0000000000   -0.3941980761 ]
         }
       )
       % basis set specification
       basis<GaussianBasisSet>: (
         name = 'STO-3G'
         molecule = $:molecule
       )
       mpqc: (
         checkpoint = no
         savestate = no
         % method for computing the molecule's energy
         mole<CLHF>: (
           molecule = $:molecule
           basis = $:basis
           memory = 16000000
         )
       % vibrational frequency input
         freq<MolecularFrequencies>: (
           molecule = $:molecule
         )
       )

   Giving Coordinates and a Guess Hessian
       The following example shows several features that are really independent. The variable
       coordinates are explicitly given, rather than generated automatically. This is especially
       useful when a guess Hessian is to be provided, as it is here. This Hessian, as given by
       the user, is not complete and the QNewtonOpt object will fill in the missing values using
       a guess the Hessian provided by the MolecularEnergy object. Also, fixed coordinates are
       given in this sample input.

       % emacs should use -*- KeyVal -*- mode
       % molecule specification
       molecule<Molecule>: (
         symmetry = C1
         { atoms geometry } = {
             H    [ 0.088    2.006    1.438 ]
             O    [ 0.123    3.193    0.000 ]
             H    [ 0.088    2.006   -1.438 ]
             O    [ 4.502    5.955   -0.000 ]
             H    [ 2.917    4.963   -0.000 ]
             H    [ 3.812    7.691   -0.000 ]
         }
       )
       % basis set specification
       basis<GaussianBasisSet>: (
         name = 'STO-3G'
         molecule = $:molecule
       )
       mpqc: (
         checkpoint = no
         savestate = no
         % method for computing the molecule's energy
         mole<CLHF>: (
           molecule = $:molecule
           basis = $:basis
           coor = $..:coor
           memory = 16000000
         )
         % molecular coordinates for optimization
         coor<SymmMolecularCoor>: (
           molecule = $:molecule
           generator<IntCoorGen>: (
             molecule = $:molecule
             extra_bonds = [ 2 5 ]
           )
           % use these instead of generated coordinates
           variable<SetIntCoor>: [
             <StreSimpleCo>:( atoms = [ 2 5 ] )
             <BendSimpleCo>:( atoms = [ 2 5 4 ] )
             <OutSimpleCo>: ( atoms = [ 5 2 1 3 ] )
             <SumIntCoor>: (
               coor: [
                 <StreSimpleCo>:( atoms = [ 1 2 ] )
                 <StreSimpleCo>:( atoms = [ 2 3 ] )
                 ]
               coef = [ 1.0 1.0 ]
               )
             <SumIntCoor>: (
               coor: [
                 <StreSimpleCo>:( atoms = [ 4 5 ] )
                 <StreSimpleCo>:( atoms = [ 4 6 ] )
                 ]
               coef = [ 1.0 1.0 ]
               )
             <BendSimpleCo>:( atoms = [ 1 2 3 ] )
             <BendSimpleCo>:( atoms = [ 5 4 6 ] )
           ]
           % these are fixed by symmetry anyway,
           fixed<SetIntCoor>: [
             <SumIntCoor>: (
               coor: [
                 <StreSimpleCo>:( atoms = [ 1 2 ] )
                 <StreSimpleCo>:( atoms = [ 2 3 ] )
                 ]
               coef = [ 1.0 -1.0 ]
               )
             <SumIntCoor>: (
               coor: [
                 <StreSimpleCo>:( atoms = [ 4 5 ] )
                 <StreSimpleCo>:( atoms = [ 4 6 ] )
                 ]
               coef = [ 1.0 -1.0 ]
               )
             <TorsSimpleCo>:( atoms = [ 2 5 4 6] )
             <OutSimpleCo>:( atoms = [ 3 2 6 4 ] )
             <OutSimpleCo>:( atoms = [ 1 2 6 4 ] )
           ]
         )
         % optimizer object for the molecular geometry
         opt<QNewtonOpt>: (
           function = $..:mole
           update<BFGSUpdate>: ()
           convergence<MolEnergyConvergence>: (
             cartesian = yes
             energy = $..:..:mole
           )
           % give a partial guess hessian in internal coordinates
           % the missing elements will be filled in automatically
           hessian = [
               [  0.0109261670 ]
               [ -0.0004214845    0.0102746106  ]
               [ -0.0008600592    0.0030051330    0.0043149957 ]
               [  0.0             0.0             0.0          ]
               [  0.0             0.0             0.0          ]
               [  0.0             0.0             0.0          ]
               [  0.0             0.0             0.0          ]
            ]
         )
       )

   Optimization with a Hydrogen Bond
       The automatic internal coordinate generator will fail if it cannot find enough redundant
       internal coordinates. In this case, the internal coordinate generator must be explicitly
       created in the input and given extra connectivity information, as is shown below.

       % emacs should use -*- KeyVal -*- mode
       % molecule specification
       molecule<Molecule>: (
         symmetry = C1
         { atoms geometry } = {
             H    [ 0.088    2.006    1.438 ]
             O    [ 0.123    3.193    0.000 ]
             H    [ 0.088    2.006   -1.438 ]
             O    [ 4.502    5.955   -0.000 ]
             H    [ 2.917    4.963   -0.000 ]
             H    [ 3.812    7.691   -0.000 ]
         }
       )
       % basis set specification
       basis<GaussianBasisSet>: (
         name = 'STO-3G'
         molecule = $:molecule
       )
       mpqc: (
         checkpoint = no
         savestate = no
         % method for computing the molecule's energy
         mole<CLHF>: (
           molecule = $:molecule
           basis = $:basis
           coor = $..:coor
           memory = 16000000
         )
         % molecular coordinates for optimization
         coor<SymmMolecularCoor>: (
           molecule = $:molecule
           % give an internal coordinate generator that knows about the
           % hydrogen bond between atoms 2 and 5
           generator<IntCoorGen>: (
             molecule = $:molecule
             extra_bonds = [ 2 5 ]
           )
         )
         % optimizer object for the molecular geometry
         opt<QNewtonOpt>: (
           function = $..:mole
           update<BFGSUpdate>: ()
           convergence<MolEnergyConvergence>: (
             cartesian = yes
             energy = $..:..:mole
           )
         )
       )

   Fixed Coordinate Optimization
       This example shows how to selectively fix internal coordinates in an optimization. Any
       number of linearly independent coordinates can be given. These coordinates must remain
       linearly independent throughout the optimization, a condition that might not hold since
       the coordinates can be nonlinear.

       By default, the initial fixed coordinates' values are taken from the cartesian geometry
       given by the Molecule object; however, the molecule will be displaced to the internal
       coordinate values given with the fixed internal coordinates if have_fixed_values keyword
       is set to true, as shown in this example. In this case, the initial Cartesian geometry
       should be reasonably close to the desired initial geometry and all of the variable
       coordinates will be frozen to their original values during the initial displacement.

       % emacs should use -*- KeyVal -*- mode
       % molecule specification
       molecule<Molecule>: (
         symmetry = CS
         { atoms geometry } = {
           H [  3.04 -0.69 -1.59 ]
           H [  3.04 -0.69  1.59 ]
           N [  2.09 -0.48 -0.00 ]
           C [ -0.58 -0.15  0.00 ]
           H [ -1.17  1.82  0.00 ]
           H [ -1.41 -1.04 -1.64 ]
           H [ -1.41 -1.04  1.64 ]
         }
       )
       % basis set specification
       basis<GaussianBasisSet>: (
         name = '4-31G*'
         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  using mode
       following. The initial geometry was obtained by doing a few fixed coordinate optimizations
       along the inversion coordinate.

       % emacs should use -*- KeyVal -*- mode
       % molecule specification
       molecule<Molecule>: (
         symmetry = CS
         { atoms geometry } = {
           H [  3.045436 -0.697438 -1.596748 ]
           H [  3.045436 -0.697438  1.596748 ]
           N [  2.098157 -0.482779 -0.000000 ]
           C [ -0.582616 -0.151798  0.000000 ]
           H [ -1.171620  1.822306  0.000000 ]
           H [ -1.417337 -1.042238 -1.647529 ]
           H [ -1.417337 -1.042238  1.647529 ]
         }
       )
       % basis set specification
       basis<GaussianBasisSet>: (
         name = '4-31G*'
         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  using mode
       following. The initial geometry was obtained by doing a few fixed coordinate optimizations
       along the inversion coordinate. An approximate guess Hessian will be computed, which makes
       the optimization 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 = '4-31G*'
         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
           )
         )
       )