.. index::
   single: Program; RASSCF
   single: RASSCF

.. _UG\:sec\:rasscf:

:program:`rasscf`
=================

.. only:: html

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

.. xmldoc:: <MODULE NAME="RASSCF">
            %%Description:
            <HELP>
            The RASSCF program generates CASSCF, RASSCF, GASSCF and Stochastic-CASSCF type wave functions.
            It requires the one- and two-electron integral files generated by
            SEWARD, and starting orbitals from either a previous RASSCF
            calculation or from any of the other wave function generating programs,
            or from the GUESSORB facility.
            The RASSCF module can be used also for Multiconfiguration
            Pair-Density Functional Theory (MC-PDFT) calculations.
            The resulting orbitals can be visualized, e.g. by LUSCUS.
            </HELP>

The :program:`RASSCF` program in |molcas| performs
multiconfigurational SCF calculations using the Complete Active Space (CAS) :cite:`caspek1,Roos:87`, Restricted Active
Space (RAS) :cite:`raspek` or the Generalized Active Space (GAS) :cite:`gas2011` SCF construction of the wave function.

Within the :program:`RASSCF` program in |molcas| Stochastic-CASSCF calculations can be performed :cite:`limanni2016`.
The Stochastic-CASSCF method allows for CASSCF calculations with a large active space selection (calculations with about
40 electrons and 40 orbitals have been reported) :cite:`limanni2016,limanni2018,limanni2019`.

The RASSCF 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:** These orbitals are subdivided into three separate
  groups:

  * **RAS1 orbitals:** Orbitals that are doubly occupied except for
    a maximum number of holes allowed in this orbital subspace.

  * **RAS2 orbitals:** In these orbitals all possible occupations are
    allowed (former Complete Active Space orbitals).

  * **RAS3 orbitals:** Orbitals that are unoccupied except for
    a maximum number of electrons allowed in this subspace.

CASSCF (or Stochastic-CASSCF) calculations can be performed with the program, by allowing
orbitals only in the RAS2 space. For building more general GASSCF wave functions read the dedicated section below.

A single reference SDCI wave function is obtained by allowing a maximum of 2 holes in RAS1 and a maximum of
2 electrons in RAS3, while RAS2 is empty (the extension to SDT- and SDTQ-CI is
obvious). Multireference CI wave functions can be constructed by adding orbitals also in RAS2.

The :program:`RASSCF` program is based on the split GUGA formalism.
However, it uses determinant based algorithms to solve the configuration
interaction problem :cite:`rasdet`. To ensure a proper spin function,
the transformation to a determinant basis is only performed in the
innermost loops of the program to evaluate the :math:`\sigma`\-vectors in the
Davidson procedure and to compute the two-body density matrices.
The upper limit to the size of the CASSCF wave function that can be
handled with the present program is about :math:`10^7` CSFs and is,
in general, limited by the dynamic work array available to the
program. The GUGA formalism is available both for CAS, RAS and GAS wave functions.

The orbital optimization in the :program:`RASSCF` program is performed
using the super-CI method. The reader is referred to the
references :cite:`raspek,caspek3` for more details.
A quasi-Newton (QN) update method is used in order to improve
convergence. No explicit CI-orbital coupling is used in the present
version of the program, except for the coupling introduced in the QN
update.

Convergence of the orbital optimization procedure is normally good for
CASSCF type wave functions, but problems can occur in calculations on
excited states, especially when several states are close in energy.
In such applications it is better to optimize the orbitals for the
average energy of several electronic states.
Further, convergence can be slower in some cases when orbitals in RAS1
and RAS3 are included. The program is not optimal for SDCI
calculations with a large number of orbitals in RAS1 and RAS3.
Also for the GASSCF variant a slower convergence might occur.

As with other program modules, please observe that the input is preprocessed
and may therefore differ in some respects to the input file prepared by the
user. In most cases, this does not imply any functional changes as
compared to the user's requests. However, when the input
has some minor mistakes or contradictory requests, it can be modified
when it is felt that the correction is beneficial. Also, see below for
the keyword :kword:`EXPERT`. Without this keyword, the program is
assuming more flexibility to optimize the calculation, e.g. by using
CIRESTART, if the RASSCF module is called during a numerical differentiation,
even if the input requested doing CI calculations from scratch.
Using keyword :kword:`EXPERT`, such automatic modification of the
user's input is no longer done, and the input is obeyed exactly (when
possible).

It is best to provide a set of good input orbitals.
(The program can be started from scratch by using :kword:`CORE`,
but this should be used only if other possibilities fail).
They can either be from some
other type of calculation, for example :program:`SCF`, or generated by
:program:`GUESSORB`, or from a previous
:program:`RASSCF` calculation on the same system. In the first case the
orbitals are normally given in formatted form, file :file:`INPORB`, in the
second case they can also be read from a :program:`RASSCF` input unit
:file:`JOBOLD`.
Input provides both possibilities. Some care has to be taken in choosing the
input orbitals, especially for the weakly occupied ones. Different choices
may lead to convergence to different local minima. One should therefore make
sure that the input orbitals have the correct general structure. A good strategy
is often to start using a smaller basis set (MB or DZ) and once the orbitals
have been defined, increase the basis set and use :program:`EXPBAS` to generate
input orbitals.

When we speak of files like :file:`INPORB` or :file:`JOBIPH`, please note that
these can be regarded as generic names. You may have various files with different
file names available, and when invocating the :program:`RASSCF` program, these
can be linked or copied (See EMIL command LINK and COPY) so that the program
treats them as having the names INPORB or JOBIPH. Alternatively, by the keywords
:kword:`FILEORB` and :kword:`IPHNAME`, you can instruct the program to use
other file names.

There are two kinds of specifications to make for orbitals: One is the coefficient
arrays that describe the molecular orbitals, commonly called "CMO data". The other
kind is the number of inactive, RAS1, etc. orbitals of each symmetry type, which
will be called "orbital specifications". The
program can take either or both kinds of data from :file:`INPORB`, :file:`JOBIPH`
or runfile. The program selects where to fetch such data, based on rules and
input keywords. Avoid using conflicting keywords: the program may sometimes go
ahead and resolve the problem, or it may decide to stop, not to risk wasting
the user's time on a calculation that was not intended. This decision may be
in error.

The orbital specification by keyword input is easy: See keywords :kword:`FROZEN`,
:kword:`INACTIVE`, etc. If any such keyword is used, then all the orbital
specifications are assumed to be by input, and any such input that is lacking
is determined by default rules. These are
that there are no such orbitals, with the exception of
:kword:`DELETED`: If earlier calculations deleted some orbitals for reason of
(near) linear dependence, then these will continue being deleted in subsequent
calculations, and cannot be "undeleted". Another special case occurs if both
:kword:`CHARGE` and :kword:`NACTEL` are given in the input and there is no
symmetry, then the default value of :kword:`INACTIVE` will be automatically
determined.

If no such keyword has been given, but keyword :kword:`LUMORB` is used to instruct
the program to fetch CMO data from :file:`INPORB`, then also the orbitals specs
are taken from :file:`INPORB`, if (as is usually the case) this file contains
so-called **typeindex** information. The :program:`LUSCUS` program may have been
used to graphically view orbital pictures and pick out suitable active orbitals,
etc., producing a file with extension ".GvOrb". When this is used as :file:`INPORB`
file, the selected orbitals will be picked in the correct order.

An :file:`INPORB` file with typeindex can also be used to provide orbital specs while
the CMO data are taken from another source (:file:`JOBOLD`, :file:`RUNFILE`, ...).
This is achieved by :kword:`TYPEINDEX`, and you can look in the manual for this
keyword to see an explanation of how the typeindex is written. (This is usually
done by the program generating the file, but since these are ASCII files, you may
find it expedient to look at, or edit, the typeindex).

In case both keywords, such as :kword:`INACTIVE`, **and** :kword:`LUMORB`, is
given, this is of course the very common case that CMO data are read from :file:`INPORB`
but orbital specs are given by input. This is perhaps the most common usage.
However, when the :file:`INPORB` file is a produced by :program:`GV`, it happens
frequently that also keyword specs are left in the input, since the user knows
that these merely duplicate the specs in :file:`INPORB`. But the latter may also
imply a reordering of the orbitals.
For this reason, when the keyword input merely duplicates the number of
inactive, etc., that is also specified by typeindex, then the typeindex input
overrides, to produce the correct ordering. If they do **not** match precisely,
then the CMO data are read, without reordering, and the keyword input (as usual)
takes precedence.

The CMO data are obtained as follows:
With the following keywords, it is assumed that the user knows what he wants.

* :kword:`CORE`: (A bad choice, but here for completeness). Creates orbitals
  from scratch.
* :kword:`LUMORB` or :kword:`FILEORB`: Try :file:`INPORB`, or fail.
* :kword:`JOBIPH`: Try :file:`JOBOLD`, if not usable, try :file:`JOBIPH`, or fail.

If none of these keywords were used, then the user accepts defaults, namely

* look for RASSCF orbitals on :file:`RUNFILE`
* look for SCF orbitals on :file:`RUNFILE`
* look for GUESSORB orbitals on :file:`RUNFILE`
* If still nothing found, create orbitals from scratch.

As for earlier versions, notice the possibility
to read the orbitals on :file:`JOBIPH`, at a later time, by using
the keywords :kword:`OUTOrbital` and :kword:`ORBOnly`. This results in
editable ASCII files, with names like :file:`Project.RasOrb` (or :file:`Project.RasOrb5`
for the fifth root). Such orbitals will be produced by default for the lowest
roots --- up to the tenth, named now, e.g., :file:`Project.RasOrb.5`. There is a keyword :kword:`MAXORB`
to produce more (or fewer) such files.

The :program:`RASSCF` program has special input options, which will limit the degrees of
freedoms used in the orbital rotations. It is, for example, possible to impose
averaging of the orbital densities in :math:`\pi` symmetries for linear molecules.
Use the keyword :kword:`Average` for this purpose. It is also
possible to prevent specific orbitals from rotating with each other. The
keyword is :kword:`Supsym`. This can be used, for example, when the molecule
has higher symmetry than one can use with the |molcas| system. For example, in
a linear molecule the point group to be used is :math:`C_{2v}` or :math:`D_{2h}`. Both
:math:`\sigma`\- and :math:`\delta`\-orbitals will then appear in irrep 1. If the input
orbitals have been prepared to be adapted to linear symmetry, the
:kword:`Supsym` input can be used to keep this symmetry through the iterations.
The program will do this automatically with the use of the
input keyword :kword:`LINEAR`. Similarly, for single atoms, spherical
symmetry can be enforced by the keyword :kword:`ATOM`.

.. _UG\:sec\:core-hole:

States with a core hole
-----------------------

.. compound::

  For stable calculation of states with a deep hole, e.g. for X-ray transitions, one needs to compute
  a (number of) states with a core hole, and a (number of) states without the core hole, with quite
  different orbitals, and then presumably combine these states in a RASSI calculation. The core-hole
  state(s) cannot be computed in the same calculation as the full-core states, since they will be very highly excited states
  compared to the states without that hole. There is also the problem of preventing orbital optimization
  from filling the core hole. In order to make the calculation in a way that is stable, also across
  calculations with changing geometry, there is a special input to :program:`RASSCF`.
  The option :kword:`CRPR` stands for "core projection", and is followed by two numbers, e.g. as ::

      CRPR
        1   33.0

  which has the effect of selecting one orbital, in this case orbital nr. 1, from the starting orbitals.
  This orbital should be in symmetry 1, a non-degenerate orbital, doubly occupied in the state without
  core hole. A projection operator is constructed from the AO basis set, and in the subsequent
  CI calculations, in each new iteration of the orbital optimizer, this operator is multiplied with
  a shift, in this case 33.0 a.u., and added to the Hamiltonian. Regardless of the changing
  orbitals, this operator is defined by the stable AO basis, and any configuration where the core
  orbital is doubly occupied is shifted upwards in energy, above the core hole states, and are
  prevented from playing any role in the calculation. The converged solution(s) are used in a
  subsequent RASSI, for instance (then with the unperturbed Hamiltonian, of course), where it is
  combined with states without core hole, for energies and transition properties.

The perturbation on the core hole states by the projection shift is small, provided that the
basis set is able to to include the core relaxation effect, and the subsequent RASSI is
helpful in correcting for any effects of the perturbation since it will anyway compute
eigenstates which are non-interacting and orthogonal by state mixing.

.. _UG\:sec\:StochasticCAS:

Stochastic-CASSCF method
------------------------

.. warning::

   This program requires an external package to run.

The Stochastic-CASSCF :cite:`limanni2016` has been developed since 2015 by Li Manni and Alavi,
initially into a locally modified version of |molcas| and now available in |openmolcas|.
The method retains the simplicity of CASSCF, while circumventing the exponential scaling of CAS wave functions.
This is obtained by replacing the Davidson diagonalization technique, in its direct-CI implementation (default in |molcas|),
with the full-CI quantum Monte-Carlo (FCIQMC) algorithm :cite:`Alavi2009`, whilst the Super-CI method is used
for the orbital optimization.

The method is compatible with density fitting techniques available within
|openmolcas|, subsequent MC-PDFT calculations to recover correlation
outside the active space and state-averaging across multiple multiplicities.

.. _UG\:sec\:StochCAS_dependencies:

Dependencies
............

In addition to the normal :program:`RASSCF` dependencies, the Stochastic-CASSCF requires that the :program:`NECI` program is installed externally
(the :program:`NECI` program can also be embedded into |openmolcas|. This form of installation is however not fully developed and not suggested).
For the :program:`NECI` program a parallel installation (using MPI) is assumed as well as the use of hdf5 libraries to store and process
the walker population. Using the FCIQMC algorithm the user will produce one- and two-body density matrix files (:file:`ONERDM`, :file:`TwoRDM_XXXX`), that are required for the subsequent orbital optimization step.

.. _UG\:sec\:StochCAS_InpOutFiles:

Input/Output Files
..................

Two files are produced by the :program:`RASSCF` module at each MCSCF macro-iteration when the Stochastic-CASSCF method is used (in addition to the one produced by default by :program:`RASSCF`). These files are:

.. class:: filelist

:file:`FCIINP`
  The :file:`$Project.FciInp` (or :file:`FCIINP`) file contains input keywords for the :program:`NECI` code.
  These keywords need to be adjusted depending on the chemical system under investigation for an optimal FCIQMC dynamics.

:file:`FCIDMP`
  The :file:`$Project.FciDmp` (or :file:`FCIDMP`), also know as FCIDUMP, contains the MO integrals in the active space.
  It is a ASCII formatted file. Indices are sorted by symmetry (Irrep).

The Input and the FCIDUMP files are the only files necessary to :program:`NECI` to run a FCIQMC simulation from scratch.
For questions about the FCIQMC dynamics we invite to contact its developers.

As accurate density matrices are necessary for a successful Stochastic-CASSCF
calculation, users are required to use the :file:`dneci.x` and :file:`mneci.x`
binaries (this will run the FCIQMC dynamic in replica mode) :cite:`Overy2014`.
The FCIQMC dymanics can be followed in the :file:`fciqmc.out` output file or in
the :program:`NECI` generated :file:`FCIMCStats` file. In the
:file:`fciqmc.out` file there are important pieces of information, such as the list
of Slater determinants dominating the FCI wave function and the RDM energy. The
latter is passed to |openmolcas| as shown in the script below. When a stationary
condition is reached and density matrices sampled these are passed to the
:file:`RASSCF` program to continue.
This can be achieved by a simple script, such as the following: ::

  cp TwoRDM_aaaa.1 $WorkDir/$Project.TwoRDM_aaaa
  cp TwoRDM_abab.1 $WorkDir/$Project.TwoRDM_abab
  cp TwoRDM_abba.1 $WorkDir/$Project.TwoRDM_abba
  cp TwoRDM_bbbb.1 $WorkDir/$Project.TwoRDM_bbbb
  cp TwoRDM_baba.1 $WorkDir/$Project.TwoRDM_baba
  cp TwoRDM_baab.1 $WorkDir/$Project.TwoRDM_baab
  cp   OneRDM.1    $WorkDir/$Project.OneRDM
  grep 'REDUCED D' fciqmc.out | sed "s/^.*: //" > NEWCYCLE
  mv NEWCYCLE $WorkDir/.

