.. index::
   single: Program; MRCI
   single: MRCI

.. _UG\:sec\:mrci:

:program:`MRCI`
===============

.. only:: html

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

.. xmldoc:: <MODULE NAME="MRCI">
            %%Description:
            <HELP>
            The MRCI program is used for Multi-Reference
            SDCI or ACPF calculations. The code originates in an MRCI
            program by M. Blomberg and P. E. M. Siegbahn, later rewritten
            extensively. It requires a file generated by the GUGA program.
            </HELP>

.. index::
   single: Multireference; SDCI
   single: Multireference; ACPF

The
:program:`MRCI`
program generates Multi Reference :index:`SDCI <single: SDCI; using MRCI>` or :index:`ACPF <single: ACPF; using MRCI>` :cite:`Gdanitz:88`
wavefunctions. ACPF is a modification of the CPF :cite:`Ahlrichs:85`
method which allows more than one reference configuration. The program is
based on the :index:`Direct CI` method :cite:`Roos:72`,
and with the :index:`coupling coefficients <single: Coupling coefficients; MRCI>` generated with the Graphical Unitary Group
Approach :cite:`Shavitt:77,Shavitt:78,Siegbahn:80`.
(See program description for
:program:`GUGA`).
If requested, :program:`MRCI` computes matrix elements of those
one-electron properties for which it can find integrals in the
:file:`ONEINT` file. It also
generates natural orbitals that can be fed into
the property program to evaluate certain one electron properties.
The natural orbitals are also useful for Iterated Natural Orbital
(:index:`INO`) calculations.

The :program:`MRCI` code is a modification of an MRCI
program written by M. Blomberg and P. E. M. Siegbahn (Institute of Physics,
Stockholm University, Sweden), which has later been extensively modified
(P.-Å. Malmqvist)

The program can calculate several eigenvectors simultaneously, not
necessarily those with lowest eigenvalue. However, in the ACPF case,
only one single eigenvector is possible.

Orbital subspaces

The orbital space is divided into the following subspaces: Frozen,
Inactive, Active, Secondary, and Deleted orbitals. Within each
symmetry type, they follow this order.

* **Frozen:**
  :index:`Frozen orbitals <single: MRCI; Frozen>` are always doubly
  occupied, i.e., they are not correlated. Orbitals may be frozen
  already in the integral integral transformation step, program
  :program:`MOTRA`, but can also be specified in the input to the
  :program:`MRCI` program. The former method is more efficient,
  and has the effect that the frozen orbitals are effectively removed
  from the subsequent
  :program:`MRCI` calculation.

* **Inactive:**
  :index:`Inactive orbitals <single: MRCI; Inactive>` are doubly occupied
  in all reference configurations, but excitations out of this orbital
  space are allowed in the final CI wavefunction, i.e., they are
  correlated but have two electrons in all reference configurations.
  Restrictions may be applied to excitation from some inactive orbitals,
  see keyword :index:`NoCorr <single: MRCI; NoCorr>` in the :program:`GUGA` input section.

* **Active:**
  :index:`Active orbitals <single: MRCI; Active>` are those which may have
  different occupation in different reference configurations.
  Restrictions may be applied to occupation of some active orbitals,
  see keyword :index:`OneOcc <single: MRCI; OneOcc>` in the :program:`GUGA` input section.

* **Secondary:**
  :index:`This subspace <single: MRCI; Secondary>` is empty in all
  reference configurations, but may be populated with up to two
  electrons in the excited configurations. This subspace is not
  explicitly specified, but consists of the orbitals which are left over
  when other spaces are accounted for.

* **Deleted:**
  :index:`This orbital subspace <single: MRCI; Deleted>` does not
  participate in the CI wavefunction at all. Typically the 3s,4p,...
  components of 3d,4f,..., or orbitals that essentially describe core
  correlation, are deleted. Similar to freezing, deleting can be done in
  :program:`MOTRA`,
  which is more efficient, but also as input
  specifications to the
  :program:`MRCI` program.

Since ordinarily the frozen and deleted orbitals were handled by
:program:`MOTRA`
and the subdivision into inactive and
active orbitals were defined in
:program:`GUGA`, the only
time one has to specify orbital spaces in the input to
:program:`MRCI`
is when additional frozen or deleted orbitals are required without
recomputing the transformed integrals.

.. index::
   pair: Dependencies; MRCI

.. _UG\:sec\:mrci_dependencies:

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

The program needs the coupling
coefficients generated by the program
:program:`GUGA` and transformed one- and two-electron integrals
generated by the program
:program:`MOTRA`.

.. index::
   pair: Files; MRCI

.. _UG\:sec\:mrci_files:

Files
-----

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

.. class:: filelist

:file:`CIGUGA`
  Coupling coefficients from :program:`GUGA`.

:file:`TRAINT*`
  Transformed two-electron integrals from :program:`MOTRA`.

:file:`TRAONE`
  Transformed one-electron integrals from :program:`MOTRA`.

:file:`ONEINT`
  One-electron property integrals from :program:`SEWARD`.

