% gugaci.tex $ this file belongs to the Molcas repository $*/
\section{\program{GUGACI}}
\label{UG:sec:GUGACI}
\index{Program!GUGACI@\program{GUGACI}}\index{GUGACI@\program{GUGACI}}
%%%<MODULE NAME="GUGACI">
%%Description:
%%%<HELP>
%%+The MRCI 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 generates Multi Reference SDCI
\index{SDCI!using \program{GUGACI}}
\index{Multireference!SDCI}
\index{Direct CI}
\index{Coupling coefficients!GUGACI}
wavefunctions. The program is
based on the 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}--\cite{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
(INO) \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.

\subsubsection{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.
\begin{itemize}
\itemsep 9pt plus 3pt minus 3pt
\item
{\bf Frozen:}
\index{GUGACI!Frozen}
Frozen orbitals 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{MRCI} program. If it's specified, it will be ignored.
\item
{\bf Inactive:}
\index{MRCI!Inactive}
Inactive orbitals 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.
\item
{\bf Active:}
\index{GUGACI!Active}
Active orbitals are those which may have
different occupation in different reference configurations.
\item
{\bf Secondary:}
\index{GUGACI!Secondary}
This subspace 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.
\item
{\bf Deleted:}
\index{GUGACI!Deleted}
This orbital subspace does not
participate in the CI wavefunction at all. Typically the 3s,4p,$\ldots$
components of 3d,4f$\ldots$, 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{MRCI} program.
\end{itemize}

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.

\subsection{Dependencies}
\label{UG:sec:gugaci_dependencies}
\index{Dependencies!GUGACI}\index{GUGACI!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}.

\subsection{Files}
\label{UG:sec:gugaci_files}
\index{Files!GUGACI}\index{GUGACI!Files}
\subsubsection{Input files}

\begin{filelist}
%------
\item[GUGADRT]
{Distict row table from \program{GUGADRT}.}
%------
\item[TRAINT*]
{Transformed two-{}electron integrals from \program{MOTRA}.}
%------
\item[TRAONE]
{Transformed one-{}electron integrals from \program{MOTRA}.}
%------
\item[ONEINT]
{One-{}electron property integrals from \program{SEWARD}.}
%------
\item[MRCIVECT]
{Used for input only in restart case.}
%------
\end{filelist}

\subsubsection{Output files}
\begin{filelist}
%------
\item[CIORBnn]
One or more sets of natural orbitals, one for each CI root, where
nn stands for 01,02, etc.
%------
\item[CIVECT]
CI vector, for later restart.
%------
\end{filelist}

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
%\file{CIORBnn} only the first will be defined as default,
%with the FORTRAN file name
%\file{CIORB}
%used for
%\file{CIORB01 }.

\subsubsection{Local files}
\begin{filelist}
\item[FTxxF01]
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.
\end{filelist}

\subsection{Input}
\label{UG:sec:gugaci_input}
\index{Input!GUGACI}\index{GUGACI!Input}
This section describes the input to the
\program{GUGACI} program in the \molcas\ program system, with
the program name:
\begin{inputlisting}
 &MRCI
\end{inputlisting}

\subsubsection{Keywords}

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

\index{MRCI!Keywords} \index{Keywords!MRCI}
\begin{keywordlist}
%---
%%%<KEYWORD MODULE="MRCI" 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>
%%Keyword: Title basic
%%+Followed by title lines, until the next keyword is recognized.
\item[TITLe]
The lines following this keyword are treated as title lines, until
another keyword is encountered. A maximum of ten lines is allowed.
%---
%%%<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>
%---
\item[NRROots]
Specifies the number of CI roots (states) to be simultaneously
optimized. The default is 1. The value is read from the next line.
%---
%%%<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></KEYWORD>
%%+Require MRCISD calculation is restarted. MRCIVEC file should be exists.
%---
\item[RESTart]
Restart the calculation from a previous calculation. No additional
input is required. The \file{MRCIVECT} file is required for restarted
calculations.
%---
%%%<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>
%---
\item[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.
%---
%%%<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>
%---
\item[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.
%---
%%%<KEYWORD MODULE="GUGACI" NAME="PRINT" APPEAR="Print control" KIND="INT" LEVEL="ADVANCED">
%%Keyword: Print <advanced>
%%%<HELP>
%%+Set print level. Default is 5.
%%%</HELP></KEYWORD>
%---
\item[PRINt]
Print level of the program. Default is 5. The value is read from the
line following the keyword.
%---
%%%<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>
%---
\item[MAXIterations]
Maximum number of iterations. Default 20. The
value is read from the line following the keyword.
The maximum possible value is 200.
%---
%%%<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>
%---
\item[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.
%---
%%%<KEYWORD MODULE="GUGACI" NAME="CPROPERTY" APPEAR="Calculate properties" KIND="SINGLE" LEVEL="ADVANCED">
%%Keyword: Cproperty <advanced>
%%%<HELP>
%%+Request to calculate properties.
%%%</HELP></KEYWORD>
%%%</MODULE>
%---
\item[CPROperty]
Request to calculate properties. Property integrals should be saved in file \file{ONEINT}.
%---
\end{keywordlist}

\subsubsection{Input example}

\begin{inputlisting}
 &GUGACI
Title
 Water molecule. 1S frozen in transformation.
Nrroots
 1
\end{inputlisting}



