.. index::
   single: Program; DMRGSCF
   single: DMRGSCF

.. _UG\:sec\:dmrgscf:

:program:`dmrgscf`
==================

.. only:: html

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

.. xmldoc:: <MODULE NAME="DMRGSCF">
            %%Description:
            <HELP>
            The DMRGSCF program generates MPS wave functions based on a given CAS model.
            It requires the one- and two-electron integral files generated by
            SEWARD, and starting orbitals from either a previous DMRGSCF/RASSCF
            calculation or from any of the other wave function generating programs,
            or from the GUESSORB facility.
            The resulting orbitals can be visualized, e.g. by LUSCUS.
            </HELP>

The :program:`DMRGSCF` program in |molcas| performs
multiconfigurational SCF calculations in which a density matrix renormalization group (DMRG)
driver replaces a CI driver for the solution of the Complete Active Space
(CAS) problem. In the latter a matrix-product state (MPS) wave function is obtained as an approximate solution to a
full CI wave function in an active orbital space. In analogy to CASSCF, the DMRGSCF method is based on a partitioning of the occupied molecular
orbitals into the following groups:

* **Inactive orbitals:** Orbitals that are doubly occupied in all
  configurations.

* **Active orbitals:** In these orbitals all possible occupations are allowed.

* **Secondary orbitals:** Orbitals that are empty (unoccupied) in all configurations.

The :program:`DMRGSCF` program currently supports only the **QCMaquis** DMRG program suite :cite:`kell15a,kell16,knec16a` as
active space optimizer but in future it could be useful also for other DMRG programs interfaced to |molcas|
such as Block or CheMPS2. The latter two are currently activated through the :program:`RASSCF` input.

For further information concerning input orbitals, convergence (acceleration) of the orbital optimization algorithm,
dependencies, input orbitals, etc., we refer the reader to the introdcution of the :program:`RASSCF` program (see
:numref:`UG:sec:rasscf`) which is called by the :program:`DMRGSCF` program in order to perform the actual orbital optimization. DMRGSCF calculations require to have
only active orbitals in RAS2 (see the keyword list in the program :program:`RASSCF`, :numref:`UG:sec:rasscf` for
details).

**NOTE**: The :program:`DMRGSCF` program does **NOT** support RASSCF/GASSCF calculations but it can be combined with MC-PDFT. For options
concerning the latter, see the documentation of the :program:`MCPDFT` program, :numref:`UG:sec:mcpdft`.

.. _QCMaquis: https://scine.ethz.ch/static/download/qcmaquis_manual.pdf

.. _UG\:sec\:dmrgscf_input:

DMRGSCF input section
---------------------

The :program:`DRMGSCF` program is activated in general by ::

  &DMRGSCF &END
  ...
  End of Input

In the following we provide further input options for a DMRGSCF calculation.

.. class:: keywordlist

:kword:`ActiveSpaceOptimizer`
  **MANDATORY**: Sets the DMRG program to be used as active space optimizer. Currently the only choice is QCMaquis,
  i.e. ::

    ActiveSpaceOptimizer=QCMaquis

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="ACTIVESPACEOPTIMIZER" KIND="CHOICE" LIST="QCMaquis" LEVEL="BASIC">
              %%Keyword: ActiveSpaceOptimizer <basic>
              <HELP>
              Sets the DMRG program to be used as active space optimizer
              </HELP>
              </KEYWORD>

:kword:`Fiedler`
  .. compound::

    The Fiedler keyword, i.e., ::

      Fiedler=on

    enables a state-specific orbital ordering for the MPS optimization by exploiting concepts from graph theory. The ordering follows from the elements of the Fiedler vector which is the eigenvector corresponding to the second lowest eigenvalue of the so-called graph Laplacian.

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="FIEDLER" KIND="CHOICE" LIST="on" LEVEL="BASIC">
              %%Keyword: Fiedler <basic>
              <HELP>
              Enables Fiedler vector ordering.
              </HELP>
              </KEYWORD>

:kword:`CIDEAS`
  .. compound::

    The CIDEAS keyword, i.e., ::

      CIDEAS=on

    enables a more advanced algorithm to construct a suitable initial MPS (see the keyword init_state in Table 7 of the
    QCMaquis_ manual for other options) provided by the configuration interaction dynamically extended active space (CI-DEAS) approach.
    The CI-DEAS protocol can be interpreted
    as an orbital entanglement entropy guided configuration selection and the quality of this initial guess depends on the
    quality of the initial CAS vector. The CI-DEAS functionality is currently restricted to calculations performed with C1
    symmetry. Support for other point group symmetries will be available in due time. **Note**: The CIDEAS option requires to
    set the *HF occupation* for each state in the OptimizationSettings input section below by means of the :kword:`SOCC` keyword.

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="CIDEAS" KIND="CHOICE" LIST="on" LEVEL="BASIC">
              %%Keyword: CIDEAS <basic>
              <HELP>
              Enables CI-DEAS.
              </HELP>
              </KEYWORD>