:file:`MRCIVECT`
  Used for input only in restart case.

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

.. class:: filelist

:file:`CIORBnn`
  One or more sets of natural orbitals, one for each CI root, where
  nn stands for 01, 02, etc.

:file:`MRCIVECT`
  CI vector, for later restart.

Note that these file names are the FORTRAN file names used by the program,
so they have to be mapped to the actual file names. This is usually done
automatically in the |molcas| system. However, in the case of several
different numbered files
:file:`CIORBnn` only the first will be defined as default,
with the FORTRAN file name
:file:`CIORB`
used for
:file:`CIORB01`.

.. Local files
   ...........

   .. class:: filelist

   :file:`FTxxF001`
     MRCI produces a few scratch files that are not needed by any other program
     in |molcas|. Presently, these are xx=14, 15, 16, 21, 23, 25, 26, 27, and 30.
     The files are opened, used, closed and removed automatically.
     See source code for further information.

.. index::
   pair: Input; MRCI

.. UG\:sec\:mrci_input:

Input
-----

This section describes the input to the
:program:`MRCI` program in the |molcas| program system, with
the program name: ::

  &MRCI

.. index::
   pair: Keywords; MRCI

Keywords
........

.. class:: keywordlist

:kword:`TITLe`
  The line following this keyword is treated as title line

  .. xmldoc:: <KEYWORD MODULE="MRCI" NAME="TITLE" KIND="STRING" LEVEL="BASIC">
              %%Keyword: Title <basic>
              <HELP>
              Followed by a title line
              </HELP>
              </KEYWORD>

:kword:`SDCI`
  This keyword is used to perform an ordinary Multi-Reference
  Singles and Doubles CI, MR-SDCI, calculation. This is the default
  assumption of the program.
  Note that SDCI and ACPF are mutually exclusive.

  .. xmldoc:: <SELECT MODULE="MRCI" NAME="COMPMOD" APPEAR="Computation Model" CONTAINS="SDCI,ACPF" LEVEL="BASIC">
              <HELP>
              Choose one of the available quantum chemistry computational models.
              </HELP>

  .. xmldoc:: <KEYWORD MODULE="MRCI" NAME="SDCI" APPEAR="MR-SDCI" KIND="SINGLE" EXCLUSIVE="ACPF" LEVEL="BASIC">
              <HELP>
              Choose MR-SDCI calculation.
              </HELP>
              %%Keyword: SDCI <basic>
              Make an MR-SDCI calculation. (This is presently the default anyway).
              Keywords ACPF and SDCI are mutually exclusive.
              </KEYWORD>

:kword:`ACPF`
  This keyword tells the program to use the Average Coupled Pair
  Functional, ACPF, when computing the energy and natural orbitals.
  Note that SDCI and ACPF are mutually exclusive.

  .. xmldoc:: <KEYWORD MODULE="MRCI" NAME="ACPF" APPEAR="MR-ACPF" KIND="SINGLE" EXCLUSIVE="SDCI" LEVEL="BASIC">
              <HELP>
              Choose MR-ACPF calculation (Gdanitz, see manual).
              </HELP>
              %%Keyword: ACPF <basic>
              Make an MR-ACPF calculation, rather than an SDCI.
              Keywords ACPF and SDCI are mutually exclusive.
              </KEYWORD>

  .. xmldoc:: </SELECT>

:kword:`GVALue`
  The coefficient g which is used in the ACPF functional. The default
  value is = 2.0/(Nr of correlated electrons).

  .. xmldoc:: <KEYWORD MODULE="MRCI" NAME="GVALUE" APPEAR="g Value" KIND="REAL" LEVEL="BASIC">
              <HELP>
              Enter user-defined coefficient g, altering the ACPF functional.
              </HELP>
              %%Keyword: GValue <advanced>
              The coefficient g, altering the ACPF functional.
              </KEYWORD>

:kword:`NRROots`
  Specifies the number of CI roots (states) to be simultaneously
  optimized. The default is 1.

  .. xmldoc:: <KEYWORD MODULE="MRCI" NAME="NRROOTS" APPEAR="Number of states to compute." KIND="INT" LEVEL="BASIC">
              %%Keyword: NRRoots <basic>
              <HELP>
              The number of CI roots (states) to be computed. Default=1.
              </HELP>
              </KEYWORD>

:kword:`ROOTs`
  Specifies which root(s) to converge to. These are defined as the
  ordinal number of that eigenvector of the reference CI which is
  used as start approximation. The default is the sequence 1,2,3,...
  The values are entered on the next line(s). If the number of roots is
  larger than 1, it must first have been entered using keyword NRROOTS.
  The keywords ROOTS and SELECT are mutually exclusive.

  .. xmldoc:: <GROUP MODULE="MRCI" NAME="HOWCHOOSE" APPEAR="How choose roots?" KIND="RADIO">
              <HELP>
              Two ways to choose which states to compute.
              </HELP>

  .. xmldoc:: <KEYWORD MODULE="MRCI" NAME="ROOTS" APPEAR="Choose roots number" KIND="INTS" SIZE="10" LEVEL="BASIC">
              %%Keyword: Roots <basic>
              <HELP>
              Which roots to compute, as a list of numbers.
              </HELP>
              (counted in order of reference CI).
              Keywords ROOTS and SELECT are mutually exclusive.
              </KEYWORD>

