.. index::
   single: Program; MCPDFT
   single: MCPDFT

.. _UG\:sec\:MCPDFT:

:program:`mcpdft`
=================

.. only:: html

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

.. xmldoc:: <MODULE NAME="MCPDFT">
            %%Description:
            <HELP>
            The MCPDFT program performs an MC-PDFT calculation following a
            CASSCF, RASSCF, GASSCF or DMRG-SCF wave function run. It requires the
            one- and two-electron integral files generated by SEWARD, and
            a JOBIPH file generated by the RASSCF module. In the case of DMRG-SCF
            the .h5 file generated by the DMRGSCF module suffices for an MC-PDFT run.
            </HELP>

The :program:`MCPDFT` program in |openmolcas| performs multiconfiguration
pair-density functional theory (MC-PDFT) calculations, as described in
:cite:`limanni2014,limanni2015`. The MC-PDFT method involves two steps:
(i) a CASSCF, RASSCF, GASSCF, DMRG-SCF, CASCI, RASCI, or DMRG wave function
calculation to obtain the kinetic energy, classical Coulomb energy, total
electron density, and on-top pair-density;
(ii) a post-SCF calculation of the remaining energy using an on-top
pair-density functional. In the current implementation, the on-top pair-density
functionals are translated (t) or fully translated (ft) :cite:`Carlson2015`
LSDA-type or GA-type exchange correlation functionals.
For example: tLSDA, tPBE, tBLYP, trevPBE and tOPBE for translated functionals,
and ftLSDA, ftPBE, ftBLYP, ftrevPBE and ftOPBE for fully-translated
functionals. Hybrid functionals (see keyword :kword:`LAMBda`) and functionals
with scaled exchange and correlation (see keyword :kword:`DFCF`) are also
available. As multiconfigurational wave functions are used as input quantities,
spin and space symmetry are correctly conserved.

The molecular orbitals and one- and two-body density matrices are read from the
:file:`JOBIPH` (or :file:`JOBOLD`) file generated during a :program:`RASSCF`
run. In the DMRG-SCF case, the one- and two-body density matrices are read from
an :file:`.h5` file generated during a :program:`DMRGSCF` run.

Note that the keyword :kword:`KSDFt` is now deprecated and has been replaced
with the :kword:`FUNCtional` keyword instead.

.. _UG\:sec\:mcpdft_dependencies:

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

.. compound::

  To start the :program:`MCPDFT` module, the one-electron
  and two-electron integrals generated by :program:`SEWARD` are required. For MC-PDFT calculations it is suggested to use a fine or ultrafine
  grid via the following input specifications (see the :program:`SEWARD` section for further details): ::

    &SEWARD
    grid input
    grid=ultrafine
    end of grid input

  Additionally, a :file:`JOBIPH` (or :file:`wavefunction.h5`) file must be supplied to provide the molecular orbitals and one- and two-body density matrices.

.. _UG\:sec\:mcpdft_files:

Files
-----

.. _UG\:sec\:mcpdft_inp_files:

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

:program:`MCPDFT` will use the following input
files: :file:`ONEINT`, :file:`ORDINT`, :file:`RUNFILE`, :file:`JOBOLD`,
:file:`JOBIPH`, :file:`wavefunction.h5`.

If Cholesky options are selected, additional Cholesky-related files will also be used.
Only :file:`JOBIPH` or :file:`JOBOLD` or :file:`wavefunction.h5` is needed; the code will first look for :file:`JOBOLD`
first and :file:`JOBIPH` second. To switch to the HDF5 :file:`wavefunction.h5` file mandatory for a DMRGSCF reference
wave function, use the keyword :kword:`FILEORB`.

.. _UG\:sec\:mcpdft_output_files:

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

.. class:: filelist

:file:`wavefunction.h5` (optional)
  This file is written in HDF5 format and updates the content (state energies) of the input :file:`wavefunction.h5` file.

:file:`RUNFILE`
  The :file:`RUNFILE` is updated with information from the MC-PDFT calculation.