.. _UG\:sec\:dmrgsettings_input:

DMRGSettings input section
..........................

DMRGSCF calculations require to set some DMRG-specific options, which will be passed on to the **QCMaquis** program. All mandatory keywords,
which must be present in each calculation, are summarized below. In addition to those keywords, any **QCMaquis** keyword
listed in Table 8 of the QCmaquis_ manual may be specified
in this section. The start and end of the DMRGSettings input section is given by ::

  DMRGSettings
  ...
  EndDMRGSettings

.. class:: keywordlist

:kword:`max_bond_dimension`
  Maximum number of renormalized block states (commonly referred to as :math:`m`-value or bond dimension) that will be kept during each microiteration step of a sweep.

  .. xmldoc:: <GROUP MODULE="DMRGSCF" NAME="DMRGSETTINGS" APPEAR="DMRG settings" KIND="BLOCK" LEVEL="BASIC">

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="MAX_BOND_DIMENSION" KIND="INT" LEVEL="BASIC">
              %%Keyword: max_bond_dimension <basic>
              <HELP>
              Maximum bond dimension.
              </HELP>
              </KEYWORD>

:kword:`nsweeps`
  Maximum number of DMRG sweeps. Please be aware that nsweeps sets the number of combined forward and backward sweeps. Thus, the actual number of sweeps is :math:`2\times`:kword:`nsweeps`.

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="NSWEEPS" KIND="INT" LEVEL="BASIC">
              %%Keyword: nsweeps <basic>
              <HELP>
              Maximum number of DMRG sweeps.
              </HELP>
              </KEYWORD>

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="NGROWSWEEPS" KIND="INT" LEVEL="UNDOCUMENTED" />

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="NMAINSWEEPS" KIND="INT" LEVEL="UNDOCUMENTED" />

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="SWEEP_BOND_DIMENSIONS" KIND="STRING" LEVEL="UNDOCUMENTED" />

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="INIT_BOND_DIMENSIONS" KIND="INT" LEVEL="UNDOCUMENTED" />

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="CONV_THRESH" KIND="REAL" LEVEL="UNDOCUMENTED" />

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="TRUNCATION_FINAL" KIND="REAL" LEVEL="UNDOCUMENTED" />

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="IETL_JCD_TOL" KIND="REAL" LEVEL="UNDOCUMENTED" />

:kword:`donotdelete`
  Set :kword:`donotdelete=1` to restart DMRGSCF optimization from an existing QCMaquis MPS checkpoint. Useful e.g. to restart crashed calculations.

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="DONOTDELETE" KIND="INT" LEVEL="BASIC">
              %%Keyword: donotdelete <basic>
              <HELP>
              Restart DMRGSCF optimization from an existing QCMaquis checkpoint.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

OOptimizationSettings input section
...................................

The Orbital OptimizationSettings block contains general, non DMRG-specific options required for the MPS wave function optimisation
(such as number of the active electrons, active orbital specification etc.), i.e., a normal input for a CASSCF or a CASCI
calculation with the :program:`RASSCF` module. Most of the RASSCF keywords listed in the keyword section of :numref:`UG:sec:rasscf` are accepted,
with the exception of keywords relating to explicit CI wave function quantities.
Please consult the :program:`RASSCF` module description for further details on the input.
In addition to the standard :program:`RASSCF` keywords, several optional keywords are available within :program:`DMRGSCF`
are listed below. The start and end of the OptimizationSettings input section is given by ::

  OOptimizationSettings
  ...
  EndOOptimizationSettings

.. class:: keywordlist

:kword:`FCIDUMP`
  Skip the wave function optimization and write out the transformed active MO integrals to a :file:`FCIDUMP` file in :file:`$WorkDir` which can be used in subsequent **QCMaquis** DMRG calculations.

  .. xmldoc:: <GROUP MODULE="DMRGSCF" NAME="OOPTIMIZATIONSETTINGS" APPEAR="Orbital optimization settings" KIND="BLOCK" LEVEL="BASIC">

  .. xmldoc:: <INCLUDE MODULE="RASSCF" EXCEPT="VB" />

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="FCIDUMP" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: fcidump <basic>
              <HELP>
              Dump integrals on file FCIDUMP.
              </HELP>
              </KEYWORD>

:kword:`SOCCupy`
  Initial electronic configuration for the calculated state(s). This keyword is equivalent to the :kword:`hf_occ` card in the **QCMaquis** input (see Table 8 of the QCMaquis_ manual), but allows input for multiple states. The occupation is inserted as a string (strings) of aliases of occupations of the active (RAS2) orbitals with the aliases ``2`` = full, ``u`` = up, ``d`` = down, ``0`` = empty. For several states, the occupation strings for each state are separated by newlines.

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="SOCCUPY" KIND="CUSTOM" LEVEL="BASIC">
              %%Keyword: soccupy <basic>
              <HELP>
              Set HF determinant start guess for MPS wave functions.
              </HELP>
              </KEYWORD>