When performing state-averaging, the user has to ensure that the ordering of
all roots is consistent between |openmolcas| and :program:`NECI`. For instance, consider a
SA-CASSCF on a system admitting 2 doublets, 4 quartets, 3 sextets, 2 octets and
1 dectet. Using the :file:`FCIDUMP` provided by |openmolcas| (multiplicity in the |openmolcas|
input is disabled for these calculations, but should nevertheless be provided),
one can complete the :program:`NECI` dynamics, afterwards |openmolcas| will prompt for 12
consecutively numbered density matrices and energies, i.e.: ::

  When finished do:
     cp TwoRDM_* /$YOUR_WORKDIR/
     echo $your_RDM_Energy > /$YOUR_WORKDIR/NEWCYCLE

A shell script which also takes care of renaming the RDMs might look
like this: ::

  export CALCBASE="location of your calculation"
  export YOUR_WORKDIR="location of your scratch"

  cd $CALCBASE/neci-doublet/  # contains roots 1 and 2
  grep '*REDUCED' $YOUR_INPUT.out | awk '{ print $9 }' >> $CALCBASE/NEWCYCLE

  cd $CALCBASE/neci-quartet/  # contains roots 3 to 6
  grep '*REDUCED' mn3o4.out | awk '{ print $9 }' >> $CALCBASE/NEWCYCLE
  # reverse order required, otherwise redundant rename
  rename .4 .6 *.4; rename .3 .5 *.3 ; rename .2 .4 *.2; rename .1 .3 *.1

  [for the other roots same procedure]

  cd $CALCBASE
  cp neci-doublet/run$1/TwoRDM_* neci-quartet/run$1/TwoRDM_* [other roots] $YOUR_WORKDIR
  cp NEWCYCLE $YOUR_WORKDIR

.. class:: filelist

:file:`$Project.TwoRDM_XXXX`
  These files are ASCII :program:`NECI` generated output files.
  They contain spin-resolved two-body density matrix elements (and one-RDM) and are necessary
  to |molcas| to continue with the Stochastic-CASSSCF calculation.

.. _UG\:sec\:StochCAS_Keywords:

Input keywords
..............

This section describes the input to the Stochastic-CASSCF method in the |openmolcas| program.
Two input keywords are strictly required in the :program:`RASSCF` module for activating the Stochastic-CASSCF:

.. class:: keywordlist

:kword:`NECI`
  This keyword is needed to enable the Stochastic-CASSCF method.

  Additional keywords like ``totalwalkers`` have the same meaning as in :program:`NECI`
  and are just passed on.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NECI" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="DMRG">
              %%Keyword: NECI <advanced>
              <HELP>
              This keyword is used to enable Stochastic-CASSSCF
              calculations and features related to it (such as produce a FCIDUMP file).
              Additional keywords like "totalwalkers" have the
              same meaning as in NECI and are just passed on.
              </HELP>
              </KEYWORD>

:kword:`EMBD`
  This keyword enables the embedded version of the Stochastic-CASSCF where :program:`NECI` runs as subroutine of |molcas|.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="EMBD" APPEAR="Embedded NECI" KIND="SINGLE" LEVEL="ADVANCED" REQUIRE="NECI">
              %%Keyword: EMBD <advanced>
              <HELP>
              This keyword is used jointly to the NECI keyword in the context of the Stochastic-CASSCF method,
              to enable the embedded Stochastic-CASSSCF
              calculations, where NECI runs as subroutine of Molcas.
              </HELP>
              </KEYWORD>

Optional important keywords are:

.. class:: keywordlist

:kword:`DMPO`
  This keyword is used to generate the FCIDUMP file only. The program will deallocate memory and quit in a clean manner.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DMPO" APPEAR="Dump only" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: DMPO <advanced>
              <HELP>
              This keyword is used in the context of the Stochastic-CASSCF method
              to produce a FCIDUMP file in a ASCII format that can be recognized by
              the NECI program and quit in a clean way (no CI or CASSCF calculation will be done).
              </HELP>
              </KEYWORD>

:kword:`DEFD`
  This keyword is used to define an initial Slater determinant as starting guess for the FCIQMC dynamics.
  During the FCIQMC dynamics, if another Slater determinant is more populated (advanced keywords apply) than the guess determinant
  provided, the more populated determinant is used as reference, overwriting the user choice. Possible changes of reference
  determinants can be tracked in the FCIQMC output file. An example of the :kword:`DEFD` keyword follows: ::

    DEFD
      1 2 3 4 5 13 14 17 18 21 22 27 28 29 30 31 32 39 40 41 42 43 51 52 53 54 55 56 63 64 65 66

  It contains a list of the occupied spin-orbitals in the order given by the :file:`INPORB` file (space symmetry sorted).

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DEFD" APPEAR="Define determinant" KIND="STRING" LEVEL="ADVANCED" REQUIRE="NECI">
              %%Keyword: DEFD <advanced>
              <HELP>
              This keyword is used in the context of the Stochastic-CASSCF method
              to provide the FCIQMC algorithm with an initial guess for the reference Slater determinant.
              It is followed (new line) by a string of integers representing spin-orbitals in the order
              given in the INPORB file.
              </HELP>
              </KEYWORD>

:kword:`GUGA`
  Use spin eigenfunctions instead of Slater determinants in the basis for the FCIQMC dynamics to target specific
  spin states and perhaps benefit from sparsity in this basis.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="GUGA" APPEAR="GUGA" KIND="STRING" LEVEL="ADVANCED" REQUIRE="NECI">
              %%Keyword: GUGA <advanced>
              <HELP>
              Use spin eigenfunctions instead of Slater determinants in the basis for the FCIQMC dynamics.
              </HELP>
              </KEYWORD>

:kword:`REOR`
  The user can input a permutation by specifying the number of non
  fixed point elements, followed by the order of the non fixed point elements.

  .. compound::

     If the total number of active orbitals is e.g. 6
     the following example of the :kword:`REOR` keyword::

          REOR
            3
            4 5 1

     leads to an order of ``[4 2 3 5 1 6]``.

  .. compound::

     If GAS is used one can specify -1 as flag::

          REOR
            -1

     to follow the order of GAS spaces.
     This means that the orbitals are ordered by GAS space first
     and by symmetry second.
     First all orbitals of GAS1 and within it orbitals of Irrep 1 come first,
     Irrep 2 next...
     Once all orbitals of GAS1 are exhausted we continue with orbitals of GAS2
     and so on.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="REOR" APPEAR="Reordering orbitals" KIND="STRING" LEVEL="ADVANCED" REQUIRE="NECI">
              %%Keyword: REOR <advanced>
              <HELP>
              The user can input a permutation by specifying the number of non
              fixed point elements, followed by the order of the non fixed point elements.
              If the total number of active orbitals is e.g. 6
              the following example of the REOR keyword

                REOR
                  3
                  4 5 1
              </HELP>
              </KEYWORD>

.. _UG\:sec\:StochCAS_InputExample:

Input Example
.............

A minimal input example for using state-averaged Stochastic-CASSCF jointly with RICD MC-PDFT is shown below: ::

  &GATEWAY
   RICD
   COORD = coor.xyz
   BASIS = ANO-RCC-VTZP
   GROUP = full

  &SEWARD

  &RASSCF
   CIROOT = 2  2  1   * follows standard &RASSCF syntax
   NECI = ExNe
   NACTEL = 26 0 0
   INACTIVE = 20 17 17 14 0 0 0 0
   RAS2 = 0 0 0 0 7 6 6 5
   SYMMETRY = 1

  >>foreach DFT in (T:PBE, T:BLYP, T:LSDA)

     &RASSCF
        FileOrb = $CurrDir/converged.RasOrb
        CIONLY
        KSDFT = ROKS; $DFT
        NECI = ExNe
        NACTEL = 26 0 0
        INACTIVE = 20 17 17 14 0 0 0 0
        RAS2 = 0 0 0 0 7 6 6 5
        SYMMETRY = 1
  >>enddo

.. _UG\:sec\:gasscf:

GASSCF method
-------------

In certain cases it is useful/necessary to enforce restrictions on electronic
excitations within the active space beyond the ones accessible by RASSCF.
These restrictions are meant to remove configurations that contribute only
marginally to the total wave function.
In |molcas| this is obtained by the GASSCF approach :cite:`gas2011`.
GASSCF is a further generalization of the active space concept.
This method, like RASSCF, allows restrictions on the active space,
but they are more flexible than in RASSCF. These restrictions allow GASSCF to be applied to
larger and more complex systems at affordable cost. If the active space is well chosen and the
restrictions are not too severe, MCSCF methods recover most of the static correlation energy,
and part of the dynamic correlation energy. In the GASSCF method, instead
of three active spaces, an in-principle arbitrary number of active spaces (GAS1, GAS2...) may
be chosen by the user. Instead of a maximum number of holes in RAS1 and particles in RAS3,
accumulated minimum and maximum numbers of electrons are specified for GAS1,
GAS1+GAS2, GAS1+GAS2+GAS3, etc. in order to define the desired CI expansion (:numref:`fig:gas`).
All intra-space excitations are allowed (Full-CI in subspaces).
Constraints are imposed by user choice on inter-space excitations.

.. figure:: gas.*
   :name: fig:gas
   :align: center

   Pictorial representation of GAS active space.

When and how to use the GAS approach?
We consider three examples: (1) an organometallic material with separated metal
centers and orbitals not delocalized across the metal centers. One can include
the near degenerate orbitals of each center in its own GAS space.
This implies that one may choose as many GAS spaces as the number of
multiconfigurational centers. (2) Lanthanide or actinide metal compounds where
the :math:`f`-electrons require a MC treatment but they do not participate in bonding
neither mix with :math:`d` orbitals. In this case one can put the :math:`f` orbitals and their
electrons into one or more separated GAS spaces and not allow excitations
from and/or to other GAS spaces. (3) Molecules where each bond and its correlating
anti-bonding orbital could form a separate GAS space as in GVB approach.
Finally, if a wave function with a fixed number of holes in one or more
orbitals is desired, without interference of configurations where those
orbitals are fully occupied the GAS approach is the method of choice instead
of the RAS approach. There is no rigorous scheme to choose a GAS partitioning.
The right GAS strategy is system-specific. This makes the method versatile but
at the same time it is not a black box method.
An input example follows: ::

  &RASSCF
  nActEl
   6 0 0
  FROZen
  0 0 0 0 0 0 0 0
  INACTIVE
  2 0 0 0 2 0 0 0
  GASScf
  3
   1 0 0 0 1 0 0 0
  2 2
   0 1 0 0 0 1 0 0
  4 4
   0 0 1 0 0 0 1 0
  6 6
  DELEted
  0 0 0 0 0 0 0 0

In this example the entire active space counts six active electrons
and six active orbitals. These latter are partitioned in three GAS spaces
according to symmetry consideration and in the spirit of the GVB strategy.
Each subspace has a fixed number of electrons, *two*, and no interspace
excitations are allowed. This input shows clearly the difference
with the RAS approach.
Also for the GASSCF variant a slower convergence might occur.

MC-PDFT method
--------------

The RASSCF module can be used also for 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.
Three translated functionals are currently available: tPBE, tLSDA and tBLYP.
As multiconfigurational wave functions are used as input quantities, spin and space symmetry are correctly conserved.

.. _UG\:sec\:NOCI:

Non-Orthogonal Configuration Interaction
----------------------------------------

.. warning::

   This program requires an external package to run.

|openmolcas| provides an interface to GronOR :cite:`Straatsma2022`, a massively parallel and GPU-accelerated implementation of NOCI and its extension to fragments or ensembles of molecules, NOCI-F.

.. _UG\:sec\:NOCI_dependencies:

Dependencies
............

Running NOCI and NOCI-F calculations requires the external installation of the GronOR program: https://gitlab.com/gronor/gronor.

.. _UG\:sec\:NOCI_InpOutFiles:

Input/Output Files
..................

One extra file is generated for each electronic state considered in the generation of the many-electron basis functions of the NOCI.

.. class:: filelist

:file:`VECDET.x`
  The :file:`$Project.VecDet.x` (or :file:`VECDET.x`) file contains the list of determinants of root :math:`x`. The list contains the CI coefficients and the active orbital occupations.

.. _UG\:sec\:NOCI_Keywords:

Input keywords
..............

The :kword:`PRSD` keyword must be added to the input to expand the CSFs in Slater determinants, which are written to the :file:`$Project.VecDet.x` file. It is highly recommended to decrease the threshold for writing CSFs to the output file (:kword:`PRWF`) to at least 1e-5.

.. _UG\:sec\:NOCI_InputExample:

Input Example
.............

A minimal input example to generate the wave functions that describe the ground state and the first excited singlet state of fragment A. ::

  &GATEWAY
  coord = fragA.xyz
  basis = ano-s-vdz
  group = c1

  * symmetry is not implemented in GronOR

  &RASSCF
  nactel = 6
  inactive = 18
  ras2 = 6
  prwf = 1e-5
  prsd

  >>>> COPY $Project.RasOrb.1 $CurrDir/benzeneA_S0.orb
  >>>> COPY $Project.VecDet.1 $CurrDir/benzeneA_S0.det

  &RASSCF
  nactel = 6
  inactive = 18
  ras2 = 6
  prwf = 1e-5
  prsd
  ciroot = 1 2; 2

  >>>> COPY $Project.RasOrb.2 $CurrDir/benzeneA_S1.orb
  >>>> COPY $Project.VecDet.2 $CurrDir/benzeneA_S1.det

.. _UG\:sec\:rasscf_orbitals:

RASSCF output orbitals
----------------------

The :program:`RASSCF` program produces a binary output file called
:file:`JOBIPH`, which can be used in subsequent calculations. Previously, this
was usually a link, pointing to whichever file the user wanted, or by default
to the file :file:`$Project.JobIph` if no such links had been made. This default
can be changed, see keyword :kword:`NewIph` and :kword:`IphName`.
For simplicity, we refer to this as :file:`JOBIPH` in the manual. The job interface,
:file:`JOBIPH`, contains four different sets of MO's and
it is important to know the difference between the sets:

#. **Average orbitals:**
   These are the orbitals produced in the optimization
   procedure. Before performing the final CI wave function they are
   modified as follows: inactive and secondary orbitals are rotated
   (separately) such as to diagonalize an effective Fock operator, and
   they are then ordered after increasing energy. The orbitals in the
   different RAS subspaces are rotated (within each space separately)
   such that the corresponding block of the state-average density matrix becomes
   diagonal. These orbitals are therefore called "pseudo-natural
   orbitals". They become true natural orbitals only for CAS type wave
   functions. These orbitals are not ordered. The corresponding
   "occupation numbers" may therefore appear in the output in arbitrary
   order. The final CI wave function is computed using these orbitals.
   They are also the orbitals found in the printed output.

#. **Natural orbitals:**
   They differ from the above orbitals, in the active
   subspace. The entire first order density matrix has been diagonalized.
   Note that in a RAS calculation, such a rotation does not in general
   leave the RAS CI space invariant. One set of such orbitals is produced
   for each of the wave functions in an average :program:`RASSCF`
   calculation. The main use of these orbitals is in
   the calculation of one-electron properties. They are extracted by default
   (up to ten roots)
   to the working directory from :file:`JOBIPH` and named :file:`$Project.RasOrb.1`,
   :file:`$Project.RasOrb.2`, etc.
   Each set of MO's is stored together with the
   corresponding occupation numbers. The natural orbitals are identical
   to the average orbitals only for a single state CASSCF wave function.

#. **Canonical orbitals:**
   This is a special set of MO's generated for use in the
   :program:`CASPT2` and :program:`CCSDT` programs.
   They are obtained by a specific input option to the
   :program:`RASSCF` program. They are identical to the above
   orbitals in the inactive and secondary subspaces. The active orbitals
   have been obtained by diagonalizing an effective one-electron
   Hamiltonian, a procedure that leaves the CI space invariant only for
   CAS type wave functions.

