xref: /dports/science/nwchem/nwchem-7b21660b82ebd85ef659f6fba7e1e73433b0bd0a/doc/user/top-level.tex

%
% $Id$
%
\label{sec:toplevel}

Top-level directives are directives that can affect all modules in the
code.  Some specify molecular properties (e.g., total charge) or other
data that should apply to all subsequent calculations with the current
database.  However, most top-level directives provide the user with
the means to manage the resources for a calculation and to start
computations.  As the first step in the execution of a job, NWChem
scans the entire input file looking for start-up directives, which
NWChem must process before all other input.  The input file is then
rewound and processed sequentially, and each directive is processed in
the order in which it is encountered.  In this second pass, start-up
directives are ignored.

The following sections describe each of the top-level directives in
detail, noting all keywords, options, required input, and defaults.

\section{{\tt START} and {\tt RESTART} --- Start-up mode}
\label{sec:start}

A {\tt START} or {\tt RESTART} directive is
optional.  If one of these two directives is not specified
explicitly, the code will infer one, based upon the name of the
input file and the availability of the database.  When allowing NWChem
to infer the start-up directive, the user must be quite certain that
the contents of the database will result in the desired action.  It
is usually more prudent to specify the directive explicitly, using the
following format:

\begin{verbatim}
(RESTART || START)   \
            [<string file_prefix default $input_file_prefix$>] \
            [rtdb <string rtdb_file_name default $file_prefix$.db>]
\end{verbatim}

The \verb+START+ directive indicates that the calculation is one in
which a new database is to be created.  Any relevant information that
already exists in a previous database of the same name is destroyed.
The string variable {\tt <file\_prefix>} will be used as the prefix to
name any files created in the course of the calculation.

E.g., to start a new calculation on water, one might specify
\begin{verbatim}
  start water
\end{verbatim}
which will make all files begin with {\tt "water."}.

If the user does not specify an entry for {\tt <file\_prefix>} on the
\verb+START+ directive (or omits the \verb+START+ directive
altogether), the code uses the base-name of the input file as the file
prefix.  That is, the variable {\tt <file\_prefix>} is assigned the
name of the input file (not its full pathname), but without the last
``dot-suffix''.  For example, the input 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.

The user also has the option of
specifying a unique name for the database, using the keyword {\tt
  rtdb}.  When this keyword is entered, the string entered for {\tt
  rtdb\_file\_name} is used as the database name.  If the keyword {\tt
  rtbd} is omitted, the name of the database defaults to
\verb+$<file_prefix>$.db+ in the directory for permanent files.

If a calculation is to start from a previous calculation and go on
using the existing database, the \verb+RESTART+ directive
must be used.  In such a case, the previous
database must already exist.  The name specified for {\tt <file\_prefix>}
usually should
not be changed when restarting a calculation.  If it is changed, NWChem
will not
be able to find needed files when going on with the
calculation.

In the most common
situation, the previous calculation was completed (with or without an error
condition), and it is desired to perform a new task or restart the
previous one, perhaps with some input changes.  In these instances,
the \verb+RESTART+ directive should be used.  This reuses the previous
database and associated files, and reads the input file for new input
and task information.

The \verb+RESTART+ directive looks immediately for new input and task
information, deleting information about previous incomplete tasks.
For example, when doing a \verb+RESTART+ there is no need
to specify geometry or basis set declaration because the
program will detect this information since it is stored in the
run-time database.

If a calculation runs out of time, for example because it is
on a queuing system, this is another instance where doing a
\verb+RESTART+ is advisable.  Simply include nothing after the
\verb+RESTART+ directive except those tasks that are unfinished.

NOTE: Due to changes in the runtime database structure, \verb+RESTART+
will not work on database files generated by NWChem versions 4.0.1 and
older.

To summarize the default options for this start-up directive, if the
input file does {\em not} contain a \verb+START+ or a
\verb+RESTART+ directive, then
\begin{itemize}
  \item the variable {\tt <file\_prefix>} is assigned the name of the
input file for the job, without the suffix (which is usually \verb+.nw+)
  \item the variable {\tt <rtdb\_file\_name>} is assigned the default name,
\verb+$file_prefix$.db+
\end{itemize}
If the database with name \verb+$file_prefix$.db+ does {\em not}
already exist,
the calculation is carried out as if a \verb+START+ directive had
been encountered.  If the database with name \verb+$file_prefix$.db+
{\em does} exist, then the calculation is performed as if a
\verb+RESTART+ directive had been encountered.

For example, NWChem can be run using an input file with the name
\verb+water.nw+
by typing the UNIX command line,

\begin{verbatim}
   nwchem water.nw
\end{verbatim}

If the NWChem input file \verb+water.nw+ does not contain
a \verb+START+  or \verb+RESTART+ directive, the code
sets the variable {\tt <file\_prefix>} to {\tt water}.  Files created
by the job will have this prefix, and the database will be named
{\tt water.db}.  If the database \verb+water.db+ does {\em not} exist already,
the code behaves as if the input file contains the directive,

