% grid_it.tex $ this file belongs to the Molcas repository $

\section{\program{GRID\_IT}}
\label{UG:sec:gridit}
\index{Program!Grid\_It@\program{Grid\_It}}\index{Grid\_It@\program{Grid\_It}}

\subsection{Description}
\label{UG:sec:gridit_description}
%%%<MODULE NAME="GRID_IT" ONSCREEN="HF,HF-GEOMETRY,CAS,CAS-GEOMETRY">
%%Description:
%%%<HELP>
%%+GRID_IT is an interface program for calculations of molecular
%%+orbitals and density in a set of Cartesian grid points.
%%+Calculated grid can be visualized by LUSCUS programs
%%%</HELP>
\program{GRID\_IT} is an interface program for calculations of molecular
orbitals and density in a set of Cartesian grid points. The calculated grid
can be visualized by \program{LUSCUS} program.

\subsection{Dependencies}
\label{UG:sec:gridit_dependencies}
The \program{GRID\_IT} program requires the communication file \file{RUNFILE},
produced by \program{GATEWAY} and an orbital file \file{INPORB}: \file{SCFORB},
\file{RASORB}, \file{PT2ORB}, generated by program \program{SCF}(calculated with RHF or UHF hamiltonian), \program{RASSCF},
or \program{CASPT2}, respectively.

\subsection{Files}
\label{UG:sec:gridit_files}
\index{Files!GRID\_IT}\index{GRID\_IT!Files}

Below is a list of the files that are used/created by the program
\program{GRID\_IT}.

\subsubsection{Input files}

\begin{filelist}
%---
\item[RUNFILE]
File for communication of auxiliary information generated by the program
\program{GATEWAY}.
%---
\item[INPORB]
\file{SCFORB} or another orbitals file (\file{RASORB}, \file{CIORB},
\file{CPFORB}, \file{SIORB}, \file{PT2ORB}) containing calculated orbitals.
If used after \program{SCF} run, the information about one-electron
energies is also retrieved.
\end{filelist}

\subsubsection{Output files}

\begin{filelist}
%---
\item[LUS]
Output file in LUSCUS format, with default extension \file{.lus} --- the only file needed
for drawing program. In the case of
UHF calculation, \program{GRID\_IT} produces two files: \file{a.lus} and
\file{b.lus} with grids for alpha and beta electrons.
\program{LUSCUS} code could be used to combine grid files
for visualization of total or spin density.
\item[GRID]
Obsolete format of the grid file, can be converted to Cube files using 
the \program{grid2cube} tool. In order to generate a file with data
written in grid format, keyword \keyword{NOLUSCUS} should be used.
\end{filelist}

\subsection{Input}
\label{UG:sec:gridit_input}
\index{Input!GRID\_IT}\index{GRID\_IT!Input}

Normally, it is no reason to change any default setting of calculated
grid - the choice of appropriate grid size, net frequency, as well as
choice of MO can be done automatically.

If user did not specified the selection of orbitals, \program{GRID\_IT}
makes a decision based on information in the \file{InpOrb} file. For example,
if \file{InpOrb} contains data after SCF calculation, a set of orbitals
around HOMO-LUMO gap will be used. If \file{InpOrb} contains active orbitals,
they will be used as a default set.

Below follows a description of the input to \program{GRID\_IT}. The keywords
are always significant to four characters, but in order to make the
input more transparent, it is recommended to use the full keywords.
The \program{GRID\_IT} program section of the \molcas\ input starts with the
standard reference to the code:
\begin{inputlisting}
 &GRID_IT
\end{inputlisting}

Argument(s) to a keyword are always supplied on the next line of the
input file, except when explicitly stated otherwise.

\subsubsection{Optional general keywords}
\begin{keywordlist}
%---
\item[TITLe]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="TITLE" KIND="STRING" LEVEL="BASIC">
%%Keyword: Title basic
%%%<HELP>
%%+One line following this one is regarded as title.
%%%</HELP></KEYWORD>
One line following this one is regarded as title.
%---
\item[NAME]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="NAME" KIND="STRING" LEVEL="ADVANCED">
%%Keyword: Name basic
%%%<HELP>
%%+One line following this one is used for generation of
%%+grid filename in the form: "Project.Name.lus".
%%%</HELP></KEYWORD>
One line following this one is used for generation of
grid filename in the form: ``Project.Name.lus''.
%---
\item[FILE]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="FILE" APPEAR="INPORB file" KIND="STRING" LEVEL="BASIC">
%%Keyword: File basic
%%%<HELP>
%%+On the following line user can specify the filename, which will be
%%+used instead of INPORB (default).
%%%</HELP></KEYWORD>
On the following line user can specify the filename, which will be
used instead of INPORB (default). For example: \keyword{FileOrb=\$CurrDir/\$Project.ScfOrb}.

