.. 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.

.. _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:`JOBPDFT`
  This file is written in binary format and has the same structue of the :file:`JOBIPH` file.

: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:`KSDFT` is the only required keyword.

.. class:: keywordlist

:kword:`KSDFT`
  The functional choice follows. Specify the functional by prefixing
  ``T:`` or ``FT:`` to the standard DFT functionals (see keyword :kword:`KSDFT` of :program:`SCF`).
  Note that hybrid functional names (e.g. PBE0 or B3LYP) should not be used after ``KSDFT=T:`` or
  ``KSDFT=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::

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

  ::

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

  However, the following syntax should not be used.

  ::

     KSDFT=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="KSDFT" APPEAR="Pair-density functional" KIND="STRING" > LEVEL="BASIC"
              %Keyword: KSDFT <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:`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, otherwise only state-specific MC-PDFT calculations will be performed. 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::

     KSDFT = T:PBE
     LAMB  = 0.25

  .. compound::

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

       KSDFT = T:PBE0

    or::

       KSDFT = T:PBE0
       LAMB  = 0.25

    because hybrid functional names (e.g. PBE0 or B3LYP) should not be used
    after ``KSDFT=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>


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
  KSDFT=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
   KSDFT=T:PBE
   MSPDft

The following example shows a part of the input to run CMS-PDFT geometry optimization. The additional keywords are :kword:`RLXR` in :program:`RASSCF` 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
    RLXRoot=2

    &MCPDFT
    KSDFT=T:PBE
    Grad
    MSPDft

    &MCLR

    &ALASKA

    &SLAPAF
    >>> EndDo

.. xmldoc:: </MODULE>