\begin{verbatim}
  start water
\end{verbatim}

If the database \verb+water.db+ {\em does} exist,
the code behaves as if the input file contained the directive,

\begin{verbatim}
  restart water
\end{verbatim}


\section{{\tt SCRATCH\_DIR} and {\tt PERMANENT\_DIR} --- File directories}
\label{sec:dirs}

These are start-up directives that allow the user to specify the
directory location of scratch and permanent files created by NWChem.
NWChem distinguishes between permanent (or persistent) files and
scratch (or temporary) files, and allows the user the option of
putting them in different locations.  In most installations, however,
permanent and scratch files are all written to the current directory
by default.  What constitutes ``local'' disk space may also differ from
machine to machine.

The conventions for file storage are at the discretion of the specific
installation, and are quite likely to be different on different machines.
When assigning locations for permanent and
scratch files,
the user must be cognizant of the characteristics of the installation
on a particular platform.
To consider just a few examples, on
clusters, machine-specific or process-specific
names must be supplied for both local and shared file
systems, while on SMPs it is useful to specify scratch file directories
with automated striping across processors with round-robin allocation.
On SMP clusters (a.k.a. constellations), both of these specifications
are required.

The \verb+SCRATCH_DIR+ and \verb+PERMANENT_DIR+ directives are
identical in format and capability, and enable the user to specify a
single directory for all processes, or different directories for
different processes.  The general form of the directive is as follows:

\begin{verbatim}
   (PERMANENT_DIR || SCRATCH_DIR) [(<string host>||<integer process>):] \
                                       <string directory> \
                                  [...]
\end{verbatim}

Directories are extracted from the user input by executing the
following steps, in sequence:
\begin{enumerate}
\item Look for a directory qualified by the process ID number of the
  invoking process.  Processes are numbered from zero.  Else,
\item If there is a list of directories qualified by the name of the
  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.  Else,
\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}
If directory allocation directive(s) are not specified in the input
file, or if no match is found to the directory names specified by
input using these directives, then the  steps above are executed using
the installation-specific defaults.  If the code cannot find a valid
directory name based on the input specified in either the directive(s)
or the system defaults, files are automatically written to the current
working directory (\verb+"."+).

The following is a list of examples of specific allocations of scratch
directory locations:
\begin{itemize}
\item Put scratch files from all processes in the local scratch directory
(Warning: the definition of ``local scratch directory'' may change from
machine to machine):
\begin{verbatim}
      scratch_dir /localscratch
\end{verbatim}
\item Put scratch files from Process 0 in \verb+/piofs/rjh+, but put all
other scratch files in \verb+/scratch+:
\begin{verbatim}
      scratch_dir /scratch 0:/piofs/rjh
\end{verbatim}
\item Put scratch files from Process 0 in directory \verb+scr1+, those from
Process 1 in \verb+scr2+, and so forth, in a round-robin fashion, using the
given list of directories:
\begin{verbatim}
      scratch_dir /scr1 /scr2 /scr3 /scr4 /scr5
\end{verbatim}
\item Allocate files in a round-robin fashion from
  host-specific lists for processes distributed across two
 SGI multi-processor machines (node names {\em coho} and {\em bohr}):
\begin{verbatim}
      scratch_dir coho:/xfs1/rjh coho:/xfs2/rjh coho:/xfs3/rjh \
          bohr:/disk01/rjh bohr:/disk02/rjh bohr:/disk13/rjh
\end{verbatim}
\end{itemize}

\section{{\tt MEMORY} --- Control of memory limits}

This is a start-up directive that allows the user to specify the
amount of memory that NWChem can use for the job.  If this directive
is not specified, memory is allocated according to
installation-dependent defaults.  {\em The defaults should generally
  suffice for most calculations, since the defaults usually correspond
  to the total amount of memory available on the machine.  It should
usually be unnecessary to provide a memory directive!!!}

The general form of the directive is as follows:

\begin{verbatim}
  MEMORY [[total] <integer total_size>] \
         [stack <integer stack_size>] \
         [heap <integer heap_size>] \
         [global <integer global_size>] \
         [units <string units default real>] \
         [(verify||noverify)] \
         [(nohardfail||hardfail)] \
\end{verbatim}

NWChem recognizes the following memory units:
\begin{itemize}
\item \verb+real+ and \verb+double+ (synonyms)
\item \verb+integer+
\item \verb+byte+
\item \verb+kb+ (kilobytes)
\item \verb+mb+ (megabytes)
\item \verb+mw+ (megawords, 64-bit word)
\end{itemize}

In most cases, the user need specify only the total memory limit to
adjust the amount of memory used by NWChem. The following specifications
all provide for eight megabytes of total
memory (assuming 64-bit floating point numbers), which will be
distributed according to the default partitioning:
\begin{verbatim}
  memory 1048576
  memory 1048576 real
  memory 1 mw
  memory 8 mb
  memory total 8 mb
  memory total 1048576