%---
%%% <SELECT MODULE="GRID_IT" NAME="QUALITY" APPEAR="Grid Quality" LEVEL="BASIC" CONTAINS="DEFAULT,SPARSE,DENSE">
\item[SPARse]
%%Tested: ##013
%%%<KEYWORD MODULE="GRID_IT" NAME="SPARSE" APPEAR="Sparse" KIND="SINGLE" LEVEL="BASIC" EXCLUSIVE="DENSE" MEMBER="QUALITY">
%%Keyword: Sparse basic
%%%<HELP>
%%+Set up sparse Cartesian net with 1 grid point per a.u.
%%+Note that quality of the grid can be poor.
%%+Default is 3 points per a.u.
%%%</HELP></KEYWORD>
Set up sparse Cartesian net with 1 grid point per a.u.
Note that quality of the grid can be poor.
Default (without \keyword{Sparse} or \keyword{Dense}) is 3 points per a.u.
%---
\item[DENSe]
%%Tested: ##219
%%%<KEYWORD MODULE="GRID_IT" NAME="DENSE" APPEAR="Dense" KIND="SINGLE" LEVEL="BASIC" EXCLUSIVE="SPARSE" MEMBER="QUALITY">
%%Keyword: Dense basic
%%%<HELP>
%%+Set up dense Cartesian net with 10 grid point per a.u.
%%%</HELP></KEYWORD>
Set up net with 10 grid points per a.u. Note that using this option
without choice of orbitals to draw you can produce very large output file.
%%%</SELECT>
%---
%  --- not clear - do we need packing at all ---
% \item[PACK]
% %%%<KEYWORD MODULE="GRID_IT" NAME="PACK" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="NOPACK">
% %%Keyword: Pack basic
% %%%<HELP>
% %%+Use packing of data, to create a lower quality, but smaller output files.
% %%%</HELP></KEYWORD>
% Use packing of data, to create a lower quality, but smaller output files.
% %---
% \item[NOPACK]
% %%%<KEYWORD MODULE="GRID_IT" NAME="NOPACK" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="PACK">
% %%Keyword: NoPack basic
% %%%<HELP>
% %%+Do not use packing of data. By default, unless Dense grid is used,
% %%+the data is packed, so the picture has lower (screen) quality.
% %%%</HELP></KEYWORD>
% Do not use packing of data. By default, unless Dense grid is used,
% the data is packed, so the picture has lower (screen) quality.
%---
\item[GAP]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="GAP" KIND="REAL" LEVEL="ADVANCED">
%%Keyword: Gap advanced
%%%<HELP>
%%+Keyword, followed by real equals to distance between
%%+the atomic nuclei in the molecule and the border of grid.
%%+Default value is 4.0 a.u.
%%%</HELP></KEYWORD>
Keyword, followed by real equals to distance between
the atomic nuclei in the molecule and the border of grid.
Default value is 4.0 a.u.
%---
\item[ORBItal]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="ORBITAL" KIND="INTS_COMPUTED" SIZE="2" MIN_VALUE="1" LEVEL="ADVANCED" EXCLUDED="SELECT">
%%Keyword: Orbital advanced
%%%<HELP>
%%+Direct specification of orbitals to show. Follows by
%%+number of calculated grids, and pairs of integers - symmetry
%%+and orbital within this symmetry.
%%%</HELP></KEYWORD>
Direct specification of orbitals to show. Next line set up
number of calculated grids. And at next line(s) pairs of integers - symmetry
and orbital within this symmetry is given.
\item[SELEct]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="SELECT" KIND="STRING" LEVEL="ADVANCED" EXCLUDED="ORBITAL">
%%Keyword: Select advanced
%%%<HELP>
%%+Direct specification of orbitals to show. Follows by one line
%%+in the format: symmetry:FirstOrbital-LastOrbital
%%+(Ex: 1:2-7 2:5-8)
%%%</HELP></KEYWORD>
Direct specification of orbitals to show. Follows by one line
in the format: symmetry:first\_orbital-last\_orbital
(Ex: 1:2-7 2:5-8)

