.. index::
   single: Program; FFPT
   single: FFPT

.. _UG\:sec\:ffpt:

:program:`ffpt`
===============

.. only:: html

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

.. xmldoc:: <MODULE NAME="FFPT">
            %%Description:
            <HELP>
            This program applies perturbations to the one-electron Hamiltonian and the nuclear repulsion term
            for finite field perturbation calculations. These fields can be and
            external electric field or due the quadrupole moment of one or several nuclei.
            Additional contributions can be first order relativistic integrals (Darwin 1-el. term and mass-velocity contributions), or
            the so-called Well-integrals used in some forms of reaction field calculations.
            </HELP>

The program
:program:`FFPT` prepares the one-electron integral file generated by
:program:`SEWARD` for subsequent finite-field perturbation
calculations. To do so, the core Hamiltonian matrix is always
reconstructed from the nuclear attraction and kinetic energy integrals.
The perturbation matrix is then added to the core
Hamiltonian matrix where the external perturbation and its strength is
specified by input. Any suitable combination of the perturbations
is allowed. Following some examples

#. **Dipole moment operator:**
   This option corresponds
   to a homogeneous external field perturbation and can be used to
   calculate dipole moments and dipole polarizabilities.

#. **Quadrupole and higher electric moment operators:**
   This option
   corresponds to a non homogeneous external field perturbation and can be
   used to calculate quadrupole moments and quadrupole
   polarizabilities, etc.

#. **Relativistic corrections:**
   This option is used to
   calculate perturbational relativistic corrections (sum of the mass-velocity
   and the one-electron Darwin contact term) to the total energy. Note that care
   must be taken to avoid variational collapse, i.e. the perturbation correction
   should be small.

For a complete list of one-electron integrals which can be
evaluated by the program :program:`SEWARD` check out
:numref:`UG:sec:seward_description` and, especially,
:numref:`UG:sec:one-electron_integral_labels`.

Note, the perturbation matrices consist of the electronic contributions,
only. The quadrupole, electric field gradient and higher electric moment
perturbation matrices are given as the traceless tensors.

.. _UG\:sec\:ffpt_dependencies:

Dependencies
------------

In order to complete successfully, the program :program:`FFPT` needs
the one-electron integral file. The latter must include all types
of integrals needed to construct the perturbed one-electron
Hamiltonian.

.. _UG\:sec\:ffpt_files:

Files
-----

Input files
...........

The program :program:`FFPT` needs :file:`ONEINT`
(for more information see :numref:`UG:sec:files_list`).

Output files
............

The program :program:`FFPT` creates/updates file :file:`ONEINT` on output:

.. _UG\:sec\:ffpt_input:

Input
-----

The input to the :program:`FFPT` program begins with the program name: ::

  &FFPT

General keywords
................

The following keywords are known to the
:program:`FFPT` utility:

.. class:: keywordlist

:kword:`TITLe`
  Followed by a title line

  .. xmldoc:: <KEYWORD MODULE="FFPT" NAME="TITLE" APPEAR="Title (optional)" KIND="STRING" LEVEL="BASIC">
              <HELP>
              Enter title line
              </HELP>
              %%Keyword: TITLe <basic>
              Followed by a title line
              </KEYWORD>

  .. xmldoc:: <GROUP MODULE="FFPT" NAME="XFIELD" APPEAR="External Electric Field options" KIND="BOX" LEVEL="BASIC">

:kword:`DIPO`
  Add the dipole moment perturbation operator. By default, the dipole moment
  integrals are always computed with respect to the center of nuclear
  charge. The keyword is followed by up to three additional input
  lines. Each line consists of two entries, the component
  of the dipole operator and the perturbation length. The component is
  specified by a single letter (X, Y or Z).

  .. xmldoc:: <KEYWORD MODULE="FFPT" NAME="DIPO" APPEAR="External Electric Field" KIND="CUSTOM" LEVEL="BASIC">
              <HELP>
              Add the external electric field. Each line contain the letters X, Y, or Z to indicate
              the component of the electric field followed by a real number to specify the strength.
              </HELP>
              %%Keyword: DIPO <basic>
              %%Values: i w
              %%Range: (X,Y,Z) (-1.,1.)
              Add the dipole moment perturbation operator. By default, the dipole moment
              integrals are always computed with respect to the center of nuclear
              charge. The keyword is followed by up to three additional input
              lines. Each line consists of two entries, the component
              of the dipole operator and the perturbation length. The component is
              specified by a single letter (X, Y or Z).
              </KEYWORD>