.. _UG\:sec\:mcpdft_inp:

Input
-----

This section describes the input to the
:program:`MCPDFT` program in |openmolcas|. The input starts
with the program name ::

  &MCPDFT

The :kword:`FUNC` is the only required keyword.

.. class:: keywordlist

:kword:`FUNCtional`
  The functional choice follows. For LSDA and GGA exchange-correlation
  functionals, one may specify a translated or fully translated on-top
  functional by prefixing ``T:`` or ``FT:`` to the standard DFT functionals.
  For meta-GGAs, one may specify a translated on-top functional by the prefix
  ``T:``, but one cannot use ``FT:`` Hybrid functional names (e.g. PBE0 or
  B3LYP) should not be used after ``FUNC=T:`` or ``FUNC=FT:`` in this module.
  See keyword :kword:`LAMBda` for a description on how to run hybrid MC-PDFT
  calculations. Also note that the format of a number :math:`N` followed by
  :math:`N` lines, each of them containing a weight factor and a Libxc
  functional name, is not supported in this module. Examples of this keyword

  ::

     FUNC=T:PBE                 * A functional keyword, can be used for MC-PDFT calculations.

  ::

     FUNC=T:GGA_X_PBE           * A Libxc functional name, can be used for MC-PDFT calculations.

  However, the following syntax should not be used.

  ::

     FUNC=T: 2                   * two components with their weights, CANNOT be used for MC-PDFT calculations.
           1.00 GGA_X_PBE        * Libxc functional names
           1.00 GGA_C_PBE        * Libxc functional names

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="FUNC" APPEAR="Pair-density functional" KIND="STRING" > LEVEL="BASIC"
              %Keyword: FUNCtional <basic>
              <HELP>
              Needed to perform MC-PDFT calculations.
              The functional choice follows. Specify the functional by prefixing
              T: or FT: to the standard DFT functionals (see keyword KSDFT of SCF program)
              </HELP>
              </KEYWORD>


:kword:`EXPM`
  The :kword:`EXPM` keyword allows one to use on-top functionals with parameters that are defined by users. 
  It should be followed by the filename of the external-parameter file in the scratch directory. 
  The external parameters in the external-parameter file has the following format:
  ::

     N_Functions
     N_Parameters1, N_Parameters2, ...
     Parameters_In_Function1
     Parameters_In_Function2
     ...

  where ``N_Functions`` is the number of Libxc functions that are called when a functional is invoked.
  For example, M06-L requires two Libxc functions, one for the exchange functional and the other for the correlation functional.
  Therefore, ``N_Functions`` is ``2`` if the on-top functional to be used has the translated M06-L form 
  but with different parameters than those used in the original M06-L functional.
  ``N_Parameters1, NParameters2, ...`` are the number of parameters for each Libxc function.
  For M06-L, these numbers are ``18`` and ``28``, respectively.
  ``Parameters_In_Function1`` is a list of parameter values for the first Libxc function, and so on.

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="EXPM" APPEAR="Libxc EXternal ParaMeter" KIND="STRING" LEVEL="ADVANCED">
              %Keyword: EXPM <advanced>
              <HELP>
              For changing Libxc functional parameters.
              The file for external parameters follows.
              </HELP>
              </KEYWORD>

:kword:`DFCF`
  Use this keyword to scale the exchange terms and/or correlation terms of the functional requested.
  This keyword should be followed by the scaling factor for the exchange terms and the scaling factor for the correlation terms, separated by a space.
  If the values are 1.0 (default), then the original functional is used.
  For an HLE-type functional, use 1.25 (for exchange) and 0.5 (for correlation).
  Example: ``DFCF=1.25 0.5``

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="DFCF" APPEAR="DFT exch. &amp; corr. scaling factors" KIND="REALS" SIZE="2" LEVEL="ADVANCED">
              %%Keyword: DFCF <advanced>
              <HELP>
              Use this keyword to scale the exchange terms and/or correlation terms of the functional requested.
              This keyword should be followed by the scaling factor for the exchange terms
              and the scaling factor for the correlation terms, separated by a space.
              If the values are 1.0 (default), then the original functional is used.
              For an HLE-type functional, use 1.25 (for exchange) and 0.5 (for correlation).
              Example: DFCF=1.25 0.5
              </HELP>
              </KEYWORD>