#. **Spin orbitals:**
   This set of orbitals is generated by diagonalizing the first order
   spin density matrix and can be used to compute spin properties.

#. **Improved virtual orbitals:**
   This refers only to virtual orbitals, when the :kword:`IVO` keyword is employed
   in the input. In this case, the virtual orbitals are those which diagonalize
   the core Hamiltonian. Since the energies of virtual orbitals become thus undefined,
   the obtained :file:`RASORB` and :file:`JOBIPH` files can **not** be used for CASPT2 or MRCI or any correlated
   calculations. The printed virtual orbitals are quite localized and could be used only to
   decide which ones should be included in an (enlarged) active space in a subsequest
   :program:`RASSCF` calculation.

.. _UG\:sec\:rasscf_dependencies:

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

To start the :program:`RASSCF` module at least the one-electron
and two-electron integrals generated by :program:`SEWARD` have to
be available (exception: See keyword :kword:`ORBONLY`). Moreover, the
:program:`RASSCF` requires a suitable start wave function such as the
orbitals from a RHF-SCF calculation or produced by :program:`GUESSORB`.

For MC-PDFT calculations, it is recommended to use a fine grid via the following input specifications (see the :program:`SEWARD`, :numref:`UG:sec:seward`, for details): ::

  &SEWARD
  grid input
  grid=ultrafine
  end of grid input

CI coefficients are needed to generate one- and two-body density matrices. They are usually pre-optimized vectors passed to the :program:`RASSCF` module via :program:`EMIL` command: ::

  >>> COPY $WorkDir/$Project.JobIph JOBOLD

A pre-optimized CI vector is not compulsory; however, it is recommended to use a pre-optimized CI vector stored in a :file:`JOBIPH` file.
A set of input orbitals is required. They may be stored in :file:`JOBIPH` or in a formatted :file:`INPORB` file.

.. _UG\:sec\:rasscf_files:

Files
-----

.. _UG\:sec\:rasscf_inp_files:

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

:program:`RASSCF` will use the following input
files: :file:`ONEINT`, :file:`ORDINT`, :file:`RUNFILE`, :file:`INPORB`,
:file:`JOBIPH`
(for more information see :numref:`UG:sec:files_list`).

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

.. _UG\:sec\:rasscf_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 CI root x.

:file:`RASORB`
  This ASCII file contains molecular orbitals, occupation numbers, and
  orbital indices from a :program:`RASSCF` 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.).

.. _UG\:sec\:rasscf_inp:

Input
-----

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

  &RASSCF

There are no compulsory keywords, but almost any meaningful calculation
will require some keyword. At the same time, most choices have default
settings, and many are able to take relevant values from earlier
calculations, from available orbital files, etc.

To run an MC-PDFT calculation in the :program:`RASSCF` module, the keywords :kword:`CIONLY`, :kword:`KSDFT`,
:kword:`ROKS` and the functional choice are needed. The currently available functionals are tPBE,
tBLYP and tLSDA. Also: :kword:`LUMORB` is needed if external orbitals are used.
:kword:`JOBIPH` is needed if external orbital stored in :file:`JobIph` files are used.
:kword:`CIRESTART` is needed if a pre-optimized CI vector stored in :file:`JOBIPH` is to be used.

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

There is a large number of optional keywords you can specify. They are
used to specify the orbital spaces, the CI wave function etc., but also
more arcane technical details that can modify e.g. the convergence or
precision. The first 4 characters of the keyword are recognized by the
input parser and the rest is ignored. If not otherwise stated the numerical
input that follows a keyword is read in free format.
A list of these keywords is given below:

.. class:: keywordlist

:kword:`TITLe`
  Follows the title for the calculation in a single line

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="TITLE" KIND="STRING" LEVEL="BASIC">
              %%Keyword: TITLe <basic>
              <HELP>
              Follows the title in a single line
              </HELP>
              </KEYWORD>

:kword:`SYMMetry`
  Specify the selected symmetry type (the irrep) of the wave
  function as a number between 1 and 8 (see SYMMETRY keyword in GATEWAY section). Default is 1, which always
  denote the totally symmetric irrep.

  .. xmldoc:: <GROUP MODULE="RASSCF" NAME="SPIN/SYMMETRY" KIND="BOX">

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="SYMMETRY" APPEAR="Symmetry" LEVEL="BASIC" KIND="INT" DEFAULT_VALUE="1" MIN_VALUE="1" MAX_VALUE="8">
              %%Keyword: SYMMetry <basic>
              <HELP>
              Specify symmetry type (irrep) as a number between 1 and 8. Default is 1.
              </HELP>
              </KEYWORD>

:kword:`SPIN`
  The keyword is followed by an integer giving the value of spin
  multiplicity (:math:`2S+1`). Default is 1 (singlet).

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="SPIN" APPEAR="Spin" LEVEL="BASIC" KIND="INT" DEFAULT_VALUE="1" MIN_VALUE="1">
              %%Keyword: SPIN <basic>
              <HELP>
              The keyword is followed by an integer giving the value of spin
              multiplicity (2S+1). Default is 1 (singlet).
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`CHARge`
  Specify the total charge on the system as an integer. If this keyword is used, the
  :kword:`NACTEL` keyword should not be used, unless the symmetry group is C1 and
  :kword:`INACTIVE` is not used (in this case the number of inactive orbitals will
  be computed from the total charge and active electrons). Default value: 0

  .. xmldoc:: <GROUP MODULE="RASSCF" NAME="TOTALCHARGE" KIND="BOX">

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CHARGE" LEVEL="BASIC" APPEAR="Charge" KIND="INT" DEFAULT_VALUE="0">
              %%Keyword: CHARge <basic>
              <HELP>
              Specify the total charge of the system as an integer.
              </HELP>
              </KEYWORD>

:kword:`RASScf`
  Specify two numbers: maximum number of holes in RAS1 and the maximum number of electrons
  occupying the RAS3 orbitals
  Default values are: 0,0
  See also keyword :kword:`CHARGE` and :kword:`NACTEL`. The specification using
  :kword:`RASSCF`, and :kword:`CHARGE` if needed, together replace the single keyword
  :kword:`NACTEL`.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="RASSCF" LEVEL="BASIC" APPEAR="Allow RAS holes/electrons" KIND="INTS" SIZE="2" EXCLUSIVE="NACTEL" MIN_VALUE="0">
              %%Keyword: RASScf <basic>
              <HELP>
              Specify two numbers: maximum number of RAS1 holes, and maximum number of RAS3 electrons.
              </HELP>
              </KEYWORD>

:kword:`NACTel`
  Requires one or three numbers to follow, specifying

  #. the total number of active electrons
     (all electrons minus twice the number of inactive and frozen orbitals)
  #. the maximum number of holes in RAS1
  #. the maximum number of electrons occupying the RAS3 orbitals

  If only one number is given, the maximum number of holes in RAS1 and of electrons in RAS3 are both set to zero.
  Default values are: x,0,0, where x is the number needed to get a neutral system.
  See also keywords :kword:`CHARGE` and :kword:`RASSCF`, which offer an alternative specification.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NACTEL" LEVEL="BASIC" APPEAR="Active electrons" KIND="INTS" SIZE="3" EXCLUSIVE="RASSCF" MIN_VALUE="0">
              <ALTERNATE KIND="INT" />
              %%Keyword: NACTel <basic>
              <HELP>
              Specify three numbers: total number of active electrons,
              maximum number of RAS1 holes, and maximum number of RAS3 electrons.
              </HELP>
              </KEYWORD>

:kword:`STAVerage`
  Specifies the number of roots to include in a state-average calculation.
  This is a simplified for of the :kword:`CIROot` keyword, and ``STAVerage = n`` is equivalent to ``CIROot = n n 1`` (see below).
  Only one of :kword:`STAverage` and :kword:`CIROot` should be given.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="STAVERAGE" APPEAR="State average" LEVEL="BASIC" KIND="INT" EXCLUSIVE="CIROOT" DEFAULT_VALUE="1" MIN_VALUE="1">
              %%Keyword: STAVerage <basic>
              <HELP>
              The keyword is followed by an integer giving the number of roots
              to include in a state-average calculation.
              STAV=N is equivalent to (and incompatible with) CIROOT=N N 1
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`CIROot`
  Specifies the CI root(s) and the dimension of
  the starting CI matrix used in the CI Davidson procedure. This input
  makes it possible to perform orbital optimization for the average
  energy of a number of states. The first line of input gives two or three
  numbers, specifying the number of roots used in the average
  calculation (NROOTS), the dimension of the small CI matrix in
  the Davidson procedure (LROOTS), and possibly a non-zero integer IALL.
  If IALL\ :math:`\ne`\1 or there is no IALL, the second line gives the index of
  the states over which the average is taken (NROOTS numbers,
  IROOT). **Note** that the size of the CI matrix, LROOTS, must be at least as
  large as the highest root, IROOT. If, **and only if**, NROOTS\ :math:`>`\1 a third
  line follows, specifying the weights of the different states in the average
  energy. If IALL=1 has been specified, no more lines are read. A state average
  calculation will be performed over the NROOTS lowest states with equal weights.
  energy. Examples: ::

    CIRoot= 3 5; 2 4 5; 1 1 3

  The average is taken over three states corresponding to roots 2, 4, and
  5 with weights 20%, 20%, and 60%, respectively. The size of the
  Davidson Hamiltonian is 5. Another example is: ::

    CIRoot= 19 19 1

  A state average calculation will be performed over the 19 lowest states each
  with the weight 1/19
  Default values are NROOTS = LROOTS = IROOT = 1 (ground state), which is the same
  as the input: ::

    CIRoot= 1 1; 1

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CIROOT" LEVEL="BASIC" APPEAR="CI root(s)" KIND="CUSTOM" SIZE="3" EXCLUSIVE="STAVERAGE">
              %%Keyword: CIROot <basic>
              <HELP>
              Specifies the CI root(s) and the dimension of the
              starting CI matrix used in the CI Davidson procedure.
              This input makes it possible to perform orbital
              optimization for the average energy of a number of
              states. The first line of input gives two or three
              numbers, specifying the number of roots used in the
              average calculation (NROOTS), the dimension of the
              small CI matrix in the Davidson procedure (LROOTS),
              and possibly a non-zero integer IALL. If IALL.ne.1 or
              there is no IALL, the second line gives the index of
              the states over which the average is taken (NROOTS
              numbers,IROOT). Note, that the size of the CI matrix,
              LROOTS, must be at least as large as the highest root,
              IROOT. If, and only if, NROOTS > 1 a third line follows,
              specifying the weights of the different states in the
              average energy. If IALL=1 has been specified, no more
              lines are read. A state average calculation will be
              performed over the NROOTS lowest states with equal
              weights.
              </HELP>
              </KEYWORD>

:kword:`PPT2`
  Prepare stochastic CASPT2 in pseudo-canonical orbitals.
  This keyword will cause a transformation of the output :file:`RasOrb` to
  pseudo-canonical orbitals, equivalent to ``OUTO = canonical``.

  The performance of FCIQMC depends significantly on the orbital basis. In
  the pseudo-canonical basis, sampling the contraction of the (diagonal) Fock
  matrix with the 7-index 4RDM is cheaper than in non-canonical orbitals; however,
  converging FCIQMC may take a (very) high number of walkers.
  Sampling in a non-diagonal basis is highly recommended, refer to the :kword:`NDPT`
  keyword for more information.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="PPT2" LEVEL="ADVANCED" APPEAR="FCIQMC-CASPT2" KIND="SINGLE">
              %%Keyword: PPT2 <ADVANCED>
              <HELP>
              Prepare the active-active block of the generalized Fock matrix
              and a corresponding FCIDUMP for CASPT2 in the pseudo-canonical
              basis.
              </HELP>
              </KEYWORD>

:kword:`NDPT`
  Prepare stochastic CASPT2 in any orbital basis. A :file:`fockdump.h5` file
  will be dumped to the :file:`WorkDir` which can be used with the same :file:`FCIDUMP`
  as used for the last CASSCF iteration to perform stochastic-CASPT2.

  The performance of FCIQMC depends to a large degree on the orbital basis and
  working in a non-pseudo-canonical orbital basis may alleviate the burden to
  converge the dynamics significantly. This comes at the price of higher
  computational requirements for the contraction of the full 4RDM with the
  non-diagonal Fockian. In practice, this expense is compensated for by
  requiring one to two orders of magnitude fewer walkers compared to canonical
  orbitals.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NDPT" LEVEL="ADVANCED" APPEAR="Non-diagonal FCIQMC-CASPT2" KIND="SINGLE">
              %%Keyword: NDPT <ADVANCED>
              <HELP>
              Prepare the generalized Fock matrix in any orbital basis
              for stochastic CASPT2. Mutually exclusive with the PPT2 keyword.
              </HELP>
              </KEYWORD>

:kword:`MCM7`
  Use the M7 package instead of NECI to perform the CI step in the
  stochastic-CASSCF interface. Currently no multi-root functionality
  is implemented.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="MCM7" LEVEL="BASIC" APPEAR="FCIQMC-M7" KIND="SINGLE">
              %%Keyword: MCM7 <BASIC>
              <HELP>
              Use the M7 package to perform the CI step in the stochastic-CASSCF interface.
              Currently no multi-root functionality is implemented.
              </HELP>
              </KEYWORD>

:kword:`RGRA`
  Compute the norm of the orbital gradient for each CI root instead of just
  for the root specified in geometry optimization.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="RGRA" LEVEL="BASIC" APPEAR="Root Gradients" KIND="SINGLE">
              %%Keyword: RGRA <BASIC>
              <HELP>
              Compute the CI-root-resolved orbital gradient.
              </HELP>
              </KEYWORD>

:kword:`WRMA`
  Dump the 1RDM and (anti)symmetrised 2RDM arrays to disk.
  These matrices can be used in conjunction with the GUGA-FCIQMC interface
  to create deterministic reference calculations for state-averaged CASSCF across
  different spin multiplicities. Works only for one root per spin sector per
  calculation.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="WRMA" LEVEL="BASIC" APPEAR="Write matrices" KIND="SINGLE">
              %%Keyword: WRMA <BASIC>
              <HELP>
              Dump the 1RDM DMAT and (anti)symmetrised PSMAT/PAMAT arrays for a single
              CASSCF root to disk.
              </HELP>
              </KEYWORD>

:kword:`SSCR`
  Computes the orbital resolved spin-correlation function between two ranges of
  orbitals. For physically meaningful results prior localisation and sorting by
  atomic sites is required. The latter step is not performed by the
  :program:`Localisation` module and must be performed manually on the
  :file:`LocOrb` file.

  At least one integer is required, specifying the length of the orbital
  vectors. An optional second integer determines whether the vectors are
  the same (``1``) or different (any other number or no argument). In the latter
  case, both orbital vectors must be specified in the next two lines.

  Consider a triangle with sites A B C, each having three unpaired electrons,
  corresponding to a CAS(9,9). Below, two practical examples are given: ::

    * Spin correlation from orbital 1 to 6, i.e. local spin S_AB expectation value
    * < S_AB > = S_AB (S_AB + 1)
    SSCR = 6 1
    * or
    SSCR = 6
    1 2 3 4 5 6
    1 2 3 4 5 6
    * Spin correlation between sites A (1-3) and C (7-9), i.e < S_A \cdot S_C >
    SSCR = 3
    1 2 3
    7 8 9

  Notice that the numbering is consecutive and each entry in an orbital range
  has to be unique.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="SSCR" LEVEL="BASIC" APPEAR="spin-spin-correlation" KIND="INTS_COMPUTED" SIZE="2">
              <ALTERNATE KIND="INTS" SIZE="2" />
              %%Keyword: SSCR <basic>
              <HELP>
              Calculate the pairwise orbital resolved spin-correlation
              function, for instance between two magnetically coupled centers,
              after localisation and site-ordering of the corresponding
              orbitals. Please consult the manual for further guidance. The
              keyword uses a modified syntax already known from CIROots. At
              least one input is required, specifying the length of the orbital
              vectors. An optional second input determines whether the
              vectors are the same (1) or different (any other or no number).
              In the latter case, both orbital vectors must be
              specified in the following two lines.
              </HELP>
              </KEYWORD>