:kword:`QUAD`
  Add the quadrupole moment perturbation operator.
  The keyword is followed by at least one additional
  input line and may be complemented by as many additional lines as
  needed. Each line consists of two entries, the component
  of the operator and the perturbation strength. The component is
  specified by a pair of letters (XX, XY, XZ, YY, YZ or ZZ).
  By default, the quadrupole moment integrals are calculated with
  respect to the center of mass. For any other selection
  the origin of the perturbation operator also needs to be specified
  by entering a line starting with the string ORIG followed by the coordinates.

  .. xmldoc:: <KEYWORD MODULE="FFPT" NAME="QUAD" APPEAR="External Electric Field Gradient" KIND="CUSTOM" LEVEL="BASIC">
              <HELP>
              Add the external electric field gradient. Each line contains the letters XX, XY, XZ, YY, YZ, or ZZ to indicate
              the component of the electric field gradient followed by a real number to indicate the value.
              </HELP>
              %%Keyword: QUAD <basic>
              %%Values: i [w,x] [y] [z]
              %%Range: (XX,XY,XZ,YY,YZ,ZZ,ORIG)
              Add the quadrupole moment perturbation operator.
              The keyword is followed by at least one additional
              input line and may be complemented by as many additional lines as
              needed. Each line consists of two entries, the component
              of the operator and the perturbation strength. The component is
              specified by a pair of letters (XX, XY, XZ, YY, YZ or ZZ).
              By default, the quadrupole moment integrals are calculated with
              respect to the center of mass. For any other selection
              the origin of the perturbation operator also needs to be specified
              by entering a line starting with the string ORIG followed by the coordinates.
              </KEYWORD>

:kword:`OCTU`
  Add the octupole moment perturbation operator.
  The keyword is followed by at least one additional
  input line and may be complemented by as many additional lines as
  needed. Each line consists of two entries, the component
  of the operator and the perturbation strength. The component is
  specified by a triple of letters (XXX, XXY, XXZ, XYY, XYZ, XZZ, YYY, YYZ, YZZ, or ZZZ).
  By default, the octupole moment integrals are calculated with
  respect to the center of mass. For any other selection
  the origin of the perturbation operator also needs to be specified
  by entering a line starting with the string ORIG followed by the coordinates.

  .. xmldoc:: <KEYWORD MODULE="FFPT" NAME="OCTU" APPEAR="External Electric Field Hessian" KIND="CUSTOM" LEVEL="BASIC">
              <HELP>
              Add the external electric field Hessian. Each line contains the letters XXX, XXY, XXZ, XYY, XYZ, XZZ, YYY, YYZ, YZZ, or ZZZ to indicate
              the component of the electric field Hessian followed by a real number to indicate the value.
              </HELP>
              %%Keyword: OCTU <basic>
              %%Values: i [w,x] [y] [z]
              %%Range: (XXX,XXY,XXZ,XYY,XYZ,XZZ,YYY,YYZ,YZZ,ZZZ,ORIG)
              Add the octupole moment perturbation operator.
              The keyword is followed by at least one additional
              input line and may be complemented by as many additional lines as
              needed. Each line consists of two entries, the component
              of the operator and the perturbation strength. The component is
              specified by a triple of letters (XXX, XXY, XXZ, XYY, XYZ, XZZ, YYY, YYZ, YZZ, or ZZZ).
              By default, the octupole moment integrals are calculated with
              respect to the center of mass. For any other selection
              the origin of the perturbation operator also needs to be specified
              by entering a line starting with the string ORIG followed by the coordinates.
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`EFLD`
  Add the electric field perturbation operator.
  The keyword is followed by at least two additional
  input lines and may be complemented by as many additional lines as
  needed. Each line consists of two entries, the component
  of the operator and the perturbation strength. The component is
  specified by a single letter (X, Y or Z).
  In addition, the origin of the perturbation operator also needs to be specified
  by entering a line starting with the string ORIG followed by the coordinates.

  .. xmldoc:: <GROUP MODULE="FFPT" NAME="NFIELD" APPEAR="Nuclear charge fields" KIND="BOX" LEVEL="BASIC">

  .. xmldoc:: <KEYWORD MODULE="FFPT" NAME="EFLD" APPEAR="Nuclear dipole moment" KIND="CUSTOM" LEVEL="BASIC">
              <HELP>
              Add contributions due to an nuclear dipole moment. Each line contains the letters X, Y, or Z to indicate
              component of the nuclear dipole moment followed by a real number to indicate the value. Finally a line is added with the
              syntax "ORIG x y z" is used to specify the position of the center considered.
              </HELP>
              %%Keyword: EFLD <basic>
              %%Values: i [w,x] [y] [z]
              %%Range: (X,Y,Z,ORIG)
              Add the electric field perturbation operator.
              The keyword is followed by at least two additional
              input lines and may be complemented by as many additional lines as
              needed. Each line consists of two entries, the component
              of the operator and the perturbation strength. The component is
              specified by a single letter (X, Y or Z).
              In addition, the origin of the perturbation operator also needs to be specified
              by entering a line starting with the string ORIG followed by the coordinates.
              </KEYWORD>