%---
\item[MULLiken]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="MULLIKEN" KIND="STRING" LEVEL="ADVANCED">
%%Keyword: Mulliken advanced
%%%<HELP>
%%+Compute Mulliken charges separately for each occupied MO specified in
%%+the GRID_IT input. "LONG print" is an optional argument for more
%%+detailed printout.
%%%</HELP></KEYWORD>
Compute Mulliken charges separately for each occupied MO specified in
the GRID\_IT input. "LONG print" is an optional argument for more
detailed printout.

%---
\item[NoSort]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="NOSORT" APPEAR="NoSort" KIND="SINGLE" LEVEL="ADVANCED">
%%Keyword: NoSort advanced
%%%<HELP>
%%+Do not sort orbitals by occupation numbers and orbital energies
%%%</HELP></KEYWORD>
Do not sort orbitals by occupation numbers and orbital energies
%---

%---
\item[ORANge]
%%%<SELECT MODULE="GRID_IT" NAME="SELECTION" APPEAR="Orbital Selection" LEVEL="ADVANCED" CONTAINS="DEFAULT,ERANGE,ORANGE,ALL">
%%Tested: ##205
%%%<KEYWORD MODULE="GRID_IT" NAME="ORANGE" APPEAR="oRange" KIND="REALS" SIZE="2" MIN_VALUE="0" MAX_VALUE="2" LEVEL="ADVANCED" EXCLUSIVE="ERANGE,ALL" MEMBER="SELECTION">
%%Keyword: ORANge advanced
%%%<HELP>
%%+Followed by 2 numbers to limit the interval of
%%+orbitals by occupation numbers
%%%</HELP></KEYWORD>
Followed by 2 numbers, to limit the interval of
orbitals by occupation numbers.
%---
%---
\item[ERANge]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="ERANGE" APPEAR="eRange" KIND="REALS" SIZE="2" MIN_VALUE="0" MAX_VALUE="2" LEVEL="ADVANCED" EXCLUSIVE="ORANGE,ALL" MEMBER="SELECTION">
%%Keyword: ERANge advanced
%%%<HELP>
%%+Followed by 2 numbers to limit the interval of
%%+orbitals by one-electron energies
%%%</HELP></KEYWORD>
Followed by 2 numbers, to limit the interval of
orbitals by one-electron energies
%---
\item[ALL]
%%Tested: ##219
%%%<KEYWORD MODULE="GRID_IT" NAME="ALL" APPEAR="ALL Orbitals" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="ORANGE,ERANGE" MEMBER="SELECTION">
%%Keyword: All advanced
%%%<HELP>
%%+Calculate grids for all molecular orbitals.
%%%</HELP></KEYWORD>
Calculate grids for all molecular orbitals. Using this keyword you can produce a
huge output file!
%%%</SELECT>
%---
% \item[NODEnsity]
% %%%<KEYWORD MODULE="GRID_IT" NAME="NODENSITY" APPEAR="No Density" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="TOTAL">
% %%+Keyword: NoDensity advanced
% %%+<HELP>
% %%+Keyword to suppress calculation of grid for density
% %%%</HELP></KEYWORD>
% Keyword to suppress calculation of grid for density
%---
\item[TOTAl]
%%Tested: ##071
%%%<KEYWORD MODULE="GRID_IT" NAME="TOTAL" APPEAR="Total Density" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="NODENSITY">
%%Keyword: Total advanced
%%%<HELP>
%%+Request to calculate a grid for the (correct) total
%%+density computed
%%+from contributions of all orbitals, instead of (default)
%%+just from the orbitals chosen by user.
%%%</HELP></KEYWORD>
Request to calculate a grid for the (correct) total
density computed from contributions of all orbitals, instead of (default)
just from the orbitals chosen by user.
%---
\item[VB]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="VB" KIND="SINGLE" LEVEL="NOTIMPLEMENTED">
%%Keyword: VB advanced
%%%<HELP>
%%+Plots orbitals from the latest CASVB calculation.
%%%</HELP></KEYWORD>
This keyword enables plotting of the orbitals from the latest \program{CASVB} orbitals.
Note that the appropriate \file{RASORB} orbitals must be available in the \file{INPORB} file.
%---
%%% <SELECT MODULE="GRID_IT" NAME="FORMAT" APPEAR="Output Format" LEVEL="ADVANCED" CONTAINS="DEFAULT,ASCII,ATOM,CUBE">
\item[ATOM]
%%Tested: ##071 ##219
%%%<KEYWORD MODULE="GRID_IT" NAME="ATOM" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="ASCII">
%%Keyword: ATOM advanced
%%%<HELP>
%%+Calculate density in the position of atoms
%%%</HELP></KEYWORD>
 Calculate density at the position of atoms.