:kword:`SELEct`
  Another way of specifying the roots: instead of using ordinal
  numbers, the roots selected will be those NRROOTS which have
  largest projections in a selection space
  which is specified on the next lines, as follows:
  One line gives NSEL, the number of vectors used to define the
  selection space. For each selection vector, program reads
  the number of CSFs (NC), and # NC pairs of CSEL (text strings) and SSEL (coefficients).
  The text string is composed of the
  digits 0,1,2,3 and denotes the GUGA case numbers of the active
  orbitals, defining uniquely a CSF belonging to the reference space.
  The keywords ROOTS and SELECT are mutually exclusive.

  .. xmldoc:: <KEYWORD MODULE="MRCI" NAME="SELECT" APPEAR="Roots selected:" KIND="REALS_COMPUTED" SIZE="2" LEVEL="BASIC">
              %%Keyword: Select <advanced>
              <HELP>
              Which roots to select, specified as a selection space.
              See manual for details.
              </HELP>
              Keywords ROOTS and SELECT are mutually exclusive.
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`RESTart`
  Restart the calculation from a previous calculation. No additional
  input is required. The :file:`MRCIVECT` file is required for restarted
  calculations.

  .. xmldoc:: %%Keyword: Restart <advanced>
              Use a previous wavefunction from the MRCIVECT file as start approximation.

:kword:`THRPrint`
  Threshold for printout of the wavefunction. All configurations with a
  coefficient greater than this threshold are printed.
  The default is 0.05.

  .. xmldoc:: %%Keyword: ThrPrint <advanced>
              Enter threshold of CI coefficients to be printed. Default 0.05.

:kword:`ECONvergence`
  Energy convergence threshold. The result is converged when the energy
  of all roots has been lowered less than this threshold in the last
  iteration. The default is 1.0d-8.

  .. xmldoc:: %%Keyword: EConvergence <advanced>
              Enter energy convergence threshold. Default 1.0D-8.

:kword:`PRINt`
  Print level of the program. Default is 5.

  .. xmldoc:: %%Keyword: Print <advanced>
              Set print level. Default is 5.

:kword:`MAXIterations`
  Maximum number of iterations. Default 20. The maximum possible value is 49.

  .. xmldoc:: %%Keyword: MaxIterations <advanced>
              Set max number of iterations. Default is 20. Largest possible is 49.

:kword:`MXVEctors`
  Maximum number of trial vector pairs (CI+sigma) kept on
  disk. Default is MAX(NRROOTS,10). It should never be
  smaller than NRROOTS. A good value is 3*NRROOTS or more.

  .. xmldoc:: %%Keyword: MxVectors <advanced>
              Set max nr of trial vector pairs (CI+sigma) kept on disk. Default is
              MAX(NRROOTS,10). Must be at least NRROOTS. Not much point in using
              more than 3*NRROOTS except for very few roots.

:kword:`TRANsition`
  This keyword is relevant to a multi-root calculation. In addition
  to properties, also
  the transition matrix elements of various operators, for each pair
  of wave functions, will be computed.

  .. xmldoc:: %%Keyword: Transition <advanced>
              Relevant for multi-root calculations. The transition matrix elements
              of all operators, for which there are integrals on the ONEINT file,
              will be computed for each pair of states.

:kword:`FROZen`
  Specify the number of orbitals to be frozen in
  **addition** to the orbitals frozen in the integral transformation.
  Default is 0 in all symmetries.

  .. xmldoc:: %%Keyword: Frozen <advanced>
              Enter a list specifying, for each symmetry, how many orbitals to keep
              frozen (uncorrelated), in addition to those that were frozen already
              in the integral transformation (See MOTRA). Default is 0 in all symmetries.

:kword:`DELEted`
  Specify the number of orbitals to be deleted in
  **addition** to the orbitals deleted in the integral transformation.
  Default is 0 in all symmetries.

  .. xmldoc:: %%Keyword: Deleted <advanced>
              Enter a list specifying, for each symmetry, how many orbitals to delete
              in addition to those that were deleted already
              in the integral transformation (See MOTRA). Default is 0 in all symmetries.

:kword:`REFCi`
  Perform only reference CI.

  .. xmldoc:: %%Keyword: RefCI <advanced>
              Do only a reference CI.

:kword:`PRORbitals`
  Threshold for printing natural orbitals. Only orbitals with occupation
  number larger than this threshold appears in the printed output.
  Default is 1.0d-5.

  .. xmldoc:: %%Keyword: PrOrbitals <advanced>
              Threshold on occupation number, for printing natural orbitals. Default 1.0D-5.

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

::

  &MRCI
  Title
   Water molecule. 1S frozen in transformation.
  Sdci

.. xmldoc:: </MODULE>