.. index::
   single: Program; MCLR
   single: MCLR

.. _UG\:sec\:mclr:

:program:`mclr`
===============

.. only:: html

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

.. xmldoc:: <MODULE NAME="MCLR">
            %%Description:
            <HELP>
            This program calculates the response of a SCF or MCSCF wave function
            and related second order properties.
            </HELP>

The :program:`mclr` program in |molcas| performs response calculations on
single and multiconfigurational SCF wave functions with the technique described
in :cite:`Bernhardsson:99a`.
The right hand side (RHS) and thus the perturbation has to be defined through a preceding
:program:`MCKINLEY` calculation. Second order derivatives are obtained from a :program:`MCKINLEY` and
a consecutive :program:`mclr` calculation, with a geometrical displacement as the external perturbation.
If the response of a geometrical perturbation is calculated, harmonic frequencies corresponding to
the most abundant masses are printed. :program:`MCLR` also calculates isotope shifted frequencies.
Per default, vibrational frequencies are calculated for all possible single isotopic substitutions.
:program:`MCLR` always calculates the response of an electric field and prints the polarizability.

Note that the user should not normally, for frequency calculations,
request the execution of this module since this will be automatic.

The :program:`mclr` code also calculates the Lagrangian multipliers required for a
SA-MCSCF single state gradient :cite:`Stalring:01a`, where the RHS is generated by the program itself.
Through an :program:`mclr` and a consecutive :program:`alaska` calculation, analytical gradients
of a SA-MCSCF state may be obtained. **Note** that :program:`alaska` will automatically run the :program:`mclr` module!
Thus, with :program:`slapaf` geometry optimizations of
excited MCSCF states can be performed.

The :program:`MCLR` program is based on the split GUGA formalism.
However, it uses determinant based algorithms to solve the configuration
interaction problem :cite:`rasdet`, in analogy to how it is done in the :program:`RASSCF`.
For spin symmetric wave function (:math:`M_S=0`) the time reversal symmetry is used, and the innermost loops are performed in
combinations instead of determinant.

The upper limit to the size of the CI wave function that can be
handled with the present program is about the same as for the :program:`RASSCF`.
The present version of the code is just able to handle CASSCF wave function, RASSCF
wave function will soon be included.

The orbital handling is based on a one index transformation technique.
The integrals is the transformed to occupied orbitals in two indexes,
this can be done directly or from disk based integrals generated by :program:`seward`.

.. _UG\:sec\:mclr_dependencies:

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

To start the :program:`MCLR` module the one-electron integrals generated by
:program:`SEWARD` have to be available. Moreover, :program:`MCLR` requires
the wave function from a :program:`SCF` or :program:`RASSCF` calculation and
apart from in an evaluation of SA-MCSCF gradients, it also requires the differentiated integrals
from :program:`MCKINLEY`.

.. _UG\:sec\:mclr_files:

Files
-----

.. _UG\:sec\:mclr_input_files:

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

:program:`MCLR` will use the following input
files: :file:`ONEINT`, :file:`ORDINT`, :file:`RUNFILE`, :file:`ABDATA`,
:file:`RYSRW`, :file:`JOBIPH`, :file:`QDAT`, :file:`MOTRA`
(for more information see :numref:`UG:sec:files_list`).

.. _UG\:sec\:mclr_output_files:

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

.. class:: filelist

:file:`MCKINT`
  Communication file between :program:`mclr` and :program:`mckinley` and :program:`rassi`.

:file:`UNSYM`
  ASCII file where all essential information, like geometry, Hessian normal modes and dipole
  derivatives are stored.

:file:`MLDNFQ`
  Molden input file for harmonic frequency analysis.

.. _UG\:sec\:mclr_scratch_files:

Scratch files
.............

.. class:: filelist

:file:`TEMP0x`
  x=1,8 used for for integral transformation and storing half transformed integrals.

:file:`REORD`
  Used for storing data used in the transformation of CI vectors from determinant base to CSF base.

:file:`TEMPCIV`
  Exchange file for temporary storing the CI vectors during the PCG.

:file:`RESP`
  Binary file where the solution of the response equations are stored.

:file:`JOPR`
  Used for half transformed integrals in direct mode.

:file:`KOPR`
  Used for half transformed integrals in direct mode.