%---
\item[ASCII]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="ASCII" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="ATOM">
%%Keyword: ASCII advanced
%%%<HELP>
%%+Obsolete keyword for ASCII format of output file. This option can only
%%+be used in combination with NOLUSCUS
%%%</HELP></KEYWORD>
Obsolete keyword for ASCII format of output file. This option can only
be used in combination with \keyword{NOLUSCUS}.
This keyword is useful if a calculation
of the grid file and visualization should be done on computers with
different architectures. 

%---
%%%</SELECT>
%---
\item[NPOInts]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="NPOINTS" APPEAR="nPoints" KIND="INTS" SIZE="3" LEVEL="ADVANCED" EXCLUSIVE="GRID">
%%Keyword: Npoints advanced
%%%<HELP>
%%+Keyword, followed by 3 integers equal to number of grid points
%%+in x, y, z directions
%%%</HELP></KEYWORD>
Keyword, followed by 3 integers equal to number of grid points
in x, y, z directions. Using for non-automatic choice of grid network.
%---
\item[GRID]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="GRID" KIND="REALS_COMPUTED" SIZE="3" LEVEL="ADVANCED" EXCLUSIVE="NPOINTS">
%%Keyword: GRID advanced
%%%<HELP>
%%+Keyword to set manually coordinates of a grid. Followed by number of
%%+Cartesian coordinates, and on next lines - x y z coordinates of
%%+a grid (in a.u.)
%%%</HELP></KEYWORD>
Keyword to set manually coordinates of a grid. Followed by number of
Cartesian coordinates, and on next lines - x y z coordinates of
a grid (in a.u.)
%---
\item[GORI]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="GORI" KIND="REALS" SIZE="12" LEVEL="ADVANCED" EXCLUSIVE="GRID" REQUIRE="NPOINTS">
%%Keyword: GORI advanced
%%%<HELP>
%%+Keyword to set manually the parallelepiped spanning a grid.
%%+Followed by four lines of three columns each.
%%+The first line defines the x y z location of the origin,
%%+the next three lines are three linearly independent vectors
%%+that span the parallelepiped of the grid.
%%+This keyword requires NPOINTS to build up the lattice of gridpoints.
%%%</HELP></KEYWORD>
Keyword to set manually the parallelepiped spanning a grid.
Followed by four lines of three columns each.
The first line defines the x y z location of the origin,
the next three lines are three linearly independent vectors
that span the parallelepiped of the grid.
This keyword requires \keyword{NPOINTS} to build up the lattice of gridpoints.
\item[NOLUSCUS]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="NOLUSCUS" APPEAR="Old grid format" KIND="SINGLE" LEVEL="ADVANCED">
%%Keyword: NOLUSCUS advanced
%%%<HELP>
%% Produce data file in obsolete format (which can be read by old 
%% (before 2015) versions of GV)
%%%</HELP></KEYWORD>
Produce data file in obsolete format (which can be read by old 
(before 2015) versions of \program{GV}).
\item[XFIELD]
%%Tested: NONE
%%%<KEYWORD MODULE="GRID_IT" NAME="XFIELD" KIND="SINGLE" LEVEL="ADVANCED">
%%Keyword: XFIELD advanced
%%%<HELP>
%% Use Grid_It in a special mode (to produce the grid for non-cartesian points).
%%%</HELP></KEYWORD>
Use \program{Grid\_It} it in a special mode (to produce the grid for non-cartesian points).

%%%</MODULE>
%---
\end{keywordlist}

\subsubsection{Input example}
An example for high quality picture, containing selected orbitals (from symmetry 1 and 4):
\begin{inputlisting}
 &GRID_IT
Dense
Select
1:10-20,4:3-7
\end{inputlisting}

An example for screen quality picture, containing all orbitals:
\begin{inputlisting}
 &GRID_IT
SPARSE
ALL
\end{inputlisting}

An example for selection orbitals with partial occupation
\begin{inputlisting}
 &GRID_IT
ORange = 0.01 1.99
\end{inputlisting}
