.. index::
   single: Program; Gateway
   single: Gateway
   single: Integrals

.. _TUT\:sec\:gateway:

:program:`GATEWAY` --- Definition of geometry, basis sets, and symmetry
=======================================================================

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 :file:`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 first line of the input is the program identifier ``&GATEWAY``.
Then follows the keyword used is :kword:`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.

.. The input for water is given in
   :numref:`block:gateway_input`.

.. index::
   single: Gateway; Symmetry
   single: Option; Symmetry
   single: Symmetry; Generators
   single: Symmetry; Point groups
   single: Gateway; Input

The :kword:`GROUp` keyword is followed by the generators for the :math:`C_{2v}`
point group, since the example deals with the water molecule.
The specification of the :math:`C_{2v}` point group given in
:numref:`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 :numref:`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. ::

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

.. table:: Symmetries available in |molcas| including generators, |molcas| keywords and symmetry elements.
   :name: tab:symmetry_list

   ============== ============== ================ =========== ============ ============ ============ ========= ============== ================ ================= =========== =================== =================== ===================
   Group          Generators                                  |molcas|                               Elements
   -------------- ------------------------------------------- -------------------------------------- -----------------------------------------------------------------------------------------------------------------------------------
   |zws|          :math:`g_1`    :math:`g_2`      :math:`g_3` :math:`g_1`  :math:`g_2`  :math:`g_3`  :math:`E` :math:`g_1`    :math:`g_2`      :math:`g_1g_2`    :math:`g_3` :math:`g_1g_3`      :math:`g_2g_3`      :math:`g_1g_2g_3`
   ============== ============== ================ =========== ============ ============ ============ ========= ============== ================ ================= =========== =================== =================== ===================
   :math:`C_1`                                                                                       :math:`E`
   :math:`C_2`    :math:`C_2`                                 :kword:`xy`                            :math:`E` :math:`C_2`
   :math:`C_s`    :math:`\sigma`                              :kword:`x`                             :math:`E` :math:`\sigma`
   :math:`C_i`    :math:`i`                                   :kword:`xyz`                           :math:`E` :math:`i`
   :math:`C_{2v}` :math:`C_2`    :math:`\sigma_v`             :kword:`xy`  :kword:`y`                :math:`E` :math:`C_2`    :math:`\sigma_v` :math:`\sigma_v'`
   :math:`C_{2h}` :math:`C_2`    :math:`i`                    :kword:`xy`  :kword:`xyz`              :math:`E` :math:`C_2`    :math:`i`        :math:`\sigma_h`
   :math:`D_2`    :math:`C_2^z`  :math:`C_2^y`                :kword:`xy`  :kword:`xz`               :math:`E` :math:`C_2^z`  :math:`C_2^y`    :math:`C_2^x`
   :math:`D_{2h}` :math:`C_2^z`  :math:`C_2^y`    :math:`i`   :kword:`xy`  :kword:`xz`  :kword:`xyz` :math:`E` :math:`C_2^z`  :math:`C_2^y`    :math:`C_2^x`     :math:`i`   :math:`\sigma^{xy}` :math:`\sigma^{xz}` :math:`\sigma^{yz}`
   ============== ============== ================ =========== ============ ============ ============ ========= ============== ================ ================= =========== =================== =================== ===================

.. Note: contains a nbsp

To reduce the input, the unity operator :math:`E` is always assumed. The twofold
rotation about the z-axis, :math:`C_2(z)`, and the reflection in the xz-plane,
:math:`\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 :kword:`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
:numref:`block:TUT_C2v_output`. Note that :math:`\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 :math:`a_1`
irreducible representation has the :math:`z` basis function listed which is unchanged
by any of the symmetry operations.

.. index::
   single: Character table

.. code-block:: none
   :caption: Character Table for :math:`C_{2v}`
   :name: block:TUT_C2v_output

            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

.. Note: contains a nbsp

.. index::
   single: Gateway; Test
   single: Input; Comment lines
   single: Units
   single: Gateway; Geometry
   single: Gateway; Units
   single: Coordinates; Gateway input

The geometry of the molecule is defined using the keyword :kword:`coord`. On
the next line, the name of the xyz file that defines the geometrical
parameters of the molecule (:file:`water.xyz`) is given.

#. The first line of the :file:`water.xyz` file contains the number of atoms.
#. The second line is used to indicate the units: ångström or atomic units.
   The default is to use ångström.
#. Then follows one line for each atom containing the name of each atom and its coordinates.

Basis sets are defined after the keyword :kword:`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.

.. code-block:: none
   :caption: The geometry of the water molecule
   :name: block:coord

   3

   O           .000000        .000000        .000000
   H          0.700000        .000000       0.700000
   H         -0.700000        .000000       0.700000

.. index::
   single: Gateway; Output
   single: Gateway; Geometry

:program:`GATEWAY` Output
-------------------------

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.
Inertia and rigid-rotor analysis is also included in the output along with
the timing information.

.. There is a keyword,
   :kword:`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.

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`.

.. index::
   single: Gateway; BSSE

Basis Set Superposition Error (BSSE)
------------------------------------

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

  &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

Note, that :kword:`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.

:program:`GATEWAY` Basic and Most Common Keywords
-------------------------------------------------

.. class:: keywordlist

:kword:`Coord`
  File name or inline number of atoms and XYZ coordinates

:kword:`BASIs Set`
  Atom_label.Basis_label (for example ANO-L-VTZP)

:kword:`Group`
  Full (find maximum), NoSym, or symmetry generators

:kword:`SYMMetry`
  Symmetry generators: X, Y, Z, XY, XZ, YZ, XYZ (in native format)

:kword:`RICD`
  On-the-fly auxiliary basis sets.