:file:`QDAT`
  Used for storing and transferring some data (FockI, FockA, Fock, Q). It is generated / read only if :kword:`TWOS` keyword is active.

:file:`MOTRA`
  Used for storing and transferring ERIs in MO bassis. It is generated / read only if :kword:`TWOS` keyword is active.

.. _UG\:sec\:mclr_input:

Input
-----

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

  &MCLR

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

A list of these keywords is given below:

.. class:: keywordlist

:kword:`SALA`
  Makes :program:`MCLR` compute the Lagrangian multipliers for a state average
  MCSCF wave function. These multipliers are required by :program:`ALASKA`
  to obtain analytical gradients for an excited state, when the excited
  state is determined by a SA optimization. :kword:`SALA` has
  to be followed by an integer on the next line, specifying the
  excited state for which the gradient is required.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="SALA" APPEAR="SA-CASSCF Lagrangian: root selection" KIND="INT" LEVEL="BASIC">
              <HELP>
              Makes MCLR compute the Lagrangian multipliers for the specified root in a state average
              CASSCF wave function.
              </HELP>
              %%Keyword: Sala <basic>
              Makes MCLR compute the Lagrangian multipliers for a state average
              MCSCF wave function. These multipliers are required by ALASKA
              to obtain analytical gradients for an excited state, when the excited
              state is determined by a SA optimization. SALA has
              to be followed by an integer on the next line, specifying the
              excited state for which the gradient is required.
              </KEYWORD>
:kword:`CHOF`
  Makes :program:`MCLR`, in association with compute the Lagrangian multipliers for a state average
  MCSCF wave function and the RI option, to use the so-called Cho-FOCK algorithm, rather than the default Cho-MO algorthm.
  The Cho-Fock option is the fastest for calculations with large basis sets. For details consult the paper
  entitled "Analytical gradients of the state-average complete active space self-consistent field method with density fitting", doi.org/10.1063/1.4927228.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="CHOF" APPEAR="CHO-FOCK" KIND="SINGLE" LEVEL="BASIC">
              <HELP>
              Makes MCLR use the Cho-Fock algorithm in association with the RI option for the two-electron integrals
              CASSCF wave function.
              </HELP>
              %%Keyword: CHOF <basic>
              Makes MCLR, in association with compute the Lagrangian multipliers for a state average
              MCSCF wave function and the RI option, to use the so-called Cho-FOCK algorithm, rather than the default Cho-MO algorthm.
              The Cho-Fock option is the fastest for calculations with large basis sets. For details consult the paper
              entitled "Analytical gradients of the state-average complete active space self-consistent field method with density fitting", doi.org/10.1063/1.4927228.
              </KEYWORD>

:kword:`NAC`
  Like :kword:`SALA`, but for computing nonadiabatic couplings. It must
  be followed by two integers on the next line, specifying the states
  between which the coupling is required. Note that, unlike :kword:`SALA`,
  the numbering here is absolute, regardless of which roots are included
  in the state average.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="NAC" APPEAR="Nonadiabatic coupling: root selection" KIND="INTS" SIZE="2" LEVEL="BASIC">
              <HELP>
              Makes MCLR compute the Lagrangian multipliers for the nonadiabatic coupling
              between the specified roots in a state average CASSCF wave function.
              </HELP>
              </KEYWORD>
              %%Keyword: NAC <basic>
              Makes MCLR compute the Lagrangian multipliers for a coupling
              in a state average MCSCF wave function. These multipliers are required by ALASKA
              to obtain analytical nonadiabatic couplings between states.
              NAC has to be followed by two integers on the next line, specifying the
              states between which the nonadiabatic coupling is required.

:kword:`EXPDimension`
  Here follows the dimension of the explicit Hamiltonian used as preconditioner
  in the Preconditioned conjugate gradient algorithm. Default 100.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="EXPD" APPEAR="Explicit Hamiltonian dimension" KIND="INT" DEFAULT_VALUE="100" LEVEL="BASIC">
              <HELP>
              Specify the dimension of the explicit Hamiltonian used as preconditioner
              in the Preconditioned Conjugate Gradient algorithm.
              </HELP>
              %%Keyword: EXPDimension <advanced>
              Here follows the dimension of the explicit Hamiltonian used as preconditioner
              in the Preconditioned conjugate gradient algorithm. Default 100.
              </KEYWORD>

