.. index::
   single: Program; MOTRA
   single: MOTRA

.. _UG\:sec\:motra:

:program:`motra`
================

.. only:: html

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

.. xmldoc:: <MODULE NAME="MOTRA">
            %%Description:
            <HELP>
            This program transforms one- and two-electron integrals from AO
            basis to MO basis. The integrals that are transformed are the
            one-electron Hamiltonian and the two-electron repulsion integrals.
            </HELP>

The program
:program:`MOTRA` is used to transform one- and two-electron
integrals from AO to MO basis. It reads the
one-electron file and the file of ordered
and symmetry blocked two-electron integrals generated by
:program:`SEWARD`.

The two-electron integral transformation is performed
one symmetry block at a time, as a series of four
sequential one-index transformations. The process
includes a sorting of the half transformed integrals
prior to the second half transformation. This step is
performed in core if there is space enough of memory
available to keep one symmetry block of integrals.
Otherwise the half transformed integrals are written
out on an temporary file. The result of the transformation
is two files, :file:`TRAONE` and :file:`TRAINT` which
contain the transformed one- and two-electron integrals, respectively.

The one-electron transformation is performed for the
kinetic integrals and the bare nuclei Hamiltonian. If there
are frozen orbitals :program:`MOTRA` replaces the bare nuclei
Hamiltonian by an effective Fock operator, which incorporates
the interaction between the frozen (core) electrons and the
remaining electrons. In practice this means that in any
subsequent calculation (for example :program:`MRCI`,
:program:`CPF` or :program:`MBPT`) the effect of the frozen
orbitals is incorporated into the one-electron Hamiltonian,
and these orbitals need not be explicitly accounted for. The
total energy of the frozen electrons is added to the
nuclear--nuclear repulsion energy and transferred from
:program:`MOTRA` to the subsequent program(s).

The two-electron transformation is performed from the list of ordered
integrals generated by
:program:`SEWARD` (file :file:`ORDINT`).

.. _UG\:sec\:motra_dependencies:

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

To run the program :program:`MOTRA` successfully the one-
and two-electron integrals are needed. In addition, a
set of MO coefficients must be available. The latter may
be obtained by any wave function optimization program.

.. _UG\:sec\:motra_files:

Files
-----

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

The following is a list of input files

.. class:: filelist

:file:`ONEINT`
  One-electron integral file generated by :program:`SEWARD`.

:file:`ORDINT*`
  Ordered two-electron integrals generated by :program:`SEWARD`.

:file:`INPORB`
  If MO's are read in formatted form.

:file:`JOBIPH`
  If molecular orbitals are read from a :program:`RASSCF` interface.

In general, input orbitals are supplied in the form of
a formatted ASCII file, but can also be taken directly from
the binary interface file, :file:`JOBIPH`, created by the
:program:`RASSCF` program. The selection in controlled by
input options.

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

The program :program:`MOTRA`
creates two files: The first carries all basic information
and a list of transformed one-electron integrals. The second
file includes the transformed two-electron integrals.

The following is a list of output files

.. class:: filelist

:file:`TRAONE`
  Auxiliary data and transformed one-electron integrals.

:file:`TRAINT*`
  Transformed two-electron integrals.

.. Intermediate files
   ..................

   :program:`MOTRA` generates one intermediate file with half
   transformed one-electron integrals,
   :file:`LUHALF`. It is scratched at the end of the run.
   This file can be large in calculations with extended basis sets.
   It is used to store one symmetry block of integrals at a time.

   The following is a list of local files

   .. class:: filelist

   :file:`LUHALF*`
     Auxiliary data and transformed one-electron integrals.

.. _UG\:sec\:motra_input:

Input
-----

This section describes the input to the :program:`MOTRA` program in the |molcas| program system.
The input for each module is preceded by its name like: ::

  &MOTRA

Compulsory keywords
...................

The following keywords are compulsory.

.. class:: keywordlist

