NWChem/doc/prog/ecce.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 \texttt{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 [\texttt{<module stack>}]  is a white space separated list of
  module names representing the (logical) call tree,
\item [\texttt{<dim1> ... <dimn>}] contains the size of each dimension
for arrays or tensors (unity for a scalar),
\item [\texttt{<keyword>}] identifies the quantity that is being output
(See below for more detail on the actual keywords.)
\item [\texttt{<type>}] is the data type (\texttt{"char"}, \texttt{"int"},
  \texttt{"long"}, \texttt{"float"}, \texttt{"double"}, \texttt{"complex
  float"}, and \texttt{"logical"}),
\item [\texttt{<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 \texttt{<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 \texttt{<module>} is popped
    off it, or the stack is empty.  If \texttt{<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 \texttt{\%.14e}

      Boolean data will be printed as \texttt{t} and \texttt{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 \texttt{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 \texttt{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 [\texttt{"ok"}] --- success.
\item [\texttt{"warning"}] --- success, but user should check the output for
  more information.
\item [\texttt{"error"}] --- a fatal user or program error.
\item [\texttt{"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., \texttt{"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 [\texttt{total energy}] --- the total energy at level of the module stack.
\item [\texttt{mp2 energy}] --- the total MP2 energy.
\item [\texttt{ccsd total energy}] --- the total ccsd energy.
\item [\texttt{total ccsd energy}] --- the total ccsd energy.
\item [\texttt{total ccsd(t) energy}] --- the total ccsd(t) energy.
\item [\texttt{total ccsd}t(ccsd) energy+] --- the total ccsd+t(ccsd) energy.
\item [\texttt{two-electron energy}] --- the two-electron energy
(Coulomb plus exchange).
\item [\texttt{coulomb energy}] --- the (inter-electron) Coulomb
  energy
\item [\texttt{exchange energy}] --- the exchange energy.
\item [\texttt{correlation energy}] --- the correlation energy
  (relative to the pertitnent SCF or MCSCF reference function), generally refers 
  to MP2 or DFT.
\item [\texttt{ccsd correlation energy}] --- the CCSD correlation energy
  (relative to the pertitnent SCF or MCSCF reference function).
\item [\texttt{nuclear repulsion energy}] --- the nuclear repulsion
  energy at the current geometry.
\item [\texttt{zero point energy}] --- zero point energy from a frequency calculation.
\end{description}

\subsubsection{Converged/final properties}

\begin{description}
\item [\texttt{geometry}] --- the current geometry of the molecule.
\item [\texttt{cartesian coordinates}] --- the current cartesians of the molecule.
\item [\texttt{gradients}] --- the current gradient of the molecule.
\item [\texttt{total gradient}] --- the current gradient of the molecule.
\item [\texttt{total dipole}] --- a 3--vector of $(x,y,z)$ dipole
  moments.
\item [\texttt{open shell dipole}] --- a 3--vector of $(x,y,z)$ dipole
  moments.
\item [\texttt{alpha electronic dipole}] --- a 3--vector of $(x,y,z)$ dipole
  moments.
\item [\texttt{beta electronic dipole}] --- a 3--vector of $(x,y,z)$ dipole
  moments.
\item [\texttt{nuclear dipole}] --- a 3--vector of $(x,y,z)$ dipole
  moments.
\item [\texttt{total quadrupole}] ---
\item [\texttt{open shell quadrupole}] ---
\item [\texttt{alpha electronic quadrupole}] ---
\item [\texttt{beta electronic quadrupole}] ---
\item [\texttt{nuclear quadrupole}] ---
\item [\texttt{total mulliken atomic charges}] --- an $N_{atom}$--vector of the charge
  assigned by the Mulliken analysis to each atom.
\item [\texttt{total mulliken shell charges}] --- an $N_{shell}$--vector of
  the charge assigned by the Mulliken analysis to each shell of basis
  functions. 
\item [\texttt{orbital symmetries}] --- symmetry information for each molecular 
  orbital.
\item [\texttt{orbital energies}] --- orbital energies for each molecular orbital.
\item [\texttt{frequencies}] --- frequencies.
\item [\texttt{projected frequencies}] --- projected frequencies.
\item [\texttt{normal modes}] --- normal modes associated with each frequency.
\item [\texttt{projected normal modes}] --- projected normal modes associated 
  with each frequency.
\item [\texttt{intensities}] --- frequency intensities.
\item [\texttt{intensities}] --- frequency intensities.
\item [\texttt{intensities (debye/ang)2}] --- frequency intensities in (debye/ang)2.
\item [\texttt{intensities (KM/mol)}] --- frequency intensities in (KM/mol).
\item [\texttt{projected intensities}] --- frequency projected intensities.
\item [\texttt{projected intensities (debye/ang)2}] --- frequency projected intensities 
  in (debye/ang)2.
\item [\texttt{projected intensities (KM/mol)}] --- frequency projected intensities 
  in (KM/mol).
\end{description}

\subsubsection{Convergence information}

\begin{description}
\item [\texttt{iteration}] --- the iteration number for geometry steps, starting at 1.
\item [\texttt{iteration counter}] --- the iteration counter when optimizing the
  wavefunction.
\item [\texttt{iterative total energy difference}] --- the change in the total 
  energy since the previous iteration.
\item [\texttt{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 [\texttt{gradient max}] --- an (estimate) of the maximum absolute
  value element in the gradient vector.
\item [\texttt{residual norm}] --- norm of the error vector in
  linear/non-linear equation solution
\item [\texttt{residual max}] --- the absolute maximum value of the
  residual vector
\item [\texttt{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 [\texttt{all tasks cpu time}] ---
\item [\texttt{single task cpu time}] ---
\item [\texttt{cpu time}] ---
\item [\texttt{all tasks wall time}] ---
\item [\texttt{single task wall time}] ---
\item [\texttt{wall time}] ---
\end{description}