:kword:`ITERations`
  Specify the maximum number of iterations in the PCG. Default 200.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="ITER" APPEAR="PCG Iterations" KIND="INT" DEFAULT_VALUE="200" LEVEL="BASIC">
              %%Keyword: ITERations <advanced>
              <HELP>
              Specify the maximum number of iterations in the PCG. Default 200.
              </HELP>
              </KEYWORD>

:kword:`LOWMemory`
  Lowers the amount of memory used, by paging out the CI vectors on disk.
  This will lower the performance, but the program will need less memory.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="LOWM" APPEAR="Reduced memory usage" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: LOWMemory <advanced>
              <HELP>
              Lowers the amount of memory used, by paging out the CI vectors on disk.
              This will lower the performance, but the program will need less memory.
              </HELP>
              </KEYWORD>

:kword:`PRINt`
  Raise the print level, default 0.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="PRINT" APPEAR="Print level" KIND="INT" DEFAULT_VALUE="0" LEVEL="ADVANCED">
              <HELP>
              Specify the general print level with an integer (0-99).
              </HELP>
              %%Keyword: PRINt <advanced>
              Raise the print level, default 0.
              </KEYWORD>

:kword:`RASSi`
  This keyword is used for transforming the CI vectors to split GUGA
  representation, and transforming the orbital rotations to AO basis,
  to make the response accessible for state interaction calculations.

  .. xmldoc:: %%Keyword: RASSi <advanced>
              This keyword is used for transforming the CI vectors to split GUGA
              representation, and transforming the orbital rotations to AO basis,
              to make the response accessible for state interaction calculations.

:kword:`SEWArd`
  Specify one particle operators, used as right hand side, form the :file:`ONEINT`
  file constructed by :program:`SEWARD`
  The keyword is followed by one row for each perturbation:
  LABEL symmetry Component

  .. xmldoc:: %%Keyword: SEWArd <advanced>
              Specify one particle operators, used as right hand side, form the ONEINT
              file constructed by SEWARD.
              The keyword is followed by one row for each perturbation:
              LABEL symmetry Component

:kword:`EndSeward`
  Marks the end of perturbation specifications read from :program:`SEWARD` :file:`ONEINT` file.

  .. xmldoc:: %%Keyword: EndSeward <advanced>
              Marks the end of perturbation specifications read from SEWARD ONEINT file.

:kword:`THREshold`
  Specify the convergence threshold for the PCG. Default is 1.0e-4.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="THRE" APPEAR="PCG Threshold" KIND="REAL" DEFAULT_VALUE="1.0D-4" LEVEL="BASIC">
              %%Keyword: THREshold <advanced>
              <HELP>
              Specify the convergence threshold for the PCG. Default is 1.0e-4.
              </HELP>
              </KEYWORD>

:kword:`DISOTOPE`
  Calculates frequencies modified for double isotopic substitution.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="DISO" APPEAR="Double isotopic substitutions" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: DISOtope <advanced>
              <HELP>
              Calculates frequencies modified for double isotopic substitution.
              </HELP>
              </KEYWORD>

:kword:`THERmochemistry`
  Request an user specified thermochemical analysis.
  The keyword must be followed by a line containing the Rotational Symmetry Number,
  a line containing the Pressure (in atm), and lines containing the Temperatures (in K)
  for which the thermochemistry will be calculated. The section is ended by the
  keyword "End of PT".

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="THERMO" APPEAR="Thermochemistry" KIND="CUSTOM" LEVEL="ADVANCED">
              %%Keyword: THERM <advanced>
              <HELP>
              Request an user specified thermochemical analysis.
              The keyword is followed by the Rotational Symmetry Number,
              the Pressure (in atm), and lines containing the Temperatures (in K)
              for which the thermochemistry will be calculated.
              The section is ended by the keyword "End of PT".
              </HELP>
              </KEYWORD>

:kword:`TIME`
  Calculates the time dependent response of an electric periodic perturbation.
  The frequency of the perturbation should be specified on the following line.
  Used to calculated time dependent polarizabilities and required in
  a :program:`RASSI` calculation of two photon transition moments.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="TIME" APPEAR="Time dep. response" KIND="REAL" LEVEL="ADVANCED">
              <HELP>
              Activate time dependent response of an electronic periodic perturbation
              and specify the frequency of the perturbation.
              </HELP>
              %%Keyword: TIME <advanced>
              Calculates the time dependent response of an electric periodic perturbation.
              The frequency of the perturbation should be specified on the following line.
              Used to calculated time dependent polarizabilities and required in
              a RASSI calculation of two photon transition moments.
              </KEYWORD>

