.. index::
   single: Program; GRID_IT
   single: GRID_IT

.. _UG\:sec\:gridit:

:program:`GRID_IT`
==================

.. warning::

   This program requires a submodule

.. only:: html

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

.. _UG\:sec\:gridit_description:

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

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

.. _UG\:sec\:gridit_dependencies:

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.

.. index::
   pair: Files; GRID_IT

.. _UG\:sec\:gridit_files:

Files
-----

Below is a list of the files that are used/created by the program
:program:`GRID_IT`.

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

.. class:: filelist

:file:`RUNFILE`
  File for communication of auxiliary information generated by the program
  :program:`GATEWAY`.

:file:`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.

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

.. class:: filelist

:file:`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.

:file:`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 :kword:`NOLUSCUS` should be used.

.. index::
   pair: Input; GRID_IT

.. _UG\:sec\:gridit_input:

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

  &GRID_IT

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

Optional general keywords
.........................

.. class:: keywordlist

:kword:`TITLe`
  One line following this one is regarded as title.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="TITLE" KIND="STRING" LEVEL="BASIC">
              %%Keyword: Title <basic>
              %%Tested: NONE
              <HELP>
              One line following this one is regarded as title.
              </HELP>
              </KEYWORD>

:kword:`NAME`
  One line following this one is used for generation of
  grid filename in the form: "Project.Name.lus".

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="NAME" KIND="STRING" LEVEL="ADVANCED">
              %%Keyword: Name <basic>
              %%Tested: NONE
              <HELP>
              One line following this one is used for generation of
              grid filename in the form: "Project.Name.lus".
              </HELP>
              </KEYWORD>

:kword:`FILE`
  On the following line user can specify the filename, which will be
  used instead of INPORB (default). For example: :kword:`FileOrb=$CurrDir/$Project.ScfOrb`.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="FILE" APPEAR="INPORB file" KIND="STRING" LEVEL="BASIC">
              %%Keyword: File <basic>
              %%Tested: NONE
              <HELP>
              On the following line user can specify the filename, which will be
              used instead of INPORB (default).
              </HELP>
              </KEYWORD>

:kword:`SPARse`
  Set up sparse Cartesian net with 1 grid point per a.u.
  Note that quality of the grid can be poor.
  Default (without :kword:`Sparse` or :kword:`Dense`) is 3 points per a.u.

  .. xmldoc:: <SELECT MODULE="GRID_IT" NAME="QUALITY" APPEAR="Grid Quality" LEVEL="BASIC" CONTAINS="DEFAULT,SPARSE,DENSE">

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="SPARSE" APPEAR="Sparse" KIND="SINGLE" LEVEL="BASIC" EXCLUSIVE="DENSE" MEMBER="QUALITY">
              %%Keyword: Sparse <basic>
              %%Tested: ##013
              <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>

:kword:`DENSe`
  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.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="DENSE" APPEAR="Dense" KIND="SINGLE" LEVEL="BASIC" EXCLUSIVE="SPARSE" MEMBER="QUALITY">
              %%Keyword: Dense <basic>
              %%Tested: ##219
              <HELP>
              Set up dense Cartesian net with 10 grid point per a.u.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </SELECT>

  .. --- not clear - do we need packing at all ---

     :kword:`PACK`
       Use packing of data, to create a lower quality, but smaller output files.

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

     :kword:`NOPACK`
       Do not use packing of data. By default, unless Dense grid is used,
       the data is packed, so the picture has lower (screen) quality.

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

:kword:`GAP`
  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.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="GAP" KIND="REAL" LEVEL="ADVANCED">
              %%Keyword: Gap <advanced>
              %%Tested: NONE
              <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>

:kword:`ORBItal`
  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.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="ORBITAL" KIND="INTS_COMPUTED" SIZE="2" MIN_VALUE="1" LEVEL="ADVANCED" EXCLUDED="SELECT">
              %%Keyword: Orbital <advanced>
              %%Tested: NONE
              <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>

:kword:`SELEct`
  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)

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="SELECT" KIND="STRING" LEVEL="ADVANCED" EXCLUDED="ORBITAL">
              %%Keyword: Select <advanced>
              %%Tested: NONE
              <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>

:kword:`MULLiken`
  Compute Mulliken charges separately for each occupied MO specified in
  the GRID_IT input. "LONG print" is an optional argument for more
  detailed printout.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="MULLIKEN" KIND="STRING" LEVEL="ADVANCED">
              %%Keyword: Mulliken <advanced>
              %%Tested: NONE
              <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>

:kword:`NoSort`
  Do not sort orbitals by occupation numbers and orbital energies

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

:kword:`ORANge`
  Followed by 2 numbers, to limit the interval of
  orbitals by occupation numbers.

  .. xmldoc:: <SELECT MODULE="GRID_IT" NAME="SELECTION" APPEAR="Orbital Selection" LEVEL="ADVANCED" CONTAINS="DEFAULT,ERANGE,ORANGE,ALL">

  .. xmldoc:: <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>
              %%Tested: ##205
              <HELP>
              Followed by 2 numbers to limit the interval of
              orbitals by occupation numbers
              </HELP>
              </KEYWORD>

:kword:`ERANge`
  Followed by 2 numbers, to limit the interval of
  orbitals by one-electron energies

  .. xmldoc:: <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>
              %%Tested: NONE
              <HELP>
              Followed by 2 numbers to limit the interval of
              orbitals by one-electron energies
              </HELP>
              </KEYWORD>

:kword:`ALL`
  Calculate grids for all molecular orbitals. Using this keyword you can produce a
  huge output file!

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="ALL" APPEAR="ALL Orbitals" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="ORANGE,ERANGE" MEMBER="SELECTION">
              %%Keyword: All <advanced>
              %%Tested: ##219
              <HELP>
              Calculate grids for all molecular orbitals.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </SELECT>

  .. :kword:`NODEnsity`
       Keyword to suppress calculation of grid for density

       .. .. xmldoc:: %<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>

:kword:`TOTAl`
  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.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="TOTAL" APPEAR="Total Density" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="NODENSITY">
              %%Keyword: Total <advanced>
              %%Tested: ##071
              <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>

:kword:`VB`
  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.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="VB" KIND="SINGLE" LEVEL="NOTIMPLEMENTED">
              %%Keyword: VB <advanced>
              %%Tested: NONE
              <HELP>
              Plots orbitals from the latest CASVB calculation.
              </HELP>
              </KEYWORD>

:kword:`ATOM`
  Calculate density at the position of atoms.

  .. xmldoc:: <SELECT MODULE="GRID_IT" NAME="FORMAT" APPEAR="Output Format" LEVEL="ADVANCED" CONTAINS="DEFAULT,ASCII,ATOM,CUBE">

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="ATOM" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="ASCII">
              %%Keyword: ATOM <advanced>
              %%Tested: ##071 ##219
              <HELP>
              Calculate density in the position of atoms
              </HELP>
              </KEYWORD>

:kword:`ASCII`
  Obsolete keyword for ASCII format of output file. This option can only
  be used in combination with :kword:`NOLUSCUS`.
  This keyword is useful if a calculation
  of the grid file and visualization should be done on computers with
  different architectures.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="ASCII" KIND="SINGLE" LEVEL="ADVANCED" EXCLUSIVE="ATOM">
              %%Keyword: ASCII <advanced>
              %%Tested: NONE
              <HELP>
              Obsolete keyword for ASCII format of output file. This option can only
              be used in combination with NOLUSCUS
              </HELP>
              </KEYWORD>

  .. xmldoc:: </SELECT>

:kword:`NPOInts`
  Keyword, followed by 3 integers equal to number of grid points
  in x, y, z directions. Using for non-automatic choice of grid network.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="NPOINTS" APPEAR="nPoints" KIND="INTS" SIZE="3" LEVEL="ADVANCED" EXCLUSIVE="GRID">
              %%Keyword: Npoints <advanced>
              %%Tested: NONE
              <HELP>
              Keyword, followed by 3 integers equal to number of grid points
              in x, y, z directions
              </HELP>
              </KEYWORD>

:kword:`GRID`
  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.)

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="GRID" KIND="REALS_COMPUTED" SIZE="3" LEVEL="ADVANCED" EXCLUSIVE="NPOINTS">
              %%Keyword: GRID <advanced>
              %%Tested: NONE
              <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>

:kword:`GORI`
  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 :kword:`NPOINTS` to build up the lattice of gridpoints.

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="GORI" KIND="REALS" SIZE="12" LEVEL="ADVANCED" EXCLUSIVE="GRID" REQUIRE="NPOINTS">
              %%Keyword: GORI <advanced>
              %%Tested: NONE
              <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>

:kword:`NOLUSCUS`
  Produce data file in obsolete format (which can be read by old
  (before 2015) versions of :program:`GV`).

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="NOLUSCUS" APPEAR="Old grid format" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: NOLUSCUS <advanced>
              %%Tested: NONE
              <HELP>
              Produce data file in obsolete format (which can be read by old
              (before 2015) versions of GV)
              </HELP>
              </KEYWORD>

:kword:`XFIELD`
  Use :program:`Grid_It` in a special mode (to produce the grid for non-cartesian points).

  .. xmldoc:: <KEYWORD MODULE="GRID_IT" NAME="XFIELD" KIND="SINGLE" LEVEL="ADVANCED">
              %%Keyword: XFIELD <advanced>
              %%Tested: NONE
              <HELP>
              Use Grid_It in a special mode (to produce the grid for non-cartesian points).
              </HELP>
              </KEYWORD>

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

An example for high quality picture, containing selected orbitals (from symmetry 1 and 4): ::

  &GRID_IT
  Dense
  Select
  1:10-20,4:3-7

An example for screen quality picture, containing all orbitals: ::

  &GRID_IT
  SPARSE; PACK
  ALL

An example for selection orbitals with partial occupation: ::

  &GRID_IT
  ORange = 0.01 1.99

.. xmldoc:: </MODULE>
