Overview
--------

Postg is a program that implements the calculation of the dispersion
energy and related quantities using the exchange-hole dipole
moment(XDM) model. This program reads the output of a
Gaussian (http://www.gaussian.com/) calculation (a wfn, wfx, fchk or
molden file) and computes the XDM atomic moments and volumes,
dispersion coefficients ($C_6$, $C_8$, and $C_{10}$), Hirshfeld
charges, the dispersion energy and its first and second derivatives,
and the total energy. The code can be used to calculate the dispersion
energy at a single point or to perform geometry optimizations and
frequency calculations using Gaussian's "external" keyword. 

To use postg, you will need the parameters for the damping function,
which depend on the exchange-correlation functional you are using and
also on the basis set (if it is far from complete). A list of
parameters is shipped with the postg distribution (a file called
xdm.param) and can also be found online at http://schooner.chem.dal.ca .

Compilation
-----------

To build postg, first uncompress the package or clone the repository:

    tar xjvf postg.tar.bz2
    cd postg/

and then edit the Makefile and uncomment the block corresponding to
your compiler (or write your own if it's not in the list). I normally
use the Intel fortran compiler for postg, so my compilation flags look
like: 

    FC = ifort
    FCFLAGS = -O2 -openmp
    LDFLAGS = -O2 -openmp
  
The "-openmp" option activates the shared-memory parallelizaton. After
this, you should be able to generate the "postg" binary by running:

    make

No environment variables need to be set to run postg nor any special
setup is required. Shared-memory parallelization is implemented using
the OpenMP library, so the OMP_NUM_THREADS environment variable can be
used to control the number of processors that is used in the
calculation. For instance, use:

    export OMP_NUM_THREADS=8

in your .bashrc (or the equivalent setenv in your .cshrc if you use
csh) to get postg to use 8 threads in your calculations. Usually postg
takes mere seconds to complete the calculation, but in large systems
this may be important.

Use
---

In order to use postg, you need a gaussian-style wfn, wfx, fchk
(formatted checkpoint) or molden file. The first two are generated by
passing the "output=wfn" or "output=wfx" keywords to the gaussian
input, followed by the name of the file at the end. The fchk can be
obtained from the checkpoint file (use "%chk" before the route
section) by applying the formchk utility program to it. Many programs
(including psi4, gaussian, and gamess) generate molden-style
wavefunction files (extension .molden).

If, for instance, your wavefunction file is calc.wfn, then

    postg 0.754 1.102 calc.wfn lcwpbe

calculates the dispersion energy using damping parameters $a1=0.754$,
$a2=1.102$ Å and the atomic volumes corresponding to the LC-wPBE
functional. Damping function parameters for common functionals and
basis sets can be found in http://schooner.chem.dal.ca. The functional
keyword can be one of:

* blyp
* b3lyp
* bhandhlyp, bhandh, bhah, bhahlyp
* camb3lyp, cam-b3lyp
* pbe
* pbe0
* lcwpbe, lc-wpbe
* pw86, pw86pbe
* b971, b97-1
* A number between 0 and 1 specifying the amount of exact exchange in
  the functional. In this case, the atomic volumes of the lighter
  elements are found by interpolation.

Using wfx instead of wfn is **strongly** recommended. We never got the
format of the wfn nailed down so using wfns may fail for large systems
with thousands of primitives. 

Optimizations and frequency calculations
----------------------------------------

The "external" keyword in gaussian can be used together with the
"gxdmopt.sh" script, provided in the postg package, to perform
geometry optimizations ("opt") and frequency ("freq")
calculations. The typical input is:

    #p external='./gxdmopt.sh' opt=(nomicro) freq
    
    title
    
    0 1
    ... geometry ...

The "gxdmopt.sh" script has to be modified to specify the functional,
basis, ECPs, etc. Inside this script, you can find a "modify this"
section at the beginning, that encapsulates all the information that
needs to be tweaked:

    ## modify this
    chf="lcwpbe"          # the functional keyword for postg. Can be a number
    c1=1.0875             # a1 parameter
    c2=0.4850             # a2 parameter
    basis="aug-cc-pvtz"   # basis set file or (if not found) basis set keyword
    ecp=""                # ecp file
    G09="g09"             # gaussian executable
    POSTG="postg"         # postg executable
    verbose=""            # verbose flag: write more info about the
                          # intermediate gaussian calculation. verbose=1
                          # gives huge output files.
    guesstrick=""         # if guesstrick=bleh, use bleh.chk as checkpoint file
                          # for the underlying calculation and re-use it from
			  # one step to the next. Speeds up geometry optimizations.
    cat > $2.route <<EOF  # this is the route section of the calculation
    %mem=2GB              # it is passed as-is to the underlying gaussian process
    %nprocs=4             # basis set and ecp's pseudo=read are inserted automatically
    #p lc-wpbe int(grid=ultrafine)
    EOF
    #########

The directory "examples" contains some input files showing how to use
this script with gaussian: 

- ecps: optimization of the Zn-He dimer using ECPs for Zn.
- opt: optimization of the CO2 dimer.
- optfreq: optimization and frequency calculation in the Ne dimer.
- opt_open: methane/methyl radical optimization (open shell).
- sp: fixed-geometry calculation in the methane dimer. This can be
      done using the gxdmopt.sh script (ch4_ch4_script) or manually 
      by requesting the wfx file to be written with 'output=wfx' and
      then running postg (ch4_ch4_manual and runme.sh).

References and citation
-----------------------

The basic references for postg are:

* A. Otero-de-la-Roza and E. R. Johnson, J. Chem. Phys. **138**, 204109 (2013). 
  (http://dx.doi.org/10.1063/1.4807330) 
* F. O. Kannemann and A. D. Becke, J. Chem. Theory Comput. **6**, 1081 (2010).
  (http://dx.doi.org/10.1021/ct900699r)

Please, consider citing us if you find this program useful. The basic
XDM references are:

* E. R. Johnson and A. Becke, J. Chem. Phys. **123**, 024101 (2005).
  (http://dx.doi.org/10.1063/1.1949201)
* A. D. Becke and E. R. Johnson, J. Chem. Phys. **122**, 154104 (2005).
  (http://dx.doi.org/10.1063/1.1884601)
* A. D. Becke and E. R. Johnson, J. Chem. Phys. **123**, 154101 (2005).
  (http://dx.doi.org/10.1063/1.2065267)
* A. D. Becke and E. R. Johnson, J. Chem. Phys. **124**, 014104 (2006).
  (http://dx.doi.org/10.1063/1.2139668)
* E. R. Johnson and A. D. Becke, J. Chem. Phys. **124**, 174104 (2006).
  (http://dx.doi.org/10.1063/1.2190220)
* E. R. Johnson and A. D. Becke, Chem. Phys. Lett. **432**, 600 (2006).
  (http://dx.doi.org/10.1016/j.cplett.2006.10.094)
* A. D. Becke and E. R. Johnson, J. Chem. Phys. **127**, 124108 (2007).
  (http://dx.doi.org/10.1063/1.2768530)
* A. D. Becke and E. R. Johnson, J. Chem. Phys. **127**, 154108 (2007).
  (http://dx.doi.org/10.1063/1.2795701)
* F. O. Kannemann and A. D. Becke, J. Chem. Theory Comput. **5**, 719 (2009).
  (http://dx.doi.org/10.1021/ct800522r)
* F. O. Kannemann and A. D. Becke, J. Chem. Theory Comput. **6**, 1081 (2010).
  (http://dx.doi.org/10.1021/ct900699r)
* A. D. Becke, A. Arabi, and F. O. Kannemann, Can. J. Chem. **88**, 1057 (2010).
  (http://dx.doi.org/10.1139/V10-073)
* E. R. Johnson, J. Chem. Phys. **135**, 234109 (2011).
  (http://dx.doi.org/10.1063/1.3670015)
* A. Arabi and A. Becke, J. Chem. Phys. **137**, 014104 (2012).
  (http://dx.doi.org/10.1063/1.4731342)
* A. Otero-de-la Roza and E. R. Johnson, J. Chem. Phys. **138**, 054103 (2013).
  (http://dx.doi.org/10.1063/1.4789421)

And XDM applied to solid-state calculations:

* A. Otero-de-la Roza and E. R. Johnson, J. Chem. Phys. **136**, 174109 (2012).
  (http://dx.doi.org/10.1063/1.4705760)
* A. Otero-de-la Roza and E. R. Johnson, J. Chem. Phys. **137**, 054103 (2012).
  (http://dx.doi.org/10.1063/1.4738961)
* E. R. Johnson and A. Otero-de-la Roza, J. Chem. Theory Comput. **8**, 5124 (2012).
  (http://dx.doi.org/10.1021/ct3006375)

Copyright notice
----------------

Copyright (c) 2013-2015 Alberto Otero de la Roza, Felix Kannemann,
Erin R. Johnson, Ross M. Dickson, Hartmut Schmider, and Axel D. Becke.

postg is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.