:kword:`CISElect`
  This keyword is used to select CI roots by an overlap
  criterion. The input consists of three lines per root
  that is used in the CI diagonalization (3*NROOTS lines in total).
  The first line gives the number of configurations used in the comparison,
  :math:`n_{\text{Ref}}`, up to five.
  The second line gives :math:`n_{\text{Ref}}` reference configuration indices.
  The third line gives estimates of CI coefficients for these CSF's.
  The program will select the roots which have the largest overlap with
  this input.
  Be careful to use a large enough value for LROOTS (see above) to cover
  the roots of interest.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CISELECT" LEVEL="ADVANCED" APPEAR="CI select" KIND="UNKNOWN">
              %%Keyword: CISElect <advanced>
              <HELP>
              This keyword is used to select CI roots by an overlap
              criterion. The input consists of three lines per root
              that is used in the CI diagonalization (3*NROOTS lines in total).
              The first line gives the number of configurations used in the comparison,
              nRef, where nRef at most 5.
              The second line gives nRef reference configuration indices.
              The third line gives estimates of CI coefficients for these CSF's.
              </HELP>
              </KEYWORD>

:kword:`CRPRoject`
  This keyword is followed by two numbers, which define a Hamiltonian shift by a
  projection operator times a scalar number. For choosing these numbers, please
  read the section about core hole states above.
  The shift acts to raise the energy of any configuration where the selected
  orbital is doubly occupied so the lie far enough above the target core hole
  states for the duration of the calculation. The purpose is to obtain RASSCF
  states that are properly optimized, yet with no risk of collapsing the core
  hole, for use in subsequent RASSI calculations.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CRPR" LEVEL="ADVANCED" APPEAR="Core project" KIND="STRING">
              %%Keyword: CRPRoject <advanced>
              <HELP>
              This keyword is followed by two numbers, which define a Hamiltonian shift by a
              projection operator times a scalar number. For choosing these numbers (integer
              and real), please read the section about core hole states in the manual for
              the RASSCF program.
              </HELP>
              </KEYWORD>

:kword:`ATOM`
  This keyword is used to get orbitals with pure spherical
  symmetry for atomic calculations (the radial dependence can vary for different
  irreps though). It causes super-symmetry to be
  switched on (see :kword:`SUPSym` keyword) and generates automatically the
  super-symmetry vector needed. Also, at start and after each iteration,
  it sets to zero any CMO coefficients with the wrong symmetry. Use this keyword
  instead of :kword:`SUPSym` for atoms.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ATOM" APPEAR="Purify spherical" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="LINEAR,SUPSYM">
              %%Keyword: ATOM <advanced>
              <HELP>
              This keyword is used to get orbitals with pure spherical
              symmetry for atoms. Use this instead of SUPSYM for single atoms.
              </HELP>
              </KEYWORD>

:kword:`LINEar`
  This keyword is used to get orbitals with pure rotational
  symmetry for linear molecules. It causes super-symmetry to be
  switched on (see :kword:`SUPSym` keyword) and generates automatically the
  super-symmetry vector needed. Also, at start and after each iteration,
  it sets to zero any CMO coefficients with the wrong symmetry. Use this keyword
  instead of :kword:`SUPSym` for linear molecules.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="LINEAR" APPEAR="Purify linear" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="ATOM,SUPSYM">
              %%Keyword: LINEar <advanced>
              <HELP>
              This keyword is used to get orbitals with pure rotational
              symmetry for linear molecules. Use this instead of SUPSYM for linear molecules.
              </HELP>
              </KEYWORD>

:kword:`RLXRoot`
  .. compound::

    Specifies which root to be relaxed in a geometry optimization of a
    state average wave function. Thus, the keyword has to be combined
    with :kword:`CIRO`.
    In a geometry optimization the following input ::

      CIRoot= 3 5; 2 4 5; 1 1 3
      RLXRoot= 4

    will relax CI root number 4.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="RLXROOT" APPEAR="Relaxed root" KIND="INT" LEVEL="ADVANCED">
              %%Keyword: RLXRoot <advanced>
              <HELP>
              Specifies which root to be relaxed in a geometry optimization of a
              state average wave function. Thus, the key word has to be combined
              with CIRO.
              </HELP>
              </KEYWORD>

:kword:`MDRLxroot`
  Selects a root from a state average wave function for gradient computation in
  the first step of a molecular dynamics simulation. The root is specified in
  the same way as in the :kword:`RLXR` keyword. In the following steps the
  trajectory surface hopping can change the root if transitions between the
  states occur. This keyword is mutually exclusive with the :kword:`RLXR` keyword.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="MDRL" APPEAR="Dynamic relaxed root" KIND="INT" LEVEL="ADVANCED">
              %%Keyword: MDRLxroot <advanced>
              <HELP>
              Defines the root for gradient computation in the first step of a
              molecular dynamics simulation. It is used like RLXR keyword except
              that its value is determined by the trajectory surface hopping
              algorithm in the following steps.
              </HELP>
              </KEYWORD>

:kword:`EXPErt`
  This keyword forces the program to obey the input. Normally, the program can
  decide to change the input requests, in order to optimize the calculation.
  Using the :kword:`EXPERT` keyword, such changes are disallowed.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="EXPERT" APPEAR="Expert input" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: EXPErt <advanced>
              <HELP>
              This keyword forces the program to obey the input. Normally, the program can
              decide to change the input requests, in order to optimize the calculation.
              Using the EXPERT keyword, such changes are disallowed.
              </HELP>
              </KEYWORD>

:kword:`RFPErt`
  This keyword will add a constant reaction field perturbation to the
  Hamiltonian. The perturbation is read from the :file:`RUNOLD` (if not present defaults to :file:`RUNFILE`) and
  is the latest self-consistent perturbation generated
  by one of the programs :program:`SCF` or :program:`RASSCF`.

  .. xmldoc:: <GROUP MODULE="RASSCF" NAME="RF" APPEAR="Reaction field" KIND="BOX">

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="RFPERT" APPEAR="Add reaction field" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: RFPErt <advanced>
              <HELP>
              This keyword will add a constant reaction field perturbation to the
              bare nuclei Hamiltonian. The perturbation is read from the
              RUNOLD (if not present defaults to RUNFILE) and is the latest self consistent perturbation generated
              by one of the programs SCF or RASSCF.
              </HELP>
              </KEYWORD>

:kword:`NONEquilibrium`
  Makes the slow components of the reaction field of another state present in the
  reaction field calculation (so-called non-equilibrium solvation). The slow component
  is always generated and stored on file for equilibrium solvation calculations so that
  it potentially can be used in subsequent non-equilibrium calculations on other states.
  If the total charge is greater (i.e., fewer electrons) than that of the reference state,
  for which the slow component was calculated, PCM is initialized with a fake total charge
  equal to the reference one, thus allowing to calculate ionized states.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NONEQUILIBRIUM" APPEAR="Non-equilibrium reaction field" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: NONEquilibrium <advanced>
              <HELP>
              Makes the slow components of the reaction field of another state present in the
              reaction field calculation (so-called non-equilibrium solvation). The slow component
              is always generated and stored on file for equilibrium solvation calculations so that
              it potentially can be used in subsequent non-equilibrium calculations on other states.
              If the total charge is greater (i.e., fewer electrons) than that of the reference state,
              for which the slow component was calculated, PCM is initialized with a fake total charge
              equal to the reference one, thus allowing to calculate ionized states.
              </HELP>
              </KEYWORD>

:kword:`RFROot`
  Enter the index of that particular root in a state-average
  calculation for which the reaction-field is generated. It is used with the PCM model.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="RFROOT" APPEAR="Reaction field root" LEVEL="ADVANCED" KIND="INT">
              %%Keyword: RFROot <advanced>
              <HELP>
              Enter the index number of that particular root in a state-average
              calculation for which the reaction-field is generated. Used with the PCM model.
              </HELP>
              </KEYWORD>

:kword:`CIRFroot`
  Enter the relative index of one of the roots specified in CISElect
  for which the reaction-field is generated. Used with the PCM model.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CIRFROOT" APPEAR="Reaction field CISE root" LEVEL="ADVANCED" KIND="INT">
              %%Keyword: CIRFroot <advanced>
              <HELP>
              Enter the relative index of one of the roots specified in CISElect
              for which the reaction-field is generated. Used with the PCM model.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`NEWIph`
  The default name of the :file:`JOBIPH` file will be determined by any already existing such files
  in the work directory, by appending "01", "02", etc. so a new unique name is
  obtained.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NEWI" LEVEL="ADVANCED" APPEAR="Automatic JOBIPH name" KIND="SINGLE">
              %%Keyword: NEWIph <advanced>
              <HELP>
              The default name of the JOBIPH file will be determined by any already existing such files
              in the work directory, by appending "01", "02", etc. so a new unique name is
              obtained.
              </HELP>
              </KEYWORD>

:kword:`FROZen`
  Specifies the number of frozen orbitals in each symmetry.
  (see below for condition on input orbitals). Frozen
  orbitals will not be modified in the calculation. Only doubly occupied
  orbitals can be left frozen. This input can be used for example for
  inner shells of heavy atoms to reduce the basis set superposition
  error. Default is 0 in all symmetries.

  .. xmldoc:: <GROUP MODULE="RASSCF" NAME="ORBITALS" APPEAR="Orbital spaces" LEVEL="BASIC" KIND="BOX">

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="FROZEN" APPEAR="Frozen" LEVEL="BASIC" KIND="INTS_LOOKUP" SIZE="NSYM" DEFAULT_VALUE="0" MIN_VALUE="0">
              %%Keyword: FROZen <basic>
              <HELP>
              Specifies the number of frozen orbitals in each symmetry.
              (see below for condition on input orbitals). Frozen
              orbitals will not be modified in the calculation. Only doubly occupied
              orbitals can be left frozen. This input can be used for example for
              inner shells of heavy atoms to reduce the basis set superposition
              error. Default is 0 in all symmetries.
              </HELP>
              </KEYWORD>

:kword:`INACtive`
  Specify on the next line the number of inactive (doubly occupied) orbitals in each
  symmetry. Frozen orbitals should not be included here. Default is 0 in
  all symmetries, but if there is no symmetry (C1) and both :kword:`CHARGE` and
  :kword:`NACTEL` are given, the number of inactive orbitals will be calculated
  automatically.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="INACTIVE" APPEAR="Inactive" LEVEL="BASIC" KIND="INTS_LOOKUP" SIZE="NSYM" DEFAULT_VALUE="0" MIN_VALUE="0">
              %%Keyword: INACtive <basic>
              <HELP>
              Specify the number of inactive (doubly occupied) orbitals in each
              symmetry, not counting frozen orbitals. Default is 0 in
              all symmetries.
              </HELP>
              </KEYWORD>

:kword:`RAS1`
  On the next line specify the number of orbitals in each symmetry
  for the RAS1 orbital subspace. Default is 0 in all symmetries.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="RAS1" APPEAR="RAS1" LEVEL="BASIC" KIND="INTS_LOOKUP" SIZE="NSYM" DEFAULT_VALUE="0" MIN_VALUE="0">
              %%Keyword: RAS1 <basic>
              <HELP>
              Specify the number of orbitals in each symmetry
              for the RAS1 orbital subspace. Default is 0 in all symmetries.
              </HELP>
              </KEYWORD>

:kword:`RAS2`
  On the next line specify the number of orbitals in each symmetry
  for the RAS2 orbital subspace. Default is 0 in all symmetries.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="RAS2" APPEAR="RAS2" LEVEL="BASIC" KIND="INTS_LOOKUP" SIZE="NSYM" DEFAULT_VALUE="0" MIN_VALUE="0">
              %%Keyword: RAS2 <basic>
              <HELP>
              Specify the number of orbitals in each symmetry
              for the RAS2 orbital subspace. Default is 0 in all symmetries.
              </HELP>
              </KEYWORD>

:kword:`RAS3`
  On the next line specify the number of orbitals in each symmetry
  for the RAS3 orbital subspace. Default is 0 in all symmetries.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="RAS3" APPEAR="RAS3" LEVEL="BASIC" KIND="INTS_LOOKUP" SIZE="NSYM" DEFAULT_VALUE="0" MIN_VALUE="0">
              %%Keyword: RAS3 <basic>
              <HELP>
              Specify the number of orbitals in each symmetry
              for the RAS3 orbital subspace. Default is 0 in all symmetries.
              </HELP>
              </KEYWORD>

:kword:`DELEted`
  Specify the number of deleted orbitals in each
  symmetry. These orbitals will not be allowed to mix into the occupied
  orbitals. It is always the last orbitals in each symmetry that are deleted.
  Default is 0 in all symmetries, unless orbitals wer already deleted by previous
  programs due to near-linear dependence.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DELETED" LEVEL="BASIC" APPEAR="Deleted" KIND="INTS_LOOKUP" SIZE="NSYM" DEFAULT_VALUE="0" MIN_VALUE="0">
              %%Keyword: DELEted <basic>
              <HELP>
              Specify the number of deleted orbitals in each
              symmetry. Default is normally 0 in all symmetries, but see manual for exception.
              </HELP>
              </KEYWORD>

:kword:`GASScf`
  Needed to perform a Generalized Active Space (GASSCF) calculation.
  It is followed by an integer that defines the number of active subspaces,
  and two lines for each subspace. The first line gives the number of orbitals
  in each symmetry, the second gives the minimum and maximum number of
  electrons in the accumulated active space.

  An example of an input that uses this keyword is the following: ::

    GASSCF
     5
     2 0 0 0 2 0 0 0
     4 4
     0 2 0 0 0 2 0 0
     8 8
     0 0 2 0 0 0 2 0
     12 12
     0 0 0 1 0 0 0 1
     14 14
     4 2 2 1 4 2 2 1
     20 20

  In the example above (20in32), excitations from one subspace to another are not allowed since
  the values of MIN and MAX for GSOC are identical for each of the five subspaces.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="GASSCF" APPEAR="GASSCF" KIND="CUSTOM" LEVEL="ADVANCED">
              %%Keyword: GASSCF <advanced>
              <HELP>
              Needed to perform a Generalized Active Space (GASSCF) calculation.
              It is followed by an integer that defines the number of active subspaces,
              and two lines for each subspace. The first line gives the number of orbitals
              in each symmetry, the second gives the minimum and maximum number of
              electrons in the accumulated active space.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`KSDFT`
  Needed to perform MC-PDFT calculations. It must be used together with
  :kword:`CIONLY` keyword (it is a post-SCF method not compatible with SCF) and :kword:`ROKS` keyword.
  The functional choice follows. Specify the functional by prefixing
  ``T:`` or ``FT:`` to the standard DFT functionals (see keyword :kword:`KSDFT` of :program:`SCF`)
  An example of an input that uses this keyword follows: ::

    &RASSCF
    JOBIPH
    CIRESTART
    CIONLY
    Ras2
    1 0 0 0 1 0 0 0
    KSDFT
    ROKS; T:PBE

  In the above example, :kword:`JOBIPH` is used to use orbitals stored in :file:`JobIph`, :kword:`CIRESTART` is used to
  use a pre-optimized CI vector, :kword:`CIONLY` is used to avoid conflicts between the standard :program:`RASSCF` module
  and the MC-PDFT method (not compatible with SCF so far). The functional chosen is the translated-PBE.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="KSDFT" APPEAR="MC-PDFT" KIND="STRINGS" SIZE="2" LEVEL="ADVANCED" REQUIRE="CIONLY">
              %%Keyword: KSDFT <advanced>
              <HELP>
              Needed to perform MC-PDFT calculations. It must be used together with
              CIONLY keyword (it is a post-SCF method not compatible with SCF) and ROKS keyword.
              The functional choice follows. Currently available functionals are
              prefix T: or FT: to the standard DFT functionals (see keyword KSDFT of SCF program)
              </HELP>
              </KEYWORD>