\end{verbatim}

In NWChem there are three distinct regions of memory: stack, heap,
and global. Stack and heap are node-private, while the union of the
global region on all processors is used to provide globally-shared memory.
The allowed limits on each category are determined from a default
partitioning (currently 25\% heap, 25\% stack, and 50\% global).
Alternatively, the keywords \verb+stack+, \verb+heap+, and
\verb+global+ can be used to define specific allocations for each of
these categories.  If the user sets only one of the stack, heap, or
global limits by input, the limits for the other two categories are
obtained by partitioning the remainder of the total memory available
in proportion to the weight of those two categories in the default
memory partitioning.  If two of the category limits are given, the
third is obtained by subtracting the two given limits from the total
limit (which may have been specified or may be a default value).  If
all three category limits are specified, they determine the total
memory allocated.  However, if the total memory is also specified, it
must be larger than the sum of all three categories.  The code will
abort if it detects an inconsistent memory specification.

The following memory directives also allocate 8 megabytes, but specify
a complete partitioning as well:

\begin{verbatim}
  memory total 8 stack 2 heap 2 global 4 mb
  memory stack 2 heap 2 global 4 mb
\end{verbatim}

The optional keywords \verb+verify+ and \verb+noverify+ in the
directive give the user the option of enabling or disabling automatic
detection of corruption of allocated memory.  The default is
\verb+verify+, which enables the feature. This incurs some
overhead (which can be around 10\% increase in walltime on some platforms),
which can be eliminated by specifying \verb+noverify+.

The keywords \verb+hardfail+ and \verb+nohardfail+ give the user the
option of forcing (or not forcing) the local memory management
routines to generate an internal fatal error if any memory operation
fails.  The default is \verb+nohardfail+, which allows the code to
continue past any memory operation failure, and perhaps generate a
more meaningful error message before terminating the calculation.
Forcing a hard-fail can be useful when poorly coded applications do
not check the return status of memory management routines.

When assigning the specific memory allocations using the keywords
\verb+stack+, \verb+heap+, and \verb+global+ in the \verb+MEMORY+
directive, the user should be aware that some of the distinctions
among these categories of memory have been blurred in their actual
implementation in the code.  The memory allocator (MA) allocates both
the heap and the stack from a single memory region of size {\tt
  heap+stack}, without enforcing the partition.  The heap vs.\ stack
partition is meaningful only to applications developers, and can be
ignored by most users.  Further complicating matters, the global array
(GA) toolkit is allocated from within the MA space on distributed
memory machines, while on shared-memory machines it is
separate\footnote{This is because on true shared-memory machines there
  is no choice but to allocate GAs from within a shared-memory
  segment, which is managed differently by the operating system.}.

On distributed memory platforms, the MA region is actually the total
size of
\begin{verbatim}
   stack+heap+global
\end{verbatim}
All three types of memory allocation
compete for the same pool of memory, with no limits except on the
total available memory.  This relaxation of the memory category
definitions usually benefits the user, since it can allow allocation
requests to succeed where a stricter memory model would cause the
directive to fail.  These implementation characteristics must be kept
in mind when reading program output that relates to memory usage.

Standard default for memory is currently 400 MB.

\section{{\tt ECHO} --- Print input file}
\label{sec:echo}

This start-up directive is provided as a convenient way to include a
listing of the input file in the output of a calculation.  It causes
the entire input file to be printed to Fortran unit six (standard
output).  It has no keywords, arguments, or options, and consists of
the single line:

\begin{verbatim}
  ECHO
\end{verbatim}

The \verb+ECHO+ directive is processed only
once, by Process 0 when the input file is read.

\section{{\tt TITLE} --- Specify job title}

This top-level directive allows the user to identify a job or series
of jobs that use a particular database.  It is an optional directive,
and if omitted, the character string containing the input title will
be empty.  Multiple {\tt TITLE} directives may appear in the input
file (e.g., the example file in Section \ref{sec:realsample}) in which
case a task will use the one most recently specified.  The format for
the directive is as follows:

\begin{verbatim}
  TITLE <string title>
\end{verbatim}

The character string \verb+<title>+ is assigned to the contents of the
string following the \verb+TITLE+ directive.  If the string contains
white space, it must be surrounded by double quotes.  For example,

\begin{verbatim}
  title "This is the title of my NWChem job"
\end{verbatim}

The title is stored in the database and will be used in all subsequent
tasks/jobs until redefined in the input.

\section{{\tt PRINT} and {\tt NOPRINT} --- Print control}
\label{sec:printcontrol}

The \verb+PRINT+ and \verb+NOPRINT+ directives allow the user to
control how much output NWChem generates.  These two directives are
special in that the compound directives for {\em all} modules are
supposed to recognize them. Each module can control both the overall
print level (general verbosity) and the printing of individual items
which are identified by name (see below).  The standard form of the
\verb+PRINT+ directive is as follows:

\begin{verbatim}
  PRINT [(none || low || medium || high || debug) default medium] \
        [<string list_of_names ... >]

  NOPRINT <string list_of_names ... >
\end{verbatim}
The default print level is medium.

Every output that is printed by NWChem has a print threshold
associated with it. If this threshold is equal to or lower than the
print level requested by the user, then the output is generated.  For
example, the threshold for printing the SCF energy at convergence is
\verb+low+ (Section \ref{sec:scfprint}).  This means that if the
user-specified print level on the \verb+PRINT+ directive is
\verb+low+, \verb+medium+, \verb+high+, or \verb+debug+, then the SCF
energy will be printed at convergence.

The overall print level specified
using the \verb+PRINT+ directive is a convenient tool for controlling
the verbosity
of NWChem. Setting the print level to \verb+high+ might be helpful in
diagnosing convergence problems.  The print level of \verb+debug+ might
also be of use in evaluating problem cases, but the user should be aware
that this can generate a huge amount of output.  Setting the print level
to \verb+low+ might be the preferable choice for geometry
optimizations that will perform many steps which are in themselves of
little interest to the user.

In addition, it is possible to enable the printing of specific
items by naming them in the \verb+PRINT+ directive in the
\verb+<list_of_names>+.  Items identified in this way will be printed,
regardless of the overall print level specified.  Similarly, the
\verb+NOPRINT+ directive can be used to suppress the printing of specific
items by naming them in its \verb+<list_of_names>+.  These items will
{\em not} be printed, regardless of the overall print level, or the
specific print level of the individual items.

The list of items that can be printed for each module is documented
as part of the input instructions for that module.
The items recognized by the top level of the code, and their thresholds,
are:
\begin{table}[htbp]
\begin{center}
\begin{tabular}{lcc}
  {\bf Name}          & {\bf Print Level} & {\bf Description} \\
 ``total time''        & medium & Print cpu and wall time at job end\\
 ``task time''         & high   & Print cpu and wall time for each task\\
 ``rtdb''              & high    & Print names of RTDB entries\\
 ``rtdbvalues''        & high    & Print name and values of RTDB entries\\
 ``ga summary''        & medium & Summarize GA allocations at job end \\
 ``ga stats''          & high   & Print GA usage statistics at job end \\
 ``ma summary''        & medium & Summarize MA allocations at job end \\
 ``ma stats''          & high   & Print MA usage statistics at job end \\
 ``version''           & debug  & Print version number of all compiled routines \\
  ``tcgmsg''           & never  & Print TCGMSG debug information \\
\end{tabular}
\end{center}
\caption{Top Level Print Control Specifications}
\end{table}


The following example shows how a \verb+PRINT+ directive for the top level
process can be used to limit printout to only essential information.
The directive is

\begin{verbatim}
  print none "ma stats" rtdb
\end{verbatim}

This directive instructs the NWChem main program to print nothing,
except for the memory usage statistics (\verb+ma stats+) and
the names of all items stored in the database at the end of the job.

The print level within a module is inherited from the
calling layer.  For instance, by specifying the print to be low
within the MP2 module will cause the SCF, CPHF and gradient modules
when invoked from the MP2 to default to low print.  Explicit user
input of print thresholds overrides the inherited value.

\section{{\tt SET} --- Enter data in the RTDB}
\label{sec:set}

This top-level directive allows the user to enter data directly into the
run-time
database (see Section \ref{sec:database} for a description of the database).
The format of the directive is as follows:

\begin{verbatim}
  SET <string name> [<string type default automatic>] <$type$ data>
\end{verbatim}

The entry for variable \verb+<name>+ is the name of
data to be entered into the database.  This must be specified; there is no default.  The variable \verb+<type>+, which is
optional, allows the user to define a string specifying the type of
data in the array \verb+<name>+.  The data type can be explicitly
specified as \verb+integer+, \verb+real+, \verb+double+,
\verb+logical+, or \verb+string+.  If no entry for \verb+<type>+ is
specified on the directive, its value is inferred from the data type
of the {\em first} datum.  In such a case, floating-point data
entered using this directive must include either an exponent or a
decimal point, to ensure that the correct default type will be
inferred.  The correct default type will be inferred for logical
values if logical-true values are specified as \verb+.true.+,
\verb+true+, or \verb+t+, and logical-false values are specified as
\verb+.false.+, \verb+false+, or \verb+f+.  One exception to the
automatic detection of the data type is that the data type {\bf must}
be explicitly stated to input integer ranges, unless the first
element in the list is an integer that is not a range (c.f.,
\ref{sec:syntax}).  For example,
\begin{verbatim}
  set atomid 1 3:7 21
\end{verbatim}
will be interpreted as a list of integers.  However,
\begin{verbatim}
  set atomid 3:7 21
