.. _UG\:sec\:false:

:program:`false`
================

.. only:: html

  .. contents::
     :local:
     :backlinks: none

.. xmldoc:: <MODULE NAME="FALSE">
            %%Description:
            <HELP>
            FALSE is an interface module that allows using external programs to
            compute energies and gradients for geometry optimizations with SLAPAF.
            </HELP>

:program:`FALSE` is an interface module that allows using external programs to
compute energies and gradients for geometry optimizations with
:program:`SLAPAF`. :program:`FALSE` creates a text file with the current
Cartesian coordinates, launches an external program (specified by the
:kword:`RUN` keyword), and then reads an output text file and stores the
information in the :file:`RUNFILE` for :program:`SLAPAF` to use. In a parallel
environment, only the master process executes the external program (which can
run on a different parallel environment).

Note that, even though the external program most likely does not use the
integrals produced by :program:`SEWARD`, :program:`SEWARD` will still need to
be run for every new geometry before :program:`FALSE` to update the
coordinates. It can, however, use a dummy basis set and/or the :kword:`ONEOnly`
keyword.

:program:`FALSE` can also be run in "add" mode, where the results from the
external program are added to the existing values, instead of replacing them
(see the :kword:`MODE` keyword). In this case, :program:`FALSE` should be
called after all desired energies and gradients have been calculated with some
other method.

.. _UG\:sec\:false_files:

Files
-----

.. class:: filelist

:file:`$Project.false.in`
  This file is generated by :program:`FALSE`, and contains
  the current Cartesian coordinates of the system.

:file:`$Project.false.out`
  This file should be generated by the external program,
  and contain the energy and possibly gradient and other properties.

.. _UG\:sec\:false_inp:

Input
-----

.. class:: keywordlist

:kword:`RUN`
  This is the only and compulsory keyword of the program.
  It specifies the executable to run the external program.
  The external program will be run as ``<program> <input> <output>``, where ``<program>``
  is the value of this keyword, and ``<input>`` and ``<output>`` are, respectively,
  :file:`$Project.false.in` and :file:`$Project.false.out`.

  .. xmldoc:: <KEYWORD MODULE="FALSE" NAME="RUN" APPEAR="External executable" KIND="STRING" INPUT="REQUIRED" LEVEL="BASIC">
              %%Keyword: RUN <basic>
              <HELP>
              Specify the external executable.
              It will be run as:

                program input output
              </HELP>
              </KEYWORD>

:kword:`MODE`
  Specifies whether the values computed by the external program will replace any
  pre-existing values (`REPLACE`, which is the default), or they will be added as
  a new contribution (`ADD`). If set to `ADD`, and the output from the external
  program contains values for a single root, the values will be added to all
  roots.

  .. xmldoc:: <KEYWORD MODULE="FALSE" NAME="MODE" APPEAR="Mode" KIND="CHOICE" LIST="REPLACE,ADD" DEFAULT_VALUE="REPLACE" LEVEL="BASIC">
              %%Keyword: MODE <basic>
              <HELP>
              Set to REPLACE (default) to use the bare external program results.
              Set to ADD to add the external program results as a contribution.
              </HELP>
              </KEYWORD>

.. _UG\:sec\:false_format:

Format
------

The format of the :file:`$Project.false.in` file is simply the header ``[XYZ]``
followed by the Cartesian coordinates in xyz format (number of atoms, comment
line, atomic symbols and coordinates in ångström). Example: ::

  [XYZ]
       3
  angstrom
   O      -0.000000000000      0.000000000000      1.585980150915
   H      -1.441800130217      0.000000000000     -1.265660575457
   H       1.441800130217      0.000000000000     -1.265660575457

The expected format for the :file:`$Project.false.out` has sections marked by
bracketed headers (case-insensitive), and all values are in atomic units.
Unknown sections are ignored.

* ``[ROOTS]`` is compulsory, followed by the number of roots for which energies
  and other properties will be given later. If :kword:`MODE` is `ADD`, it should
  match the number of roots already existing, or be `1` (in which case the
  external contribution will be added to all roots).

* ``[RELAX ROOT]`` is optional, followed by the index of the root that will
  be optimized. If not given, the highest root will be assumed. If given, it must
  appear before other properties.

* ``[ENERGIES]`` is compulsory, followed by the energies of the specified roots
  in free format.

* ``[GRADIENT]`` is optional, followed by a root index and the Cartesian gradient
  of that root, in the order :math:`x`, :math:`y`, :math:`z` components of first
  atom, :math:`x`, :math:`y`, :math:`z` of second atom, etc. Numbers are in free
  format. This section can appear several times for different roots. If not present
  for the root to be optimized, numerical gradients will be computed.

* ``[NAC]`` is optional, followed by two root indices and the Cartesian nonadiabatic
  coupling vector for those two roots, in the same order as the gradient. Numbers
  are in free format. This section can appear several times for different root pairs.

* ``[HESSIAN]`` is optional, followed by a root index and the lower triangle of the
  Cartesian Hessian of that root, in row order (same component order as the gradient).
  Numbers are in free format. This section can appear several times for different roots.

* ``[DIPOLES]`` is optional, followed by the dipole moments (:math:`x`, :math:`y`,
  :math:`z` components) of the specified roots. The numbers are in free format,
  but the dipole for each root must start on a new line.

Example: ::

  [ROOTS]
  1

  [ENERGIES]
  -0.00023387481687211915

  [GRADIENT]
  1
  0.0 0.0 1.305627486117155e-06
  4.46416708565692e-07 0.0 -6.528137430585775e-07
  -4.46416708565692e-07 0.0 -6.528137430585775e-07

.. xmldoc:: </MODULE>