:kword:`JOBIph`
  Input molecular orbitals are read from an unformatted file with
  FORTRAN file name :file:`JOBOLD`.
  **Note**, the keywords :kword:`Lumorb`, :kword:`Core`, and
  :kword:`Jobiph` are mutually exclusive. If none is given the program will
  search for input orbitals on the runfile in the order: :program:`RASSCF`,
  :program:`SCF`, :program:`GUESSORB`. If none is found, the keyword :kword:`CORE`
  will be activated.

  .. xmldoc:: <GROUP MODULE="RASSCF" NAME="ORBSTART" APPEAR="Starting orbitals" KIND="BOX">

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="JOBIPH" APPEAR="JobIph" KIND="SINGLE" EXCLUSIVE="LUMORB,CORE" LEVEL="BASIC">
              %%Keyword: JOBIph <basic>
              <HELP>
              Get starting molecular orbitals from a binary file called JOBOLD.
              </HELP>
              </KEYWORD>

:kword:`IPHName`
  Override the default choice of name of the :file:`JOBIPH` file by giving the file name you want.
  The name will be truncated to 8 characters and converted to uppercase.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="IPHN" LEVEL="ADVANCED" APPEAR="JobIph Name" KIND="STRING" DEFAULT_VALUE="JOBIPH">
              %%Keyword: IPHName <advanced>
              <HELP>
              Override the default choice of name of the JOBIPH file by giving the file name you want.
              The name will be truncated to 8 characters and converted to uppercase.
              </HELP>
              </KEYWORD>

:kword:`LUMOrb`
  Input molecular orbitals are read from a formatted file with
  FORTRAN file name :file:`INPORB`.
  **Note**, the keywords :kword:`Lumorb`, :kword:`Core`, and
  :kword:`Jobiph` are mutually exclusive. If none is given the program will
  search for input orbitals on the runfile in the order: :program:`RASSCF`,
  :program:`SCF`, :program:`GUESSORB`. If none is found, the keyword :kword:`CORE`
  will be activated.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="LUMORB" APPEAR="Orbitals file" KIND="SINGLE" EXCLUSIVE="CORE,JOBIPH" LEVEL="BASIC">
              %%Keyword: LUMOrb <basic>
              <HELP>
              Get starting molecular orbitals from an ASCII file called INPORB.
              </HELP>
              </KEYWORD>

:kword:`FILEorb`
  Override the default name (:file:`INPORB`) for starting orbital file by giving the file name you want.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="FILE" LEVEL="ADVANCED" APPEAR="Starting orbitals file" KIND="STRING" DEFAULT_VALUE="INPORB">
              %%Keyword: FILEorb <advanced>
              <HELP>
              Override the default name (INPORB) for starting orbital file by giving the file name you want.
              </HELP>
              </KEYWORD>

:kword:`CORE`
  Input molecular orbitals are obtained by diagonalizing the core Hamiltonian.
  This option is only recommended in simple cases. It often leads to divergence.
  **Note**, the keywords :kword:`Lumorb`, :kword:`Core`, and
  :kword:`Jobiph` are mutually exclusive.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CORE" APPEAR="Core Hamiltonian" KIND="SINGLE" EXCLUSIVE="LUMORB,JOBIPH" LEVEL="BASIC">
              %%Keyword: CORE <basic>
              <HELP>
              Get starting molecular orbitals by diagonalizing the core Hamiltonian.
              Not recommended.
              </HELP>
              </KEYWORD>

:kword:`ALPHaOrBeta`
  With UHF orbitals as input, select alpha or beta as starting orbitals. A positive value selects alpha,
  a negative value selects beta. Default is 0, which fails with UHF orbitals. This keyword does not
  affect the spin of the wave function (see the :kword:`SPIN` keyword).

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ALPH" LEVEL="ADVANCED" APPEAR="Alpha or beta" KIND="INT" DEFAULT_VALUE="0" MIN_VALUE="-1" MAX_VALUE="1">
              %%Keyword: ALPHaOrBeta <advanced>
              <HELP>
              With UHF orbitals as input, select alpha (1) or beta (-1) as starting orbitals.
              </HELP>
              </KEYWORD>

:kword:`TYPEIndex`
  This keyword forces the program to use information about subspaces from the
  :file:`INPORB` file.

  User can change the order of orbitals by editing of "Type Index" section
  in the :file:`INPORB` file. The legend of the types is:

  * **F** --- Frozen
  * **I** --- Inactive
  * **1** --- RAS1
  * **2** --- RAS2
  * **3** --- RAS3
  * **S** --- Secondary
  * **D** --- Deleted

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="TYPEINDEX" APPEAR="Use type index" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: TYPEindex <advanced>
              <HELP>
              Use extra information from the INPORB file to decide about orbital
              subspaces.
              </HELP>
              </KEYWORD>

:kword:`ALTEr`
  This keyword is used to change the ordering of MO in :file:`INPORB` or
  :file:`JOBOLD`. The keyword requires first the number of pairs to be interchanged,
  followed, for each pair, the symmetry species of
  the pair and the indices of the two permuting MOs. Here is an example: ::

    ALTEr= 2; 1 4 5; 3 6 8

  In this example, 2 pairs of MO will be exchanged: 4 and 5 in symmetry 1 and
  6 and 8 in symmetry 3.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ALTER" APPEAR="Change order" KIND="INTS_COMPUTED" SIZE="3" MIN_VALUE="1" LEVEL="ADVANCED">
              %%Keyword: ALTEr <advanced>
              <HELP>
              ALTEr interchanges pairs of MOs taken from the files INPORB or JOBOLD before
              starting the RASSCF calculation. Specify the number of pairs to exchange and,
              for each pair, by symmetry species and indices of the two permuting MOs.
              </HELP>
              </KEYWORD>

:kword:`ORTH`
  Specify the orthonormalization scheme to apply on the read orbitals.
  The possibilities are ``Gram_Schmidt``, ``Lowdin``, ``Canonical``, or ``no_ON``
  (no_orthonormalization).
  For a detailed explanation see :cite:`szabo_ostlund` (p. 143).
  The default is Gram_Schmidt.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ORTHON" APPEAR="Orthonormalization" LEVEL="ADVANCED" KIND="CHOICE" LIST="----,Gram_Schmidt,Lowdin,Canonical,no_ON">
              %%Keyword: ORTH <basic>
              <HELP>
              Specify the orthonormalization scheme to apply on the input orbitals.
              The possibilities are Gram_Schmidt, Lowdin, Canonical, or no_ON
              (no_orthonormalization).
              The default is Gram_Schmidt.
              </HELP>
              </KEYWORD>

:kword:`CLEAnup`
  This input is used to set to zero specific coefficients of the input
  orbitals. It is of value, for example, when the actual symmetry is
  higher than given by input and the trial orbitals are contaminated
  by lower symmetry mixing. The input requires at least one line
  per symmetry specifying the number of additional groups of orbitals
  to clean. For each group of orbitals within the symmetry, three lines
  follow. The first line indicates the number of considered orbitals
  and the specific number of the orbital (within the symmetry) in the
  set of input orbitals. Note the input lines cannot be longer than 72
  characters and the program expects as many continuation lines as are
  needed. The second line indicates the number of
  coefficients belonging to the prior orbitals which are going to be
  set to zero and which coefficients. The third line indicates the
  number of the coefficients of all the complementary orbitals of
  the symmetry which are going to be set to zero and which are these
  coefficients. Here is an example of what an input would look like: ::

    CLEAnup
    2
       3 4 7 9; 3 10 11 13; 4 12 15 16 17
       2 8 11; 1 15; 0
    0; 0; 0

  In this example the first entry indicates that two groups of orbitals are
  specified in the first symmetry. The first item of the
  following entry indicates that there are three orbitals considered
  (4, 7, and 9). The first item of the following entry indicates that there
  are three coefficients of the orbitals 4, 7, and 9 to be set to zero,
  coefficients 10, 11, and 13. The first item of the following entry indicates
  that there are four coefficients (12, 15, 16, and 17) which will be zero
  in all the remaining orbitals of the symmetry. For the second group of
  the first symmetry orbitals 8 and 11 will have their coefficient 15 set
  to zero, while nothing will be applied in the remaining orbitals.
  If a geometry optimization is performed the keyword is inactive after
  the first structure iteration.

  .. xmldoc:: %%Keyword: CLEAnup <advanced>
              This input is used to set to zero specific coefficients of the input
              orbitals. The option is, for instance, of great value if the symmetry of a
              molecule is higher than given by input and hence the trial orbitals are
              contaminated by components of lower symmetry. The restrictions are
              introduced by grouping orbitals of the same symmetry into additional
              classes. Orbitals belonging to a given classes are requested to obey a set
              of rules. In addition, all orbitals not belonging to that class, can be
              requested to obey another set of rules. Here, a rule is defined as being
              identical to the instruction: set coefficient i in orbital j to zero.

              The keyword requires at least one line of input per symmetry specifying
              the number of additional classes in this symmetry (a 0 (zero) denotes that
              there is no additional classes). If the number of additional classes is not
              zero then the program expects for each classes three lines of input: The
              first entry includes as first datum the dimension of the class followed by
              the list of orbitals included in this class. The second entry defines the
              set of rules which are applied to all orbitals within the class. The first
              datum defines the number of MO-coefficients to be set to zero and is
              followed by a list of which coefficients are to be touched. Finally, the
              third entry of input define the set of rules to be applied to all orbital
              not belonging to the class. Here too, the first value defines the number of
              MO-coefficients to be set to zero and is followed by a list of which
              coefficients are to be touched.

  .. xmldoc:: </GROUP>

:kword:`CIREstart`
  Starting CI-coefficients are read from a binary file :file:`JOBOLD`.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CIRESTART" APPEAR="CI restart" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: CIRESTART <basic>
              <HELP>
              Starting CI-coefficients are read from a binary file JOBOLD.
              </HELP>
              </KEYWORD>

:kword:`ORBOnly`
  This input keyword is used to get a formated ASCII file
  (:file:`RASORB`, :file:`RASORB.2`, etc.)
  containing molecular orbitals and occupations reading from a
  binary :file:`JobIph` file. The program will not perform any other operation.
  (In this usage, the program can be run without any files, except the :file:`JOBIPH` file).

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ORBONLY" APPEAR="Orbitals only" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: ORBOnly <basic>
              <HELP>
              This input keyword is used to get a formated ASCII file (RASORB, RASORB.2, etc.)
              containing molecular orbitals and occupations reading from a
              binary JobIph file. The program will not perform any other operation.
              </HELP>
              </KEYWORD>

:kword:`CIONly`
  This keyword is used to disable orbital optimization, that is,
  the CI roots are computed only for a given set of input orbitals.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CIONLY" APPEAR="CI only" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: CIONly <basic>
              <HELP>
              This keyword is used to disable orbital optimization, that is,
              the CI roots are computed only for a given set of input orbitals.
              </HELP>
              </KEYWORD>

:kword:`CHOInput`
  This marks the start of an input section for modifying
  the default settings of the Cholesky RASSCF.
  Below follows a description of the associated options.
  The options may be given in any order,
  and they are all optional except for
  :kword:`ENDChoinput` which marks the end of the :kword:`CHOInput` section.

  :kword:`NoLK`
    Available only within ChoInput. Deactivates the "Local Exchange" (LK) screening algorithm :cite:`Aquilante:07a` in computing
    the Fock matrix. The loss of speed compared to the default algorithm can be substantial, especially for electron-rich systems.
    Default is to use LK.

    .. xmldoc:: <GROUP MODULE="RASSCF" NAME="CHOINPUT" APPEAR="Cholesky input section" KIND="BLOCK" LEVEL="ADVANCED">
                %%Keyword: Choinput <advanced>
                Manually modify the settings of the Cholesky RASSCF.

    .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NOLK" APPEAR="Turn off LK screening" LEVEL="ADVANCED" KIND="SINGLE">
                %%Keyword: NoLK <advanced>
                <HELP>
                Deactivates LK screening.
                </HELP>
                </KEYWORD>

    .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ALGORITHM" LEVEL="UNDOCUMENTED" KIND="INT" />

    .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="LOCK" LEVEL="UNDOCUMENTED" KIND="SINGLE" />

  :kword:`DMPK`
    Available only within ChoInput. Modifies the thresholds used in the LK screening.
    The keyword takes as argument a (double precision) floating point (non-negative) number used
    as correction factor for the LK screening thresholds.
    The default value is 1.0d-1. A smaller value results in a slower but more accurate calculation.

    **Note:** The default choice of the LK screening thresholds is tailored to achieve as much as possible an
    accuracy of the converged RASSCF energies consistent with the choice of the Cholesky decomposition
    threshold.

    .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DMPK" APPEAR="Damping for LK" LEVEL="ADVANCED" KIND="REAL" EXCLUSIVE="NOLK">
                %%Keyword: dmpK <advanced>
                <HELP>
                Modifies the thresholds used in the LK screening.
                The default value is 1.0d-1. A smaller value results in a slower but more accurate calculation.
                </HELP>
                </KEYWORD>

  :kword:`NODEcomposition`
    Available only within ChoInput. Deactivates the Cholesky decomposition of the inactive AO 1-particle density matrix.
    The inactive Exchange contribution to the Fock matrix is therefore computed using inactive canonical orbitals
    instead of (localized) "Cholesky MOs" :cite:`Aquilante:06a`. This choice tends to lower the performances of the
    LK screening.
    Default is to perform this decomposition in order to obtain the Cholesky MOs.

    .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NODE" APPEAR="Turn off density decomposition" LEVEL="ADVANCED" KIND="SINGLE">
                %%Keyword: NODE <advanced>
                <HELP>
                The inactive exchange contribution to the Fock matrix is computed using inactive canonical orbitals
                instead of (localized) "Cholesky MOs".
                </HELP>
                </KEYWORD>

    .. xmldoc:: </GROUP>

  :kword:`TIME`
    Activates printing of the timings of each task of the Fock matrix build.
    Default is to not show these timings.

  :kword:`MEMFraction`
    Set the fraction of memory to use as global Cholesky vector buffer.
    Default: for serial runs 0.0d0; for parallel runs 0.3d0.

:kword:`OFEMbedding`
  Performs a Orbital-Free Embedding (OFE)RASSCF calculation, available only in combination with Cholesky or RI integral representation.
  The runfile of the environment subsystem renamed AUXRFIL is required.
  An example of input for the keyword :kword:`OFEM` is the following: ::

    OFEMbedding
     ldtf/pbe
    dFMD
     1.0   1.0d2
    FTHAw
     1.0d-4

  The keyword :kword:`OFEM` requires the specification of two functionals in the form fun1/fun2, where fun1 is the functional
  used for the Kinetic Energy (available functionals: Thomas-Fermi, with acronym LDTF, and the NDSD functional), and where
  fun2 is the xc-functional (LDA, LDA5, PBE and BLYP available at the moment).
  The OPTIONAL keyword :kword:`dFMD` has two arguments: first, the fraction of correlation potential to be added to the OFE potential;
  second, the exponential decay factor for this correction (used in PES calculations).
  The OPTIONAL keyword :kword:`dFMD` specifies the fraction of correlation potential to be added to the OFE potential.
  The OPTIONAL keyword :kword:`FTHA` is used in a freeze-and-thaw cycle (EMIL Do While) to specify the (subsystems) energy convergence threshold.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="OFEMBEDDING" APPEAR="Orbital-free embedding" LEVEL="ADVANCED" KIND="STRING">
              %%Keyword: OFEM <advanced>
              <HELP>
              Performs a Orbital-Free Embedding (OFE)RASSCF calculation, available only in combination with Cholesky or RI integral representation.
              The runfile of the environment subsystem renamed AUXRFIL is required.
              An example of input for the keyword OFEM is the following:

                OFEMbedding
                 ldtf/pbe
                dFMD
                 1.0   1.0d2
                FTHAw
                 1.0d-4

              The keyword OFEM requires the specification of two functionals in the form fun1/fun2, where fun1 is the functional used for the
              Kinetic Energy (available functionals: Thomas-Fermi, with acronym LDTF, and the NDSD functional), and where
              fun2 is the xc-functional (LDA, LDA5, PBE and BLYP available at the moment).
              </HELP>
              </KEYWORD>

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DFMD" LEVEL="ADVANCED" KIND="REALS" SIZE="2" REQUIRE="OFEMBEDDING">
              %%Keyword: dFMD <advanced>
              <HELP>
              The OPTIONAL keyword dFMD has two arguments: first, the fraction of correlation potential to be added to the OFE potential;
              second, the exponential decay factor for this correction (used in PES calculations).
              </HELP>
              </KEYWORD>

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="FTHAW" LEVEL="ADVANCED" KIND="REAL" REQUIRE="OFEMBEDDING">
              %%Keyword: FTHAw <advanced>
              <HELP>
              The OPTIONAL keyword FTHA is used in a freeze-and-thaw cycle (EMIL Do While) to specify the (subsystems) energy
              convergence threshold.
              </HELP>
              </KEYWORD>