\end{verbatim}
will not work since the first element will be interpreted as a
string and not an integer.  To work around this feature, use instead
\begin{verbatim}
  set atomid integer 3:7 21
\end{verbatim}
which says to write  three through seven, as well as twenty-one.


The \verb+SET+ directive is useful for providing indirection by
associating the name of a basis set or geometry with the standard
object names (such as \verb+"ao basis"+ or \verb+geometry+) used by
NWChem.  The following input file shows an example using the
\verb+SET+ directive to direct different tasks to different
geometries.  The required input lines are as follows:

\begin{verbatim}
  title "Ar dimer BSSE corrected MP2 interaction energy"
  geometry "Ar+Ar"
    Ar1 0 0 0
    Ar2 0 0 2
  end

  geometry "Ar+ghost"
    Ar1 0 0 0
    Bq2 0 0 2
  end

  basis
    Ar1 library aug-cc-pvdz
    Ar2 library aug-cc-pvdz
    Bq2 library Ar aug-cc-pvdz
  end

  set geometry "Ar+Ar"
  task mp2

  scf; vectors atomic; end

  set geometry "Ar+ghost"
  task mp2
\end{verbatim}

This input tells the code to perform MP2 energy calculations
on an argon dimer in the first task, and then
on the argon atom in the presence of the ``ghost'' basis of the other
atom.

The \verb+SET+ directive can also be used as an indirect means of
supplying input to a part of the code that does not have a separate
input module (e.g., the atomic SCF, Section \ref{sec:atomscf}).
Additional examples of applications of this directive can be found in
the sample input files (see Section \ref{sec:realsample}), and
its usage with basis sets (Section \ref{sec:basis}) and geometries
(Section \ref{sec:geom}). Also see Section \ref{sec:database} for
an example of how to store an array in the database.

\section{{\tt UNSET} --- Delete data in the RTDB}
\label{sec:unset}

This directive gives the user a way to delete simple entries from the
database.  The general form of the directive is as follows:

\begin{verbatim}
  UNSET <string name>[*]
\end{verbatim}

This directive cannot be used with complex objects such as geometries
and basis sets\footnote{Complex objects are stored using a structured
  naming convention that is not matched by a simple wild card.}.  A
wild-card (*) specified at the end of the string \verb+<name>+ will
cause {\em all} entries whose name begins with that string to be
deleted.  This is very useful as a way to reset modules to their
default behavior, since modules typically store information in the
database with names that begin with \verb+module:+.  For example, the
SCF program can be restored to its default behavior by deleting all
database entries beginning with \verb+scf:+, using the directive

\begin{verbatim}
  unset scf:*
\end{verbatim}

Section \ref{sec:fragguess} has an example  using
\verb+ unset+ on a water dimer calculation.

The following example makes an entry in the database using the
\verb+SET+ directive, and then immediately deletes it using the
\verb+UNSET+ directive:

\begin{verbatim}
  set mylist 1 2 3 4
  unset mylist
\end{verbatim}


\section{{\tt STOP} --- Terminate processing}

This top-level directive provides a convenient way of verifying
an input file without actually running the calculation.  It consists
of the single line,

\begin{verbatim}
  STOP
\end{verbatim}

As soon as this directive is encountered, all processing ceases and
the calculation terminates with an error condition.

\section{{\tt TASK} --- Perform a task}
\label{sec:task}

The \verb+TASK+ directive is used to tell the code what to do.  The
input directives are parsed sequentially until a \verb+TASK+ directive
is encountered, as described in Section \ref{sec:inputstructure}.  At
that point, the calculation or operation specified in the \verb+TASK+
directive is performed.  When that task is completed, the code looks
for additional input to process until the next \verb+TASK+ directive
is encountered, which is then executed.  This process continues to the
end of the input file.  NWChem expects the last directive before the
end-of-file to be a \verb+TASK+ directive.  If it is not, a warning
message is printed.  Since the 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 four main forms of the the \verb+TASK+ directive.  The most
common form is used to tell the code at what level of theory to
perform an electronic structure calculation, and which specific
calculations to perform.  The second form is used to specify tasks
that do not involve electronic structure calculations or tasks that
have not been fully implemented at all theory levels in NWChem, such
as simple property evaluations.  The third form is used to execute
UNIX commands on machines having a Bourne shell.  The fourth form is
specific to combined 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
termination, and is recognized by all forms of the \verb+TASK+
directive.  When a \verb+TASK+ directive includes the keyword
\verb+ignore+, a warning message is printed if the task fails, and
code execution continues with the next task. An example of this feature
is given in the sample input file
in Section \ref{sec:DFTsample}.

The input options, keywords, and defaults for each of these four forms
for the \verb+TASK+ directive are discussed in the following sections.

\subsection{{\tt TASK} Directive for Electronic Structure Calculations}
\label{sec:first_task}