:kword:`NEVPT2prep`
  Prepare for a subsequent DMRG-NEVPT2 or CASPT2 calculation. Then the four- and transition three-particle density matrices (4- and t-3RDMs), required for the MRPT2 calculations, will be evaluated and stored on disk in :file:`$WorkDir`. **QCMaquis** input files for the 4- and t-3RDMs evaluation are prepared and the RDM evaluation may be performed externally or directly in the :program:`NEVPT2` program. More about external RDM evaluation in Section 6.3 of the QCMaquis_ manual.
  If this keyword is used with :kword:`ITER=0,0` keyword, the DMRG-SCF/DMRG-CI calculation is skipped and only **QCMaquis** input files for the 4- and t-3RDMs evaluation are prepared. This is useful for a NEVPT2 calculation for an already converged DMRG-CI/DMRG-SCF calculation.

  .. xmldoc:: <KEYWORD MODULE="DMRGSCF" NAME="NEVPT2PREP" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: NEVPT2prep <basic>
              <HELP>
              Prepare input for higher-order RDM/TDM evaluation.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

Runtime options
---------------

**QCMaquis** is built by default with a shared-memory OMP parallelization. To speed up calculations the user can thus set at runtime the environment variable :variable:`QCMaquis_CPUS` or :variable:`OMP_NUM_THREADS` to the number of shared-memory cores to be used. Example: ::

  >>> EXPORT QCMaquis_CPUS=16

The default is to use a single core.

Input files
-----------

:program:`DMRGSCF` will use (in analogy to :program:`RASSCF`) the following input
files: :file:`ONEINT`, :file:`ORDINT`, :file:`RUNFILE`, :file:`INPORB`,
:file:`JOBIPH`
(for more information see :numref:`UG:sec:files_list`). We strongly recommend to use the HDF5 files
(:file:`$Project.ProgramName.h5`) produced by the wave
function modules in |molcas| as orbital input files, see the keyword :kword:`FILEORB` in the :program:`RASSCF` input,
:numref:`UG:sec:rasscf` for further details.

A number of additional files generated by :program:`SEWARD` are also used by the
:program:`DMRGSCF` program.
The availability of either of the files named :file:`INPORB` and
:file:`JOBOLD` is optional and determined by the input options
:kword:`LUMORB` and :kword:`JOBIPH`, respectively.

.. _UG\:sec\:dmrgscf_output_files:

Output files
------------

.. class:: filelist

:file:`JOBIPH`
  This file is written in binary format and carries the results
  of the wave function optimization such as MO- and CI-coefficients.
  If several consecutive RASSCF calculations are made, the file names will
  be modified by appending "01","02", etc.

:file:`RUNFILE`
  The :file:`RUNFILE` is updated with information from the RASSCF calculation
  such as the first order density and the Fock matrix.

:file:`MD_CAS.x`
  Molden input file for molecular orbital analysis for MPS state x.

:file:`RASORB`
  This ASCII file contains molecular orbitals, occupation numbers, and
  orbital indices from a :program:`DMRGSCF` calculation. The natural orbitals
  of individual states in an average-state calculation are also produced,
  and are named :file:`RASORB.1`, :file:`RASORB.2`, etc.

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

:file:`dmrgscf.h5`
  This .h5 file contains contains molecular orbitals, occupation numbers, and
  orbital indices from a :program:`DMRGSCF` calculation. In addition, it stores the names of the **QCMaquis** output files.

:file:`checkpoint_state.x.h5`
  Directory containing the MPS for state x.

:file:`results_state.x.h5`
  File containing the MPS optimization information and property data calculated for state x.

Input example
-------------

The following example shows the input to the
:program:`DMRGSCF` program for a calculation on the nitrogen molecule. The calculation is
performed in :math:`D_{2h}` symmetry. The :kword:`max_bond_dimension` is set to 100, which is sufficient
for a small CAS(6,6) problem. ::

  &GATEWAY
   coord
   2
  angstrom
   N       0.000000  0.000000  -0.54880
   N       0.000000  0.000000   0.54880
   basis=cc-pvdz
  &SEWARD
  &SCF
  &DMRGSCF
  ActiveSpaceOptimizer=QCMaquis
  DMRGSettings
    conv_thresh        = 1e-4
    truncation_final   = 1e-5
    ietl_jcd_tol       = 1e-6
    nsweeps            = 4
    max_bond_dimension = 100
  EndDMRGSettings
  OOptimizationSettings
    inactive = 2 0 0 0 2 0 0 0
    RAS2     = 1 1 1 0 1 1 1 0
    ITER     = 15,100
    SOCC     = 2,2,2,0,0,0
    LINEAR
  EndOOptimizationSettings

.. xmldoc:: </MODULE>