:kword:`ITERations`
  Specify the maximum number of
  :program:`RASSCF` iterations, and the maximum number of iterations used in the orbital
  optimization (super-CI) section. Default and maximum values are 200,100.

  .. xmldoc:: <GROUP MODULE="RASSCF" NAME="CNVCTL" APPEAR="Convergence control" KIND="BOX" WINDOW="POPUP" LEVEL="BASIC">

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ITER" LEVEL="BASIC" APPEAR="Maximum iterations" KIND="INTS" SIZE="2" DEFAULT_VALUES="200,100">
              %%Keyword: ITERations <basic>
              <HELP>
              Specify the maximum number of
              RASSCF iterations and the maximum number of iterations used in the orbital optimization
              section. Default and maximum values are 200,100.
              </HELP>
              </KEYWORD>

:kword:`PERI`
  Write the orbital file per iteration.
  The obtained files are named `${Project}.IterOrb.${iter_number}`
  and if HDF5 is available `${Project}.rasscf.${iter_number}.h5`.
  Note that up until the last iteration all states in a state-averaged calculation
  are in the same orbital basis.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="PERI" APPEAR="Write per iteration" KIND="SINGLE" EXCLUSIVE="" LEVEL="BASIC">
              %%Keyword: PERI <basic>
              <HELP>
              Write the orbital file per iteration.
              The obtained files are named ${Project}.IterOrb.${iter_number}
              and if HDF5 is available ${Project}.rasscf.${iter_number}.h5.
              </HELP>
              </KEYWORD>

:kword:`LEVShft`
  Define a level shift value for the super-CI Hamiltonian. Typical values are in the range
  0.0--1.5. Increase this value if a calculation diverges. The default value 0.5,
  is normally the best choice when Quasi-Newton is performed.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="LEVSHFT" LEVEL="BASIC" APPEAR="Level shift" KIND="REAL" DEFAULT_VALUE="0.5">
              %%Keyword: LEVShft <basic>
              <HELP>
              Define a level shift value for the super-CI Hamiltonian. Typical values are in the range
              0.0-1.5. Increase this value if a calculation diverges. The default value 0.5,
              is normally the best choice when Quasi-Newton is performed.
              </HELP>
              </KEYWORD>

:kword:`THRS`
  Specify convergence thresholds for: energy,
  orbital rotation matrix, and energy gradient. Default values are:
  1.0e-08, 1.0e-04, 1.0e-04.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="THRS" APPEAR="Thresholds" LEVEL="ADVANCED" KIND="REALS" SIZE="3" DEFAULT_VALUES="1.0e-8,1.0e-4,1.0e-4">
              %%Keyword: THRS <advanced>
              <HELP>
              Specify convergence thresholds for: energy,
              orbital rotation matrix, and energy gradient. Default values are:
              1.0e-08, 1.0e-04, 1.0e-04.
              </HELP>
              </KEYWORD>

:kword:`TIGHt`
  Convergence thresholds for the Davidson diagonalization procedure. Two
  numbers should be given: THREN and THFACT. THREN specifies the energy
  threshold in the first iteration. THFACT is used to compute the
  threshold in subsequent iterations as THFACT\ :math:`\cdot`\DE, where DE is the
  RASSCF energy change. Default values are 1.0d-04 and 1.0d-3.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="TIGHT" APPEAR="Davidson thresholds" LEVEL="ADVANCED" KIND="REALS" SIZE="2" DEFAULT_VALUES="1.0e-4,1.0e-3">
              %%Keyword: TIGHt <advanced>
              <HELP>
              Convergence thresholds for the Davidson diagonalization procedure. Two
              numbers should be given: THREN and THFACT. THREN specifies the energy
              threshold in the first iteration. THFACT is used to compute the
              threshold in subsequent iterations as THFACT*DE, where DE is the
              RASSCF energy change. Default values are 1.0d-04 and 1.0d-3.
              </HELP>
              </KEYWORD>

:kword:`NOQUne`
  This input keyword is used to switch off the
  Quasi-Newton update procedure for the Hessian. Pure super-CI
  iterations will be performed. (Default setting: QN update is used
  unless the calculation involves numerically integrated DFT contributions.)

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NOQUNE" KIND="SINGLE" APPEAR="No quasi-Newton update" LEVEL="ADVANCED" EXCLUSIVE="QUNE">
              %%Keyword: NOQUne <advanced>
              <HELP>
              This input keyword is used to switch off the Quasi-Newton update procedure for the
              Hessian. Pure super-CI iterations will be performed. (Default setting: QN update is
              used unless the calculation involves numerically integrated DFT contributions.)
              </HELP>
              </KEYWORD>

:kword:`QUNE`
  This input keyword is used to switch on the
  Quasi-Newton update procedure for the Hessian.
  (Default setting: QN update is used
  unless the calculation involves numerically integrated DFT contributions.)

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="QUNE" KIND="SINGLE" APPEAR="Quasi-Newton update" LEVEL="ADVANCED" EXCLUSIVE="NOQU">
              %%Keyword: QUNE <advanced>
              <HELP>
              This input keyword is used to switch on the Quasi-Newton update procedure for the
              Hessian. (Default setting: QN update is used unless the calculation involves
              numerically integrated DFT contributions.)
              </HELP>
              </KEYWORD>

:kword:`CIMX`
  Specify the maximum number of iterations allowed in the CI
  procedure. Default is 100 with maximum value 200.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CIMX" APPEAR="Maximum CI iterations" KIND="INT" DEFAULT_VALUE="100" MIN_VALUE="0" MAX_VALUE="200" LEVEL="BASIC">
              %%Keyword: CIMX <basic>
              <HELP>
              Specify the maximum number of iterations allowed in the CI
              procedure. Default is 100 with maximum value 200.
              </HELP>
              </KEYWORD>

:kword:`HEXS`
  Highly excited states. Will eliminate the maximum occupation in
  one or more RAS/GAS's thereby eliminating all roots below.
  Very helpful for core excitations where the ground-state input
  can be used to eliminate unwanted roots. Works with RASSI.
  First input is the number of RAS/GAS where the maximum occupation
  should be eliminated. Second is the RAS/GAS or RAS/GAS's where
  maximum occupation will not be allowed.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="HEXS" APPEAR="Highly excited states" KIND="INTS" SIZE="2" LEVEL="ADVANCED">
              %%Keyword: HEXS <advanced>
              <HELP>
              Highly excited states. Will eliminate the maximum occupation in
              one or more RAS/GAS's thereby eliminating all roots below.
              Very helpful for core excitations where the ground-state input
              can be used to eliminate unwanted roots. Works with RASSI.
              First input is the number of RAS/GAS where the maximum occupation
              should be eliminated. Second is the RAS/GAS or RAS/GAS's where
              maximum occupation will not be allowed.
              </HELP>
              </KEYWORD>

:kword:`DEXS`
  Doubly highly excited states. Will eliminate the maximum and maximum - 1
  occupations in one or more RAS/GAS's thereby eliminating all roots below.
  Very helpful for double-core excitations where the ground-state input
  can be used to eliminate unwanted roots. Works with RASSI.
  First input is the number of RAS/GAS where the maximum and maximum - 1
  occupations should be eliminated. Second is the RAS/GAS or RAS/GAS's where
  maximum and maximum - 1 occupations will not be allowed.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DEXS" APPEAR="Doubly highly excited states" KIND="INTS" SIZE="2" LEVEL="ADVANCED">
              %%Keyword: DEXS <advanced>
              <HELP>
              Doubly highly excited states. Will eliminate the maximum and
              maximum - 1 occupations in one or more RAS/GAS's thereby
              eliminating all roots below.  Very helpful for double-core
              excitations where the ground-state input can be used to eliminate
              unwanted roots. Works with RASSI.  First input is the number of
              RAS/GAS where the maximum and maximum - 1 occupations should be
              eliminated. Second is the RAS/GAS or RAS/GAS's where maximum and
              maximum - 1 occupations will not be allowed.
              </HELP>
              </KEYWORD>

:kword:`SDAV`
  Here follows the dimension of the explicit Hamiltonian used to speed up
  the Davidson CI iteration process. An explicit H matrix is constructed
  for those configurations that have the lowest diagonal elements.
  This H matrix is used instead of the corresponding diagonal elements
  in the Davidson update vector construction. The result is a large saving
  in the number if CI iterations needed. Default value is the smallest of 100
  and the number of configurations. Increase this value if there is problems
  converging to the right roots.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="SDAV" APPEAR="Davidson explicit Hamiltonian" LEVEL="ADVANCED" KIND="INT">
              %%Keyword: SDAV <advanced>
              <HELP>
              The keyword is followed by one line of input giving the dimension
              of the explicit Hamiltonian used as preconditioner in the
              Davidson procedure.Increase this value if there is problems
              converging to the right roots.
              </HELP>
              </KEYWORD>

:kword:`NKEE`
  Here follows the maximum dimension of the full Davidson Hamiltonian.
  This Hamiltonian contains the current CI vectors for each state as well
  as a set of correction vectors from a number of past iterations.
  Default value is the smallest of 400 and 6 times the number of states, though
  at least 2 times the number of states.
  Increasing this size reduces the number of CI iterations but increases memory requirements and can
  increase the computational cost associated with forming and diagonalizing the Hamiltonian matrix.
  Very large values can lead to numerical instabilities.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NKEE" APPEAR="Number of kept vectors" LEVEL="ADVANCED" KIND="INT">
              %%Keyword: SDAV <advanced>
              <HELP>
              The keyword is followed by one line of input giving the maximum dimension
              of the Hamiltonian used in the Davidson procedure.
              Increase this value if the CI does not converge.
              </HELP>
              </KEYWORD>

:kword:`SXDAmp`
  A variable called SXDAMP regulates the size of the orbital rotations.
  Use keyword :kword:`SXDAmp` and enter a real number.
  The default value is 0.0002. Larger values can give slow
  convergence, very low values may give problems e.g. if some active
  occupations are very close to 0 or 2.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="SXDAMP" APPEAR="Orbital rotation damp" LEVEL="ADVANCED" KIND="REAL">
              %%Keyword: SXDAmp <advanced>
              <HELP>
              SXDAMP (default 0.0002) regulates the speed of orbital relaxation.
              Large values give slower but safer convergence.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`SUPSym`
  This input is used to restrict possible orbital
  rotations. It is of value, for example, when the actual symmetry is
  higher than given by input. Each orbital is given a label IXSYM(I).
  If two orbitals in the same symmetry have different labels they will
  not be allowed to rotate into each other and thus prevents from obtaining
  symmetry broken solutions. Note, however, that the starting orbitals must
  have the right symmetry. The input requires one or more entries
  per symmetry. The first specifies the number of additional subgroups in this
  symmetry (a 0 (zero) denotes that there is no additional subgroups and the
  value of IXSYM will be 0 (zero) for all orbitals in that symmetry ).
  If the number of additional subgroups is not zero there are additional
  entries for each subgroup: The dimension of the subgroup and
  the list of orbitals in the subgroup counted relative to the first orbital
  in this symmetry. Note, the input lines cannot be longer than 180 characters
  and the program expects continuation lines as many as there are needed.
  As an example assume an atom treated in :math:`C_{2v}` symmetry for
  which the d\ :math:`_{z^2}` orbitals (7 and 10) in symmetries 1 may mix with the
  s orbitals. In addition, the d\ :math:`_{z^2}` and d\ :math:`_{x^2-y^2}` orbitals (8 and 11)
  may also mix. Then the input would look like:

  .. If the number of additional subgroups is not zero then the
     program expects for each subgroup at least one additional entry of which
     the first number denotes the dimension of the subgroup (number of
     orbitals involved) followed by the orbital index relative to the first
     orbital in this symmetry.

  ::

    SUPSym
    2
       2 7 10; 2 8 11
    0; 0; 0

  In this example the first entry indicates that we would like to specify
  two additional subgroups in the first symmetry (total symmetric group). The
  first item in the following two entries declares that each subgroup consists
  of two orbitals. Orbitals 7 and 10 constitute the first group and it is
  assumed that these are orbitals of d\ :math:`_{z^2}` character. The second group
  includes the d\ :math:`_{x^2-y^2}` orbitals 8 and 11. The following three entries
  denote that there are no further subgroups defined for the remaining
  symmetries. Ordering of the orbitals according to energy is deactivated
  when using :kword:`SUPSym`. If you activate ordering using :kword:`ORDEr`,
  the new labels will be printed in the output section.
  If a geometry optimization is performed the reordered matrix will be stored
  in the :file:`RUNFILE` file and read from there instead of from the input
  in each new structure iteration.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="SUPSYM" APPEAR="Supersymmetry" LEVEL="ADVANCED" KIND="CUSTOM">
              %%Keyword: SUPSym <advanced>
              <HELP>
              Used to prohibit certain orbital rotations. Please consult the manual!
              </HELP>
              This input is used to restrict possible orbital rotations. The
              restrictions are introduced by grouping orbitals of the same
              symmetry into additional classes. Orbitals belonging to different
              classes are not allowed to mix up during optimization.
              The input requires at least one entry per symmetry specifying
              the number of additional classes in this symmetry (a 0 (zero)
              denotes that there is no additional classes).
              If the number of additional classes is not zero then the program expects
              for each classes the following input: The dimension of the classes and
              the list of orbitals in the classes counted relative to the first orbital
              in this symmetry.
              </KEYWORD>

:kword:`HOME`
  With this keyword, the root selection in the Super-CI orbital update
  is by maximum overlap rather than lowest energy.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="HOME" APPEAR="Root homing" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: HOME <advanced>
              <HELP>
              Make the root selection in the Super-CI orbital update
              by maximum overlap rather than by energy ordering.
              </HELP>
              </KEYWORD>

:kword:`IVO`
  The :program:`RASSCF` program will diagonalize the core Hamiltonian in the space of virtual orbitals,
  before printing them in the output. The resulting orbitals are only suitable to select which ones
  should enter the active space in a subsequent :program:`RASSCF` calculation. The :program:`RASSCF` wave function and
  orbitals are not suitable for CASPT2, MRCI or any other correlated methods, because the energies
  of the virtual orbitals are undefined.
  This keyword is equivalent to the :kword:`IVO` keyword of the :program:`SCF` program.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="IVO" APPEAR="Improved Virtual Orbitals" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: IVO <basic>
              <HELP>
              The RASSCF program will diagonalize the core Hamiltonian in the space of virtual orbitals,
              before printing them in the output. The resulting orbitals are only suitable to select which ones
              should enter the active space in a subsequent RASSCF calculation. The RASSCF wave function and
              orbitals are not suitable for CASPT2, MRCI or any other correlated methods, because the energies
              of the virtual orbitals are undefined.
              This keyword is equivalent to the IVO keyword of the SCF program.
              </HELP>
              </KEYWORD>

:kword:`VB`
  .. _vbinrasscf:

  Using this keyword, the CI optimization step in the :program:`RASSCF` program will be
  replaced by a call to the :program:`CASVB` program, such that fully variational valence
  bond calculations may be carried out. The :kword:`VB` keyword can be followed by any
  of the directives described in :numref:`UG:sec:casvb` and should be terminated
  by :kword:`ENDVB`. Energy-based optimization of the VB parameters is the default,
  and the output level for the main :program:`CASVB` iterations is reduced to :math:`-1`,
  unless the print level for :program:`CASVB` print option 6 is :math:`\geq`\2.

  .. xmldoc:: <GROUP MODULE="RASSCF" NAME="VB" APPEAR="CASVB" KIND="BLOCK" LEVEL="BASIC">
              %%Keyword: VB <basic>
              <HELP>
              Perform fully variational VB calculations, by
              invoking CASVB in place of the CI optimization step.
              </HELP>

  .. xmldoc:: <INCLUDE MODULE="CASVB" EXCEPT="FROZEN,INACTIVE,NACTEL,RAS2,SPIN,SYMMETRY" />

  .. xmldoc:: </GROUP>