This is the most commonly used version of the \verb+TASK+ directive, and
it has the following form:

\begin{verbatim}
  TASK <string theory> [<string operation default energy>] [ignore]
\end{verbatim}

The string \verb+<theory>+ specifies the level of theory to be used in the
calculations for this task.  NWChem currently supports ten different
options.  These are listed below, with the corresponding entry for
the variable {\tt <theory>}:
\begin{itemize}
 \item \verb+scf+ --- Hartree-Fock
 \item \verb+dft+ --- Density functional theory for molecules
 \item \verb+sodft+ --- Spin-Orbit Density functional theory
% \item \verb+gapss+ --- Density functional theory for periodic systems
 \item \verb+mp2+ --- MP2 using a semi-direct algorithm
 \item \verb+direct_mp2+ --- MP2 using a full-direct algorithm
 \item \verb+rimp2+ --- MP2 using the RI approximation
 \item \verb+ccsd+ --- Coupled-cluster single and double excitations
 \item \verb+ccsd(t)+ --- Coupled-cluster linearized triples approximation
 \item \verb#ccsd+t(ccsd)# --- Fourth order triples contribution
 \item \verb+mcscf+ --- Multiconfiguration SCF
 \item \verb+selci+ --- Selected configuration interaction with perturbation
   correction
 \item \verb+md+ --- Classical molecular dynamics simulation
 \item \verb+pspw+ --- Pseudopotential plane-wave density functional theory for molecules and insulating solids using NWPW
 \item \verb+band+ --- Pseudopotential plane-wave