:kword:`GRAD`
  The keyword is needed to calculate potentials for analytical gradients.
  This keyword can be used with state-specific and state-averaged CASSCF reference wavefunctions and with the CMS-PDFT method.

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="GRAD" APPEAR="Potentials for Gradients" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: GRAD <basic>
              <HELP>
              Needed to compute potentials for MC-PDFT analytical gradients.
              </HELP>
              </KEYWORD>

:kword:`MSPDft`
  This keyword allows one to run Multi-State Pair-Density Functional Theory
  (MS-PDFT). This keyword is only effective when a file named
  :file:`H0_Rotate.txt` is present in the scratch directory. With the
  :kword:`MSPD` keyword, the program reads the Hamiltonian matrix from
  :file:`H0_Rotate.txt`, replaces the diagonal elements with the MC-PDFT
  energies of the intermediate states (presumably obtained from a previous
  :program:`RASSCF` module in which the keyword :kword:`ROST`, :kword:`XMSI` or
  :kword:`CMSI` is used), and diagonalizes the Hamiltonian matrix in the
  intermediate basis (called the effective Hamiltonian matrix) to obtain the
  MS-PDFT states and energies. An input example is shown below. More details
  regarding the theory, the input, and the output can be found on the Minnesota
  OpenMolcas page\ [#fn1]_.

  XMS-PDFT and CMS-PDFT are two MS-PDFT options in the code.

  .. [#fn1] https://comp.chem.umn.edu/openmolcas/

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="MSPD" APPEAR="MS-PDFT" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: MSPDft <basic>
              <HELP>
              Enables MS-PDFT. Requires H0_Rotate.txt file in the scratch directory.
              </HELP>
              </KEYWORD>

:kword:`WJOB`
    This keyword allows one to write the energies and eigenstates of MC-PDFT or MS-PDFT into :file:`JOBIPH` (or :file:`wavefunction.h5`). For MC-PDFT, only the energy of each state is written into :file:`JOBIPH` (or :file:`wavefunction.h5`), since an MC-PDFT calculation is based on a previous wave function (CASSCF, SA-CASSCF, RASSCF, GASSCF, DMRG-SCF, CASCI, RASCI...); for MS-PDFT, both the energy and the CI coefficients of the eigenstates are written into :file:`JOBIPH`, because an MS calculation changes the wave functions. The latter option is not yet available for DMRG-SCF reference wave functions.


  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="WJOB" APPEAR="Write into JOBIPH" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: WJOB <basic>
              <HELP>
              Enable one to write the energies and eigenstates of MC-PDFT or MS-PDFT into the JOBIPH file.
              </HELP>
              </KEYWORD>

:kword:`LAMBda`
  This keyword is used to run a hybrid MC-PDFT or hybrid MS-PDFT calculation.
  In hybrid MC-PDFT calculations, the total energy is a weighted sum of the MC-PDFT energy
  and the wave function energy. In hybrid MS-PDFT calculations, the intermediate state energies
  (the diagonal elements of the model-space Hamiltonian) are weighted sums of the MC-PDFT energy
  and the wave function energy. The weight of the wave function energy is given by the variable :math:`\lambda`
  (which is set by the :kword:`LAMBda` keyword), and the weight of the PDFT energy :math:`(1 - \lambda)`;
  for example, to run MC-PDFT with tPBE0, the value for :math:`\lambda` should be 0.25. The default is :math:`\lambda` = 0.0.

  Example of running tPBE0::

     FUNC = T:PBE
     LAMB  = 0.25

  .. compound::

    However, the following two examples will NOT give tPBE0 results::

       FUNC = T:PBE0

    or::

       FUNC = T:PBE0
       LAMB  = 0.25

    because hybrid functional names (e.g. PBE0 or B3LYP) should not be used
    after ``FUNC=T:`` in this module.

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="LAMBDA" APPEAR="Lambda in hybrid PDFT" KIND="REAL" LEVEL="BASIC">
              %%Keyword: MSPDFT <basic>
              <HELP>
              Enables hybrid PDFT calculations.
              </HELP>
              </KEYWORD>

:kword:`FILEORB`
  This keyword allows one to set a reference wave function file to be used instead of the default,
  which is the :file:`JOBIPH` file; in particular, one can use an :file:`HDF5` file.
  If a MC-PDFT calculation is to be followed by an MPSSI calculation for a reference DMRG wave function, please also add the keyword :kword:`WJOB`.
  Example: ``FileOrb = wavefunction.h5``

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="FILEORB" APPEAR="Set reference wave function file" KIND="STRING" LEVEL="BASIC">
              %%Keyword: FILEORB <basic>
              <HELP>
              Enables one to set the reference wave function file for an MC-PDFT run, in particular for an HDF5 formatted file.
              </HELP>
              </KEYWORD>

:kword:`NAC`
  This keyword is used to request the computation of nonadiabatic coupling vectors (which are often called NACs).
  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="MCPDFT" NAME="NAC" APPEAR="Nonadiabatic coupling: root selection" KIND="INTS" SIZE="2" LEVEL="BASIC">
              %%Keyword: NAC <basic>
              <HELP>
              Makes MCPDFT compute the Lagrangian multipliers for the nonadiabatic coupling
              between the specified roots in a CMS-PDFT Calculation.
              NAC has to be followed by two integers on the next line, specifying the
              states between which the nonadiabatic coupling is required.
              </HELP>
              </KEYWORD>

:kword:`MECI`
  The keyword is needed to calculate potentials for analytical gradients when calculating
  minimum energy conical intersections (MECIs)
  This calculates the first derivative of the effective Hamiltonian matrix element rather
  than the NAC.

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="MECI" APPEAR="Potentials for Off-Diagaonal Gradients" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: MECI <basic>
              <HELP>
              Needed to compute potentials for CMS-PDFT analytical gradients during MECI.
              Calculates the first derivative of the effective Hamiltonian matrix element
              rather than the NAC.
              Must be used with the NAC keyword.
              </HELP>
              </KEYWORD>

:kword:`RLXRoot`
  Specifies which root to be relaxed in a geometry optimization of a SA-MC-PDFT
  or MS-PDFT wave function. Defaults to the highest root or root defined by the
  same keyword in the :program:`RASSCF` module.

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="RLXROOT" APPEAR="Relaxed root" KIND="INT" MIN_VALUE="1" LEVEL="BASIC">
              %%Keyword: RLXRoot <basic>
              <HELP>
              Which root to use in a geometry optimization of a SA-MC-PDFT or
              MS-PDFT wave function. Default: root defined by RLXROOT in the
              RASSCF module, if any, else the highest root.
              </HELP>
              </KEYWORD>

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

The following example shows the input to the
:program:`RASSCF` and :program:`MCPDFT` programs for a calculation on the water molecule.
The tPBE functional is used. The calculation is
performed in |Ctv| symmetry (symmetries: |ao|, |bt|, |bo|, |at|, where the two
last species are antisymmetric with respect to the molecular plane). Inactive
orbitals are 1\ |ao| (oxygen 1\ |s|), 2\ |ao| (oxygen 2\ |s|), and
1\ |bo| (the :math:`\pi` lone-pair orbital). Two bonding and two anti-bonding
:math:`\ce{OH}` orbitals are active, |ao| and |bt| symmetries. The calculation is
performed for the |SAO| ground state. Note that no information about basis set,
geometry, etc. has to be given. Such information is supplied by the
:program:`SEWARD` integral program via the one-electron integral file :file:`ONEINT`. ::

  &RASSCF
  Title= Water molecule. Active orbitals OH and OH* in both symmetries
  Spin     = 1
  Symmetry = 1
  Inactive = 2 0 1 0
  Ras2     = 2 2 0 0

  &MCPDFT
  FUNC=T:PBE

The first :program:`RASSCF` run is a standard CASSCF calculation that leads to variationally optimized orbitals and CI coefficients.
The MC-PDFT run will use the orbitals and density matrices optimized during the preceding :program:`RASSCF` run.

The following example shows a part of the input to run a CMS-PDFT calculation.
For XMS-PDFT calculations, one simply replaces :kword:`CMSI` with :kword:`XMSI`.
The system is :math:`\ce{LiF}` and the point group used is |Ctv|. ::

   &RASSCF
   Spin=1
   Symmetry=1
   CIRoot= 2 2 1
   Inactive=2 0 0 0
   Ras2=4 1 0 1
   Nactel=8 0 0

   >>COPY $CurrDir/LiF.RasOrb $CurrDir/UseOrb

   &RASSCF
   CIOnly
   Spin=1
   Symmetry=1
   CIRoot= 2 2 1
   Inactive=2 0 0 0
   Ras2=4 1 0 1
   Nactel=8 0 0
   CMSI

   &MCPDFT
   FUNC=T:PBE
   MSPDft

The following example shows a part of the input to run CMS-PDFT geometry optimization. The additional keywords are :kword:`RLXR` and :kword:`GRAD` in :program:`MCPDFT`. The additional modules include :program:`MCLR`, :program:`ALASKA` and :program:`SLAPAF`. ::

   &GATEWAY
    Coord
    2
    angstrom
    Li 0.0 0.0  1.3
    F  0.0 0.0 -1.3
    Group=XY Y
    Basis=STO-3G

   >>> DO WHILE
    &Seward

    &RASSCF
    Spin=1
    Symmetry=1
    CIRoot= 2 2 1
    Inactive=2 0 0 0
    Ras2=4 1 0 1
    Nactel=8 0 0
    CMSI

    &MCPDFT
    FUNC=T:PBE
    Grad
    MSPDft
    RLXRoot=2

    &MCLR

    &ALASKA

    &SLAPAF
    >>> EndDo

The following example shows the :program:`MCPDFT` part of input to run MC23 with external parameters. ::

    &MCPDFT
     KSDFt  = T:M06L
     LAMB   = 0.2952
     EXPM   = MC23_params.txt

.. compound::

  The file :file:`MC23_params.txt` is in the same place as files like :file:`JOBIPH`, and it has the following content.::

    2
    18 27
    3.352197e+00 6.332929e-01 -9.469553e-01 2.030835e-01 2.503819e+00 8.085354e-01 -3.619144e+00 -5.572321e-01 -4.506606e+00 9.614774e-01 6.977048e+00 -1.309337e+00 -2.426371e+00 -7.896540e-03 1.364510e-02 -1.714252e-06 -4.698672e-05 0.0
    0.06 0.0031 0.00515088 0.00304966 2.427648e+00 3.707473e+00 -7.943377e+00 -2.521466e+00 2.658691e+00 2.932276e+00 -8.832841e-01 -1.895247e+00 -2.899644e+00 -5.068570e-01 -2.712838e+00 9.416102e-02 -3.485860e-03 -5.811240e-04 6.668814e-04 0.0 2.669169e-01 -7.563289e-02 7.036292e-02 3.493904e-04 6.360837e-04 0.0 1e-10

  where ``2`` means there are two Libxc functions invoked by for M06-L, 
  ``18`` means there are 18 parameters for the first Libxc function (M06-L exchange functional),
  ``27`` means there are 27 parameters for the second Libxc function (M06-L correlation functional).
  The third line are 18 values for the first function, and the last line are the 27 values for the second functional.

.. xmldoc:: </MODULE>