:kword:`PRINt`
  The keyword is followed by a line giving the print
  levels for various logical code sections. It has the following structure:
  IW IPR IPRSEC(I), I=1,7

  * IW --- logical unit number of printed output (normally 6).
  * IPR --- is the overall print level (normally 2).
  * IPRSEC(I) --- gives print levels in different sections of the program.

    #. Input section
    #. Transformation section
    #. CI section
    #. Super-CI section
    #. Not used
    #. Output section
    #. Population analysis section

  The meaning of the numbers: 0=Silent, 1=Terse, 2=Normal, 3=Verbose, 4=Debug,
  and 5=Insane. If input is not given, the default (normally=2) is determined
  by a global setting which can be altered bubroutine call.
  (Programmers: See programming guide). The local print level in any section is
  the maximum of the IPRGLB and IPRSEC() setting, and is automatically reduced
  e.g. during structure optimizations or numerical differentiation. Example: ::

    Print= 6 2 2 2 3 2 2 2 2

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="PRINT" LEVEL="ADVANCED" APPEAR="Print" KIND="INTS" SIZE="9">
              %%Keyword: Print <advanced>
              <HELP>
              Enter the print levels for seven logical code sections (see users guide).
              </HELP>
              </KEYWORD>

:kword:`MAXOrb`
  Maximum number of :file:`RasOrb` files to produce, one for each root up to the maximum.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="MAXORB" APPEAR="Maximum orbital files" KIND="INT" LEVEL="BASIC">
              %%Keyword: MAXOrb <basic>
              <HELP>
              Maximum number of RasOrb files to produce, one for each root.
              </HELP>
              </KEYWORD>

:kword:`OUTOrbitals`
  This keyword is used to select the type of orbitals to be written
  in a formated ASCII file. By default a formated :file:`RASORB` file
  containing average orbitals and subsequent :file:`RASORB.1`,
  :file:`RASORB.2`, etc., files containing natural orbitals for each
  of the computed (up to ten) roots will be generated in the working directory.
  An entry follows with an additional keyword selecting the orbital type.
  The possibilities are:

  AVERage orbitals: this is the default option.
  This keyword is used to produce a formated ASCII file of orbitals
  (:file:`RASORB`) which correspond to the final state average density matrix obtained by
  the :program:`RASSCF` program. The inactive and
  secondary orbitals have been transformed to make an effective Fock
  matrix diagonal. Corresponding diagonal elements are given as orbital
  energies in the :program:`RASSCF` output listing. The active orbitals have been
  obtained by diagonalizing the sub-blocks of the average density matrix
  corresponding to the three different RAS orbital spaces, thereby
  the name pseudo-natural orbitals. They will be true natural orbitals
  only for a CASSCF wave function.

  CANOnical orbitals:
  Use this keyword to produce the canonical orbitals. They differ from
  the natural orbitals, because also the active part of the Fock matrix is
  diagonalized. Note that the density matrix is no longer diagonal and
  the CI coefficients have not been transformed to this basis.
  This option substitutes the previous keyword :kword:`CANOnical`.

  NATUral orbitals:
  Use this keyword to produce the true natural orbitals. The keyword
  should be followed by a new line with an integer specifying the maximum
  CI root for which the orbitals and occupation numbers are needed.
  One file for each root will be generated up to the specified number.
  In a one state RASSCF calculation this number is always 1, but if an average
  calculation has been performed, the NO's can be obtained for all the states
  included in the energy averaging. Note that the natural orbitals main
  use is as input for property calculations using :program:`SEWARD`.
  The files will be named :file:`RASORB`, :file:`RASORB.2`, :file:`RASORB.3`, etc.
  This keyword is on by default for up to ten roots.

  SPIN orbitals.
  This keyword is used to produce a set of spin orbitals and is
  followed by a new line with an integer specifying the maximum CI root
  for which the orbitals
  and occupation numbers are needed. One file for each root will be
  generated up to the specified number. Note, for convenience the
  doubly occupied and secondary orbitals have been added to these
  sets with occupation numbers 0 (zero). The main use of these orbitals
  is to act as input to property calculations and for graphical
  presentations.
  This keyword is on by default for all roots.

  An example input follows in which five files are requested containing
  natural orbitals for roots one to five of a RASSCF calculation.
  The files are named :file:`RASORB.1`, :file:`RASORB.2`, :file:`RASORB.3`, :file:`RASORB.4`, and :file:`RASORB.5`,
  respectively for each one of the roots.
  Although this is the default, it can be used complemented by the :kword:`ORBOnly`
  keyword, and the orbitals will be read from
  a JobIph file from a previous calculation, in case the formated files
  were lost or you require more than ten roots. As an option the
  :kword:`MAXOrb` can be also used to increase the number of files
  over ten. ::

    OUTOrbital= Natural; 15

  .. xmldoc:: <GROUP MODULE="RASSCF" NAME="OUTORBITALS" APPEAR="RASSCF orbital type" KIND="RADIO">
              <HELP>
              Type of orbitals to put in RASORB file.
              </HELP>
              %%Keyword: OUTOrbitals <basic>
              Type of orbitals to put in RASORB file. Specify in the next entry any of:

              AVERage   -- Average MCSCF orbitals.
              CANOnical -- Average pseudocanonical orbitals.
              NATUral   -- State-specific natural orbitals. Next entry, number of states.
              SPIN      -- State-specific spin orbitals. Next entry, number of states.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="AVERAGEORB" APPEAR="Average" KIND="SINGLE" LEVEL="BASIC">
              <HELP>
              Average MCSCF orbitals.
              </HELP>
              </KEYWORD>

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CANONICALORB" APPEAR="Canonical" KIND="SINGLE" LEVEL="BASIC">
              <HELP>
              Average pseudocanonical orbitals.
              </HELP>
              </KEYWORD>

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NATURALORB" APPEAR="Natural" KIND="INT" LEVEL="BASIC">
              <HELP>
              State-specific natural orbitals. Enter number of roots which should produce RASORB files.
              </HELP>
              </KEYWORD>

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="SPINORB" APPEAR="Spin" KIND="INT" LEVEL="BASIC">
              <HELP>
              State-specific spin orbitals. Enter number of roots which should produce RASORB files.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`ORBListing`
  .. compound::

    This keyword is followed with a word showing
    how extensive you want the orbital listing to be in the printed output.
    The alternatives are:

    * **NOTHing:** No orbitals will be printed (suggested for
      numerical CASPT2 optimization). (Also, the old VERYbrief will be accepted).
    * **FEW:** The program will print the occupied orbitals, and any
      secondary with less than 0.15 a.u. orbital energy. (Old BRIEF also accepted).
    * **NOCOre:** The program will print the active orbitals, and any
      secondary with less than 0.15 a.u. orbital energy.
    * **ALL:** All orbitals are printed. (Old LONG also accepted).

    (unless other limits are specified by the :kword:`PROR` keyword).

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ORBLISTING" LEVEL="BASIC" APPEAR="Printed orbitals" KIND="CHOICE" LIST="----,Nothing,Few,NoCore,All">
              %%Keyword: ORBListing <basic>
              <HELP>
              Select how extensive orbital list you want in the output file.
              </HELP>
              </KEYWORD>

:kword:`ORBAppear`
  This keyword requires an entry with a word showing
  the appearance of the orbital listing in the printed output.
  The alternatives are:

  * **COMPact:** The format of the orbital output is changed from a
    tabular form to a list giving the orbital indices and MO-coefficients.
    Coefficients smaller than 0.1 will be omitted.
  * **FULL:** The tabular form will be chosen.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ORBAPPEAR" LEVEL="BASIC" APPEAR="Orbital appearance" KIND="CHOICE" LIST="----,Compact,Full">
              %%Keyword: ORBAppear <basic>
              <HELP>
              Select appearance of orbital list in the output file.
              </HELP>
              </KEYWORD>

:kword:`PROR`
  This keyword is used to alter the printout of the MO-coefficients.
  Two numbers must be given of which the first is an upper boundary for the
  orbital energies and the second is a lower boundary for the occupation
  numbers. Orbitals with energy higher than the threshold or occupation
  numbers lower that the threshold will not be printed.
  By default these
  values are set such that all occupied orbitals are printed, and
  virtual orbitals with energy less than 0.15 au. However, the values
  are also affected by use of :kword:`OUTPUT`.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="PROR" LEVEL="BASIC" APPEAR="Orbital print thresholds" KIND="REALS" SIZE="2">
              %%Keyword: PROR <basic>
              <HELP>
              Enter upper limit for orbital energies, and lower limit for occupation
              number, for printing orbitals to the output.
              </HELP>
              </KEYWORD>

:kword:`PRSD`
  This keyword is used to request that not only CSFs are printed with
  the CI coefficients, but also the determinant expansion.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="PRSD" APPEAR="Print determinant expansion" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: PRSD <advanced>
              <HELP>
              Activate printing of CSFs in terms of determinants.
              </HELP>
              </KEYWORD>

:kword:`ORDEr`
  This input keyword is used to deactivate or activate ordering of the output orbitals
  according to energy.
  One number must be given: 1 if you want ordering
  and 0 if you want to deactivate ordering. Default is 1 and with :kword:`SUPSym` keyword
  default is 0.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ORDER" APPEAR="Orbital print order" KIND="INT" LEVEL="ADVANCED">
              %%Keyword: ORDEr <advanced>
              <HELP>
              Enter 1 to order the output orbitals by energy, 0 if not.
              </HELP>
              </KEYWORD>

:kword:`PRSP`
  Use this keyword to get the spin density matrix for the active orbitals printed.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="PRSP" APPEAR="Print spin density" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: PRSP <basic>
              <HELP>
              Use this keyword to get the spin density matrix for the active orbitals printed.
              </HELP>
              </KEYWORD>

:kword:`PRWF`
  Enter the threshold for CI coefficients to be printed (Default: 0.05).

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="PRWF" LEVEL="BASIC" APPEAR="CI coefficients print threshold" KIND="REAL" DEFAULT_VALUE="0.05">
              %%Keyword: PRWF <basic>
              <HELP>
              Enter the threshold for CI coefficients to be printed.
              </HELP>
              (Default: 0.05)
              </KEYWORD>

:kword:`TDM`
  If this keyword is given, and if HDF5 support is enabled, the active 1-electron transition
  density matrix between every pair of states in the current calculation
  (and transition spin density matrix for non-singlet states) will be computed and
  stored in the HDF5 file.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="TDM" LEVEL="BASIC" APPEAR="Transition density matrices" KIND="SINGLE">
              %%Keyword: TDM <basic>
              <HELP>
              Compute and save active transition density matrices. Requires HDF5.
              </HELP>
              </KEYWORD>