:kword:`EFGR`
  Add the electric field gradient perturbation operator.
  The keyword is followed by at least one additional
  input line and may be complemented by as many additional lines as
  needed. Each line consists of two entries, the component
  of the operator and the perturbation strength. The component is
  specified by a pair of letters (XX, XY, XZ, YY, YZ or ZZ).
  In addition, the origin of the perturbation operator also needs to be specified
  by entering a line starting with the string ORIG followed by the coordinates.

  .. xmldoc:: <KEYWORD MODULE="FFPT" NAME="EFGR" APPEAR="Nuclear quadrupole moment" KIND="CUSTOM" LEVEL="BASIC">
              <HELP>
              Add contributions due to an nuclear quadrupole moment. Each line contains the letters XX, XY, XZ, YY, YZ, or ZZ to indicate
              component of the nuclear quadrupole moment followed by a real number to indicate the value. Finally a line is added with the
              syntax "ORIG x y z" is used to specify the position of the center considered.
              </HELP>
              %%Keyword: EFGR <basic>
              %%Values: i [w,x] [y] [z]
              %%Range: (XX,XY,XZ,YY,YZ,ZZ,ORIG)
              Add the electric field gradient perturbation operator.
              The keyword is followed by at least one additional
              input line and may be complemented by as many additional lines as
              needed. Each line consists of two entries, the component
              of the operator and the perturbation strength. The component is
              specified by a pair of letters (XX, XY, XZ, YY, YZ or ZZ).
              In addition, the origin of the perturbation operator also needs to be specified
              by entering a line starting with the string ORIG followed by the coordinates.
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`RELA`
  Add the relativistic correction (mass-velocity and one-electron
  Darwin contact term). The command is followed by one additional line
  of input specifying the perturbation strength.

  .. xmldoc:: <GROUP MODULE="FFPT" NAME="MFIELD" APPEAR="Miscellaneous Perturbations" KIND="BOX" LEVEL="BASIC">

  .. xmldoc:: <KEYWORD MODULE="FFPT" NAME="RELA" APPEAR="Relativistic additions" KIND="REAL" LEVEL="BASIC">
              <HELP>
              Specify the perturbation strength of the relativistic correction (mass-velocity and one-electron
              Darwin contact term).
              </HELP>
              %%Keyword: RELA <basic>
              %%Values: w
              %%Range: (0,1)
              Add the relativistic correction (mass-velocity and one-electron
              Darwin contact term). The command is followed by one additional line
              of input specifying the perturbation strength.
              </KEYWORD>

