.. 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, or GASSCF wave function run. It requires the
            one- and two-electron integral files generated by SEWARD, and
            a JOBIPH file generated by the RASSCF module.
            </HELP>

The :program:`MCPDFT` program in |molcas| 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, or GASSCF 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 density functional.
In the current implementation, the on-top pair density functional is obtained by "translation" (t) of exchange-correlation functionals.
Four translated functionals are currently available: tLSDA, tPBE, tBLYP, and trevPBE, in addition to the "fully-translated" (ft)
variants :cite:`Carlson2015`: ftLSDA, ftPBE, ftBLYP, and ftrevPBE.
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.

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

If Cholesky options are selected, additional Cholesky-related files will also be used.
Only :file:`JOBIPH` or :file:`JOBOLD` is needed; the code will first look for :file:`JOBOLD`
first and :file:`JOBIPH` second.

.. _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:`RUNFILE`
  The :file:`RUNFILE` is updated with information from the MC-PDFT calculation.

:file:`MCDENS`
  This ASCII file is generated for MC-PDFT calculations.
  It contains spin densities, total density and on-top pair density values on grid (coordinates in a.u.).

.. _UG\:sec\:mcpdft_inp:

Input
-----

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

  &MCPDFT

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

.. class:: keywordlist

:kword:`KSDFT`
  The functional choice follows. Currently available functionals are: tPBE, tBLYP, tLSDA, trevPBE, tOPBE,
  ftPBE, ftBLYP, ftLSDA, ftrevPBE and ftOPBE.

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="KSDFT" APPEAR="Pair-density functional" KIND="CHOICE" LIST="----,tLSDA,tPBE,tBLYP,trevPBE,tOPBE,ftLSDA,ftPBE,ftBLYP,ftrevPBE,ftOPBE"> LEVEL="BASIC"
              %Keyword: KSDFT <basic>
              <HELP>
              Needed to perform MC-PDFT calculations.
              The functional choice follows. Currently available functionals: tPBE, tBLYP, tLSDA, trevPBE, tOPBE, ftPBE, ftBLYP, ftLSDA, ftrevPBE, ftOPBE.
              </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 both state-specific and state-averaged CASSCF reference wavefunctions.

  .. 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 rotated states (presumably obtained from a previous :program:`RASSCF` module in which the keyword :kword:`ROST` or :kword:`XMSI` is used), and diagonalizes the Hamiltonian matrix in the XMS 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]_.

  Currently the only MS-PDFT option in the code is XMS-PDFT.

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

  .. xmldoc:: <KEYWORD MODULE="MCPDFT" NAME="MSPD" APPEAR="MS-PDFT" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: MSPDFT <basic>
              <HELP>
              Enable MS-PDFT. Requires H0_Rotate.txt file in the scratch directory.
              </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=TPBE

The first 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 RASSCF run.

The following example shows a part of the input to run XMS-PDFT calculation.
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
   XMSI

   &MCPDFT
   KSDFT=TPBE
   NoGrad
   MSPDft

.. xmldoc:: </MODULE>