:kword:`XMSInter`
  This keyword can be used in an XMS-PDFT calculation (which needs :program:`RASSCF` and :program:`MCPDFT` modules). This keyword stands for XMS Intermediate states. It rotates the CASSCF, CASCI, RASSCF or RASCI states into the XMS intermediate states.
  This keyword generates a file named :file:`Do_Rotate.txt` that stores the rotation vector and another file named :file:`H0_Rotate.txt` that stores the Hamiltonian matrix, called the intermediate Hamiltonian matrix, for the XMS intermediate states. The intermediate Hamiltonian matrix is the XMS-PDFT effective Hamiltonian matrix before one replaces the diagonal elements with the MC-PDFT energies.
  This keyword currently does not work for wave functions optimized with the DMRG algorithm.
  This keyword performs the functions called by :kword:`ROSTate`; therefore one does not need to use :kword:`ROSTate` when this keyword is used.
  More information regarding XMS-PDFT can be found on the Minnesota OpenMolcas page\ [#fn1]_.

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

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="XMSI" APPEAR="XMS Intermediate States" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: XMSI <basic>
              <HELP>
              This keyword rotates the states after the last diagonalization of the CASSCF, CASCI, RASSCF or RASCI calculation into XMS intermediate states.
              </HELP>
              </KEYWORD>

:kword:`CMSInter`
  This keyword can be used in a CMS-PDFT calculation (which needs :program:`RASSCF` and :program:`MCPDFT` modules). This keyword stands for CMS Intermediate states. It rotates the CASSCF, CASCI, RASSCF or RASCI states into the CMS intermediate states.
  This keyword generates a file named :file:`Do_Rotate.txt` that stores the rotation vector and another file named :file:`H0_Rotate.txt` that stores the Hamiltonian matrix, called intermediate the Hamiltonian matrix, for the CMS intermediate states. The intermediate Hamiltonian matrix is the CMS-PDFT effective Hamiltonian matrix before one replaces the diagonal elements with the MC-PDFT energies.
  This keyword currently does not work for wave functions optimized with the DMRG algorithm.
  This keyword performs the functions called by :kword:`ROSTate`; therefore one does not need to use :kword:`ROSTate` when this keyword is used.
  More information regarding CMS-PDFT can be found on the Minnesota OpenMolcas page\ [#fn1]_.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CMSI" APPEAR="CMS Intermediate States" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: CMSI <basic>
              <HELP>
              This keyword rotates the states after the last diagonalization of the CASSCF, CASCI, RASSCF or RASCI calculation into CMS intermediate states.
              </HELP>
              </KEYWORD>

:kword:`CMSStart`
  This keyword gives the file that stores the starting rotation matrix for finding the CMS intermediate states (see :kword:`CMSInter`). The file has the same format as :file:`Do_Rotate.txt`. The default is to use the XMS intermediate states (see :kword:`XMSInter`).

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CMSS" LEVEL="ADVANCED" APPEAR="CMS starting rotation matrix" KIND="STRING" DEFAULT_VALUE="XMS">
              %%Keyword: CMSS <advanced>
              <HELP>
              This keyword specifies file that provides the starting rotation matrix for CMS intermediate states.
              </HELP>
              </KEYWORD>

:kword:`CMSOpt`
  This keyword defines the maximization algorithm to find the CMS intermediate states (see :kword:`CMSInter`). The allowed values are:

  * **Newton:** Newton's method. The Hessian and the gradient of the sum-over-states
    of the active--active classical Coulomb energies (Q_a-a) are computed. This is the
    default for calculations with more than two states. Note that Q_a-a may decrease within
    the minimum number of cycles defined by `CMMI` if a step is too big. After the minimum
    number of cycles, a smaller step will be taken to ensure that Q_a-a increases, and an
    extra cycle will always be taken if a smaller step is used.
  * **Jacobi:** Jacobi's method. States are rotated in pairwise succession,
    and a trigonometric function is used to fit such rotation to find the
    maximum. This is the default for calculations with two states.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CMSO" APPEAR="CMS Optimization Option" LEVEL="ADVANCED" KIND="CHOICE" LIST="Newton,Jacobi" DEFAULT_VALUE="Newton" >
              %%Keyword: CMSO <advanced>
              <HELP>
              This keyword specifies the maximization algorithm to find the CMS intermediate states.
              </HELP>
              </KEYWORD>

:kword:`CMMAx`
  This keyword defines the maximum number of cycles to find the CMS intermediate states (see :kword:`CMSInter`). The default value is 100.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CMMA" APPEAR="CMS Maximum Cycles" LEVEL="ADVANCED" KIND="INT" DEFAULT_VALUE="100" MIN_VALUE="1">
              %%Keyword: CMMA <advanced>
              <HELP>
              This keyword specifies the maximum number of cycles to optimize the CMS intermediate states.
              </HELP>
              </KEYWORD>

:kword:`CMMIn`
  This keyword defines the minimum number of cycles to find the CMS intermediate states (see :kword:`CMSInter`). The default value is 5.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CMMI" APPEAR="CMS Mininum Cycles" LEVEL="ADVANCED" KIND="INT" DEFAULT_VALUE="5" MIN_VALUE="1">
              %%Keyword: CMMI <advanced>
              <HELP>
              This keyword specifies the minimum number of cycles to optimize the CMS intermediate states.
              </HELP>
              </KEYWORD>

:kword:`CMTHreshold`
  This keyword defines the threshold for the change in the sum over states of the classical Coulomb energy for CMS intermediate states to converge (see :kword:`CMSInter`). The default value is 1.0d-8.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CMTH" APPEAR="CMS Threshold" LEVEL="ADVANCED" KIND="REAL" DEFAULT_VALUE="1.0d-8">
              %%Keyword: CMTH <advanced>
              <HELP>
              This keyword specifies the threshold for the change of sum over states of the classical Coulomb energy for CMS intermediate states to converge.
              </HELP>
              </KEYWORD>

:kword:`ROSTate`
  This keyword can be used in an MS-PDFT calculation. This keyword stands for ROtate STates, and it rotate the states after the last diagonalization of the CASSCF, CASCI, RASSCF or RASCI calculation.
  This keyword is only effective when there is a file named :file:`Do_Rotate.txt` present in the scratch directory; otherwise the states will not be rotated.
  The file :file:`Do_Rotate.txt` stores the rotation vector that rotates the states; the rotation vector is stored in a format such that the first line of the file records the first row of the rotation matrix, and so on. This keyword writes a file called :file:`H0_Rotate.txt` in the scratch directory; :file:`H0_Rotate.txt` contains the Hamiltonian matrix of the rotated states.
  This keyword currently does not work for wave functions optimized with the DMRG algorithm.
  More information regarding XMS-PDFT or CMS-PDFT can be found on the Minnesota OpenMolcas page\ [#fn1]_.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="ROSTATE" APPEAR="Rotate states" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: ROSTate <basic>
              <HELP>
              This keyword rotates the states after the last diagonalization of the CASSCF, CASCI, RASSCF or RASCI calculation.
              </HELP>
              </KEYWORD>

DMRG keywords
.............

.. warning::

   The :kword:`DMRG` keyword has different meanings for QCMaquis, Block and CheMPS2 DMRG interfaces.

.. class:: keywordlist

:kword:`DMRG`
  For QCMaquis interface, this keyword is used standalone and activates the DMRG calculation with QCMaquis. In this case, the input should also contain :kword:`RGINPUT` block with parameters controlling the DMRG optimization settings in QCMaquis.

  For Block and CheMPS2 interfaces, it should be followed by an integer :math:`m`
  Specify maximum number of renormalized states in the DMRG calculation, also known as (virtual) bond dimension :math:`m` in each microiteration in DMRG calculations.
  :math:`m` should be at least 500.
  This keyword is supported in both CheMPS2 and Block interfaces.
  Note that DMRG-CASSCF calculations for excited states are not fully supported by the Block interface.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DMRG" LEVEL="BASIC" APPEAR="DMRG flag" KIND="INT" DEFAULT_VALUE="0" EXCLUSIVE="NECI">
              <ALTERNATE KIND="SINGLE" />
              %%Keyword: DMRG <basic>
              <HELP>
              DMRG flag:
              - for QCMaquis interface, activates the DMRG calculation
              - for Block and CheMPS2 interfaces, sets the number of renormalized states m
              </HELP>
              </KEYWORD>

Keywords for the QCMaquis DMRG interface:

.. warning::

   Using :kword:`DMRG` with QCMaquis interface is deprecated. It is advised to use the :program:`DMRGSCF` module for QCMaquis DMRG calculations.

.. class:: keywordlist

:kword:`RGInput`
  This block, terminated by :kword:`EndRG`, is mandatory and contains parameters to QCMaquis which control the DMRG wavefunction optimization. This block is equivalent to the
  :kword:`DMRGSettings..EndDMRGSettings` block of the :program:`DMRGSCF` module (see :numref:`UG:sec:dmrgsettings_input`).

  .. xmldoc:: <GROUP MODULE="RASSCF" NAME="RGINPUT" APPEAR="QCMaquis DMRG settings" KIND="BLOCK" LEVEL="BASIC">
              <INCLUDE MODULE="DMRGSCF" EXCEPT="ACTIVESPACEOPTIMIZER,FIEDLER,CIDEAS,OOPTIMIZATIONSETTINGS,FCIDUMP,SOCCUPY,NEVPT2PREP" />
              </GROUP>

: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="RASSCF" NAME="SOCCUPY" KIND="CUSTOM" LEVEL="BASIC">
              %%Keyword: soccupy <basic>
              <HELP>
              Set HF determinant start guess for MPS wave functions. (QCMaquis)
              </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.

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

Keywords for the CheMPS2 DMRG interface:

.. class:: keywordlist

:kword:`3RDM`
  Use this keyword to get the 3-particle and Fock matrix contracted with the 4-particle reduced density
  matrices (3-RDM and F.4-RDM) for DMRG-CASPT2.
  :kword:`OUTOrbitals` = ``CANOnical`` is automatically activated.
  In CheMPS2 interface, both 3-RDM and F.4-RDM are calculated.
  In Block interface, only 3-RDM is calculated while F.4-RDM is approximated in the CASPT2 module.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="3RDM" APPEAR="Calculate 3- and 4-particle reduced density matrices" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: 3RDM <basic>
              <HELP>
              Use this keyword to get the 3-particle and 4-particle reduced density matrices (3-RDM and F.4-RDM) for DMRG-CASPT2 with CheMPS2 interface.
              </HELP>
              </KEYWORD>

:kword:`CHBLb`
  Specify a threshold for activating restart in CheMPS2.
  After each macroiteration, if the max BLB value is smaller than CHBLb, activate partial restart in CheMPS2.
  If the max BLB value is smaller than CHBLb/10.0, activate full restart in CheMPS2.
  Default value is: 0.5d-2.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CHBLB" LEVEL="BASIC" APPEAR="Threshold for restart (CheMPS2)" KIND="REAL" DEFAULT_VALUE="0.05">
              %%Keyword: CHBLb <basic>
              <HELP>
              Threshold for activating restart in CheMPS2.
              </HELP>
              (Default: 0.05)
              </KEYWORD>

:kword:`DAVTolerance`
  Specify value for Davidson tolerance in CheMPS2.
  Default value is 1.0d-7.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DAVTOLERANCE" LEVEL="BASIC" APPEAR="Davidson tolerance (CheMPS2)" KIND="REAL" DEFAULT_VALUE="1.0d-7">
              %%Keyword: DAVTolerance <basic>
              <HELP>
              Davidson tolerance in CheMPS2.
              </HELP>
              (Default: 1.0d-7)
              </KEYWORD>

:kword:`NOISe`
  Specify value for noise pre-factor in CheMPS2.
  This noise is set to 0.0 in the last instruction.
  Default value (recommended) is: 0.05.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="NOISE" LEVEL="BASIC" APPEAR="Noise pre-factor (CheMPS2)" KIND="REAL" DEFAULT_VALUE="0.05">
              %%Keyword: NOISe <basic>
              <HELP>
              Noise pre-factor in CheMPS2.
              </HELP>
              (Default: 0.05)
              </KEYWORD>

:kword:`MXSWeep`
  Maximum number of sweeps. in the last instruction in CheMPS2.
  Default value is: 8.
  In the last iteration of DMRG-SCF, :kword:`MXSW` is increased by five times (default 40).

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="MXSWEEP" LEVEL="BASIC" APPEAR="Maximum number of sweeps (CheMPS2)" KIND="INT" DEFAULT_VALUE="8">
              %%Keyword: MXSWeep <basic>
              <HELP>
              Maximum number of sweeps in the last instruction in CheMPS2.
              </HELP>
              (Default: 8)
              </KEYWORD>

:kword:`MXCAnonical`
  Maximum number of sweeps in the last instruction with pseudocanonical orbitals in CheMPS2.
  Default value is: 40.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="MXCANONICAL" LEVEL="BASIC" APPEAR="Maximum number of sweeps with pseudocanonical orbitals (CheMPS2)" KIND="INT" DEFAULT_VALUE="40">
              %%Keyword: MXCAnonical <basic>
              <HELP>
              Maximum number of sweeps in the last instruction with pseudocanonical orbitals in CheMPS2.
              </HELP>
              (Default: 40)
              </KEYWORD>

:kword:`CHREstart`
  Use this keyword to activate restart in the first DMRG iteration from a previous calculation.
  The working directory must contain :file:`molcas_natorb_fiedler.txt` and :file:`CheMPS2_natorb_MPSx.h5` (``x``\=0 for the ground state,
  1 for the first excited state, etc.).
  If these files are not in the working directory, a warning is printed at the beginning of
  the calculation and restart is skipped (start from scratch).

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="CHRESTART" APPEAR="Restart in the first DMRG iteration (CheMPS2)" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: CHREstart <basic>
              <HELP>
              Use this keyword to activate restart in the first DMRG iteration from a previous calculation in CheMPS2.
              </HELP>
              </KEYWORD>

:kword:`DMREstart`
  Use this keyword to activate restart in the last DMRG iteration from the previous iteration or calculation.
  This keyword only works when using :kword:`OUTOrbitals` = ``CANOnical`` or :kword:`3RDM`.
  :kword:`DMREstart` = ``0`` (default): start from scratch to calculate 3-RDM and F.4-RDM.

  :kword:`DMREstart` = ``1``: start form user-supplied checkpoint files.
  The working directory must contain :file:`molcas_canorb_fiedler.txt` and :file:`CheMPS2_canorb_MPSx.h5` (``x``\=0 for the ground state,
  1 for the first excited state, etc.).
  If these files are not in the working directory, a warning is printed at the
  beginning of the calculation and restart is skipped (start from scratch).

  :kword:`DMREstart` = ``2`` (Not recommended): start form previous checkpoint files with natural orbitals.
  :kword:`DMREstart` = ``2`` is not recommended since this may produce non-optimal energy
  because the orbital ordering is not optimized.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DMRESTART" LEVEL="BASIC" APPEAR="Restart in the last DMRG iteration (CheMPS2)" KIND="INT" DEFAULT_VALUE="0">
              %%Keyword: DMREstart <basic>
              <HELP>
              Activate restart in the last DMRG iteration in CheMPS2.
              </HELP>
              (Default: 0)
              </KEYWORD>

A general comment concerning the input orbitals: The orbitals are ordered by
symmetry. Within each symmetry block the order is assumed to be:
frozen, inactive, active, external (secondary), and deleted. Note that
if the :kword:`Spdelete` option has been used in a preceding
:program:`SCF` calculation, the deleted orbitals will automatically be placed as
the last ones in each symmetry block.

For calculations of a molecule in a reaction field see :numref:`UG:sec:rfield`
of the present manual and :numref:`TUT:sec:cavity` of the examples manual.

HCI-CASSCF keywords
...................

.. warning::

   An external package (DICE) is required to run HCI-CASSCF.

.. class:: keywordlist

:kword:`DICE`
  Use this keyword to activate Heat-Bath Configuration Interaction (HCI)-CASSCF, calculated with the Dice--|molcas| interface.
  The perturbative component will be calculated deterministically.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DICE" APPEAR="DICE" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: DICE <basic>
              <HELP>
              Use this keyword to activate HCI-CASSCF.
              </HELP>
              </KEYWORD>

:kword:`EPSIlons`
  Array of two thresholds. :math:`\epsilon_1`: the threshold for adding determinants to the Fock space during the variational calculation; and
  :math:`\epsilon_2`: the threshold for the second-order perturbative energy correction to the variational energy. :math:`\epsilon_2 < \epsilon_1`.
  Lower thresholds will give lower HCI energy, but increase the computational cost.
  Default values are: 1.0d-4, 1.0d-5.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="EPSILONS" LEVEL="BASIC" APPEAR="Thresholds (DICE)" KIND="REALS" SIZE="2" DEFAULT_VALUES="1.0d-4,1.0d-5">
              %%Keyword: EPSIlons <basic>
              <HELP>
              Thresholds in the variational and pertubational steps.
              </HELP>
              (Default: 1.0d-4 1.0d-5)
              </KEYWORD>

:kword:`DITErations`
  Maximum number of iterations in the variational step.
  Default value is: 20.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DITERATION" LEVEL="BASIC" APPEAR="Maximum number of iterations in the variational step (DICE)" KIND="INT" DEFAULT_VALUE="20">
              %%Keyword: DITErations <basic>
              <HELP>
              Maximum number of iterations in the variational step (DICE).
              </HELP>
              (Default: 20)
              </KEYWORD>

:kword:`DIREstart`
  Use this keyword to activate restart in the first HCI iteration from a previous calculation.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DIRESTART" APPEAR="Restart in the first HCI iteration (DICE)" KIND="SINGLE" LEVEL="BASIC">
              %%Keyword: DIREstart <basic>
              <HELP>
              Use this keyword to activate restart in the first HCI iteration from a previous calculation.
              </HELP>
              </KEYWORD>

:kword:`DIOCcupy`
  Initial electronic configuration for the HCI-CASSCF calculations. This keyword is required.
  The keyword requires first the number of configurations :math:`n`, followed by :math:`n` configuration.
  Each configuration is inserted as a string of aliases of occupations/couplings of the active (RAS2) orbitals with the aliases ``2`` = full, ``u`` = up, ``d`` = down, ``0`` = empty.

  ::

    DIOCcupy
    3
    u u 2 0 2 0
    2 0 u u 2 0
    2 u d 0 u u

  In this CAS(6,6) example, three initial configurations will be read. The first configuration is :math:`\ket{\mathord{\uparrow\uparrow}2020}`.

  .. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DIOCCUPY" KIND="STRINGS_COMPUTED" LEVEL="BASIC">
              %%Keyword: DIOCcupy <basic>
              <HELP>
              Set HF determinant start guess for HCI wave functions (DICE).
              </HELP>
              </KEYWORD>

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

The following example shows the input to the
:program:`RASSCF` program for a calculation on the water molecule. The calculation is
performed in :math:`C_{2v}` symmetry (symmetries: :math:`a_1`, :math:`b_2`, :math:`b_1`, :math:`a_2`, where the two
last species are antisymmetric with respect to the molecular plane). Inactive
orbitals are :math:`1a_1` (oxygen 1s) :math:`2a_1` (oxygen 2s) and
:math:`1b_1` (the :math:`\pi` lone-pair orbital). Two bonding and two anti-bonding
OH orbitals are active, :math:`a_1` and :math:`b_2` symmetries. The calculation is
performed for the :math:`^1A_1` 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

The following input is an example of how to use the RASSCF program to run MC-PDFT calculations: ::

  &RASSCF
  Ras2
  1 0 0 0 1 0 0 0

  >>COPY $CurrDir/$Project.JobIph JOBOLD

  &RASSCF
  JOBIPH
  CIRESTART
  CIONLY
  Ras2
  1 0 0 0 1 0 0 0
  KSDFT
  ROKS; T:PBE

The first RASSCF run is a standard CASSCF calculation that leads to variationally optimized orbitals and CI coefficients.
The second call to the RASSCF input will use the CI vector and the orbitals previously optimized. The second RASSCF will
require the :kword:`CIONLY` keyword as the MC-PDFT is currently not compatible with SCF. :kword:`KSDFT` :kword:`ROKS` and the functional choice will
provide MC-PDFT energies.

More advanced examples can be found in the tutorial section of the manual.

Input example for DMRG-CASSCF with CheMPS2--|molcas| interface: ::

  &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
  DMRG     = 500
  3RDM

Input example for HCI-CASSCF with Dice--|molcas| interface: ::

  &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
  THRS     = 1.0e-07 1.0e-03 1.0e-03
  DICE
  EPSIlons = 1.0d-4 1.0d-5
  DITErations = 30
  DIOCuppy
  1
  2 0  2 0

.. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="H5CI" LEVEL="UNDOCUMENTED" KIND="SINGLE" />

.. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="AVERAGE" LEVEL="UNDOCUMENTED" KIND="INTS_COMPUTED" SIZE="2" />

.. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="FAROALD" LEVEL="UNDOCUMENTED" KIND="SINGLE" />

.. xmldoc:: <KEYWORD MODULE="RASSCF" NAME="DEXS" LEVEL="UNDOCUMENTED" KIND="INTS" SIZE="2" />

.. xmldoc:: </MODULE>
