chemshell_qchem / commitdiff
| doc/manual/qchem.htp | patch | blob | history |
diff --git a/doc/manual/qchem.htp b/doc/manual/qchem.htp
--- a/doc/manual/qchem.htp
+++ b/doc/manual/qchem.htp
<h2>Introduction</H2>
-The interface is designed to access basic functionality of the <A HREF="http://www.q-chem.com/" TARGET="_blank"> Q-Chem program
-package</A>. It is capable of calculating ground state energies and gradients
-on the restricted closed-shell Hartree-Fock, DFT (BLYP, BP86, BPW91, B3PW91, S-VWN-LDA)
-and RI-MP2 level of theory. The interface creates the necessary input
-files for the Q-Chem run, executes Q-Chem and finally extracts the QM-results.<br><br>
+The interface is designed to access basic functionality of the <A
+HREF="http://www.q-chem.com/" TARGET="_blank"> Q-Chem program package</A>. Currently the interface is
+capable of calculating ground state energies and gradients on the restricted
+closed-shell Hartree-Fock, DFT and RI-MP2 levels of theory.
+For DFT calculations the functionals BLYP, BP86, B3LYP, B3PW91, BPW91, S-VWN-LDA, PBE0 are available.
-In order to use the interface, the environment must be set up as
-required for a Q-Chem standard run depending on the Q-Chem version .
-Commonly, at least the shell environment
-variables<br><br>
+The interface creates the necessary input files for the Q-Chem run, executes
+Q-Chem and finally extracts the QM-results.<br><br>
+
+In order to use the interface, the environment must be set up as required for a
+Q-Chem standard run depending on the Q-Chem version. Commonly, at least the
+shell environment variables<br><br>
<TABLE CELLPADDING=3 BORDER="1">
<TR>
<TD>QC </TD> <TD>Path to Q-Chem main directory </TD>
</TR>
<TR>
-<TD>QCAUX </TD> <TD>Path to Q-Chem basis set directory </TD>
+<TD>QCAUX </TD> <TD>Path to Q-Chem auxiliary directory </TD>
</TR>
<TR>
<TD>QCSCRATCH </TD> <TD>Path to scratch directory for Q-Chem scratch output</TD>
</TABLE>
<br>
-need to be set (see <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual</A>).
-For an example see the qchemrc in the example/qchem folder.
+need to be set and "qchem" needs to be in the path, e.g. by sourcing
+$QC/bin/qchem.setup.sh
+(see <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf"
+TARGET="_blank">Q-Chem manual</A>). See also the file "qchemrc" in the
+example/qchem folder as example file that can be sourced before the
+ChemShell run.<br><br>
+
+Informations on further developments of the Q-Chem interface and how to join the ChemShell-Q-Chem project
+can be found on <A HREF="http://ccpforge.cse.rl.ac.uk/gf/project/chemshell_qchem/" TARGET="_blank">http://ccpforge.cse.rl.ac.uk/gf/project/chemshell_qchem/</A>.
+
<a name="args"></a>
<H2>Command Line Arguments</H2>
<TD ALIGN="LEFT" VALIGN="TOP">keyword</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">STO-3G</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Required basis set (qchem library <A HREF="#Notes">[1]</A>)</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Required basis set (Q-Chem library <A HREF="#Notes">[1]</A>)</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">basisspec</TD>
-<TD ALIGN="LEFT" VALIGN="TOP"><use list_link></TD>
+<TD ALIGN="LEFT" VALIGN="TOP">ChemShell notation</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">sto-3g all</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Required basis set (ChemShell library)</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Required basis set (ChemShell library <A HREF="#Notes">[2]</A>)</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">keyword</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">medium</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Determines accuracy of SCF calculation <A HREF="#Notes">[2]</A>: debug, lowest, low, medium, high, highest </TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Determines accuracy of SCF calculation <A HREF="#Notes">[3]</A>: debug, lowest, low, medium, high, highest </TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">integer</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">undefined</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Determines accuracy of DFT grid in Q-Chem notation <A HREF="#Notes">[3]</A>.</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Determines size and type of DFT grid in Q-Chem notation <A HREF="#Notes">[4]</A>.</TD>
</TR>
<TR>
@@ -91,28 +101,28 @@ Currently the following ChemShell command line arguments are available:<br><br>
<TD ALIGN="LEFT" VALIGN="TOP">string</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">qchem</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Determines the name of qchem input (jobname.com), output (jobname.log) and scratch (jobname.scr <A HREF="#Notes">[4]</A>).</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Determines the name of Q-chem input (jobname.com), output (jobname.log) and scratch (jobname.scr <A HREF="#Notes">[5]</A>).</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">hamiltonian</TD>
<TD ALIGN="LEFT" VALIGN="TOP">keyword</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">hf</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Choice of QM Hamiltonian: hf, blyp, bp86, b3lyp <A HREF="#Notes">[5]</A>, b3lyp5 <A HREF="#Notes">[5]</A>, b3pw91, bpw91, s-vwn-lda, rimp2, rimp2_svp <A HREF="#Notes">[6]</A></TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Choice of QM Hamiltonian: hf, blyp, bp86, b3lyp <A HREF="#Notes">[6]</A>, b3lyp5 <A HREF="#Notes">[6]</A>, b3pw91, bpw91, s-vwn-lda, pbe0, rimp2, rimp2_svp <A HREF="#Notes">[7]</A></TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">mem_total</TD>
<TD ALIGN="LEFT" VALIGN="TOP">integer</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">2000</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Sets the total memory available to Q-Chem, in megabytes <A HREF="#Notes">[7]</A>.</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Sets the total memory available to Q-Chem, in megabytes <A HREF="#Notes">[8]</A>.</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">mem_static</TD>
<TD ALIGN="LEFT" VALIGN="TOP">integer</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">100</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Sets the memory for individual Q-Chem program modules, in megabytes <A HREF="#Notes">[8]</A>.</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Sets the memory for individual Q-Chem program modules, in megabytes <A HREF="#Notes">[9]</A>.</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">harmonic</TD>
<TD ALIGN="LEFT" VALIGN="TOP">integer</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">undefined</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Allows for specification of cartesian GTOs vs. pure sherical harmonics by Q-Chem nomenclature <A HREF="#Notes">[9]</A>.</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Allows for specification of cartesian GTOs vs. pure sherical harmonics by Q-Chem nomenclature <A HREF="#Notes">[10]</A>.</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">keyword</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">sad</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Initial guess for the one-particle density matrix: SAD, CORE, GWH or READ <A HREF="#Notes">[10]</A>.</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Initial guess for the one-particle density matrix: SAD, CORE, GWH or READ <A HREF="#Notes">[11]</A>.</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">bool</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">1</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Switch on/off the separate formation of Coulomb and exchange part <A HREF="#Notes">[11]</A>.</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Switch on/off the separate formation of Coulomb and exchange part <A HREF="#Notes">[12]</A>.</TD>
</TR>
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">integer</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">-1</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Controls the number of lowest-level boxes in one dimension for CFMM <A HREF="#Notes">[12]</A>: -1, 1 , >=8 <A HREF="#Notes">[13]</A>.
+<TD ALIGN="LEFT" VALIGN="TOP">Controls the number of lowest-level boxes in one dimension for CFMM <A HREF="#Notes">[13]</A>: -1, 1 , >=8 <A HREF="#Notes">[14]</A>.
</TD>
</TR>
<TD ALIGN="LEFT" VALIGN="TOP">bool</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">0</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Switch on/off linear scaling screening for the exchange part (LinK <A HREF="#Notes">[14]</A>) <A HREF="#Notes">[15]</A>.</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Switch on/off linear scaling screening for the exchange part (LinK <A HREF="#Notes">[15]</A>) <A HREF="#Notes">[16]</A>.</TD>
</TR>
<TR>
@@ -167,15 +177,7 @@ Currently the following ChemShell command line arguments are available:<br><br>
<TD ALIGN="LEFT" VALIGN="TOP">keyword</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">undefined</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Switch on Grimme's dispersion type correction: EMPIRICAL_GRIMME <A HREF="#Notes">[16]</A>.</TD>
-</TR>
-
-<TR>
-<TD ALIGN="LEFT" VALIGN="TOP">verbose</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">keyword</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">yes</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Choose verbosity.</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Switch on Grimme's dispersion type correction: EMPIRICAL_GRIMME <A HREF="#Notes">[17]</A>.</TD>
</TR>
<TR>
@@ -183,34 +185,29 @@ Currently the following ChemShell command line arguments are available:<br><br>
<TD ALIGN="LEFT" VALIGN="TOP">Q-Chem notation</TD>
<TD ALIGN="LEFT" VALIGN="TOP">no</TD>
<TD ALIGN="LEFT" VALIGN="TOP">undefined</TD>
-<TD ALIGN="LEFT" VALIGN="TOP">Set additional Q-Chem input. Use with care <A HREF="#Notes">[17]</A> !</TD>
+<TD ALIGN="LEFT" VALIGN="TOP">Set additional Q-Chem input. Use with care <A HREF="#Notes">[18]</A> !</TD>
</TR>
</TABLE>
-<H3>
-Examples</H3>
-Single point MP2 energy of a charged species:<br>
-<tt>energy coords=start.c energy=e theory=turbomole : { hamiltonian=mp2 ri_memory=1000 basis=TZVPP charge=-3 }
-print_matrix matrix=e</tt><br>
-
-Parallel geometry optimisation, using an already existing control file:<br>
-<tt>hdlcopt coords=start.c result=final.c theory=turbomole : { hamiltonian=bp86
-ri_memory=1000 nproc=4 read_control=yes } <A HREF="#Notes">3</A></tt>
<H3>
-<A NAME="Notes">Notes</A></H3>
+<A NAME="Notes">Notes and references </A></H3>
<OL>
<LI>
-Using the argument "basis" the basis set needs to be specified in Q-Chem nomenclature. Especially note that Ahlrichs SVP is denoted VDZ**.
+Using the argument "basis" the basis set needs to be specified in Q-Chem nomenclature. In particular note that the basis set Ahlrichs SVP is denoted as VDZ** in Q-Chem.
+
+<LI>
+If a basis set is taken from the ChemShell library the basis set is explicitly included in the Q-Chem input within a $basis-section and the Q-Chem $rem-variable
+basis is set to "gen" (see <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual</A>). As for an explicit basis set the default guess
+(Superposition of atomic densities, SAD) is not available, the guess is created by basis set projection based on an initial STO-3G calculation.
<LI>
-The different levels determine the SCF accuracy concerning
-the SCF convergence (A), the threshold for density based Schwarz screening
-of electron repulsion integrals (B) and the DFT grid size (C).
+The different levels determine the SCF accuracy concerning three aspects: (A) The SCF convergence, (B) the threshold for density based Schwarz screening
+of electron repulsion integrals and (C) the DFT grid size.
<TABLE CELLPADDING=3 BORDER="1" >
<TR><TD> keyword</TD><TD ALIGN="CENTER"> (A) </TD><TD ALIGN="CENTER"> (B) </TD><TD ALIGN="CENTER"> (C) </TD></TR>
<TR><TD> debug </TD><TD ALIGN="CENTER"> 10<sup>-3</sup></TD><TD ALIGN="CENTER"> 10<sup>-6</sup></TD><TD ALIGN="CENTER">"Low quality" grid </TD></TR>
</TABLE>
Use the largest affordable accuracy. Typically "medium" is sufficient
for standard SCF energetics but you might need to choose "high" for RI-MP2,
-gradients or also for large QM regions! For details concerning the grid abbreviations see the <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual</A>.
+gradients or also for large QM regions! For details concerning the grid abbreviations see <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual</A>.
<LI>
If not specified the DFT grid is chosen according to the argument "accuracy".
<LI>
-The Q-Chem scratch then is written to $QCSCRATCH/jobname.scr/
+The Q-Chem scratch is written to $QCSCRATCH/jobname.scr/
<LI>
B3LYP and B3LYP5 differ in the correlation functional:
<TABLE BORDER=0>
<TR><TD>B3LYP </TD><TD>(correlation: 0.8100 LYP + 0.1900 VWN1RPA)</TD></TR>
-<TR><TD>B3LYP5</TD><TD>(correlation: 0.1900 VWN + 0.8100 LYP)</TD></TR>
+<TR><TD>B3LYP5</TD><TD>(correlation: 0.8100 LYP + 0.1900 VWN )</TD></TR>
</TABLE>
-See <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual</A>.
+For example, Q-Chem-B3LYP corresponds to Turbomole-B3LYP_GAUSSIAN (and Gaussian-B3LYP), while Q-CHEM-B3LYP5 corresponds to Turbomole-B3LYP (and original parameters).
+Possible remaining differences are due to different DFT grids (see argument "accuracy" or "grid").
<LI>
-For RI-MP2 calculation with Ahlrichs SVP basis set and corresponding auxiliary basis set.
+Use this Hamiltonian for RI-MP2 calculations with SVP auxiliary basis set. In addition specify the "basis" argument as usual <A HREF="#Notes">[1]</A>.</TD>.
<LI>
-Make sure you physically provide the specified memory. For large QM regions the default (2GB) needs to be increased. See <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual</A> for details.
+Make sure you physically provide the specified RAM. For large QM regions the default (2GB) needs to be increased. See <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual</A> for details.
<LI>
-Make sure you physically provide the specified memory. For large QM regions the default (100MB) needs to be increased. See <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual for details</A>.
+Make sure you physically provide the specified RAM. For large QM regions the default (100MB) needs to be increased. See <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual for details</A>.
<LI>
-If the "purecart" argument is used the specifications by "harmonic" are overwritten. See <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual</A> for the purecart variable.
+If the "purecart" argument is used, the specifications by "harmonic" are overwritten. See <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual</A> for the purecart variable.
<LI>
Q-Chem provides the core hamiltonian guess (CORE), the superposition of atomic densities (SAD, default), and
-the generalized Wolfsberg-Helmholtz guess (GWH). Addidionally by the keyword "READ" an adequate guess can be read in from file. For this purpose, the file containing the guess
+the generalized Wolfsberg-Helmholtz guess (GWH). Additionally by the keyword "READ" an adequate guess can be read in from file. For this purpose, the file containing the guess
needs to be located in the scratch directory, i.e. $QCSCRATCH/jobname.scr/. See <A HREF="http://www.q-chem.com/doc_for_web/qchem_manual_3.2.pdf" TARGET="_blank">Q-Chem manual</A> for details.
<LI>
Switch on for large QM systems as "separate_jk" is required to make use of
-CFMM <A HREF="#Notes">[12]</A> and LinK <A HREF="#Notes">[14]</A>.
+CFMM <A HREF="#Notes">[13]</A> and LinK <A HREF="#Notes">[15]</A>.
<LI>
-C. A. White, B. G. Johnson and M. Head-Gordon, The Continuous Fast Multipole Method, <em>Chem. Phys. Letters</em>, <strong>230</strong>, 8 (1994).
+C. A. White, B. G. Johnson, P. M.W. Gill and M. Head-Gordon, The Continuous Fast Multipole Method, <em>Chem. Phys. Letters</em>, <strong>230</strong>, 8 (1994).
<LI>Use the default (-1) unless you really want to change the CFMM behavior (-1: Program decides best value turning on CFMM when useful, 1: Do not use CFMM, n >=8: Use CFMM with n lowest-level boxes in one dimension).
@@ -283,8 +281,17 @@ Set any additional input designated for the $rem-section of Q-Chem (see <A HREF
<TR><TD> </TD><TD> </TD><TD>. </TD><TD> </TD></TR>
<TR><TD> </TD><TD>}</TD><TD> </TD><TD> </TD></TR>
</TABLE>
-Be aware, of course, that by this the Q-Chem output may be modified in such a way that the proper extraction of QM results fails!
+Use with care and be aware, of course, that by this the Q-Chem output may be modified in such a way that the proper extraction of QM results may fail!
</OL>
+<H3>
+Examples</H3>
+Some basic examples are provided in the example/qchem folder along with an example for setting the Q-Chem environment (qchemrc).
+The names of example inputs (.chm) and corresponding outputs (.log) are structured as follows:<br>
+
+[system]_[e(nergy)/g(radient)]_[QM/QMMM]_[Hamiltonian]_[basis/(basis)spec]_[basisname] <br>
+
+For the DNA-Enzyme complex also the required Amber prmtop and inpcrd are provided.
+
<file include="tail.htp">
