.. index::
   single: Program; GUGACI
   single: GUGACI

.. _UG\:sec\:gugaci:

:program:`GUGACI`
=================

.. only:: html

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

Description
-----------

.. xmldoc:: <MODULE NAME="GUGACI">
            %%Description:
            <HELP>
            The GUGACI program is used for Multi-Reference
            SDCI calculations. The code originates in an MRCI
            program by Zhenyi Wen and Yubin Wang, Zhenting Gan, Bingbing Suo
            Yibo Lei also contribute to this program.
            It requires a file generated by the GUGADRT program.
            </HELP>

The
:program:`GUGACI`
program :index:`generates <single: Coupling coefficients; GUGACI>` :index:`Multi Reference <single: Multireference; SDCI>` :index:`SDCI <single: SDCI; using GUGACI>`
wavefunctions. The program is
based on the :index:`Direct CI <single: Direct CI>` method :cite:`Roos:72`,
and with distict row table generated by :program:`GUGADRT`
(See program description for
:program:`GUGADRT`). The hole-particle symmetry based on GUGA is used
in :program:`GUGACI` :cite:`YBWang:1,BSuo:1`.
If requested, :program:`GUGACI` computes matrix elements of those
one-electron properties for which it can find integrals in the
:file:`ONEINT` file. It also
generates natural orbitals that can be fed into
the property program to evaluate certain one electron properties.
The natural orbitals are also useful for Iterated Natural Orbital
(:index:`INO`) calculations.

The :program:`GUGACI` code is written by Yubin Wang,
Zhenyi Wen, Zhenting Gan, Bingbing Suo and Yibo Lei
(Institute of Modern Physics, Northwest University, China).

The program can calculate several eigenvectors simultaneously.

Orbital subspaces
.................

The orbital space is divided into the following subspaces: Frozen,
Inactive, Active, Secondary, and Deleted orbitals. Within each
symmetry type, they follow this order.

* **Frozen:**
  :index:`Frozen orbitals <single: GUGACI; Frozen>` are always doubly
  occupied, i.e., they are not correlated. Orbitals should be frozen
  already in the integral transformation step, program
  :program:`MOTRA`, and need not be specified in the input to the
  :program:`GUGACI` program. If it's specified, it will be ignored.

* **Inactive:**
  :index:`Inactive orbitals <single: GUGACI; Inactive>` are doubly occupied
  in all reference configurations, but excitations out of this orbital
  space are allowed in the final CI wavefunction, i.e., they are
  correlated but have two electrons in all reference configurations.

* **Active:**
  :index:`Active orbitals <single: GUGACI; Active>` are those which may have
  different occupation in different reference configurations.

* **Secondary:**
  :index:`This subspace <single: GUGACI; Secondary>` is empty in all
  reference configurations, but may be populated with up to two
  electrons in the excited configurations. This subspace is not
  explicitly specified, but consists of the orbitals which are left over
  when other spaces are accounted for.

* **Deleted:**
  :index:`This orbital subspace <single: GUGACI; Deleted>` does not
  participate in the CI wavefunction at all. Typically the 3s,4p,...
  components of 3d,4f,..., or orbitals that essentially describe core
  correlation, are deleted. Similar to freezing, deleting should be done in
  :program:`MOTRA`,
  which is more efficient, and do not need to be specified in the
  :program:`GUGACI` program.

Since ordinarily the frozen and deleted orbitals were handled by
:program:`MOTRA`
and the subdivision into inactive and
active orbitals were defined in
:program:`GUGADRT`, program :program:`GUGACI` will neglect them.

.. index::
   pair: Dependencies; GUGACI

.. _UG\:sec\:gugaci_dependencies:

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

The program needs the distict row table generated by the program
:program:`GUGADRT` and transformed one- and two-electron integrals
generated by the program
:program:`MOTRA`.

.. index::
   pair: Files; GUGACI

.. _UG\:sec\:gugaci_files:

Files
-----

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

.. class:: filelist

:file:`GUGADRT`
  Distict row table from :program:`GUGADRT`.

:file:`TRAINT*`
  Transformed two-electron integrals from :program:`MOTRA`.

:file:`TRAONE`
  Transformed one-electron integrals from :program:`MOTRA`.

:file:`ONEINT`
  One-electron property integrals from :program:`SEWARD`.

:file:`MRCIVECT`
  Used for input only in restart case.

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

.. class:: filelist

:file:`CIORBnn`
  One or more sets of natural orbitals, one for each CI root, where
  nn stands for 01,02, etc.

:file:`CIVECT`
  CI vector, for later restart.

.. :file:`CIORBnn`
     only the first will be defined as default,
     with the FORTRAN file name

   :file:`CIORB`
     used for

   :file:`CIORB01`
     ..

Note that these file names are the FORTRAN file names used by the program,
so they have to be mapped to the actual file names. This is usually done
automatically in the |molcas| system. However, in the case of several
different numbered files

Local files
...........

.. class:: filelist

:file:`FTxxF01`
  :program:`MRCI` produces a few scratch files that are not needed by any other program
  in |molcas|. Presently, these are xx=14, 15, 16, 21, 25, 26, 27, and 30.
  The files are opened, used, closed and removed automatically.
  See source code for further information.

.. index::
   pair: Input; GUGACI

.. _UG\:sec\:gugaci_input:

Input
-----

This section describes the input to the
:program:`GUGACI` program in the |molcas| program system, with
the program name: ::

  &GUGACI

.. index::
   pair: GUGACI; Keywords

Keywords
........

The first four characters are decoded and the rest are ignored.

.. class:: keywordlist

:kword:`TITLe`
  The lines following this keyword are treated as title lines, until
  another keyword is encountered. A maximum of ten lines is allowed.

  .. xmldoc:: <KEYWORD MODULE="GUGACI" NAME="TITLE" APPEAR="Title" KIND="STRING" LEVEL="BASIC">
              <HELP>
              Enter at most ten lines of arbitrary title. Do not use any keywords
              as the first characters of each line.
              </HELP>
              %%Keyword: Title <basic>
              Followed by title lines, until the next keyword is recognized.
              </KEYWORD>

:kword:`NRROots`
  Specifies the number of CI roots (states) to be simultaneously
  optimized. The default is 1. The value is read from the next line.

  .. xmldoc:: <KEYWORD MODULE="GUGACI" NAME="NRROOTS" APPEAR="Number of states" KIND="INT" LEVEL="BASIC">
              %%Keyword: NRRoots <basic>
              <HELP>
              The number of CI roots (states) to be computed. Default=1.
              </HELP>
              </KEYWORD>

:kword:`RESTart`
  Restart the calculation from a previous calculation. No additional
  input is required. The :file:`MRCIVECT` file is required for restarted
  calculations.

  .. xmldoc:: <KEYWORD MODULE="GUGACI" NAME="RESTART" APPEAR="Restart CI calculation" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: Restart <advanced>
              <HELP>
              Use a previous wavefunction from the MRCIVECT file as start approximation.
              </HELP>
              Require MRCISD calculation is restarted. MRCIVEC file should be exists.
              </KEYWORD>

:kword:`THRPrint`
  Threshold for printout of the wavefunction. All configurations with a
  coefficient greater than this threshold are printed.
  The default is 0.05. The value is read from the line
  following the keyword.

  .. xmldoc:: <KEYWORD MODULE="GUGACI" NAME="THRPRINT" APPEAR="Threshold for printing CFSs" KIND="REAL" LEVEL="ADVANCED">
              %%Keyword: Thrprint <advanced>
              <HELP>
              Enter threshold of CI coefficients to be printed. Default 0.05.
              </HELP>
              </KEYWORD>

:kword:`CONvergence`
  Energy convergence threshold. The result is converged when the energy
  of all roots has been lowered less than this threshold in the last
  iteration. The default is 1.0d-8. The value is read from the line
  following the keyword.

  .. xmldoc:: <KEYWORD MODULE="GUGACI" NAME="CONVERGENCE" APPEAR="Convergence threshold" KIND="REALS" SIZE="3" LEVEL="ADVANCED">
              %%Keyword: Convergence <advanced>
              <HELP>
              Three float numbers to enter energy, ci vector, and residual vector
              convergence threshold. Default 1.0D-8,1.0D-6,1.0D-8
              </HELP>
              </KEYWORD>

:kword:`PRINt`
  Print level of the program. Default is 5. The value is read from the
  line following the keyword.

  .. xmldoc:: <KEYWORD MODULE="GUGACI" NAME="PRINT" APPEAR="Print control" KIND="INT" LEVEL="ADVANCED">
              %%Keyword: Print <advanced>
              <HELP>
              Set print level. Default is 5.
              </HELP>
              </KEYWORD>

:kword:`MAXIterations`
  Maximum number of iterations. Default 20. The
  value is read from the line following the keyword.
  The maximum possible value is 200.

  .. xmldoc:: <KEYWORD MODULE="GUGACI" NAME="MAXITERATIONS" APPEAR="Maximum number of CI iterations" KIND="INT" LEVEL="ADVANCED">
              %%Keyword: Maxiterations <advanced>
              <HELP>
              Set maximum number of iterations. Default is 30. Largest possible is 200.
              </HELP>
              </KEYWORD>

:kword:`PRORbitals`
  Threshold for printing natural orbitals. Only orbitals with occupation
  number larger than this threshold appears in the printed output. The
  value is read from the line following the keyword.
  Default is 1.0d-5.

  .. xmldoc:: <KEYWORD MODULE="GUGACI" NAME="PRORBITALS" APPEAR="Threshold for printing natural orbitals" KIND="REAL" LEVEL="ADVANCED">
              %%Keyword: Prorbitals <advanced>
              <HELP>
              Threshold on occupation number, for printing natural orbitals. Default 1.0D-5.
              </HELP>
              </KEYWORD>

:kword:`CPROperty`
  Request to calculate properties. Property integrals should be saved in file :file:`ONEINT`.

  .. xmldoc:: <KEYWORD MODULE="GUGACI" NAME="CPROPERTY" APPEAR="Calculate properties" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: Cproperty <advanced>
              <HELP>
              Request to calculate properties.
              </HELP>
              </KEYWORD>

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

::

  &GUGACI
  Title
   Water molecule. 1S frozen in transformation.
  Nrroots
   1

.. xmldoc:: <KEYWORD MODULE="GUGACI" NAME="PTHR" KIND="REAL" LEVEL="UNDOCUMENTED" />

.. xmldoc:: </MODULE>