:kword:`GLBL`
  This command marks the beginning of a more general perturbation
  description which is not included as a subcommand of the
  :kword:`FFPT` command.
  This card is followed by as many additional input lines as needed and
  is terminated if the next input line starts with a command. Each input
  line contains only one perturbation description and three data fields
  which are: Label, component and perturbation strength. The label
  consists of a character string of length 8 and names the one-electron
  integrals produced by :program:`SEWARD`. The component of
  an operator is given as an integer. The last parameter denotes
  the strength of a perturbation operator and is given as a real number.
  For a list of the available one-electron integral labels refer to
  :numref:`UG:sec:seward`.

  For example to add Pauli repulsion integrals for
  reaction field calculations the input would look like: ::

    &FFPT
    GLBL
    'Well   1' 1 1.000
    'Well   2' 1 1.000
    'Well   3' 1 1.000

  .. xmldoc:: <KEYWORD MODULE="FFPT" NAME="GLBL" APPEAR="Well-integrals" KIND="CUSTOM" LEVEL="BASIC">
              <HELP>
              Add so-called well-integrals to the one-electron Hamiltonian. Syntax " 'Well   n' 1 x " where
              n is specifying the index of the well-integrals as computed by Seward and x is the coefficient
              used when the term is added (normally the value should be 1.0).
              </HELP>
              %%Keyword: GLBL <advanced>
              This command marks the beginning of a more general perturbation
              description which is not included as a predefined command.
              This card is followed by as many additional input lines as needed and
              is terminated if the next input line starts with a command. Each input
              line contains only one perturbation description and three data fields
              which are: Label, component and perturbation strength. The label
              consists of a character string of length 8 and names the one-electron
              integrals produced by SEWARD. The last parameter denotes the strength
              of a perturbation operator and is given as a real number. For a list
              of the available one-electron integral labels refer to the program
              description of SEWARD.

              example:
                &FFPT
                GLBL
                'Well   1' 1 1.000
                'Well   2' 1 1.000
                'Well   3' 1 1.000
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`SELEctive`
  .. compound::

    With the same localization scheme as used in :program:`LOPROP`, the perturbation
    from :program:`FFPT` is localized in an orthogonal basis. Then the user can
    specify on which basis functions the perturbation should act.
    For example, the input ::

      &FFPT
      DIPO
      X 0.005
      SELECTIVE
      2
      .true. 1 26
      .false. 67 82
      .true.
      0.5

    leads to that the perturbation only acts on densities with (1) both basis
    function indexes in the set :math:`\{1,\ldots,26\}` or (2) one index
    in the set :math:`\{1,\ldots,26\}` while the other is in the set
    :math:`\{67,\ldots,82\}`, and in this case the perturbation should be multiplied
    by 0.5.; all other densities are unaffected by the perturbation.
    We call the former type of subset an atom domain and the latter a bond
    domain. Generally, the input structure is this: First line specifies how
    many subsets, :math:`N`, that will be defined. Then follow :math:`N` lines starting
    with a logical flag telling if the subset is an atom domain with the starting
    and ending basis function indexes thereafter. :math:`N-1` lines follow where the
    bond domain is defined in the following way: ::

      Do i=2,nSets
        Read(*,*)(Bonds(i,j),j=1,i-1)
      Enddo

  Finally a scalar is given which scales the defined bond domains.

  The LoProp-functions will almost coincide with the
  original input AO-basis, although the localization will modify the meaning
  slightly, hence it is not possible to exactly localize the perturbation to
  a group of atoms; :program:`LOPROP` is a way to come close to perfect
  localization. :program:`FFPT` calls :program:`LOPROP` internally and no call to
  :program:`LOPROP` has to specified by the user.

  .. xmldoc:: <KEYWORD MODULE="FFPT" NAME="SELE" APPEAR="Selective perturbation" KIND="CUSTOM" LEVEL="ADVANCED">
              %%Keyword: SELE <advanced>
              <HELP>
              Specify on which basis functions the perturbation should act.
              </HELP>
              </KEYWORD>

:kword:`CUMUlative`
  Adds the perturbation to the current H0, enabling many consecutive
  FFPT calls. Without this keyword, the perturbation always starts from
  the unperturbed H0.

  .. xmldoc:: <GROUP MODULE="FFPT" NAME="AFIELD" APPEAR="Additional options" KIND="BOX" LEVEL="BASIC">

  .. xmldoc:: <KEYWORD MODULE="FFPT" NAME="CUMU" APPEAR="Cumulative (optional)" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: CUMU <advanced>
              <HELP>
              Adds the perturbation to the current H0, enabling many consecutive
              FFPT calls. Without this keyword, the perturbation always starts from
              the unperturbed H0.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

Input example
-------------

The following input will prepare the one-electron integral file generated by
:program:`SEWARD` for subsequent finite-field perturbation calculations by adding
a linear electric field in z-direction. ::

  &FFPT
  DIPO
  Z 0.001

Response properties are obtained by numerical differentiation of the total energy
with respect to the field parameter. For definitions of the response properties
the interested reader is referred to the paper of A.D. Buckingham :cite:`Buckingham:67`.
According to the definition of the dipole
moment, it is obtained as the first derivative of the energy with
respect to the field strength. Similarly, the dipole polarizability is given
by the second derivative of the energy with respect to the field strength.

.. xmldoc:: </MODULE>