diff --git a/doc/user/ccsd.tex b/doc/user/ccsd.tex index 2b865e68bd..d6459e2b66 100644 --- a/doc/user/ccsd.tex +++ b/doc/user/ccsd.tex @@ -109,10 +109,10 @@ include the directive TASK CCSD+T(CCSD) \end{verbatim} -Lower-level results which come as by-products of the requested -calculation are generally also printed in the output file and stored -on the run-time database, but the method specified in the \verb+TASK+ -directive is considered the primary result. +Lower-level results which come as by-products (such as MP3/MP4) of the +requested calculation are generally also printed in the output file +and stored on the run-time database, but the method specified in the +\verb+TASK+ directive is considered the primary result. \section{Debugging and Development Aids} diff --git a/doc/user/dft.tex b/doc/user/dft.tex index a10847789a..8a2d5dda83 100644 --- a/doc/user/dft.tex +++ b/doc/user/dft.tex @@ -17,30 +17,18 @@ The formal scaling of the DFT computation can be reduced by choosing to use auxiliary gaussian basis sets to fit the charge density (CD) and/or fit the exchange-correlation (XC) potential. -The DFT module is invoked in NWChem -by specifying the keyword \verb+dft+ as a TASK directive, e.g., - -\begin{verbatim} - TASK DFT -\end{verbatim} - -The keyword \verb+dft+ tells the code that this is a compound directive -potentially containing input for the DFT module. Additional subdirectives -may be specified by the user to define a particular -problem. The \verb+dft+ input will be processed until the -\verb+END+ directive is encountered. - +DFT input is provided using the compound \verb+DFT+ directive \begin{verbatim} DFT ... END \end{verbatim} -The actual DFT calculation will -be performed when the input module encounters the \verb+TASK+ directive. -Refer to the \verb+TASK+ directive description in -Section \ref{sec:task} for a complete list of operations that can be -specified in the DFT module. +The actual DFT calculation will be performed when the input module +encounters the \verb+TASK+ directive (Section \ref{sec:task}). +\begin{verbatim} + TASK DFT +\end{verbatim} Once a user has specified a geometry and a Kohn-Sham orbital basis set the DFT module can be invoked with no input directives (defaults @@ -643,7 +631,7 @@ would be interpreted as 80 radial points, 20 theta points, and 40 phi points per center (or 64000 points per center before pruning). A second quadrature available for the numerical integration is an -Euler-MacLaurin scheme for the radial components and a Lebedev +Euler-Mac\-Laurin scheme for the radial components and a Lebedev scheme for the angular components\footnote{The subroutine for the Lebedev grid was supplied by M.~Caus\`a of the University of Torino.}. Within this numerical integration procedure various levels diff --git a/doc/user/driver.tex b/doc/user/driver.tex index 397b475084..c8082b477f 100644 --- a/doc/user/driver.tex +++ b/doc/user/driver.tex @@ -1,34 +1,38 @@ \label{sec:driver} -The DRIVER module is one of two drivers to perform a geometry -optimization function on the molecule defined by input using the -\verb+GEOMETRY+ directive (see Section \ref{sec:geom}). Geometry -optimization is either an energy minimization or a transition state -optimization. DRIVER is selected by default out of the two available -modules to perform geometry optimization. Selection of the other -optimization driver STEPPER may be made through the use of a SET -directive : ( SET OPT:DRIVER F ) . Optional input for this module is -specified within the compound directive, +The DRIVER module is one of two drivers (see Section \ref{sec:stepper} +for documentation on STEPPER) to perform a geometry optimization +function on the molecule defined by input using the \verb+GEOMETRY+ +directive (see Section \ref{sec:geom}). Geometry optimization is +either an energy minimization or a transition state optimization. +The algorithm programmed in DRIVER is a quasi-newton optimization +with line searches and approximate energy hessian updates. +DRIVER is selected by default out of the two available modules to +perform geometry optimization. In order to force use of DRIVER (e.g., +because a previous optimization used STEPPER) provide a DRIVER input +block (below) --- even an empty block will force use of DRIVER. + +Optional input for this module is specified within the compound +directive, \begin{verbatim} DRIVER ... END \end{verbatim} -The algorithm programmed in DRIVER is a quasi-newton optimization -with line searches and approximate energy hessian updates. - Input specified for the DRIVER module may appear anywhere in the input -file. In the current version of NWChem, DRIVER uses geometries that -are defined via Cartesian coordinates or internal coordinates. The -latter may be user-defined with the ZMT input or may be automatically -defined as a result of the AUTOZ option. The initial guess nuclear -Hessian is the identity matrix and there is an ASCII interface file to -input a Hessian from another code. The automatic generation of finite -difference Hessians will be available soon. When internal coordinates -are selected an appropriate initial hessian matrix is automatically -created to match the internal coordinate definition. +file preceding the \verb+TASK+ directive performing the optimization. +In the current version of NWChem, DRIVER uses geometries that are +defined via Cartesian coordinates or internal coordinates. The latter +may be user-defined with the Z-matrix input (Section +\ref{sec:Z-matrix}) or may be automatically generated using the +\verb+AUTOZ+ option (Section \ref{sec:geomkeys}). The initial guess +nuclear Hessian is the identity matrix and there is an ASCII interface +file to input a Hessian from another code. The automatic generation +of finite difference Hessians will be available soon. When internal +coordinates are selected an appropriate initial hessian matrix is +automatically created to match the internal coordinate definition. Execution of the DRIVER module calculation is invoked with a \verb+TASK+ directive (see Section \ref{sec:task}). @@ -37,29 +41,37 @@ No input is required for DRIVER. If no input is present the default actions are to minimize the energy as a function of the geometry with a maximum of 20 stepper iterations. +\section{{\tt NTPOPT} --- Maximum number of steps} + \begin{verbatim} NTPOPT \end{verbatim} -The value specified for the integer \verb+ntpopt+ defines the maximum +The value specified for the integer \verb++ defines the maximum number of geometry optimization steps. +\section{{\tt CVGOPT} --- Convergence criterion} + \begin{verbatim} CVGOPT \end{verbatim} -The value specified for the real \verb+cvgopt+ defines the convergence +The value specified for the real \verb++ defines the convergence threshold of the optimization algorithm. The convergence criterion is the largest component of the energy gradient for the coordinates used in the optimization ( cartesian or internal coordinates ). +\section{{\tt LINOPT} --- Linear search} + \begin{verbatim} LINOPT \end{verbatim} -The value specified for the integer \verb+linopt+ defines the maximum +The value specified for the integer \verb++ defines the maximum number of energy points during any linear search. +\section{{\tt INHESS} and {\tt MODUPD} --- Hessian update algorithm} + \begin{verbatim} INHESS \end{verbatim} @@ -68,18 +80,22 @@ number of energy points during any linear search. MODUPD \end{verbatim} -The value specified for the integer \verb+modupd+ defines the hessian -update algorithm, Fletcher-Powell update ( modupd 0 ) or -Broyden-Fletcher-Goldfar-Shanno update ( modupd 1 ) +The value specified for the integer \verb++ defines the hessian +update algorithm, Fletcher-Powell update (\verb+ = 0+) or +Broyden-Fletcher-Goldfar-Shanno update (\verb+ = 1+) + +\section{{\tt MODSAD} --- Optimization mode} \begin{verbatim} MODSAD \end{verbatim} The value specified for the integer \verb+modsad+ defines the type -of optimization to be performed, an energy minimization ( modsad 0 ) -or a transition state optimization ( modsad 1 ). +of optimization to be performed, an energy minimization +(\verb+ = 0+) +or a transition state optimization (\verb+ = 1+). +\section{{\tt MODDIR} --- Normal mode selection} \begin{verbatim} MODDIR diff --git a/doc/user/functionality.tex b/doc/user/functionality.tex index 3da6ed7cd8..6c81b1af3e 100644 --- a/doc/user/functionality.tex +++ b/doc/user/functionality.tex @@ -30,6 +30,8 @@ For all methods, the following operations may be performed \begin{itemize} \item Single point energy. \item Geometry Optimization (Minimization and Transition State). +\item Molecular dynamics on the fully {\em ab initio} potential energy + surface. \item Numerical first and second derivatives automatically computed if analytic derivatives are not available. \item Generation of the electron density file for the {\em Insight} @@ -59,4 +61,13 @@ simulations \item Free energy simulation \end{itemize} +There is also the capability to combine classical and quantum +descriptions in order to perform +\begin{itemize} +\item Mixed quantum-mechanics and molecular-mechanics (QM/MM) + minimizations and molecular dynamics using any of the quantum + mechanical wavefunctions. +\end{itemize} + + diff --git a/doc/user/geometry.tex b/doc/user/geometry.tex index 83bd436d6d..31e7d142eb 100644 --- a/doc/user/geometry.tex +++ b/doc/user/geometry.tex @@ -59,6 +59,7 @@ keywords in each of the three main parts. % These are examined in the following sections. \section{Main keywords on the {\tt GEOMETRY} directive} +\label{sec:geomkeys} This section presents the options that can be specified using the keywords and optional input on the main line of the {\tt GEOMETRY} directive. @@ -248,19 +249,20 @@ usage and definitions of the values specified for the variable \verb++ to describe the centers in a system; \begin{itemize} \item If the tag begins with characters that cannot be - matched against an atom, and those characters are not \verb+BQ+ - or \verb+X+, then a fatal - error is generated. -\item The tag of a center is used in the \verb+BASIS+ directive (Section -\ref{sec:basis}) to associate functions with centers. + matched against an atom, and those characters are not \verb+BQ+ + or \verb+X+, then a fatal + error is generated. +\item The tag of a center is used in the \verb+BASIS+ (Section + \ref{sec:basis}) and \verb+ECP+ (Section \ref{sec:ecp}) directives + to associate functions with centers. \item All centers with the same tag will have the same basis -functions. + functions. \item When automatic symmetry detection is functional, only centers -with the same tag will be candidates for testing for symmetry -equivalence. + with the same tag will be candidates for testing for symmetry + equivalence. \item The user specified charges (of all centers, atomic and dummy) -and any net total charge of the system (Section \ref{sec:charge}) are -used to determine the number of electrons. + and any net total charge of the system (Section \ref{sec:charge}) are + used to determine the number of electrons. \end{itemize} The Cartesian coordinates of the atom in the molecule are specified as @@ -528,9 +530,9 @@ geometry CF2 1.3669 CF3 1.3669 constants - HCH1 10428 - HCH2 10474 - HCH3 1047 + HCH1 104.28 + HCH2 104.74 + HCH3 104.7 CCF1 112.0713 CCF2 112.0341 CCF3 112.0340 @@ -562,40 +564,28 @@ internal coordinates. These are arranged as follows: \section{{\tt ZCOORD} --- Forcing internal coordinates} \label{sec:zcoord} -Specifying the keyword \verb+AUTOZ+ on the first line of the \verb+GEOMETRY+ -directive forces automatic generation of internal -coordinates for use in geometry optimizations. Connectivity -is inferred by comparing inter-atomic distances with van de Waals -radii, and under some circumstances it may be necessary to augment the +Specifying the keyword \verb+AUTOZ+ on the first line of the +\verb+GEOMETRY+ directive forces automatic generation of internal +coordinates for use in geometry optimizations. Connectivity is +inferred by comparing inter-atomic distances with van de Waals radii, +and under some circumstances it may be necessary to augment the automatically generated list of internal coordinates. This is -accomplished by including the optional directive {\tt ZCOORD} within the geometry -directive. The general form of the \verb+ZCOORD+ directive is as follows, +accomplished by including the optional directive {\tt ZCOORD} within +the geometry directive. The general form of the \verb+ZCOORD+ +directive is as follows, \begin{verbatim} - [ZCOORD - - ... - END] + ZCOORD + [ijbond ] + [ijkang ] + [ijklto ] + [ijklop ] + [ijklnb ] + END \end{verbatim} -% The centers \verb+i+, \verb+j+, \verb+k+ and \verb+l+ below {\em must} be -% specified using number of the centers. -The specific input that must be supplied for the \verb+i+, \verb+j+, \verb+k+, and -\verb+l+ is described below. The centers -\verb+i+, \verb+j+, \verb+k+ and \verb+l+ are numbered automatically in the -order they are supplied on the input for the \verb+ZMATRIX+ directive. The -user must adhere to this convention when suppliying the \verb+ZCOORD+ -directive input described here. The bond length and angles for the centers -are defined as follows; - -\begin{verbatim} - ZCOORD - ijbond i j - ijkang i j k - ijklto i j k l - ijklop i j k l - ijklnb i j k l - END -\end{verbatim} +The centers \verb+i+, \verb+j+, \verb+k+ and \verb+l+ {\em must} +be specified using the number of the centers as supplied in the input +for the \verb+ZMATRIX+ directive. \begin{itemize} \item {\tt ijbond} --- a bond between the two centers. diff --git a/doc/user/getstart.tex b/doc/user/getstart.tex index 8b47ff5ac3..af109d179a 100644 --- a/doc/user/getstart.tex +++ b/doc/user/getstart.tex @@ -199,11 +199,6 @@ scf print low end -stepper - trust 0.5 - convgg 0.01 -end - set "ao basis" "starting basis" task scf optimize @@ -217,10 +212,6 @@ end set "mp2_grad:print" low -stepper - convgg 1d-6 -end - task mp2 optimize set "mp2_grad:print" none @@ -265,14 +256,6 @@ available for open-shell systems currently (see Section reduce the output from the SCF module to a minimum during the geometry optimization. -For this calculation, the gradient convergence threshold for the -geometry optimization module {\tt STEPPER} is set to the -relaxed value of $10^{-2}$, rather than the default $10^{-4}$. This is -acceptable because the initial optimization only serves to provide a -starting guess. Increasing the trust radius (using the \verb+TRUST+ -directive) beyond the default of $0.1$ makes the optimization more -efficient (though less robust in hard to converge cases). - The final step in setting up the input for the SCF calculation is to specify that the \verb+"starting basis"+ should be used. This is accomplished by means of the \verb+SET+ directive, which specifies that @@ -312,19 +295,8 @@ guess vectors are reset to be the atomic guess, since the STO3G vectors are not appropriate (see Section \ref{sec:vectors} for details on the different possible starting guesses). -The convergence threshold for the geometry optimization module is reset -to $10^{-6}$ for the second task, a value which is smaller than -the default of $10^{-4}$. The default is appropriate for determination of the -optimized geometry and minimum energy, but a higher accuracy is -required in this task, for use in the subsequent computation of the -frequencies. The second {\tt TASK} directive invokes an MP2 -optimization, instead of the SCF optimization. - -% There is currently no input block for the MP2 gradients, so parameters -% for this module have to be set in the database via the {\tt set} -% directive. Currently only print options are recognized, and in this -% example, the \verb+SET+ directive is used to reduce the amount of -% output a reasonable minimum. +The second {\tt TASK} directive invokes an MP2 optimization, instead +of the SCF optimization. Once the MP2 optimization is completed, the geometry obtained in the calculation is used to perform a frequency calculation. This task is @@ -402,6 +374,8 @@ other. The following notation and syntax conventions are used in the generic descriptions of the NWChem input in the following sections. +\sloppy + \begin{itemize} \item a directive name always appears in all-capitals, in computer-type face; (e.g.; \verb+GEOMETRY+, \verb+BASIS+, \verb+SCF+). Note that @@ -437,6 +411,8 @@ characters following \verb+#+ (up to the physical end of the line) are ignored. \item \verb+...+ is used to indicate indefinite continuation of a list \end{itemize} +\fussy + An input parameter is identified in the description of the directive by prefacing the item with the name of the type of data expected; i.e., @@ -446,12 +422,12 @@ i.e., \item \verb+integer+ -- integer value(s) for a variable or an array \item \verb+logical+ -- true/false logical variable \item \verb+real + -- real floating point value(s) for a variable or -\item \verb+double + -- double-precision +\item \verb+double + -- synonymous with real an array \end{itemize} If an input item is not prefaced by one of these type names, -it is assumed to be of type 'string'. +it is assumed to be of type ``string''. The directive \verb+VECTORS+ (Section \ref{sec:vectors}) is presented here as an example of an NWChem input directive. The general form of the diff --git a/doc/user/intro.tex b/doc/user/intro.tex index 3c6af7ae6b..907f38ec27 100644 --- a/doc/user/intro.tex +++ b/doc/user/intro.tex @@ -75,8 +75,11 @@ including; \begin{itemize} \item detailed description of problem -\item platform you are running on +\item site name (e.g., EMSL, NERSC, \ldots) +\item platform you are running on including \begin{itemize} +\item vendor name +\item computer model \item operating system \item compiler \end{itemize} @@ -92,16 +95,13 @@ with the code and discuss problems. Announcements of new releases and bug fixes will also be made to this list. To subscribe to the user list, send a message to - -\begin{itemize} -\item {\tt majordomo@emsl.pnl.gov} -\end{itemize} - +\begin{verbatim} + majordomo@emsl.pnl.gov +\end{verbatim} The body of the message must contain the line - -\begin{itemize} -\item {\tt subscribe nwchem-users} -\end{itemize} +\begin{verbatim} + subscribe nwchem-users +\end{verbatim} The automated list manager is capable of recognizing a number of commands, including 'subscribe', 'unsubscribe', 'get', 'index', diff --git a/doc/user/nwarch.tex b/doc/user/nwarch.tex index 8bfc2dfade..8174674a33 100644 --- a/doc/user/nwarch.tex +++ b/doc/user/nwarch.tex @@ -68,10 +68,9 @@ Objects are built in the database by storing associated data as multiple entries using an internally consistent naming convention. This data is exclusively managed by the subroutines (or methods) that are associated with the object. Currently, the code has two main -objects; basis sets and geometries. Sections \ref{sec:geom}, -\ref{sec:basis}, and -\ref{sec:ecp} present a complete discussion of the input to describe -these objects. +objects; basis sets and geometries. Sections \ref{sec:geom} and +\ref{sec:basis}present a complete discussion of the input to describe +these objects. As an illustration of what comprises a geometry object, the following table contains a partial listing of the NWChem output of a water molecule @@ -101,12 +100,6 @@ for the water molecule, for example, an input file could be constructed with all of the geometries of interest by storing them in the database under different names. -% The {\tt -% GEOMETRY} directive (Section \ref{sec:geom}) permits geometries to -% be named (the default name is \verb+geometry+). For example, the -% input directive to define a geometry object in the database with the -% name \verb+"test water geometry"+ can be specified as follows; - The run-time database contents for the file \verb+h2o.db+ listed above were generated from the user-specified input directive, \begin{verbatim} @@ -146,12 +139,6 @@ NWChem will automatically check for such indirections when loading geometries. The basis set object functions in an identical fashion, using the default name \verb+"ao basis"+. -% , and it is intended that all -% future such objects will do so. (Note: the naming conventions and -% internal mechanisms for associating data with specific modules or -% tasks is expected to change in the future, but the directive for -% specifying names should remain the same.) - \section{Persistence of data and restart} \label{sec:persist} diff --git a/doc/user/nwargos.tex b/doc/user/nwargos.tex index 131691fc13..96899cc692 100644 --- a/doc/user/nwargos.tex +++ b/doc/user/nwargos.tex @@ -20,25 +20,27 @@ \def\nwrst{{\bf nwRST}} \def\nwsgm{{\bf nwSGM}} \def\argos{{\bf ARGOS}} + \section{Introduction} + \subsection{Spacial decomposition} \nwargos\ is the \nwchem\ module for molecular dynamics simulations of macromolecules and solutions. The module is a parallel implementation of \argos, a vectorized molecular dynamics package developed by T.P.Straatsma at the University of Houston. -\par + The distribution of data is based on a spacial decomposition of the molecular system, which offers the most efficient parallel implementation in terms of both memory requirements and communication costs, especially for simulations of large molecular systems. -\par + Inter-processor communication using the global array tools and the design of a data structure allowing distribution based on spacial decomposition are the key elements in taking advantage of the distribution of memory requirements and computational work with minimal communication. -\par + In the spacial decomposition approach, the physical simulation volume is divided into rectangular boxes, each of which is assigned to a processor. Depending on the conditions of the @@ -50,7 +52,7 @@ and the shape of the boxes, the frequent reassignment of atoms to boxes leading to a fluctuating number of atoms per box, and the locality of communication which is the main reason for the efficiency of this approach for very large molecular systems. -\par + To improve efficiency, molecular systems are broken up into separately treated solvent and solute parts. Solvent molecules are assigned to the domains according to their @@ -72,12 +74,12 @@ Consequently, one of the main efforts is to design algorithms and data structures to minimize the cost of this communication. However, for very large molecular systems, memory requirements also need to be taken into account. -\par + To compromise between these requirements exchange of data is performed in successive point to point communications rather than using the shift algorithm which reduces the number of communication calls for the same amount of communicated data. -\par + For inhomogeneous systems, the computational load of evaluating atomic interactions will generally differ between box pairs. This will lead to load imbalance between processors. In \nwargos\ @@ -94,7 +96,7 @@ box-box interactions. This method represents a more coarse load balancing scheme, but does not have the disadvantages of the box resizing algorithm. For most molecular systems the box pair redistribution is the more efficient and preferred method. -\par + The description of a molecular system consists of static and dynamic information. The static information does not change during a simulation and includes items such as connectivity, excluded and third @@ -104,8 +106,9 @@ the topology of the molecular system, and is kept on a separate topology file. The dynamic information includes coordinates and velocities for all atoms in the molecular system, and is kept in a so-called restart file. + \subsection{Topology} -\label{topology} +\label{sec:nwatopology} The static information about a molecular system that is needed for a molecular simulation is provided to the simulation module in a topology file. @@ -113,7 +116,7 @@ Items in this file include, among many other things, a list of atoms, their non-bonded parameters for van der Waals and electrostatic interactions, and the complete connectivity in terms of bonds, angles and dihedrals. -\par + In \nwargos, molecular systems a distinction is made between {\it solvent} and {\it solute}, which are treated separately. A solvent molecule is defined only once in the topology file, @@ -122,7 +125,7 @@ actual molecular system. In the current implementation only one solvent can be defined. Everything that is not solvent in the molecular system is solute. Each solute atom in the system must be explicitly defined in the topology. -\par + Molecules are defined in terms of one or more {\it segment}s. Typically, repetitive parts of a molecule are each defined as a single segment, such as the amino acid residues in a protein.. @@ -130,44 +133,45 @@ Segments can be quite complicated to define and are, therefore, collected in a set of database files. The definition of a molecular system in terms of segments is a {\it sequence}. -\par + A utility \nwtop\ reads the sequence file, retrieves all needed segments from the available segment databases, substitutes parameters from the force field parameter database files, and generates the topology file. -\par + A utility \nwsgm\ reads a rudimentary, force-field independent {\it fragment} defining atom types and connectivity, and constructs a template for a force-field dependent segment. Fragments can be also be collected into a set of fragment database files. -\par + A utility \nwrst\ generates a {\it restart} file, given a topology and coordinates from a PDB formatted file or another restart file. This utility can also be used to solvate a molecular system. + \subsection{Files} -\label{filenames} -\par -File names used by \nwargos\ have the form {\bf project\_id.ext}, with -exception of the topology file (\ref{topology}), which is named -{\bf project.top}. +\label{sec:nwafilenames} + +File names used by \nwargos\ have the form \verb+$project$_$id$.$ext$+, with +exception of the topology file (Section \ref{sec:nwatopology}), which is named +\verb+$project$.top+. Anything that refers to the definition of the chemical system can be used -for {\bf project}, as long as no periods or underlines are used. -The identifier {\bf id} can be anything that refers to the type of +for \verb++, as long as no periods or underlines are used. +The identifier \verb++ can be anything that refers to the type of calculation to be performed for the system with the topology defined. This file naming convention allows for the creation of a single -topology file {\bf project.top} that can be used for a number of -different calculations, each identified with a different {\bf id}. -For example, if {\bf crown.top} is the name of the topology file for -a crown ether, {\bf crown\_em}, {\bf crown\_md}, {\bf crown\_mcti} could +topology file \verb+$project$.top+ that can be used for a number of +different calculations, each identified with a different \verb++. +For example, if {\tt crown.top} is the name of the topology file for +a crown ether, {\tt crown\_em}, {\tt crown\_md}, {\tt crown\_mcti} could be used with appropriate extensions for the filenames for energy minimization, molecular dynamics simulation and multiconfiguration thermodynamic integration respectively. All of these calculations -would use the same topology file {\bf crown.top}. -\par -\label{extensions} -\par -The extensions {\bf ext} identify the kind of information on a file, +would use the same topology file {\tt crown.top}. + +\label{sec:nwaextensions} + +The extensions \verb++ identify the kind of information on a file, and are pre-determined. The complete list of extensions is \begin{tabbing} @@ -189,12 +193,13 @@ xxxxx\=\kill {\bf top} \> topology file, contains the static description of a system\\ {\bf vel} \> velocity trajectory file\\ \end{tabbing} + \subsection{Databases} -Database file names used by the setup programs \nwtop\ (\ref{nwtop}), -\nwrst\ (\ref{nwrst}) and \nwsgm\ (\ref{nwsgm}) have the form -{\bf forcefield\_level.ext}, where {\bf forcefield} stands for any of the -supported force fields (\ref{forcefields}). The source of the data is -identified by {\bf level}, and can be +Database file names used by the setup programs \nwtop\ (Section \ref{sec:nwanwtop}), +\nwrst\ (Section \ref{sec:nwanwrst}) and \nwsgm\ (Section \ref{sec:nwanwsgm}) have the form +\verb+$forcefield$_$level$.$ext$+, where \verb++ is any of the +supported force fields (Section \ref{sec:nwaforcefields}). The source of the data is +identified by \verb++, and can be \begin{center} \begin{tabular}{lll} \hline @@ -206,14 +211,14 @@ level & Description & Availability \\ \hline \end{tabular} \end{center} -\par + Only the level {\bf s} and {\bf x} databases are publicly available. The user is responsible for the private level {\bf u} and {\bf r} databases. When the utility programs scan the databases, the priority is {\bf t}$>${\bf u}$>${\bf x}$>${\bf s}$>$. -\par -The extension defines the type of database file. The complete list of -extensions is + +The extension \verb++ defines the type of database file. The +complete list of extensions is \begin{tabbing} xxxxx\=\kill {\bf att} \> atom type translation\\ @@ -222,13 +227,14 @@ xxxxx\=\kill {\bf seq} \> sequences\\ {\bf sgm} \> segments\\ \end{tabbing} -\par + Filenames including their paths of the different databases should be defined in a file -{\bf .nwargos} in a user's home directory, and provides the user the +{\tt .nwargos} in a user's home directory, and provides the user the option to select which database files are scanned. + \subsection{Force fields} -\label{forcefields} +\label{sec:nwaforcefields} Force fields supported by \nwargos\ are \begin{center} \begin{tabular}{lll} @@ -243,6 +249,7 @@ Keyword & Force field & Current status \\ \hline \end{tabular} \end{center} + \section{Creating fragment files} Fragment files contain the basic information needed to specify all interactions that need to be considered in a molecular simulation. @@ -251,7 +258,7 @@ The format of the fragment files is \begin{tabular}{lll} \hline\hline Card & Format & Description \\ \hline -I-1-1 & a1 & \$ to identify the start of a fragment \\ +I-1-1 & a1 & \$ to identify the start of a fragment \\ % $ for emacs I-1-2 & a10 & name of the fragment, the tenth character\\ & & N: identifies beginning of a chain\\ & & C: identifies end of a chain\\ @@ -290,8 +297,9 @@ III-1-1 & 16i5 & connectivity, duplication allowed\\ \hline\hline \end{tabular} \end{center} + \section{Creating segment files} -\label{nwsgm} +\label{sec:nwanwsgm} Program \nwsgm\ can be used to generate a template for a segment file from a corresponding fragment file. The segment file contains all information for the calculation of bonded and non-bonded interaction @@ -299,13 +307,13 @@ for a given chemical system using a specific force field. If a fragment is available in a local file or in a database file, the segment can be generated using \begin{verbatim} -nwsgm fragment ffield + nwsgm \end{verbatim} -where \verb+fragment+ is the name of the fragment. Since fragment +where \verb++ is the name of the fragment. Since fragment names rely on the last character for the type of fragment, spaces -should be replaced by underlines. \verb+ffield+ should be the +should be replaced by underlines. \verb++ should be the name of an available force field. -\par + The program \nwsgm\ only provides a template for a segment. It is often needed to make additional changes in this file. One important restriction is that dihedral interactions may only involve atoms on @@ -321,7 +329,7 @@ The format of a segment is \begin{tabular*}{150mm}{p{12mm}p{12mm}l} \hline\hline Deck & Format & Description \\ \hline -I-1-1 & a1 & \$ to identify the start of a segment \\ +I-1-1 & a1 & \$ to identify the start of a segment \\ %$ for emacs I-1-2 & a10 & name of the segment, the tenth character\\ & & N: identifies beginning of a chain\\ & & C: identifies end of a chain\\ @@ -468,6 +476,7 @@ VI-2-6 & e12.5 & improper dihedral force constant in kJ mol$^{-1}$, set 3 \\ \hline\hline \end{tabular*} \end{center} + \section{Creating sequence files} A sequence file describes a molecular system in terms of segments. The file format is @@ -475,7 +484,7 @@ file format is \begin{tabular*}{150mm}{p{12mm}p{12mm}l} \hline\hline Card & Format & Description \\ \hline -I-1-1 & a1 & \$ to identify the start of a sequence \\ +I-1-1 & a1 & \$ to identify the start of a sequence \\ %$ for emacs I-1-2 & a10 & name of the sequence\\ \multicolumn{3}{l}{Any number of cards in deck II to specify the system} \\ II-1-1 & i5 & segment number, except\\ @@ -509,10 +518,11 @@ II-1-2 & i3 & link atom in link segment 10\\ \hline\hline \end{tabular*} \end{center} + \section{Creating topology files} -\label{nwtop} -\par -The topology (\ref{topology}) describes all static information +\label{sec:nwanwtop} + +The topology (Section \ref{sec:nwatopology}) describes all static information that describes a molecular system. This includes the connectivity in terms of bond-stretching, angle-bending and torsional interactions, as well as the non-bonded interactions van der Waals and Coulombic interactions. @@ -521,219 +531,224 @@ generator \nwtop\ from the sequence in terms of segments as read from the sequence file. For each unique segment specified in this file the segment databases are searched for the segment definition. For segments not found in one of the database files a segment definition -needs to be generated, for example using the utility \nwsgm (\ref{nwsgm}). -\par +needs to be generated, for example using the utility \nwsgm (Section \ref{sec:nwanwsgm}). + The command line to run \nwtop\ is \begin{verbatim} -nwtop project forcefield + nwtop \end{verbatim} -where {\tt project} refers to the name of a sequence in one of the -sequence databases or in a local file {\bf project.seq}, and -{\tt forcefield} is the name of one of the available force fields -(\ref{forcefields}). +where \verb++ refers to the name of a sequence in one of the +sequence databases or in a local file \verb+$project$.seq+, and +\verb++ is the name of one of the available force fields +(Section \ref{sec:nwaforcefields}). If the sequence is found, the segment definitions are read from the -segment databases or from a local file {\bf project.sgm}. If all +segment databases or from a local file \verb+$project$.sgm+. If all segments are found, the parameter subsitutions are performed, using force field parameters taken from the parameter databases or from a -local file {\bf project.par}. After all lists have been generated the -topology is written to a local topology file {\bf project.top}. +local file \verb+$project$.par+. After all lists have been generated the +topology is written to a local topology file \verb+$project$.top+. + \section{Creating restart files} -\label{nwrst} +\label{sec:nwanwrst} Restart files contain all dynamical information about a molecular system and are created using preparation utility \nwrst. The command line is \begin{verbatim} -nwrst project + nwrst \end{verbatim} -in which case directives are taken from {\tt project}{\bf.rin}, or +in which case directives are taken from \verb+$project$.rin+, or \begin{verbatim} -nwrst + nwrst \end{verbatim} in which case directives are taken from standard input. -\par + The directives can be any of \begin{itemize} \item \begin{verbatim} -title + title \end{verbatim} reading three title cards immediately following the directive \item \begin{verbatim} -read topology + read topology \end{verbatim} -where {\tt filtop} is the topology file name. In general, this +where \verb++ is the topology file name. In general, this directive needs to be given before any coordinates can be read from a PDB formatted file or an existing restart file, or solvent coordinates can be read for solvation. \item \begin{verbatim} -read solvent + read solvent \end{verbatim} -where {\tt filslv} is the solvent name. In general, this directive +where \verb++ is the solvent name. In general, this directive needs to be given before any coordinates can be read from a PDB formatted file or an existing restart file. \item \begin{verbatim} -read PDB + read PDB \end{verbatim} -where {\tt filpdb} is the file with coordinates in PDB format. This +where \verb++ is the file with coordinates in PDB format. This directive, in general needs to be preceeded by reading the topology file and reading the solvation coordinates file. \item \begin{verbatim} -write PDB + write PDB \end{verbatim} -where {\tt filpdc} is the file with coordinates in PDB format +where \verb++ is the file with coordinates in PDB format \item \begin{verbatim} -read rst + read rst \end{verbatim} -where {\tt filrsi} is a restart file. This directive, in general needs +where \verb++ is a restart file. This directive, in general needs to be preceeded by reading the topology file and reading the solvation coordinates file. \item \begin{verbatim} -write rst + write rst \end{verbatim} -where {\tt filrst} is a restart file +where \verb++ is a restart file \item \begin{verbatim} -orient + orient \end{verbatim} changes the orientation of the solute to fit the smallest rectangular box with largest dimension along z and smallest dimension along x. \item \begin{verbatim} -solvate box [[[]]] + solvate box [[[]]] \end{verbatim} solvates the system in a rectangular box with dimensions bx $\times$ by $\times$ bz in nm \item \begin{verbatim} -center + center \end{verbatim} to put the solute center of geometry in the center of the simulation box \item \begin{verbatim} -expand with [[]] + expand with [[]] \end{verbatim} to expand the simulation box with xx, xy and xz in the x, y and z direction respectively \item \begin{verbatim} -expand to [[]] + expand to [[]] \end{verbatim} to expand the simulation box to xx, xy and xz in the x, y and z direction respectively \item \begin{verbatim} -boxsize + boxsize \end{verbatim} to resize the box to fit all atoms present \item \begin{verbatim} -periodic + periodic \end{verbatim} to specify the use of periodic boundary conditions \item \begin{verbatim} -vacuo + vacuo \end{verbatim} to specify a system in vacuo \item \begin{verbatim} -set touch + set touch \end{verbatim} to specify the minimum distance between any atom in the system and a solvent atom to be added during solvation \item \begin{verbatim} -velocities {solvent | solute} zero + velocities (solvent || solute) zero \end{verbatim} to initialize velocities \item \begin{verbatim} -reference {solvent | solute} zero + reference (solvent || solute) zero \end{verbatim} to initialize reference coordinates \item \begin{verbatim} -{ end | exit | quit | stop } + (end || exit || quit || stop) \end{verbatim} to stop the restart file generation \end{itemize} + \section{Molecular simulations} The type of molecular dynamics simulation is specified by the NWChem task directive. \begin{verbatim} -task md [ energy | optimize | dynamics | thermodynamics ] + task md [ energy || optimize || dynamics || thermodynamics ] \end{verbatim} -where the theory keyword {\bf md} specifies use of the molecular +where the theory keyword {\tt md} specifies use of the molecular dynamics module, and the operation keyword is one of \begin{itemize} \item -{\bf energy} for single configuration energy evaluation +{\tt energy} for single configuration energy evaluation \item -{\bf optimize} for energy minimization +{\tt optimize} for energy minimization \item -{\bf dynamics} for molecular dynamics simulations and single step +{\tt dynamics} for molecular dynamics simulations and single step thermodynamic perturbation free energy molecular dynamics simulations \item -{\bf thermodynamics} for combined multiconfiguration thermodynamic +{\tt thermodynamics} for combined multiconfiguration thermodynamic integration and multiple step thermodynamic perturbation free energy molecular dynamics simulations. \end{itemize} + \section{System specification} The chemical system for a calculation is specified in the topology and restart files. These files should be created using the utilities \nwtop\ and \nwrst\ before a simulation can be performed. The names of these files are determined from the NWChem START directive. -There is no default. If the project name is given as {\bf pr\_id}, -the topology file used is {\bf pr.top}, while all other files -are named {\bf pr\_id.ext}. +There is no default. If the project name is given as {\tt pr\_id}, +the topology file used is {\tt pr.top}, while all other files +are named {\tt pr\_id.ext}. + \section{Parameter set} \begin{itemize} \item The parameter set used for the simulation is specified by \begin{verbatim} -set + set \end{verbatim} -where {\bf iset} is the parameter set found on the -topology file. The default for {\bf iset} is 1. +where \verb++ is the parameter set found on the +topology file. The default for \verb++ is 1. \item The perturbation parameter set used in molecular dynamics simulations to evaluate single step thermodynamic perturbation free energies is specified by \begin{verbatim} -pset [] + pset [] \end{verbatim} -where {\bf isetp1} specifies the first perturbation parameter set and -{\bf isetp2} specifies the second perturbation parameter set. Legal -values for {\bf isetp1} are 2 and 3. Legal value for {\bf isetp2} is -3, in which case {\bf isetp1} can only be 2. If specified, {\bf iset} +where \verb++ specifies the first perturbation parameter set and +\verb++ specifies the second perturbation parameter set. Legal +values for \verb++ are 2 and 3. Legal value for \verb++ is +3, in which case \verb++ can only be 2. If specified, \verb++ is automatically set to 1. \end{itemize} + \section{Energy minimization algorithms} The energy minimization of the system as found in the restart file is performed with the following directives. @@ -741,28 +756,31 @@ is performed with the following directives. \item To specify steepest descent steps \begin{verbatim} -sd [init ] [min ] [max ] + sd [init ] [min ] \ + [max ] \end{verbatim} -where {\bf msdit} is the maximum number of steepest descent steps taken, -for which the default is 100, {\bf dx0sd} is the initial step size in nm -for which the default is 0.001, {\bf dxsdmx} is the threshold for the -step size in nm for which the default is 0.0001, and {\bf dxmsd} is the +where \verb++ is the maximum number of steepest descent steps taken, +for which the default is 100, \verb++ is the initial step size in nm +for which the default is 0.001, \verb++ is the threshold for the +step size in nm for which the default is 0.0001, and \verb++ is the maximum allowed step size in nm for which the default is 0.05. \item To specify conjugate gradient steps \begin{verbatim} -cg [init ] [min ] [cy ] + cg [init ] [min ] \ + [cy ] \end{verbatim} -where {\bf mcgit} is the maximum number of conjugate gradient steps taken, -for which the default is 100, {\bf dx0cg} is the initial search +where \verb++ is the maximum number of conjugate gradient steps taken, +for which the default is 100, \verb++ is the initial search interval size size in nm -for which the default is 0.001, {\bf dxcgmx} is the threshold for the -step size in nm for which the default is 0.0001, and {\bf ncgcy} +for which the default is 0.001, \verb++ is the threshold for the +step size in nm for which the default is 0.0001, and \verb++ is the number of conjugate gradient steps after which the gradient history is discarded for which the default is 10. \end{itemize} Steepest descent energy minimization preceeds conjugate gradient minimization if both are specified. + \section{Multiconfiguration thermodynamic integration} The following keywords control free energy difference simulations. Multiconfiguration thermodynamic integrations are always combined @@ -771,40 +789,40 @@ with multiple step thermodynamic perturbations. \item To specify the direction and number of ensembles \begin{verbatim} -{forward | reverse} [[ of] ] + (forward || reverse) [[ of] ] \end{verbatim} -with {\bf forward} being the default direction, and -where {\bf mrun} is the number of ensembles that will be generated in -this calculation, and {\bf maxlam} is the total number of ensembles -for the thermodynamic integration. The default value for {\bf maxlam} -is 21. The default value of {\bf mrun} is the value of {\bf maxlam}. +with {\tt forward} being the default direction, and +where \verb++ is the number of ensembles that will be generated in +this calculation, and \verb++ is the total number of ensembles +for the thermodynamic integration. The default value for \verb++ +is 21. The default value of \verb++ is the value of \verb++. \item To specify the maximum statistical error per ensemble \begin{verbatim} -error + error \end{verbatim} -where {\bf edacq} is the maximum error allowed in the ensemble average +where \verb++ is the maximum error allowed in the ensemble average derivative of the Hamiltonian with respect to lambda with a default of 5.0 kJ~mol$^{-1}$. \item To specify the maximum drift in the derivative per ensemble \begin{verbatim} -drift + drift \end{verbatim} -where {\bf ddacq} is the maximum drift allowed in this +where \verb++ is the maximum drift allowed in this ensemble average with a default of 5.0 kJ~mol$^{-1}$ps$^{-1}$. \item To specify the size factor of an ensemble comapred to the previous ensemble \begin{verbatim} -factor + factor \end{verbatim} -where {\bf fdacq} is the minimum size of an ensemble relative to the +where \verb++ is the minimum size of an ensemble relative to the previous ensemble in the calculation with a default value of 0.75. \item To specify that a free energy decomposition has to be carried out \begin{verbatim} -decomp + decomp \end{verbatim} Since free energy contributions are path dependent, results from a decomposition analysis can not be unambiguously interpreted, and @@ -812,117 +830,124 @@ the default is not to perform this decomposition. \item To specify separation-shifted scaling \begin{verbatim} -sss [delta ] + sss [delta ] \end{verbatim} -where {\bf delta} is the separation-shifted scaling factor with a default +where \verb++ is the separation-shifted scaling factor with a default of 0.075 nm$^2$. \item To specify the starting point \begin{verbatim} -new | renew | extend + new || renew || extend \end{verbatim} -where {\bf new} indicates that this is an initial mcti calculation, which -is also the default. {\bf renew} instructs to obtain the initial +where {\tt new} indicates that this is an initial mcti calculation, which +is also the default. {\tt renew} instructs to obtain the initial conditions for each $\lambda$ from the {\bf mro}-file from a previous mcti calculation, which has to be renamed to an {\bf mri}-file. The -keyword {\bf extend} will extend a previous mcti calculation from the +keyword {\tt extend} will extend a previous mcti calculation from the data read from an {\bf mri}-file. \end{itemize} + \section{Time and integration algorithm directives} Following directives control the integration of the equations of motion. \begin{itemize} \item To specify the integration algorithm \begin{verbatim} -leapfrog | vverlet + leapfrog || vverlet \end{verbatim} -where {\bf leapfrog} specifies the default leap frog integration, and -{\bf vverlet} specifies the velocity Verlet integrator. +where {\tt leapfrog} specifies the default leap frog integration, and +{\tt vverlet} specifies the velocity Verlet integrator. \item To specify the number of equilibration steps \begin{verbatim} -equil + equil \end{verbatim} -where {\bf mequi} is the number of equilibration steps, with a default +where \verb++ is the number of equilibration steps, with a default of 100. \item To specify the number of data gathering steps \begin{verbatim} -data [over ]] + data [over ]] \end{verbatim} -where {\bf mdacq} is the number of data gathering steps with a +where \verb++ is the number of data gathering steps with a default of 500. In multiconfiguration thermodynamic integrations -{\bf mequi} and {\bf mdacq} are for each of the ensembles, and -variable {\bf ldacq} specifies the minimum number of datagathering steps -in each ensemble. In regular molecular dynamics simulations {\bf ldacq} -is not used. The default value for {\bf ldacq} is the value of {\bf mdacq}. +\verb++ and \verb++ are for each of the ensembles, and +variable \verb++ specifies the minimum number of datagathering steps +in each ensemble. In regular molecular dynamics simulations \verb++ +is not used. The default value for \verb++ is the value of \verb++. \item To specify start time \begin{verbatim} -time + time \end{verbatim} -where {\bf stime} is the start time of a molecular simulation in ps, +where \verb++ is the start time of a molecular simulation in ps, with a default of 0.0. \item To specify the time step \begin{verbatim} -step + step \end{verbatim} -where {\bf tstep} is the time step in ps, with 0.001 as the default value. +where \verb++ is the time step in ps, with 0.001 as the default value. \end{itemize} + \section{Ensemble selection} Following directives control the ensemble type. \begin{itemize} \item To specify a constant temperature ensemble using Berendsen's thermostat \begin{verbatim} -isotherm [] [trelax []] + isotherm [] [trelax []] \end{verbatim} -where {\bf tmpext} is the external temperature with a default of 298.15~K, -and {\bf tmprlx} and {\bf tmsrlx} are temperature relaxation times in ps -with a default of 0.1. If only {\bf tmprlx} is given the complete system -is coupled to the heat bath with relaxation time {\bf tmprlx}. If both +where \verb++ is the external temperature with a default of 298.15~K, +and \verb++ and \verb++ are temperature relaxation times in ps +with a default of 0.1. If only \verb++ is given the complete system +is coupled to the heat bath with relaxation time \verb++. If both relaxation times are supplied, solvent and solute are independently coupled -to the heat bath with relaxation times {\bf tmprlx} and {\bf tmsrlx} +to the heat bath with relaxation times \verb++ and \verb++ respectively. \item To specify a constant pressure ensemble using Berendsen's piston \begin{verbatim} -isobar [] [trelax ] [compress ] + isobar [] [trelax ] \ + [compress ] \end{verbatim} -where {\bf prsext} is the external temperature with a default of 1.025~10$^5$ Pa, -{\bf prsrlx} is the pressure relaxation time in ps with a default of 0.5, and -{\bf compr} is the system compressibility in m$^2$N$^{-1}$ with a +where \verb++ is the external temperature with a default of 1.025~10$^5$ Pa, +\verb++ is the pressure relaxation time in ps with a default of 0.5, and +\verb++ is the system compressibility in m$^2$N$^{-1}$ with a default of 4.53E-10. \end{itemize} + \section{Velocity reassignments} Velocities can be periodically reassigned to reflect a certain temperature. \begin{itemize} \item \begin{verbatim} -vreass + vreass \end{verbatim} -specifies that velocities will be reassigned every {\bf nfgaus} molecular -dynamics steps, reflecting a temperature of {\bf tgauss}~K. The default -is not to reassign velocities, i.e.\ {\bf nfgaus} is 0. +specifies that velocities will be reassigned every \verb++ molecular +dynamics steps, reflecting a temperature of \verb++~K. The default +is not to reassign velocities, i.e.\ \verb++ is 0. \end{itemize} + \section{Cutoff radii} Cutoff radii can be specified for short range and long range interactions. \begin{itemize} \item \begin{verbatim} -cutoff [short] [long ] [qmmm ] + cutoff [short] [long ] \ + [qmmm ] \end{verbatim} -where {\bf rshort} is the short range cutoff radius in nm, and {\bf rlong} +where \verb++ is the short range cutoff radius in nm, and \verb++ is the long range cutoff radius in nm. If the long range cutoff radius is larger than the short range cutoff radius the twin range method will be used, in which short range forces and energies are evaluated every molecular dynamics step, and long range forces and energies with a -frequency of {\bf nflong} molecular dynamics steps. Keyword +frequency of \verb++ molecular dynamics steps. Keyword \verb+qmmm+ specifies the radius of the zone around quantum atoms defining the qmmm bare charges. -The default value for {\bf rshort}, {\bf rlong} and {\bf rqmmm} is 0.9~nm. +The default value for \verb++, \verb++ and \verb++ is 0.9~nm. \end{itemize} + \section{Polarization} First order and self consistent electronic polarization models have been implemented. @@ -930,59 +955,65 @@ been implemented. \item The use of polarizable potentials is specified by \begin{verbatim} -polar {first | scf [[] ]} + polar (first || scf [[] ]) \end{verbatim} -where the keyword {\bf first} specifies the first order polarization -model, and {\bf scf} specifies the self consistent polarization field -model, iteratively determined with a maximum of {\bf mpolit} -iterations to within a tolerance of {\bf ptol} D in the generated +where the keyword {\tt first} specifies the first order polarization +model, and {\tt scf} specifies the self consistent polarization field +model, iteratively determined with a maximum of \verb++ +iterations to within a tolerance of \verb++ D in the generated induced dipoles. The default is not to use polarization models. \end{itemize} + \section{External electrostatic field} \begin{itemize} \item An external electrostatic field can be specified by \begin{verbatim} -field [freq ] [vector ] + field [freq ] [vector ] \end{verbatim} -where {\bf xfield} is the field strength, {\bf xffreq} is the -frequency in MHz and {\bf xfvect} is the external field vector. +where \verb++ is the field strength, \verb++ is the +frequency in MHz and \verb++ is the external field vector. \end{itemize} + \section{Constraints} Constraints involving hydrogens are satisfied using the SHAKE coordinate resetting preocedure. \begin{itemize} \item \begin{verbatim} -shake [ []] [ []] + shake [ []] \ + [ []] \end{verbatim} -where {\bf mshitw} is the maximum number of solvent SHAKE iterations, -and {\bf mshits} is the maximum number of solute SHAKE iterations. If -only {\bf mshitw} is specified, the value will also be used for {\bf mshits}. +where \verb++ is the maximum number of solvent SHAKE iterations, +and \verb++ is the maximum number of solute SHAKE iterations. If +only \verb++ is specified, the value will also be used for \verb++. The default maximum number of iterations is 100 for both. -{\bf tlwsha} is the solvent SHAKE tolerance in nm, and {\bf tlssha} is -the solute SHAKE tolerance in nm. If only {\bf tlwsha} is specified, the -value given will also be used for {\bf tlwsha}. The default tolerance +\verb++ is the solvent SHAKE tolerance in nm, and \verb++ is +the solute SHAKE tolerance in nm. If only \verb++ is specified, the +value given will also be used for \verb++. The default tolerance is 0.001 for both. \item \begin{verbatim} -noshake {solvent | solute} + noshake {solvent || solute} \end{verbatim} disables SHAKE and treats the bonded interaction according to the force field. \end{itemize} + \section{Long range interaction corrections} Long range electrostatic interactions are implemented using the particle mesh Ewald technique. \begin{itemize} \item \begin{verbatim} -ewald [grid [ []]] [alpha ] + ewald [grid [ []]] \ + [alpha ] \end{verbatim} where $ngx$, $ngy$ and $ngz$ are the number of grid points per dimension, and $ealpha$ is the argument of the error function in nm$^{-1}$, with a default of 4.0. \end{itemize} + \section{Fixing coordinates} The solvent or solute part of a system may be fixed or unfixed using the following keywords. Fixing part of the system will not propagate to @@ -990,13 +1021,14 @@ simulations using restart files written. \begin{itemize} \item \begin{verbatim} -fix {all | solvent | solute | non-H} + fix (all || solvent || solute || non-H) \end{verbatim} \item \begin{verbatim} -unfix {all | solvent | solute | non-H} + unfix (all || solvent || solute || non-H) \end{verbatim} \end{itemize} + \section{Autocorrelation function} For the evaluation of the statistical error of multiconfiguration thermodynamic integration free energy results a correlated data @@ -1007,51 +1039,53 @@ respect to the control variable $\lambda$. \item The calculation of the autocorrelation is controlled with the keywords \begin{verbatim} -auto [fit ] [weight ] + auto [fit ] [weight ] \end{verbatim} -where {\bf lacf} is the length of the autocorrelation function, with -a default of 1000, {\bf nfit} is the number of functions used in the +where \verb++ is the length of the autocorrelation function, with +a default of 1000, \verb++ is the number of functions used in the fit of the autocorrelation function, with a default of 15, and -{\bf weight} is the weight factor for the autocorrelation function, +\verb++ is the weight factor for the autocorrelation function, with a default value of 0.0. \end{itemize} + \section{Print options} Keywords that control print to the output file, with extension {\bf out}. \begin{itemize} \item Printing topology information \begin{verbatim} -print topol [nonbond] [solvent] [solute] + print topol [nonbond] [solvent] [solute] \end{verbatim} -where {\bf nonbond} refers to the non-bonded interaction parameters, -{\bf solvent} to the solvent bonded parameters and {\bf solute} to the -solute bonded parameters. If only {\bf topol} is specified, all +where {\tt nonbond} refers to the non-bonded interaction parameters, +{\tt solvent} to the solvent bonded parameters and {\tt solute} to the +solute bonded parameters. If only {\tt topol} is specified, all topology information will be printed to the output file. \item Printing time step information \begin{verbatim} -print step [extra] [energy] + print step [extra] [energy] \end{verbatim} -where {\bf nfoutp} is the frequency of printing molecular dynamics step -information to the output file. If the keyword {\bf extra} is specified +where \verb+nfoutp+ is the frequency of printing molecular dynamics step +information to the output file. If the keyword {\tt extra} is specified additional energetic data are printed for solvent and solute separately. -If the keyword {\bf energy} is specified, information is printed for +If the keyword {\tt energy} is specified, information is printed for all bonded solute interactions. -The default for {\bf nfoutp} is 0. For molecular dynamics simulations +The default for \verb+nfoutp+ is 0. For molecular dynamics simulations this frequency is in time steps, and for multiconfiguration thermodynamic integration in $\lambda$ steps. \item Printing statistical information \begin{verbatim} -print stat + print stat \end{verbatim} -where {\bf nfstat} is the frequency of printing statistical information +where \verb++ is the frequency of printing statistical information of properties that are calculated during the simulation. For molecular dynamics simulation this frequency is in time steps, for multiconfiguration thermodynamic integration in $\lambda$ steps. \end{itemize} Print directives may be combined to a single directive. + \section{Periodic updates} Following keywords control periodic events during a molecular dynamics or thermodynamic integration simulation. @@ -1059,9 +1093,9 @@ dynamics or thermodynamic integration simulation. \item Updating pair lists \begin{verbatim} -update pairs + update pairs \end{verbatim} -where {\bf nfpair} is the frequency in molecular dynamics steps of +where \verb++ is the frequency in molecular dynamics steps of updating the pair lists. The default for the frequency is 1. In addition, pair lists are also updated after each step in which recording of the restart or trajectory files is performed. Updating @@ -1070,9 +1104,9 @@ domain and load balancing, if specified. \item Updating long range forces \begin{verbatim} -update long + update long \end{verbatim} -where {\bf nflong} is the frequency in molecular dynamics steps +where \verb++ is the frequency in molecular dynamics steps of updating the long range forces. The default frequency is 1. The distinction of short range and long range forces is only made if the long range cutoff radius was specified to be larger @@ -1082,13 +1116,13 @@ pair lists are regenerated. \item Updating the simulation volume center \begin{verbatim} -update center [fraction ] + update center [fraction ] \end{verbatim} -where {\bf nfcntr} is the frequency in molecular dynamics steps in +where \verb++ is the frequency in molecular dynamics steps in which the center of geometry of the solute(s) is translated to the center of the simulation volume. The solute fractions determining the solutes that will be centered are specified by the keyword -{\bf fraction} and the vector {\bf idscb}, with a maximum of 5 entries. +{\tt fraction} and the vector \verb++, with a maximum of 5 entries. This translation is implemented such that it has no effect on any aspect of the simulation. The default is not to center, i.e. nfcntr is 0. The default fraction used to center solute is 1. @@ -1096,22 +1130,22 @@ aspect of the simulation. The default is not to center, i.e. nfcntr is Periodic removal of center of mass motion is specified by the following keyword. \begin{verbatim} -update motion + update motion \end{verbatim} -where {\bf nfslow} is the frequency in molecular dynamics steps in +where \verb++ is the frequency in molecular dynamics steps in which the center of mass motion is removed. \item Updating the radial distribution functions \begin{verbatim} -update rdf [range ] [bins ] + update rdf [range ] [bins ] \end{verbatim} -where {\bf nfrdf} is the frequency in molecular dynamics steps in +where \verb++ is the frequency in molecular dynamics steps in which contributions to the radial distribution functions are evaluated. The default is 0. The range of the radial distribution -functions is given by {\bf rrdf} in nm, with a default of the short +functions is given by \verb++ in nm, with a default of the short range cutoff radius. Note that radial distribution functions is not be evaluated beyond the short range cutoff radius. The number of -bins in each radial distribution function is given by {\bf ngl}, with +bins in each radial distribution function is given by \verb++, with a default of 1000. If radial distribution function are to be calculated, a {\bf rdi} files needs to be available in which the @@ -1130,108 +1164,109 @@ I-4 & i & Second atom number \\ \end{center} \end{itemize} Update directives may be combined to a single directive. + \section{Recording} The following keywords control recording data to file. \begin{itemize} \item The file format of selected recording files is specified with \begin{verbatim} -record {binary | ascii [ecce | argos]} + record (binary || ascii [ecce || argos]) \end{verbatim} with the default of ascii in ecce readable format. \item The restart file, file extension {\bf rst} \begin{verbatim} -record rest [keep] + record rest [keep] \end{verbatim} -where {\bf nfrest} is the frequency in molecular dynamics steps +where \verb++ is the frequency in molecular dynamics steps of writing information to this file. For multiconfiguration thermodynamic integration simulations the frequency is in steps in $\lambda$. The default is not to record. The restart -file is used to start or restart simulations. The keyword {\bf keep} +file is used to start or restart simulations. The keyword {\tt keep} causes all restart files written to be kept on disk, rather than be overwritten, \item The coordinate trajectory file, file extension {\bf coo} \begin{verbatim} -record coord + record coord \end{verbatim} -where {\bf nfcoor} is the frequency in molecular dynamics steps +where \verb++ is the frequency in molecular dynamics steps of writing information to this file. For multiconfiguration thermodynamic integration simulations the frequency is in steps in $\lambda$. The default is not to record. \item The solute coordinate trajectory file, file extension {\bf sco} \begin{verbatim} -record scoor + record scoor \end{verbatim} -where {\bf nfscoo} is the frequency in molecular dynamics steps +where \verb++ is the frequency in molecular dynamics steps of writing information to this file. For multiconfiguration thermodynamic integration simulations the frequency is in steps in $\lambda$. The default is not to record. \item The velocity trajectory file, file extension {\bf vel} \begin{verbatim} -record veloc + record veloc \end{verbatim} -where {\bf nfvelo} is the frequency in molecular dynamics steps +where \verb++ is the frequency in molecular dynamics steps of writing information to this file. For multiconfiguration thermodynamic integration simulations the frequency is in steps in $\lambda$. The default is not to record. \item The solute velocity trajectory file, file extension {\bf svl} \begin{verbatim} -record svelo + record svelo \end{verbatim} -where {\bf nfsvel} is the frequency in molecular dynamics steps +where \verb++ is the frequency in molecular dynamics steps of writing information to this file. For multiconfiguration thermodynamic integration simulations the frequency is in steps in $\lambda$. The default is not to record. \item The property file, file extension {\bf prp} \begin{verbatim} -record prop + record prop \end{verbatim} -where {\bf nfprop} is the frequency in molecular dynamics steps +where \verb++ is the frequency in molecular dynamics steps of writing information to this file. For multiconfiguration thermodynamic integration simulations the frequency is in steps in $\lambda$. The default is not to record. \item The energy minimization trajectory, file extension {\bf emt} \begin{verbatim} -record mind + record mind \end{verbatim} -where {\bf nfem} is the frequency in nenergy minimization steps of +where \verb++ is the frequency in nenergy minimization steps of writing the minimization trajectory to file. \item The free energy file, file extension {\bf gib} \begin{verbatim} -record free + record free \end{verbatim} -where {\bf nffree} is the frequency in multiconfiguration +where \verb++ is the frequency in multiconfiguration thermodynamic integration simulations to record data to this file. The default is 1, i.e.\ to record at every $\lambda$. \item The free energy convergence file, file extension {\bf cnv} \begin{verbatim} -record cnv + record cnv \end{verbatim} \item The free energy derivative autocorrelation file, file extension {\bf acf} \begin{verbatim} -record acf + record acf \end{verbatim} \item The free energy vs. time file, file extension {\bf fet} \begin{verbatim} -record fet + record fet \end{verbatim} \item The synchronization time file, file extension {\bf syn} \begin{verbatim} -record sync + record sync \end{verbatim} -where {\bf nfsync} is the frequency in molecular dynamics steps +where \verb++ is the frequency in molecular dynamics steps of writing information to this file. The default is not to record. The information written is the simulation time, the wall clock time of the previous MD step, the wall clock time of the previous force @@ -1240,15 +1275,16 @@ synchronization time and the node on which the largest synchronization time was found. \end{itemize} Record directive may be combined to a single directive. + \section{Program control options} \begin{itemize} \item Load balancing is determined by \begin{verbatim} -load {none | size | pairs} + load (none || size || pairs) \end{verbatim} -where the default is {\bf none}. Load balancing option {\bf size} -is resizing boxes on a node, and {\bf pairs} redistributes the +where the default is {\tt none}. Load balancing option {\tt size} +is resizing boxes on a node, and {\tt pairs} redistributes the box-box interactions over nodes. \item The distribution of the available nodes over the three Cartesian @@ -1260,7 +1296,7 @@ of $npx$, $npy$ and $npz$ are possible, the combination is chosen with the minimum value of $npx+npy+npz$. To change the default setting the following optional input option is provided. \begin{verbatim} -nodes + nodes \end{verbatim} \item The molecular system is decomposed into boxes, that form the smallest @@ -1271,27 +1307,27 @@ long-range cutoff radius is it is larger than the short-range cutoff. The number of boxes per dimension can also be set explicitly, using the following keyword. \begin{verbatim} -boxes + boxes \end{verbatim} If the number of boxes in a dimension is less than the number of processors in that dimension, the number of boxes is set to the number of processors. \item In rare events the amount of memory set aside per node is insufficient -leading to aborts because {\bf mwm} or {\bf msa} is too small. Jobs +leading to aborts because {\tt mwm} or {\tt msa} is too small. Jobs may be restarted with additional space allocated by \begin{verbatim} -extra + extra \end{verbatim} -where {\bf madbox} is the number of additional boxes that are allocated -on each node. The default for {\bf madbox} is 6. In some case {\bf madbox} +where \verb++ is the number of additional boxes that are allocated +on each node. The default for \verb++ is 6. In some case \verb++ can be reduced to 4 is memory usage is a concern. Values of 2 or less will almost certainly result in memory shortage. \item To limit the allocated amount of memory used by the molecular dynamics module, \begin{verbatim} -memory + memory \end{verbatim} where $memlim$ is the amount of memory allocated by the module in kB. Per default all available memory is allocated. diff --git a/doc/user/property.tex b/doc/user/property.tex index 9d0585114c..f37c9069b3 100644 --- a/doc/user/property.tex +++ b/doc/user/property.tex @@ -7,26 +7,24 @@ The following properties can be extracted from the wavefunction. -dipole moment -quadrupole moment -octupole moment -Mulliken population analysis and bond order analysis -electrostatic potential ( diamagnetic shielding ) at nuclei + grid -electric field at nuclei + grid -electric field gradient at nuclei + grid -electron density and electron wavefunction at nuclei + grid - -Boy's localized orbitals -spin density -Stone's distributed multipole analysis -static dipole polarizabilities and hyperpolarizabilities -dynamic dipole polarizabilitites and hyperpolarizabilities - -natural bond analysis +\begin{itemize} +\item dipole moment +\item quadrupole moment +\item octupole moment +\item Mulliken population analysis and bond order analysis +\item electrostatic potential (diamagnetic shielding) at nuclei and grid +\item electric field at nuclei and grid +\item electric field gradient at nuclei and grid +\item electron density and electron wavefunction at nuclei and grid +\item Boy's localized orbitals +\item spin density +\item Stone's distributed multipole analysis +\item static dipole polarizabilities +\item natural bond analysis +\end{itemize} \subsection{nbofile} -======= -\section{nbofile} + Following the successful completion of an electronic structure calculation, a Natural Bond Orbital (NBO) analysis may be carried out in the following way. On restart specify the TASK as PROPERTY and @@ -37,3 +35,4 @@ version of the NBO program, gennbo. \verb++ is equal to string following the RESTART directive. The input deck may be edited to provide additional options to the NBO calculation, (see the NBO user's manual for details.) + diff --git a/doc/user/scf.tex b/doc/user/scf.tex index cdf1ad3bef..839963e6bc 100644 --- a/doc/user/scf.tex +++ b/doc/user/scf.tex @@ -318,10 +318,14 @@ those centers. Two parameters must be set as follows: set atomscf:z \end{verbatim} -The arrary of strings \verb+atomscf:tags_z+ should be set to the list -of tags and array \verb+atomscf:z+ should be set to the list of tags. -All atoms that have the same tag as one specified in this list will be -assigned the corresponding charge. +\sloppy + +The array of strings \verb+atomscf:tags_z+ should be set to the list +of tags, and the array \verb+atomscf:z+ should be set to the list of +charges. All atoms that have the same tag as one specified in this +list will be assigned the corresponding charge. + +\fussy For example, the following specifies that all oxygen atoms with tag \verb+O+ be assigned a charge of \verb+-1+ and all iron atoms with tag @@ -412,7 +416,7 @@ V-approximation of Alml\"{o}f and Vahtras) is automatically invoked if a basis set named \verb+"riscf basis"+ is present in the database. This basis will be used as the fitting basis. The RI-SCF method provides most computational speedup with least loss of accuracy when -applied to relatively small molecules in larage basis sets. +applied to relatively small molecules in large basis sets. Calculations on large molecules in modest basis sets will not realize a significant performance gain from RISCF. @@ -610,12 +614,13 @@ If integrals are stored with a threshold of greater than $10^{-10}$, then the integrals themselves are stored in a 32-bit fixed-point format (with special treatment for large values to retain precision). If integrals are stored with a threshold that is less than $10^{-10}$, -howwever, the values are stored in 64-bit floating-point format. If a +however, the values are stored in 64-bit floating-point format. If a replicated-data calculation is being run, then 8 bits are used for each basis function label, unless there are more than 256 functions, in which case 16 bits are used. If distributed-data is being used, then the labels are always packed to 8-bits (the distributed blocks -always being less than 256). +always being less than 256 and labels are relative to the start of the +block). Thus, the number ($W$) of 64-bit words required to store $N$ integrals, may be computed as @@ -681,10 +686,10 @@ This information may be used to optimize subsequent calculations. {\em Note to users:} It is desired that the SCF program converge reliably with the default options for a wide variety of molecules. In -addition it should be guaranteed to converge sufficient iterations for -any system. Please report significant convergence problems to -\verb+nwchem+-\verb+support@+\-\verb+emsl.pnl.gov+, including the -input file. +addition, it should be guaranteed to converge sufficient with +iterations for any system. Please report significant convergence +problems to \verb+nwchem+-\verb+support@+\-\verb+emsl.pnl.gov+, +including the input file. % An understanding of the output of the SCF program and the options % controlling convergence requires some knowledge of the convergence diff --git a/doc/user/top-level.tex b/doc/user/top-level.tex index e4af8406a4..fd81282fc6 100644 --- a/doc/user/top-level.tex +++ b/doc/user/top-level.tex @@ -46,7 +46,7 @@ prefix. That is, the variable {\tt } is assigned the name of the input file, with any directory information and the last "dot-prefix" removed. For example, the input file -name \verb+/home/dave/job.2.in+ yields \verb+job.2+ as the file +name \verb+/home/dave/job.2.nw+ yields \verb+job.2+ as the file prefix, if a name is not assigned explicitly using the \verb+START+ directive. @@ -174,9 +174,10 @@ following steps in order; \item Look for a directory qualified by the process number of the invoking process. \item If there is a list of directories qualified by the name of the - host machine (as returned by \verb+util_hostname()+), then use - round-robin allocation from the list for processes executing on the - given host. + host machine\footnote{As returned by {\tt util\_hostname()} which + maps to the output of the command {\tt hostname} on Unix + workstations.}, then use round-robin allocation from the list for + processes executing on the given host. \item If there is a list of directories unqualified by any hostname or process ID, then use round-robin allocation from this list. \end{enumerate} @@ -631,15 +632,14 @@ database is persistent, multiple tasks within one job behave {\em exactly} the same as multiple restart jobs with the same sequence of input. -There are three main forms of the the \verb+TASK+ directive. One form is -used to tell the code when to execute most of the electronic structure -and molecular dynamics -calculations. The second form is used to specify tasks such as -printing the contents of the database, or simple property -evaluations. The third form is used to execute UNIX commands on machines -having a Bourne shell. Additional forms will be added in the near -future to accomodate mixed molecular-mechanics and quantum-mechanics -(MM/QM) calculations. +There are three main forms of the the \verb+TASK+ directive. One form +is used to tell the code when to execute most of the electronic +structure and molecular dynamics calculations. The second form is +used to specify tasks such as printing the contents of the database, +or simple property evaluations. The third form is used to execute +UNIX commands on machines having a Bourne shell. Additional forms +will be added in the near future to accomodate mixed quantum-mechanics +and molecular-mechanics (QM/MM) calculations. By default, the program terminates when a task does not complete successfully. The keyword \verb+ignore+ can be used to prevent this, @@ -732,8 +732,8 @@ theory, the \verb+TASK+ directive is task dft optimize \end{verbatim} -The keyword \verb+ignore+ allows execution to continue even if the -task fails, as discussed above. +The optional keyword \verb+ignore+ can be used to allow execution to +continue even if the task fails, as discussed above. \subsection{{\tt TASK} Directive for Special Operations} @@ -778,7 +778,9 @@ that the given command will be executed in the Bourne shell. The user can also specify which process(es) will execute this command by entering values for \verb+processor+ on the directive. The default is for only process zero to execute the command. A range of processors -may be specified, using Fortran triplet notation. Alternatively, all +may be specified, using Fortran triplet notation\footnote{The notation + \verb+lo:hi:inc+ denotes the integers \verb+lo+, \verb=lo+inc=, + \verb=lo+2*inc=, \ldots, \verb+hi+}. Alternatively, all processes can be specified simply by entering the keyword \verb+all+. The input entered for \verb+command+ must form a single string, and consist of valid UNIX command(s). If the string includes white space, @@ -837,5 +839,30 @@ If centers with fractional charge have been specified (Section \ref{sec:geom}) the net charge of the system should be adjusted to ensure that there is an integral number of electrons. +The charge may be changed between tasks and is used by all +wavefunction types. For instance, in order to compute the first two +vertical ionization energies of $LiH$ one might optimize the geometry +of $LiH$ using a UHF SCF wavefunction and then perform energy +calculations at the optimized geometry in turn on $LiH^+$ and +$LiH^{2+}$. This is accomplished with the following input. +\begin{verbatim} + geometry; Li 0 0 0; H 0 0 1.64; end + basis; Li library 3-21g; H library 3-21g; end + + scf; uhf; singlet; end + task scf optimize + + charge 1 + scf; uhf; doublet; end + task scf + + charge 2 + scf; uhf; singlet; end + task scf +\end{verbatim} +The \verb+GEOMETRY+, \verb+BASIS+, and \verb+SCF+ directives are +described below (Sections \ref{sec:geom}, \ref{sec:basis} and +\ref{sec:scf} respectively) but their intent should be clear. The +\verb+TASK+ directive is described above (Section \ref{sec:task}). diff --git a/doc/user/user.tex b/doc/user/user.tex index 3bc484512d..aaf94d48d0 100644 --- a/doc/user/user.tex +++ b/doc/user/user.tex @@ -1,4 +1,4 @@ -% $Id: user.tex,v 1.17 1997-02-25 20:34:49 d3g681 Exp $ +% $Id: user.tex,v 1.18 1997-02-26 03:17:27 d3g681 Exp $ \documentstyle[fullpage,12pt]{book} \setlength{\parskip}{6pt} @@ -60,21 +60,9 @@ \chapter{Gaussian Density Functional Theory (DFT)} \input{dft.tex} -\chapter{Geometry Optimization with STEPPER} -\input{stepper} - -\chapter{Vibrational frequencies} -\input{vib} - \chapter{MP2} \input{mp2} -\chapter{Four-Index Transformation} -\input{fourindex} - -\chapter{Plane-wave periodic DFT} -\input{plnwv.tex} - \chapter{Multiconfiguration SCF} \input{mcscf.tex} @@ -84,6 +72,21 @@ \chapter{Coupled Cluster Calculations} \input{ccsd.tex} +\chapter{Four-Index Transformation} +\input{fourindex} + +\chapter{Plane-wave periodic DFT} +\input{plnwv.tex} + +\chapter{Geometry Optimization with DRIVER} +\input{driver} + +\chapter{Geometry Optimization with STEPPER} +\input{stepper} + +\chapter{Vibrational frequencies} +\input{vib} + \chapter{DPLOT} \input{dplot.tex} @@ -93,7 +96,7 @@ \chapter{Molecular Dynamics} \input{nwargos.tex} -\chapter{Combined Quantum Mechanics and Molecular Mechanics} +\chapter{Combined Quantum and Molecular Mechanics} \input{qmmm} \clearpage