% gateway.tex $ this file belongs to the Molcas repository $*/
\section{GATEWAY - Definition of geometry, basis sets, and symmetry}
\label{TUT:sec:gateway}
\index{GATEWAY}\index{Program!GATEWAY}\index{Integrals}

The program \program{GATEWAY} handles the basic molecular parameters in the
calculation. It generates data that are used in all subsequent calculations.
These data are stored in the \file{RUNFILE}. \program{GATEWAY} is the first
program to be executed, if the \variable{\$WorkDir} directory and the \file{RUNFILE} file 
has not already been generated by a previous calculation.

This tutorial is describes how to set up the basic \molcas\ input for the water molecule. 
For a more general description of the input options for \program{GATEWAY}, please refer to the Users Guide. 
%The input for water is given in 
%Figure~\ref{fig:gateway_input}. 
The first line of the input is the program identifier \&GATEWAY.
Then follows the keyword used is \keyword{TITLe} which will also get
printed in the \program{GATEWAY} section of the calculation output. 
The title line is also saved in the integral file and will appear in subsequent programs. 

\index{GATEWAY!Symmetry}\index{Option!Symmetry}
\index{Symmetry!Generators}\index{Symmetry!Point groups}
\index{GATEWAY!Input}

The \keyword{GROUp} keyword is followed by the generators for the C$_{2v}$ 
point group, since the example deals with the water molecule.
The specification of the C$_{2v}$ point group given in
Table~\ref{tab:symmetry_list} is not unique, but, in this tutorial, the 
generators have been input in an order that reproduces the ordering in the
character tables. A complete list of symmetry generator input syntax is given 
in Table~\ref{tab:symmetry_list}.  The symmetry groups available are listed 
with the symmetry generators defining the group. The \molcas\ keywords required 
to specify the symmetry groups are also listed. The last column contains the 
symmetry elements generated by the symmetry generators.

\begin{inputlisting}
 &GATEWAY
Title= Water in C2v symmetry - A Tutorial
Coord = water.xyz
Group =  XY Y
Basis Set = O.ANO-S-MB,H.ANO-S-MB
\end{inputlisting}

\begin{table}[htbp]
\caption{Symmetries available in MOLCAS including generators, MOLCAS keywords 
and symmetry elements.}
\label{tab:symmetry_list}
\begin{tabular}{c|ccc|ccc|cccccccc}
Group &
\multicolumn{3}{c|}{Generators} &
\multicolumn{3}{c|}{\molcas} &
\multicolumn{8}{c}{Elements} \\
         & $g_1$    & $g_2$      & $g_3$ &$g_1$&$g_2$&$g_3$& $E$ &  $g_1$ & $g_2$ & $g_1g_2$ & $g_3$ & $g_1g_3$ & $g_2g_3$ & $g_1g_2g_3$ \\
\hline
$C_1$    &          &            &       &&&& $E$ &        &       &          &      &      &      &     \\
$C_2$    & $C_2$    &            &       &\keyword{xy}&&& $E$ & $C_2$  &       &          &      &      &      &     \\
$C_s$    & $\sigma$ &            &       &\keyword{x}&&& $E$ & $\sigma$ &       &          &      &      &      &     \\
$C_i$    & $i$      &            &       &\keyword{xyz}&&& $E$ & $i$    &       &          &      &      &      &     \\
$C_{2v}$ & $C_2$    & $\sigma_v$ &       &\keyword{xy}&\keyword{y}&& $E$ & $C_2$  & $\sigma_v$ & $\sigma_v'$ &  &  &  & \\
$C_{2h}$ & $C_2$    & $i$        &       &\keyword{xy}&\keyword{xyz}&& $E$ & $C_2$  & $i$ & $\sigma_h$ &       &      &      &     \\
$D_2$    & $C_2^z$  & $C_2^y$    &       &\keyword{xy}&\keyword{xz}&& $E$ & $C_2^z$ & $C_2^y$ & $C_2^x$ &      &      &      &     \\
$D_{2h}$ & $C_2^z$  & $C_2^y$    & $i$   &\keyword{xy}&\keyword{xz}&\keyword{xyz}& $E$ & $C_2^z$ & $C_2^y$ & $C_2^x$ & $i$ & $\sigma^{xy}$ & $\sigma^{xz}$
& $\sigma^{yz}$ \\
\end{tabular}
\end{table}

To reduce the input, the unity operator $E$ is always assumed. The twofold 
rotation about the z-axis, C$_{2}$($z$), and the reflection in the xz-plane,
$\sigma_v$($xz$), are input as XY and Y respectively.  The \molcas\
input can be viewed as symmetry operators that operate on the
Cartesian elements specified.  For example, the reflection in the
xz-plane is specified by the input keyword \keyword{Y} which is the
Cartesian element operated upon by the reflection. 

The input produces the character table in the 
\program{GATEWAY} section of the output shown in 
Figure~\ref{fig:Tut_C2v_output}. Note that $\sigma_v$($yz$) was produced from 
the other two generators.  The last column contains the basis functions of 
each irreducible symmetry representation.  The totally symmetric $a_1$ 
irreducible representation has the $z$ basis function listed which is unchanged 
by any of the symmetry operations.