density functional theory for solids using NWPW
 \item \verb+tce+ --- Tensor Contraction Engine (please see
Section \ref{sec:inputsyntax} for a complete description of this task directive

\end{itemize}

The string \verb+<operation>+ specifies the calculation that will
be performed in the task.  The default operation is a single point energy
evaluation.  The following list gives the selection of operations currently
available in NWChem:
\begin{itemize}
\item \verb+energy+ --- Evaluate the single point energy.
\item \verb+gradient+ --- Evaluate the derivative of the energy with respect to\
   nuclear coordinates.
\item \verb+optimize+ --- Minimize the energy by varying the molecular
   structure.  By default, this geometry optimization is presently driven by the Driver
   module (see Section \ref{sec:driver}), but the Stepper module
   (see Section \ref{sec:stepper}) may also be used.
\item \verb+saddle+ --- Conduct a search for a transition state (or saddle point)
  using either Driver (Section \ref{sec:driver}, the default) or
  Stepper (Section \ref{sec:stepper}).
\item \verb+hessian+ --- Compute second derivatives.  See Section \ref{sec:hess}
  for analytic hessians.
\item \verb+frequencies+ or \verb+freq+ --- Compute second derivatives
  and print out an analysis of molecular vibrations.  See Section \ref{sec:vib}
  for controls for vibration calculations.
\item \verb+property+ --- Calculate the properties for the wave function.
\item \verb+dynamics+ --- Perform classical molecular dynamics.
\item \verb+thermodynamics+ --- Perform multi-con\-fig\-ura\-tion
  thermo\-dynamic integ\-ration using classical MD
\end{itemize}

NOTE: See Section \ref{sec:pspw_tasks}  for the complete list of operations
that accompany the NWPW module.

The user should be aware that some of these operations (gradient,
optimize, dynamics, thermodynamics) require computation of
derivatives of the energy with respect to the molecular coordinates.
If analytical derivatives are not available (Section
\ref{sec:functionality}), they must be computed numerically, which can
be very computationally intensive.

Here are some examples of the \verb+TASK+ directive, to illustrate the
input needed to specify particular calculations with the code.  To
perform a single point energy evaluation using any level of theory, the
directive is very simple, since the energy evaluation is the default
for the string \verb+operation+.  For an SCF energy calculation, the
input line is simply
\begin{verbatim}
  task scf
\end{verbatim}
Equivalently, the operation can be specified explicitly, using the
directive
\begin{verbatim}
  task scf energy
\end{verbatim}

Similarly, to perform a geometry optimization using density functional
theory, the \verb+TASK+ directive is
\begin{verbatim}
  task dft optimize
\end{verbatim}

The optional keyword \verb+ignore+ can be used to allow execution to
continue even if the task fails, as discussed above.
An example with the keyword \verb+ignore+
can be found in Section \ref{sec:DFTsample}.

\subsection{{\tt TASK} Directive for Special Operations}

This form of the \verb+TASK+ directive is used in instances where the
task to be performed does not fit the model of the previous version
(such as execution of a Python program, Section \ref{sec:python}), or
if the operation has not yet been implemented in a fashion that
applies to a wide range of theories (e.g., property evaluation).
Instead of requiring \verb+theory+ and \verb+operation+ as input, the
directive needs only a string identifying the task.  The form of the
directive in such cases is as follows:

\begin{verbatim}
  TASK <string task> [ignore]
\end{verbatim}

The supported tasks that can be accessed with this form of the \verb+TASK+
directive are listed
below, with the corresponding entries for string variable \verb+<task>+.

\begin{itemize}
  \item \verb+python+ --- Execute a Python program (Section \ref{sec:python}).
  \item \verb+rtdbprint+ --- Print the contents of the database.
  \item \verb+cphf+ --- Invoke the CPHF module.
  \item \verb+property+ --- Perform miscellaneous property calculations.
  \item \verb+dplot+ --- Execute a DPLOT run (Section \ref{sec:dplot})
\end{itemize}

This directive also recognizes the keyword \verb+ignore+, which allows
execution to continue after a task has failed.

\subsection{{\tt TASK} Directive for the Bourne Shell}

This form of the \verb+TASK+ directive is supported only on machines
with a fully UNIX-style operating system.  This directive causes
specified processes to be executed using the Bourne shell.  This form
of the task directive is:

\begin{verbatim}
  TASK shell [(<integer-range process = 0>||all)] \
             <string command>
\end{verbatim}

The keyword \verb+shell+ is required for this directive.  It specifies
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+process+ on the directive.  The default is
for only process zero to execute the command.  A range of processes
may be specified, using Fortran triplet notation\footnote{The notation
{\tt lo:hi:inc} denotes the integers {\tt lo}, {\tt lo+inc},
{\tt lo+2*inc}, \ldots, {\tt 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
must consist of valid UNIX command(s).  If the string includes white space,
it must be enclosed in double quotes.

For example, the \verb+TASK+ directive to tell process zero to copy the
molecular orbitals file to a backup location \verb+/piofs/save+ can be input as follows:

\begin{verbatim}
  task shell "cp *.movecs /piofs/save"
\end{verbatim}

The \verb+TASK+ directive to tell all processes to list the contents of
their \verb+/scratch+ directories is as follows:

\begin{verbatim}
  task shell all "ls -l /scratch"
\end{verbatim}

The \verb+TASK+ directive to tell processes 0 to 10 to remove the
contents of the current directory is as follows:

\begin{verbatim}
  task shell 0:10:1 "/bin/rm -f *"
\end{verbatim}

Note that NWChem's ability to quote special input characters is {\em
  very} limited when compared with that of the Bourne shell.  To
execute all but the simplest UNIX commands, it is usually much easier
to put the shell script in a file and execute the file from within
NWChem.

\subsection{{\tt TASK} Directive for QM/MM simulations}

This is very similar to the most commonly used version of the
\verb+TASK+ directive described in Section \ref{sec:first_task}, and
it has the following form;

\begin{verbatim}
  TASK QMMM <string theory> [<string operation default energy>] [ignore]
\end{verbatim}

The string \verb+<theory>+ specifies the QM theory to be used in the
QM/MM simulation\footnote{If theory is ``{\tt md}'' this is not a QM/MM
simulation and will result in an appropriate error}.  The level of
theory may be any QM method that can compute gradients but those
algorithms in NWChem that do not support analytic gradients should be
avoided (c.f., Section \ref{sec:functionality}).

The string \verb+<operation>+ is used to specify the calculation that will
be performed in the QM/MM task.  The default operation is a single point energy
evaluation.  The following list gives the selection of operations currently
available in the NWChem QM/MM module;
\begin{itemize}
\item \verb+energy+ --- single point energy evaluation
\item \verb+optimize+ --- minimize the energy by variation of the molecular
   structure.
\item \verb+dynamics+ --- molecular dynamics using nwARGOS
\end{itemize}

Here are some examples of the \verb+TASK+ directive for QM/MM
simulations.  To perform a single point energy of a QM/MM system using
any QM level of theory, the directive is very simple. As with the
general task directive, the QM/MM energy evaluation is the
default. For a DFT energy calculation the task directive input is,
\begin{verbatim}
  task qmmm dft
\end{verbatim}
or completely as
\begin{verbatim}
  task qmmm dft energy
\end{verbatim}

To do a molecular dynamics simulation of a QM/MM system using the SCF
level of theory the task directive input would be
\begin{verbatim}
  task qmmm scf dynamics
\end{verbatim}

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 BSSE calculations}
\label{sec:bsse_task}

NWChem computes the basis set superposition error (BSSE) when two or more
fragments are interacting by using the counterpoise method.
This directive is performed if the \verb+BSSE+ section is present.
Single point energies, energy gradients, geometry
optimizations, Hessians and frequencies, at the level of theory that allows these tasks, can be obtained with the BSSE correction.
The input options for the BSSE section are:

\begin{verbatim}
BSSE
  MON <string monomer name> <integer natoms> \
   [INPUT  [<string input>]] \
   [INPUT_WGHOST[<string input>]] \
   [CHARGE [< real charge>]] \
  [OFF] \
  [ON] \
END
\end{verbatim}

\verb+MON+ defines the monomer's name and its atoms;
 <string monomer name> defines the
name of the monomer, <integer atoms> is the list of atoms corresponding to the
monomer (where such a list is relative to the initial geometry).
This information is needed for each monomer.
With the tag \verb+INPUT+ the user can modify any calculation attributes for
each monomer without ghost.
For example, the iterations number and the grid can be
changed in a DFT calculation (see the example of the interaction between $Zn^{2+}$ and
water).  \verb+INPUT_WGHOST+ is the same than \verb+INPUT+ but for the monomer with ghost.
The input changes will be applied within this and for the following calculations,
you should be cautious reverting the changes for the next monomers.
\verb+CHARGE+
assigns a charge to a monomer and it must be consistent with the total charge
in the whole system (see Section \ref{sec:charge}). The options \verb+OFF+ and  \verb+ON+
turns off and on any BSSE calculation.

The energy evaluation involves 1 + 2N calculations, i.e. one for the supermolecule and
two for the N monomers. [S. Simon, M. Duran, J. J. Dannenberg, J. Chem. Phys., 105, 11024 (1996)]
NWChem stores the vector files for each calculation (\verb+<string monomer name>.bsse.movecs+),
and one hessian file (\verb+<string monomer name>.bsse.hess+).
The code does not assign automatically the basis set for the ghost atoms,
you must assign the corresponding bqX for each element, instead.

\subsection*{Examples}

The dimer $(FH)_2$

\begin{verbatim}
title dimer
start dimer
geometry units angstrom
symmetry c1
  F        1.47189        2.47463       -0.00000
  H        1.47206        3.29987        0.00000
  F        1.46367       -0.45168        0.00000
  H        1.45804        0.37497       -0.00000
end

basis "ao basis"
 F library 6-31G
 H library 6-31G
 bqF library F 6-31G
 bqH library H 6-31G
end
dft; xc slater 1.0 vwn_5 1.0; direct; end
bsse
  mon first 1 2
  mon second 3 4
end

task dft energy

\end{verbatim}

Changing {\tt maxiter} for a  specific monomer: $Zn^{2+}(H_2O)$

\begin{verbatim}
title znwater
start znwater

echo
geometry noautoz units angstrom
symmetry c1
  Zn      -1.89334       -0.72741       -0.00000
  O       -0.20798        0.25012        0.00000
  H       -0.14200        1.24982       -0.00000
  H        0.69236       -0.18874       -0.00000
end

basis "ao basis"
 O library 6-31G
 Zn library 6-31G
 H library 6-31G
 bqO library O 6-31G
 bqZn library Zn 6-31G
 bqH library H 6-31G
end
charge 2
scf; direct; end
mp2; end

bsse
  mon metal 1
    charge 2
    input_wghost "scf\;  maxiter 200\; end"
  mon water 2 3 4
end

task mp2 optimize
\end{verbatim}

\section{{\tt CHARGE} --- Total system charge}
\label{sec:charge}

This is an optional top-level directive that allows the user to specify
the total charge of the system.  The form of the directive is as follows:
\begin{verbatim}
  CHARGE <real charge default 0>
\end{verbatim}

The default charge\footnote{The charge directive, in conjunction with
  the charges of atomic nuclei (which can be changed via the geometry
  input, cf. Section \ref{sec:cart}), determines the total number of
  electrons in the chemical system.  Therefore, a {\tt charge n}
  specification removes "n" electrons from the chemical system.
  Similarly, {\tt charge -n} adds "n" electrons.} is zero
if this directive is omitted.  An example of a case where the
directive would be needed is for a calculation on a doubly charged
cation.  In such a case, the directive is simply,
\begin{verbatim}
  charge 2
\end{verbatim}

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 are 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 on $LiH^+$ and
$LiH^{2+}$ in turn.  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}).

\section{{\tt ECCE\_PRINT} --- Print information for Ecce}
\label{sec:ecce}

The \verb+ECCE_PRINT+ directive allows the user to print out a file,
usually called ecce.out, that will allow the calculation and its
results to be imported into \htmladdnormallink{Ecce}
{http://ecce.pnl.gov}.

\begin{verbatim}
  ECCE_PRINT <string name>
\end{verbatim}

The entry for variable \verb+<name>+ is the name of the file
that will contain the Ecce import information and should include
the full path to the directory where you want that file.  For example

\begin{verbatim}
  ecce_print /home/user/job/ecce.out
\end{verbatim}

If the full path is not given and only the file name is given, the file
will be located in whatever directory the job is started in.  For example,
if the line

\begin{verbatim}
  ecce_print ecce.out
\end{verbatim}

is in the input file, the file could end up in the scratch directory if
the user is using a batch script that copies the input file to a local
scratch directory and then launches NWChem from there.  If the system
then automatically removes files in the scratch space at the end of the
job, the ecce.out file will be lost.  So, the best
practice is to include the full path name for the file.