:kword:`LUMOrb`
  Specifies that the molecular orbitals are read from a formatted file
  produced by one of the wave function generating programs.
  **Note** that either of :kword:`Lumorb` or :kword:`Jobiph` should be
  specified. LUMORB is the default keyword.
  No additional input is required.

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="LUMORB" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: LUMOrb <basic>
              <HELP>
              Specifies that the molecular orbitals are read from a formatted file
              produced by one of the wave function generating programs (default).
              </HELP>
              No additional input is required.
              NOTE: Either of keywords LUMORB or JOBIPH should be specified
              LUMORB is the default option.
              </KEYWORD>

:kword:`JOBIph`
  Specifies that the molecular orbitals are read from a :program:`RASSCF` job
  interface file. :program:`MOTRA` will in this case read the average orbitals.
  No additional input is required.

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="JOBIPH" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: JOBIph <basic>
              <HELP>
              Specifies that the molecular orbitals are read from the job
              interface file, called JOBIPH, produced by the RASSCF program.
              MOTRA will in this case read the average orbitals.
              </HELP>
              </KEYWORD>

When natural orbitals from a RASSCF (or a state averaged CASSCF)
calculation are to be used in
:program:`MOTRA`, they can be produced, or extracted from an existing
:file:`JOBIPH` file, by :program:`RASSCF`, using keyword :kword:`OUTOrbitals`.

Optional keywords
.................

There are a few useful optional keywords that can be specified.
The following is a list

.. class:: keywordlist

:kword:`AUTO`
  This keyword specified automatic deletion of orbitals based on
  occupation numbers. The following line contain one
  threshold per symmetry, and all orbitals with occupation
  numbers smaller that the threshold will be deleted.
  If :kword:`AUTO` and :kword:`DELEte` are both specified,
  the larger number will be used.

  .. xmldoc:: %%Keyword: AUTO <basic>
              This keyword specified automatic deletion of orbitals based on
              occupation numbers. The following line contain one
              threshold per symmetry, and all orbitals with occupation
              numbers smaller that the threshold will be deleted.
              NOTE: If the keywords AUTO and DELEte are both specified,
              the larger number will be used.

:kword:`DELEted`
  Specifies the number of virtual orbitals that are not to be used as
  correlating orbitals in the subsequent CI calculation. The last
  orbitals in each symmetry are deleted. The default is no deleted
  orbitals.
  One additional line with the number of deleted orbitals in each
  symmetry (free format).

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="DELETE" APPEAR="delete orbitals" LEVEL="BASIC" KIND="INTS_LOOKUP" SIZE="NSYM">
              %%Keyword: DELEted <basic>
              <HELP>
              Specifies the number of virtual orbitals that are not to be used as
              correlating orbitals in subsequent correlation calculation(s). The
              default is no deleted orbitals.
              </HELP>
              The keyword requires one additional line of input with the number
              of deleted orbitals in each symmetry.
              NOTE: The deleted orbitals are the last orbitals in each symmetry block.
              </KEYWORD>

:kword:`FROZen`
  Specifies the number of doubly occupied orbitals that are left
  uncorrelated in subsequent correlation calculation(s). Additional orbitals can
  be frozen in these programs, but from an efficiency point of view it
  is preferable to freeze orbitals in the transformation.
  One additional line with the number of frozen
  orbitals in each symmetry (free format). For more details on freezing
  orbitals in :program:`MOTRA` see the program description. The frozen
  orbitals are the first in each symmetry block.
  Default is to freeze the core (but not semi-core) orbitals.

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="FROZEN" APPEAR="frozen orbitals" LEVEL="BASIC" KIND="INTS_LOOKUP" SIZE="NSYM">
              %%Keyword: FROZen <basic>
              <HELP>
              Specifies the number of doubly occupied orbitals that are left
              uncorrelated in subsequent correlation calculation(s).
              </HELP>
              The keyword requires one additional line of input with the number
              of frozen orbitals in each symmetry (free format).
              NOTE: The frozen orbitals are the first in each symmetry block.
              Default is to freeze the core (but not semi-core) orbitals.
              </KEYWORD>

:kword:`ONEL`
  Specifies that only one-electron integrals are to be transformed.
  No additional input is required.

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="ONEL" APPEAR="one-el transf." LEVEL="BASIC" KIND="SINGLE">
              %%Keyword: ONEL <basic>
              <HELP>
              Specifies that only one-electron integrals are to be transformed.
              </HELP>
              No additional input is required.
              </KEYWORD>