%$
\label{fig:Tut_C2v_output}
\begin{verbatim}
                             E   C2(z) s(xz) s(yz)
                    a1       1     1     1     1  z
                    b1       1    -1     1    -1  x, xz, Ry
                    a2       1     1    -1    -1  xy, Rz, I
                    b2       1    -1    -1     1  y, yz, Rx
\end{verbatim}

\index{Character table}
\index{GATEWAY!Test}\index{Input!Comment lines}

\index{Units}\index{GATEWAY!Geometry}\index{GATEWAY!Units}
\index{Coordinates!GATEWAY input}

The geometry of the molecule is defined using the keyword \keyword{coord}. On 
the next line,  the name of the xyz file that defines the geometrical 
parameters of the molecule (\file{water.xyz}) is given. 
\begin{enumerate}
\item The first line of the \file{water.xyz} file contains the number of atoms. 
\item The second line is used to indicate the units: \AA ngstr\"om or atomic units. 

The default is to use \AA ngstr\"om. 
\item Then follows one line for each atom containing the name of each atom and its coordinates. 
\end{enumerate}

Basis sets are defined after the keyword \keyword{BASIs sets}. The oxygen
and hydrogen basis set chosen, for this example, are the small Atomic Natural Orbitals 
(ANO) sets.  There are three contractions of the basis included in the input,
which can be toggled in or excluded with an asterisk, according to the desired calculation:
minimal basis, double zeta basis with polarization, or triple zeta basis with polarization.
\ifmanual
\begin{figure}[ht]
\caption{The geometry of the water molecule}
\label{fig:coord}
\end{figure}
{\footnotesize
\begin{verbatim}
 3

O	       .000000        .000000	     .000000  
H	      0.700000        .000000	    0.700000 
H	     -0.700000        .000000	    0.700000
\end{verbatim} }
\fi


\subsection{\program{GATEWAY} Output}

\index{GATEWAY!Output}
%\index{GATEWAY!RTRN option}
\index{GATEWAY!Geometry}

The \program{GATEWAY} output contains the symmetry character table, basis set 
information and input atomic centers. The basis set information lists the 
exponents and contraction coefficients as well as the type of Gaussian functions
(Cartesian, spherical or contaminated) used.  

The internuclear distances and valence bond angles (including dihedral angles) 
are displayed after the basis set information. 
%There is a keyword, 
%\keyword{RTRN}, which is used to increase the threshold for printing of bond 
%lengths, bond angles and dihedral angles from the default of 3.5 au.
Inertia and rigid-rotor analysis is also included in the output along with
the timing information.

A section of the output that is useful for determining the input to
the \molcas\ module \program{SCF} is the symmetry adapted basis
functions which appears near the end of the \program{GATEWAY} portion
of the output.  This is covered in more detail in the \program{SCF}
tutorial.

The most important file produced by the \program{GATEWAY} module is the 
\file{RUNFILE} which in our case is linked to \file{water.RunFile}.  This is 
the general \molcas\ communications file for transferring data between the
various \molcas\ program modules.  Many of the program modules add
data to the \file{RUNFILE} which can be used in still other modules. A new 
\file{RUNFILE} is produced every time \program{GATEWAY} is run. It should finally
be mentioned that for backwards compatibility one can run \program{MOLCAS} 
without invoking \program{GATEWAY}. The corresponding input and output will 
then be handled by the program \program{SEWARD}.

\ifmanual
\subsection{Basis Set Superposition Error (BSSE)}

\index{GATEWAY!BSSE}
\program{GATEWAY} can operates with several coordinate files, which is convenient
for computing BSSE corrections. \keyword{BSSE} followed by a number marks a XYZ
file which should be treated as dummy atoms. The following example demonstrates
this feature:

\begin{inputlisting}
&GATEWAY
coord = ethanol.xyz
coord = water.xyz
bsse  = 1
basis = ANO-S-MB
NOMOVE
&SEWARD; &SCF
&GRID_IT
NAME = water
***************
&GATEWAY
coord = ethanol.xyz
coord = water.xyz
bsse  = 2
basis = ANO-S-MB
NOMOVE
&SEWARD; &SCF
&GRID_IT
NAME = ethanol
**************
&GATEWAY
coord = ethanol.xyz
coord = water.xyz
basis = ANO-S-MB
NOMOVE
&SEWARD; &SCF
&GRID_IT
NAME = akvavit

\end{inputlisting}

Note, that NOMOVE keyword prevents centering of the molecule, so the computed 
grids are identical. An alternative way to compute density difference is to
modify coordinates, and change an element label to X.

\fi

\subsection{\program{GATEWAY} Basic and Most Common Keywords}

\begin{keywordlist}
\item[Coord] File name or inline number of atoms and XYZ coordinates
\item[BASIs Set] Atom\_label.Basis\_label (for example ANO-L-VTZP)
\item[Group] Full (find maximum), NoSym, or symmetry generators
\item[SYMMetry]  Symmetry generators: X, Y, Z, XY, XZ, YZ, XYZ (in native format)
\item[RICD] On-the-fly auxiliary basis sets.
\item[]
\end{keywordlist}