:kword:`MASS`
  Used to generate single and double (in conjunction with DISO) isotope
  shifted frequencies, with the isotope masses specified by the user.
  This implementation can be useful for example in calculating
  intermolecular frequencies which are contaminated by the BSSE.
  By setting the corresponding masses to very large numbers, ghost orbitals
  can be used in the frequency calculation.
  MASS needs the atomic label and the new mass in units of u (real), for each element of the molecule.

  .. xmldoc:: %%Keyword: MASS <advanced>
              Used to generate single and double (in conjunction with DISO) isotope
              shifted frequencies, with the isotope masses specified by the user.
              This implementation can be useful for example in calculating
              intermolecular frequencies which are contaminated by the BSSE.
              By setting the corresponding masses to very large numbers, ghost orbitals
              can be used in the frequency calculation.
              MASS needs the atomic label and the new mass in units of u (real), for each element of the molecule.

:kword:`TWOS`
  It is used to activate the two-step run of :program:`MCLR`, in connection to the computation of
  molecular gradients / NACs for SA-CASSCF wave function. The keyword takes two values: FIRST or SECOND.
  In the first MCLR run (i.e. TWOStep = FIRST), the MOTRA and QDAT files are generated. In the subsequent MCLR run
  (TWOstep=SECOND), the files MOTRA and QDAT are read and employed for the computation of the corresponding
  Lagrangian multipliers. This approach allows to reduce the input-output of data to/from disk during such calculations.

  .. xmldoc:: <KEYWORD MODULE="MCLR" NAME="TWOS" APPEAR="Two Step MCLR run" KIND="CHOICE" LIST="FIRST,SECOND" LEVEL="ADVANCED">
              <HELP>
              Activate the two-step run of MCLR, in connection to the computation of molecular gradients
              and NACs for SA-CASSCF wave function. Takes two values: FIRST or SECOND.
              </HELP>
              %%Keyword: TWOS <advanced>
              It is used to activate the two-step run of MCLR, in connection to the computation of
              molecular gradients / NACs for SA-CASSCF wave function. The keyword takes two values: FIRST or SECOND.
              In the first MCLR run (i.e. TWOStep = FIRST), the MOTRA and QDAT files are generated. In the subsequent MCLR run
              (TWOstep=SECOND), the files MOTRA and QDAT are read and employed for the computation of the corresponding
              Lagrangian multipliers. This approach allows to reduce the input-output of data to/from disk during such calculations.
              </KEYWORD>

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

A default input for a harmonic frequency calculation. ::

  &MCLR

An input for a harmonic frequency calculation with modified isotopic masses
for hydrogen and oxygen. ::

  &MCLR
  MASS
  H   = 2.0079
  O   = 150000.998

Thermochemistry for an asymmetric top (Rotational Symmetry Number
= 1), at 1.0 atm and 273.15, 298.15, 398.15 and 498.15 K. ::

  &MCLR
  THERmochemistry
   1
   1.0
   273.15 ;  298.15 ;  398.15 ;  498.15
  End of PT

The time dependent response is calculated for a perturbation of frequency
0.2 au. ::

  &MCLR
  TIME = 0.2

.. compound::

  The input: ::

    &MCLR
    SALA  = 2

  computes the Lagrangian multipliers for state number 2 in the SA root.
  Note, that 2 refers to the SA root. Thus, if the ground state is not
  included in the SA, the numbering of roots in the CI root and SA root
  differ. With the following :program:`RASSCF` input: ::

    &RASSCF
    CiRoot
     2 3
     2 3
     1 1
    RlxRoot = 2

  :kword:`SALA 2` yields the gradient for CI root number 3. Geometry optimization
  of an excited SA-CASSCF state can be done normally using EMIL commands,
  and requires the use of the :kword:`RLXR` keyword in the :program:`RASSCF`
  input to specify the selected root to be optimized. An explicit input
  to :program:`MCLR` is not required but can be specified if default options
  are not appropriate.

.. xmldoc:: </MODULE>