%
% $Id$ 
%
\label{sec:dplot}
\begin{verbatim}
  DPLOT
    ...
  END
\end{verbatim}

This directive is used to obtain the plots of various types of electron
densities (or orbitals) of the molecule. The electron density is calculated
on a specified set of grid points using the molecular orbitals
from SCF or DFT calculation. The output file is either in 
\htmladdnormallink{MSI Insight II} 
{http://www.msi.com/materials/insight/Insight2.html} contour format
(default)
 or in the 
\htmladdnormallink{Gaussian Cube}{http://www.gaussian.com/g_ur/u_cubegen.htm}
format.  DPLOT is not executed until the ``\verb+task dplot+'' directive is given.  
Different sub-directives are described below.

\section{{\tt GAUSSIAN} --- Gaussian Cube format}

\begin{verbatim}
  GAUSSIAN
\end{verbatim}

A outputfile is generate in Gaussian Cube format.
You can visualize this file using  \htmladdnormallink{gOpenMol}
{http://www.csc.fi/gopenmol/tutorials/quick_start.phtml\#view}
(after converting the Gaussian Cube file with 
\htmladdnormallink{gcube2plt}
{http://www.csc.fi/lul/chem/scarecrow/gcube2plt.c}),
 \htmladdnormallink{Molden}
{http://www.cmbi.kun.nl/~schaft/molden/molden.html} 
 or 
\htmladdnormallink{Molekel}
{http://www.cscs.ch/molekel/}.

\section{{\tt TITLE} --- Title directive}

\begin{verbatim}
  TITLE <string Title default Unknown Title>
\end{verbatim}

This sub-directive specifies a title line for the generated
input to the {\em Insight} program or for the Gaussian cube
file. Only one line is allowed.

\section{{\tt LIMITXYZ} --- Plot limits}

\begin{verbatim}
  LIMITXYZ [units <string Units default angstroms>]
  <real X_From> <real X_To> <integer No_Of_Spacings_X>
  <real Y_From> <real Y_To> <integer No_Of_Spacings_Y>
  <real Z_From> <real Z_To> <integer No_Of_Spacings_Z>
\end{verbatim}

This sub-directive specifies the limits of the cell to be plotted.
The grid is generated using \verb+No_Of_Spacings+~+~\verb+1+ points
along each direction. The known names for \verb+Units+ are
\verb+angstroms+, \verb+au+ and \verb+bohr+.



\section{{\tt SPIN} --- Density to be plotted}

\begin{verbatim}
  SPIN <string Spin default total>
\end{verbatim}

This sub-directive specifies, what kind of density is to be computed. The 
known names for \verb+Spin+ are \verb+total+, \verb+alpha+, \verb+beta+
and \verb+spindens+, the last being computed as the difference between
$\alpha$ and $\beta$ electron densities.



\section{{\tt OUTPUT} --- Filename}

\begin{verbatim}
  OUTPUT <string File_Name default dplot>
\end{verbatim}

This sub-directive specifies the name of the generated input to the
{\em Insight} program or the generated Gaussian cube file. 
The name \verb+OUTPUT+ is reserved for the
standard NWChem output.



\section{{\tt VECTORS} --- MO vector file name}

\begin{verbatim}
  VECTORS <string File_Name default movecs> [<string File_Name2>]
\end{verbatim}

This sub-directive specifies the name of the molecular orbital file.
If the second file is optionally given the density is computed as the
difference between the corresponding electron densities. The vector 
files have to match.

\section{{\tt DENSMAT} ---  Density matrix file name}

\begin{verbatim}
  DENSMAT <string File_Name> [<string File_Name2>]
\end{verbatim}

This sub-directive specifies the name of density matrix file,
and used for plotting the density generated by correlation methods,
such as CCSD for ground state and EOM-CCSD for excited states.

The second file is optional. When it is given, 
the difference of the densities, specified by the two density matrix files,
is computed and plotted.

\section{{\tt WHERE} --- Density evaluation}

\begin{verbatim}
  WHERE <string Where default grid>
\end{verbatim}

This sub-directive specifies where the density is to be computed.
The known names for \verb+Where+ are \verb+grid+ (the calculation of
the density is performed on the set of a grid points specified by the
sub-directive \verb+LimitXYZ+ and the file specified by the sub-directive
\verb+Output+ is generated), \verb+nuclei+ (the density is computed at
the position of the nuclei and written to the NWChem output) and
\verb+g++\verb+n+ (both).


\section{{\tt ORBITAL} --- Orbital sub-space}

\begin{verbatim}
  ORBITALS [<string Option default density>]
  <integer No_Of_Orbitals>
  <integer Orb_No_1 Orb_No_2 ...>
\end{verbatim}

This sub-directive specifies the subset of the orbital space for the
calculation of the electron density. The density is computed using the
occupation numbers from the orbital file modified according to the
\verb+Spin+ directive. If the contours of the orbitals are to be plotted
\verb+Option+ should be set to \verb+view+. Note, that in this case
\verb+No_Of_Orbitals+ should be set to \verb+1+ and sub-directive
\verb+Where+ is automatically set to \verb+grid+. Also specification
of two orbital files conflicts with the \verb+view+ option.
$\alpha$ orbitals are always plotted unless \verb+Spin+ is set to
\verb+beta+.

\section{Examples}

\subsection*{Charge Density}

Example of charge density plot (with Gaussian Cube output):
\begin{verbatim}
start n2
geometry
  n  0 0   0.53879155
  n  0 0  -0.53879155
end
basis;  n library cc-pvdz;end
scf
vectors  output n2.movecs
end
dplot
  TITLE HOMO
  vectors n2.movecs
   LimitXYZ
 -3.0 3.0 10  
-3.0 3.0 10 
-3.0  3.0  10
  spin total
  gaussian
  output lumo.cube
end
task scf     
task dplot
\end{verbatim}

\begin{verbatim}
start n2
geometry
  n  0 0   0.53879155
  n  0 0  -0.53879155
end
basis;  n library cc-pvdz;end
scf
vectors  output n2.movecs
end

tce
ccsd
densmat n2.densmat
end

task tce energy

dplot
  TITLE HOMO
   LimitXYZ
 -3.0 3.0 10
-3.0 3.0 10
-3.0  3.0  10
  spin total
  gaussian
  densmat n2.densmat
  output lumo.cube
end
task dplot
\end{verbatim}

\subsection*{Molecular Orbital}

Example of orbital plot (with Insight II contour output):
\begin{verbatim}
start n2
geometry
  n  0 0   0.53879155
  n  0 0  -0.53879155
end
basis;  n library cc-pvdz;end
scf
vectors  output n2.movecs
end
dplot
  TITLE HOMO
  vectors n2.movecs
   LimitXYZ
 -3.0 3.0 10  
-3.0 3.0 10 
-3.0  3.0  10
  spin total
  orbitals view; 1; 7
  output homo.grd
end
task scf     
task dplot
\end{verbatim}