mirror of
https://github.com/nwchemgit/nwchem.git
synced 2026-07-28 06:05:44 -04:00
454 lines
16 KiB
TeX
454 lines
16 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
% Original Author: Hugh L Taylor hl_taylor@pnl.gov
|
|
% Created: Thu Aug 29 1996
|
|
%
|
|
% RCS Information:
|
|
% $Author: d35162 $ $Locker: $
|
|
% $Revision: 1.3 $ $Date: 1998-12-15 16:22:36 $
|
|
%
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\section{NWChem Ouput to Ecce}
|
|
|
|
This section describes the output file that can be generated by NWChem that
|
|
can be processed in the Extensible Computational Chemistry Environment (Ecce).
|
|
Ecce is an integrated molecular modeling tool for analysis and
|
|
simulation of complex chemical problems. Information on Ecce itself
|
|
can be found on the web at
|
|
|
|
\begin{verbatim}
|
|
http://www.emsl.pnl.gov:2080/docs/ecce
|
|
\end{verbatim}
|
|
|
|
This
|
|
site gives access to on-line help, release notes for each version of
|
|
Ecce, information on publications and on-going research, and a FAQs page.
|
|
|
|
\subsection{Contents of Output for Ecce}
|
|
Any data object of potential interest to the user and of reasonable size
|
|
should be output to this file. Larger objects (e.g., the MOs or density
|
|
grids) in other files will be stored in XDR format; those filenames should be
|
|
included here.
|
|
|
|
Results of interest include:
|
|
\begin{enumerate}
|
|
\item Exit status for each module
|
|
\item Messages (Character output, e.g., the basis name)
|
|
\item various energies
|
|
\item geometry
|
|
\item multipole moment components and magnitudes
|
|
\item energy gradient
|
|
\item density grids
|
|
\item performance, profiling, and memory usage data
|
|
\item convergence parameters and iteration number for iterative processes
|
|
\end{enumerate}
|
|
|
|
The current version of NWChem includes output for
|
|
\begin{enumerate}
|
|
\item SCF, DFT, MP2 CCSD energies and gradients, optimization with STEPPER and DRIVER.
|
|
\item Correct module stack, including the task (e.g., {\tt
|
|
gradient|mp2|scf})
|
|
\item Module entry and exit (with status)
|
|
\item Geometry as input by the user
|
|
\item Geometry when updated by STEPPER or DRIVER
|
|
\item Name of basis set(s) used by the application (e.g., if {\tt ao
|
|
basis} was set to be \verb+6-31g*+)
|
|
\item Convergence of SCF/DFT (energy and orbital-gradient norm)
|
|
\item Final converged total energies
|
|
\item Gradients w.r.t. geometry (analytic and numerical) and norm thereof
|
|
\item MO coefficients and energies
|
|
\item Error messages reported via errquit
|
|
\end{enumerate}
|
|
|
|
\subsection{Format of Output}
|
|
|
|
To accommodate:
|
|
\begin{enumerate}
|
|
\item simple scalar data of various types
|
|
\item vector, matrix and tensor data of various types
|
|
\item begin/end of groups of data objects (for example, a matrix of
|
|
normal mode elements, along with a vector of frequencies and a
|
|
vector of symmetry labels).
|
|
\item enter/exit messages, with status, of each module
|
|
\end{enumerate}
|
|
the following general format was proposed,
|
|
\begin{verbatim}
|
|
<module stack>%begin%<keyword>%<dim1> ... <dimn>%<type>
|
|
<data>
|
|
<module stack>%end%<keyword>%<dim1> ... <dimn>%<type>
|
|
\end{verbatim}
|
|
where:
|
|
\begin{description}
|
|
\item [\verb+<module stack>+] is a white space separated list of
|
|
module names representing the (logical) call tree,
|
|
\item [\verb+<dim1> ... <dimn>+] contains the size of each dimension
|
|
for arrays or tensors (unity for a scalar),
|
|
\item [\verb+<keyword>+] identifies the quantity that is being output
|
|
(See below for more detail on the actual keywords.)
|
|
\item [\verb+<type>+] is the data type (\verb+"char"+, \verb+"int"+,
|
|
\verb+"long"+, \verb+"float"+, \verb+"double"+, \verb+"complex
|
|
float"+, and \verb+"logical"+),
|
|
\item [\verb+<data>+] contains the values (one character string per
|
|
line, multiple values per line for other data types limited to circa
|
|
80 characters per line).
|
|
\end{description}
|
|
in addition:
|
|
\begin{enumerate}
|
|
\item Floating point exponential notation should use ``e'' or ``E'',
|
|
not ``d'' or ``D''.
|
|
\item Module names will everywhere be printed with internal white space
|
|
replaced with underscores.
|
|
\item Lines should not exceed 1023 characters
|
|
\item Logical s
|
|
\end{enumerate}
|
|
|
|
Information such as units is handled by the Ecce code registration.
|
|
|
|
\subsection{NWChem Ecce Output API}
|
|
|
|
This API is written in C with FORTRAN wrappers and most of the source is
|
|
located in the
|
|
\$NWCHEM\_TOP/src/util/ecce\_print.c file.
|
|
|
|
\subsubsection{ routine ecce\_print\_module\_entry(module)}
|
|
|
|
\begin{verbatim}
|
|
subroutine ecce_print_module_entry(module)
|
|
character*(*) module
|
|
|
|
void ecce_print_module_entry(const char *module)
|
|
\end{verbatim}
|
|
If printing is enabled, prints
|
|
|
|
\begin{verbatim}
|
|
<module stack>%begin%enter%1%character
|
|
<module>
|
|
<module stack>%end%enter%1%character
|
|
\end{verbatim}
|
|
and then pushes \verb+<module>+ onto the module name stack.
|
|
|
|
Module names will everywhere be printed with internal white space
|
|
replaced with underscores.
|
|
|
|
\subsubsection{routine ecce\_print\_module\_exit(module, status)}
|
|
|
|
\begin{verbatim}
|
|
subroutine ecce_print_module_exit(module, status)
|
|
character*(*) module
|
|
character*(*) status
|
|
|
|
void ecce_print_module_exit(const char *module, const char *status)
|
|
\end{verbatim}
|
|
|
|
If printing is enabled, prints
|
|
|
|
\begin{verbatim}
|
|
<module stack>%begin%exit%2%character
|
|
<module> <status>
|
|
<module stack>%end%exit%2%character
|
|
\end{verbatim}
|
|
and (with the valid assumption that no nwchem module is reentrant)
|
|
pops the module name stack until either \verb+<module>+ is popped
|
|
off it, or the stack is empty. If \verb+<module>+ is not found on
|
|
the stack print an informative message to stderr (no more than
|
|
one such message per calculation) and continue.
|
|
|
|
Status will be lowercased and printed enclosed in double quotes with
|
|
any quotes inside the string quietly replaced with single quotes.
|
|
\begin{quotation}
|
|
|
|
"ok" implies success
|
|
|
|
"anything else" implies some sort of failure, though perhaps a
|
|
recoverable one.
|
|
|
|
\end{quotation}
|
|
|
|
\subsubsection{ routine ecce\_print1(keyword, ma\_type, data, dim1) }
|
|
|
|
\begin{verbatim}
|
|
subroutine ecce_print1(keyword, ma_type, data, dim1)
|
|
character*(*) keyword
|
|
integer ma_type
|
|
<ma_type> data(*)
|
|
integer dim1
|
|
|
|
void ecce_print1(const char *keyword, int ma_type,
|
|
const void *data, int dim1)
|
|
\end{verbatim}
|
|
|
|
Print a 1-dimensional array of the specified type.
|
|
|
|
\begin{quotation}
|
|
|
|
Real data will be printed with the printf format \verb+%.14e+
|
|
|
|
Boolean data will be printed as \verb+t+ and \verb+f+
|
|
|
|
\end{quotation}
|
|
|
|
\subsubsection{ routine ecce\_print2(keyword, ma\_type, data, dim1, dim2)}
|
|
|
|
\begin{verbatim}
|
|
subroutine ecce_print1(keyword, ma_type, data, lda1, dim1, dim2)
|
|
character*(*) keyword
|
|
integer ma_type
|
|
<ma_type> data(lda1,dim2)
|
|
integer lda1
|
|
integer dim1, dim2
|
|
|
|
void ecce_print2(const char *keyword, int ma_type,
|
|
int dim1, int lda1, int dim2, const void *data)
|
|
|
|
\end{verbatim}
|
|
|
|
Print a 2-dimensional array of the specified type.
|
|
|
|
\subsubsection{ routine ecce\_print1\_char(keyword, data, dim1) }
|
|
|
|
\begin{verbatim}
|
|
subroutine ecce_print1_char(keyword, data, dim1)
|
|
character*(*) keyword
|
|
character*(*) data(*)
|
|
integer dim1
|
|
\end{verbatim}
|
|
|
|
Print a 1-dimensional array of FORTRAN character strings (printing of
|
|
arrays of character strings from C is not currently provided for).
|
|
|
|
\begin{quotation}
|
|
|
|
Character string data will be printed one string per line
|
|
with no quoting of special characters.
|
|
|
|
\end{quotation}
|
|
|
|
\subsubsection{ routine ecce\_print2\_dbl\_tol }
|
|
|
|
\subsubsection{routine ecce\_print\_control(status, old)}
|
|
|
|
\begin{verbatim}
|
|
subroutine ecce_print_control(status, old)
|
|
integer status ! [input]
|
|
integer old ! [output]
|
|
|
|
void ecce_print_control(int status, int *old)
|
|
\end{verbatim}
|
|
|
|
Sets the boolean (0=FALSE, 1=TRUE) controling printing to \verb=status= and
|
|
returns the previous setting.
|
|
|
|
\subsubsection{ routine ecce\_print\_file\_open(filename)}
|
|
|
|
\begin{verbatim}
|
|
subroutine ecce_print_file_open(filename)
|
|
character *(*) filename
|
|
|
|
void ecce_print_file_open(const char *filename)
|
|
\end{verbatim}
|
|
Open with create/truncate the named file to accept Ecce output.
|
|
If there is an error print a message to stderr, disable all
|
|
other ecce routines, and continue.
|
|
|
|
Inside NWChem only process $0$ would open the file and all other
|
|
processes would therefore quietly ignore all \verb+ecce_*()+ calls.
|
|
|
|
\subsubsection{ routine ecce\_print\_file\_close()}
|
|
|
|
\begin{verbatim}
|
|
subroutine ecce_print_file_close()
|
|
|
|
void ecce_print_file_close(void)
|
|
\end{verbatim}
|
|
Close the ecce\_output file, if any and disable Ecce printing. If
|
|
there are any errors print a message to stderr and continue.
|
|
|
|
\subsubsection{ routine ecce\_print\_echo\_input }
|
|
|
|
\subsubsection{ routine ecce\_print\_echo\_string }
|
|
|
|
\subsubsection{ routine is\_ecce\_print\_on }
|
|
|
|
|
|
Several routines are available within NWChem that perform more general tasks,
|
|
such as printing out the basis set, geometry and the orbital vectors. These
|
|
routines are delineated below.
|
|
|
|
\subsubsection{ subroutine movecs\_ecce\_print\_on }
|
|
Found in \$NWCHEM\_TOP/src/ddscf/movecs\_ecce.F
|
|
|
|
\subsubsection{ subroutine movecs\_ecce\_print\_off }
|
|
Found in \$NWCHEM\_TOP/src/ddscf/movecs\_ecce.F
|
|
|
|
\subsubsection{ subroutine movecs\_ecce }
|
|
Found in \$NWCHEM\_TOP/src/ddscf/movecs\_ecce.F
|
|
|
|
\subsubsection{ bas\_ecce\_print\_basis }
|
|
Found in \$NWCHEM\_TOP/src/basis/bas\_input.F
|
|
|
|
\subsubsection{ geom\_print\_rtdb\_ecce }
|
|
Found in \$NWCHEM\_TOP/src/geom/geom\_print/ecce.F
|
|
|
|
\subsubsection{ geom\_print\_ecce }
|
|
Found in \$NWCHEM\_TOP/src/geom/geom\_print/ecce.F
|
|
|
|
\subsection{Standard exit status}
|
|
|
|
Each module needs to provide a short text description of its exit
|
|
status. Some of these can be standardized, most probably cannot.
|
|
|
|
Standard exit status values include
|
|
|
|
\begin{description}
|
|
\item [\verb+"ok"+] --- success.
|
|
\item [\verb+"warning"+] --- success, but user should check the output for
|
|
more information.
|
|
\item [\verb+"error"+] --- a fatal user or program error.
|
|
\item [\verb+"failed to converge"+] --- sometimes this is OK.
|
|
\end{description}
|
|
|
|
\subsection{Standard keywords}
|
|
|
|
The keyword identifies to Ecce and the user of Ecce the quantity
|
|
that is being output (e.g., an energy or dipole moment). The module
|
|
stack is also output, so Ecce is already aware of the overall context
|
|
(e.g., that this is an SCF energy computed in the course of computing
|
|
the MP2 energy). To increase the ease with which data can be input
|
|
into Ecce and also accessed within Ecce it is important that
|
|
standard values of keywords be used.
|
|
|
|
The NWChem electronic structure modules should output all quantities
|
|
in atomic units and leave it to Ecce to handle any necessary
|
|
conversions. Exceptions to this convention can be made, but a
|
|
distinct keyword should be used (perhaps including the actual units
|
|
used, e.g., \verb+"vibrational frequencies (cm-1)"+).
|
|
|
|
Here is the master list of keywords. All Ecce print keywords should
|
|
be registered here. (Note: not all keywords given by NWChem are used
|
|
by Ecce. The ones listed below are those that NWChem uses.)
|
|
|
|
\subsubsection{Converged/final energies}
|
|
|
|
\begin{description}
|
|
\item [\verb+total energy+] --- the total energy at level of the module stack.
|
|
\item [\verb+mp2 energy+] --- the total MP2 energy.
|
|
\item [\verb+ccsd total energy+] --- the total ccsd energy.
|
|
\item [\verb+total ccsd energy+] --- the total ccsd energy.
|
|
\item [\verb+total ccsd(t) energy+] --- the total ccsd(t) energy.
|
|
\item [\verb+total ccsd+t(ccsd) energy+] --- the total ccsd+t(ccsd) energy.
|
|
\item [\verb+two-electron energy+] --- the two-electron energy
|
|
(Coulomb plus exchange).
|
|
\item [\verb+coulomb energy+] --- the (inter-electron) Coulomb
|
|
energy
|
|
\item [\verb+exchange energy+] --- the exchange energy.
|
|
\item [\verb+correlation energy+] --- the correlation energy
|
|
(relative to the pertitnent SCF or MCSCF reference function), generally refers
|
|
to MP2 or DFT.
|
|
\item [\verb+ccsd correlation energy+] --- the CCSD correlation energy
|
|
(relative to the pertitnent SCF or MCSCF reference function).
|
|
\item [\verb+nuclear repulsion energy+] --- the nuclear repulsion
|
|
energy at the current geometry.
|
|
\item [\verb+zero point energy+] --- zero point energy from a frequency calculation.
|
|
\end{description}
|
|
|
|
\subsubsection{Converged/final properties}
|
|
|
|
\begin{description}
|
|
\item [\verb+geometry+] --- the current geometry of the molecule.
|
|
\item [\verb+cartesian coordinates+] --- the current cartesians of the molecule.
|
|
\item [\verb+gradients+] --- the current gradient of the molecule.
|
|
\item [\verb+total gradient+] --- the current gradient of the molecule.
|
|
\item [\verb+total dipole+] --- a 3--vector of $(x,y,z)$ dipole
|
|
moments.
|
|
\item [\verb+open shell dipole+] --- a 3--vector of $(x,y,z)$ dipole
|
|
moments.
|
|
\item [\verb+alpha electronic dipole+] --- a 3--vector of $(x,y,z)$ dipole
|
|
moments.
|
|
\item [\verb+beta electronic dipole+] --- a 3--vector of $(x,y,z)$ dipole
|
|
moments.
|
|
\item [\verb+nuclear dipole+] --- a 3--vector of $(x,y,z)$ dipole
|
|
moments.
|
|
\item [\verb+total quadrupole+] ---
|
|
\item [\verb+open shell quadrupole+] ---
|
|
\item [\verb+alpha electronic quadrupole+] ---
|
|
\item [\verb+beta electronic quadrupole+] ---
|
|
\item [\verb+nuclear quadrupole+] ---
|
|
\item [\verb+total mulliken atomic charges+] --- an $N_{atom}$--vector of the charge
|
|
assigned by the Mulliken analysis to each atom.
|
|
\item [\verb+total mulliken shell charges+] --- an $N_{shell}$--vector of
|
|
the charge assigned by the Mulliken analysis to each shell of basis
|
|
functions.
|
|
\item [\verb+orbital symmetries+] --- symmetry information for each molecular
|
|
orbital.
|
|
\item [\verb+orbital energies+] --- orbital energies for each molecular orbital.
|
|
\item [\verb+frequencies+] --- frequencies.
|
|
\item [\verb+projected frequencies+] --- projected frequencies.
|
|
\item [\verb+normal modes+] --- normal modes associated with each frequency.
|
|
\item [\verb+projected normal modes+] --- projected normal modes associated
|
|
with each frequency.
|
|
\item [\verb+intensities+] --- frequency intensities.
|
|
\item [\verb+intensities+] --- frequency intensities.
|
|
\item [\verb+intensities (debye/ang)2+] --- frequency intensities in (debye/ang)2.
|
|
\item [\verb+intensities (KM/mol)+] --- frequency intensities in (KM/mol).
|
|
\item [\verb+projected intensities+] --- frequency projected intensities.
|
|
\item [\verb+projected intensities (debye/ang)2+] --- frequency projected intensities
|
|
in (debye/ang)2.
|
|
\item [\verb+projected intensities (KM/mol)+] --- frequency projected intensities
|
|
in (KM/mol).
|
|
\end{description}
|
|
|
|
\subsubsection{Convergence information}
|
|
|
|
\begin{description}
|
|
\item [\verb+iteration+] --- the iteration number for geometry steps, starting at 1.
|
|
\item [\verb+iteration counter+] --- the iteration counter when optimizing the
|
|
wavefunction.
|
|
\item [\verb+iterative total energy difference+] --- the change in the total
|
|
energy since the previous iteration.
|
|
\item [\verb+gradient norm+] --- an (estimate) of the norm of the
|
|
gradient vector or something proportional to it for
|
|
minimization/transition state algorithms (e.g., SCF
|
|
orbital-gradient, DFT norm of occupied-virtual Fock-matrix, geometry
|
|
optimization cartesian nuclear gradient).
|
|
\item [\verb+gradient max+] --- an (estimate) of the maximum absolute
|
|
value element in the gradient vector.
|
|
\item [\verb+residual norm+] --- norm of the error vector in
|
|
linear/non-linear equation solution
|
|
\item [\verb+residual max+] --- the absolute maximum value of the
|
|
residual vector
|
|
\item [\verb+scaled residual norm+] --- the norm of the residual
|
|
scaled by the norm of the RHS vector in the iterative solution of
|
|
non-linear equations (roughly the negative logarithm of the number of
|
|
significant figures)
|
|
\end{description}
|
|
|
|
\subsubsection{Timing and performance information}
|
|
|
|
The long term plan is to get all timing information into Ecce so that
|
|
it will be possible to track performance and even form parallel
|
|
speedup curves. By using the NWChem standard libraries and timing
|
|
mechanisms most statistics will be automatically gathered.
|
|
|
|
\begin{itemize}
|
|
\item The standard module entry/exit protocol routines (to be written)
|
|
will record entry and exit cpu/wall times, MA and GA usage
|
|
statistics, and virtual memory activity etc.
|
|
\item The CHEMIO library will eventually automatically record I/O
|
|
activity and provide a routine to track activity on all nodes.
|
|
\item The PSTAT module will very soon record all performance
|
|
information it tracks.
|
|
\item MA
|
|
\end{itemize}
|
|
|
|
PSTAT should be used for nearly all performance statistics --- if it
|
|
does not do what you want then it can be extended.
|
|
|
|
Additional keywords:
|
|
\begin{description}
|
|
\item [\verb+all tasks cpu time+] ---
|
|
\item [\verb+single task cpu time+] ---
|
|
\item [\verb+cpu time+] ---
|
|
\item [\verb+all tasks wall time+] ---
|
|
\item [\verb+single task wall time+] ---
|
|
\item [\verb+wall time+] ---
|
|
\end{description}
|
|
|