.. _plots:

Visualizing electrons
=====================

Electrons in molecules are described in terms of molecular orbitals.
Molecular orbitals are not observable themselves, but provide valuable insight into molecular properties and reactivity.
In this tutorial you will learn how to visualize different types of orbitals, such as :ref:`HOMO, LUMO<plotfmos>` and :ref:`SOMOs<plotsomos>` using WEASEL.
You will also learn how to generate :ref:`spin and electron density<ploted>` plots.
We will introduce the :ref:`general keyword<plotcalc>` for plotting these properties,
show examples for constructing the cases listed above, and provide :ref:`comprehensive list options <keywordsplots>` for the MO plotting.

.. _plotcalc:

How to run the calculation
---------------------------

WEASEL can automatically generate ``.cube`` files for different MOs and for electron and spin densities by adding the following keyword to
the command line:

.. prompt:: bash $

   weasel example.xyz -plot-<options>

The ``<options>`` represent the different plot options.
A full list of all options is listed :ref:`below<keywordsplots>`.
The ``.cube`` files are located in the mainjob directory.

.. note::
   The plot features are available for ``-spdft`` calculations only.

.. _plotfmos:

Frontier molecular orbitals (HOMOs and LUMOs)
-----------------------------------------------
The ``.cube`` files for the frontier molecular orbitals (FMOs, HOMO and LUMO) can be generated as follows, e.g. for water:

.. prompt:: bash $

   weasel water.xyz -plot-fmos

Afterwards, the data can be plotted using a visualization program of your choice. 
An example is shown here:

.. figure:: plots/HOMO_LUMO_water.png
   :align: center
   :width: 300

   HOMO (left) and LUMO (right) of water.

.. _plotsomos:

Singly occupied molecular orbitals (SOMOs)
-------------------------------------------

Singly occupied molecular orbitals (SOMOs) can be generated for radicals, 
and any system with unpaired electrons:

.. prompt:: bash $

   weasel example.xyz -plot-somos -mult 2

.. important::
   SOMOs can only be generated if the molecular system contains unpaired electrons, 
   i.e. a multiplicity of 2 (``-mult 2``) or higher is required.

.. note::
   If there is more than one SOMO, the SOMOs are localized before the plots are generated. 

Let us now plot the SOMOs of this 5-fold coordinated high-spin Fe(III)-heme complex.

.. figure:: plots/FeWAT6_struct.png
   :align: center
   :width: 500
   
   Structure of the 5-coordinate Fe(III)-heme complex.

.. prompt:: bash $

   weasel heme.xyz -mult 6 -plot-somos

After structure optimization, the SOMOs are first localized, and then plotted. 
We can now easily distinguish the 5 different d-orbitals of the high-spin Fe(III) complex. 

.. figure:: plots/FeWAT6_MOs.png
   :align: center
   :width: 600
   
   The five SOMOs of the 5-coordinate Fe(III)-heme complex.

.. note::
   Without the localization step before plotting, the SOMOs of the 
   Fe(III)-heme complex would not look that *textbook*-like.

.. _ploted:

Spin and electron densities
---------------------------

The electron density (``-ed``) of a molecule is an observable property, describing the probability 
density of all its electrons summed up. 

.. prompt:: bash $

   weasel structure.mol2 -plot-ed

The spin density (``-sd``), on the other hand, describes the probability density of the molecule's unpaired electrons.

.. prompt:: bash $

   weasel structure.mol2 -plot-sd

.. _keywordsplots:

Keywords and remarks
--------------------------

**Keywords for different MO and density plots:**

.. list-table::
   :widths: 30 70
   :header-rows: 1
   :class: fixed-width-table

   * - Keyword
     - Description
   * - ``-plot-fmos``
     - Plot HOMO and LUMO, see :ref:`above<plotfmos>`.
   * - ``-plot-homo``
     - Plot HOMO.
   * - ``-plot-lumo``
     - Plot LUMO.
   * - ``-plot-somos``
     - Plot SOMOs.
   * - ``-plot-fmos-upto INT``
     - | Plots ``INT`` HOMOs and ``INT`` LUMOs, e.g. ``-plot-fmos-upto 2``:
       | -> generates HOMO-1, HOMO, LUMO, LUMO+1.
   * - ``-plot-mo INT1 INT2 ...``
     - | Plots the MOs with no. ``INT1``, ``INT2``, and all MOs that are listed.
       | Here, the absolute ordering of the MOs has to be known.
   * - ``-plot-ed``
     - Plot electron density, see below :ref:`above<ploted>`.
   * - ``-plot-sd``
     - Plot spin density, see below :ref:`above<ploted>`.


**Keywords for different plotting options:**

.. list-table::
   :widths: 30 70
   :header-rows: 1
   :class: fixed-width-table

   * - Keyword
     - Description
   * - ``-plot-format <options>``
     - Output format for plots (MO, ED, SD). Allowed <options>: ``cube``, ``vis``.
   * - ``-grid-res N``
     - | Grid resolution, i.e. number of grid points per Angstrom (x, y, and z
       | direction) for plots (MOs, ED, SD).
   * - ``-grid-x N``
     - Number of grid points in x direction for plots (MO, ED, SD).
   * - ``-grid-y N``
     - Number of grid points in y direction for plots (MO, ED, SD).
   * - ``-grid-z N``
     - Number of grid points in z direction for plots (MO, ED, SD).
   * - ``-grid-xmin N``
     - Minimum dimension on the x axis in Angstrom.
   * - ``grid-ymin N``
     - Minimum dimension on the y axis in Angstrom.
   * - ``-grid-zmin N``
     - Minimum dimension on the z axis in Angstrom.
   * - ``-grid-xmax N``
     - Maximum dimension on the x axis in Angstrom.
   * - ``-grid-ymax N``
     - Maximum dimension on the y axis in Angstrom.
   * - ``-grid-zmax N``
     - Maximum dimension on the z axis in Angstrom.
   * - ``-grid-xyzmin N``
     - Minimum dimension on x, y and z axis in Angstrom.
   * - ``-grid-xyzmax N``
     - Maximum dimension on x, y and z axis in Angstrom.