:kword:`PRINt`
  Specifies the print level in the program. The default (1) does not
  print the orbitals that are used in the transformation, but they
  appear at print level 2. Beware of large print levels since vast amounts
  of output may be produced. The value is read from the line after the
  keyword, in free format.

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="PRINT" APPEAR="print level" LEVEL="ADVANCED" KIND="INT">
              %%Keyword: PRINt <basic>
              <HELP>
              Specifies the print level in the program. The default (1) does not
              print the orbitals that are used in the transformation, but they
              appear at print level 2.
              </HELP>
              Beware of large print levels since vast amounts
              of output may be produced. The value is read from the line after the
              keyword, in free format.
              </KEYWORD>

:kword:`RFPErt`
  Add a constant reaction field perturbation to the bare nuclei Hamiltonian.
  The perturbation is read from the file :file:`RUNOLD` (if not present defaults to :file:`RUNFILE`) and
  is the latest self consistent perturbation generated
  by one of the programs :program:`SCF` or :program:`RASSCF`.

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="RFPERT" APPEAR="reaction field" LEVEL="ADVANCED" KIND="SINGLE">
              %%Keyword: RFPErt <basic>
              <HELP>
              Add a constant reaction field perturbation to the bare nuclei Hamiltonian.
              The perturbation is read from the file RUNOLD (if not present defaults to RUNFILE) and
              is the latest self consistent perturbation generated
              by one of the programs SCF or RASSCF.
              </HELP>
              </KEYWORD>

:kword:`CTONly`
  Specifies that Cholesky vectors are to be transformed without subsequent calculation of the two-el integrals.
  It requires as input one of the two following strings: "pqK" or "Kpq", which indicate the storage format as
  L(pq,K) or L(K,pq), respectively. The former is the default option. Transformed vectors are stored in the files :file:`_CHMOT`,
  one for each compound symmetry.
  Available only in combination with Cholesky or RI integral representation.

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="CTON" APPEAR="Cholesky vectors transf." LEVEL="BASIC" KIND="STRING">
              %%Keyword: CTON <basic>
              <HELP>
              Specifies that Cholesky vectors are to be transformed without subsequent calculation of the two-el integrals.
              It requires as input one of the two following strings: "pqK" or "Kpq", which indicate the storage format as
              L(pq,K) or L(K,pq), respectively. The former is the default option. Transformed vectors are stored in the files _CHMOT,
              one for each compound symmetry.
              Available only in combination with Cholesky or RI integral representation.
              </HELP>
              </KEYWORD>

:kword:`DIAGonal integrals`
  Activates the evaluation of the diagonal integrals in MO basis. Requires the keyword CTONly.
  The file :file:`DIAGINT` is generated which contains these integrals.

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="DIAG" KIND="STRING" LEVEL="BASIC">
              %%Keyword: DIAG <basic>
              <HELP>
              Activates the evaluation of the diagonal integrals in MO basis. Requires the keyword CTONly.
              The file DIAGINT is generated which contains these integrals.
              </HELP>
              </KEYWORD>

:kword:`NOORtho`
  Skips the orthogonalization of the molecular orbitals. This should only be used when preparing the
  two-electron integrals for a non-orthogonal configuration interaction calculation.

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="NOOR" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: NOOR <basic>
              <HELP>
              Skips the orthogonalization of the molecular orbitals. This should only be used when preparing
              the two-electron integrals for a non-orthogonal configuration interaction calculation.
              </HELP>
              </KEYWORD>

:kword:`TITLe`
  This keyword should be followed by exactly one title line.

  .. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="TITLE" KIND="STRING" LEVEL="BASIC">
              %%Keyword: Title <basic>
              <HELP>
              Print a title line
              </HELP>
              This keyword should be followed by exactly one title line.
              </KEYWORD>

Input example
.............

::

  &MOTRA
  Title  =  Water molecule.
  * Don't correlate 1s on oxygen
  Frozen =  1 0 0 0
  Lumorb

.. xmldoc:: <KEYWORD MODULE="MOTRA" NAME="HDF5" KIND="SINGLE" LEVEL="UNDOCUMENTED" />

.. xmldoc:: </MODULE>