Getting Started: H\ :sub:`3`\ B←NH\ :sub:`3` Lewis Adduct
#########################################################

|PyOrbb| is a tool designed to help you perform orbital interaction analyses. It provides you with a user-interface capable of producing orbital interaction diagrams. In this tutorial we will walk through the process of performing a basic |PyOrbb| analysis using the :abbr:`GUI (Graphical User Interace)` of |PyOrbb|. Throughout this tutorial we will be using the results of a calculation containing the H\ :sub:`3`\ N→BH\ :sub:`3` Lewis acid-base pair, which you can download here: :download:`NH3_BH3.rkf <NH3_BH3.rkf>`.

.. seealso::
   `Click here <https://www.scm.com/doc/Tutorials/Analysis/FragmentAnalysis.html>`_ for a tutorial on the |AMS| website on how to perform fragment calculations yourself.

.. note::
   Some functionality of |PyOrbb| requires a valid installation of the |AMS| program.



Starting PyOrbb
===============

When you open |PyOrbb| you will be greeted by the welcome screen. Here you can find a link to the |PyOrbb| article and the documentation page. You can also see articles that have been recently published that cite |PyOrbb|.

.. image:: _static/images/get_started/new_window.png
   :class: only-light

.. image:: _static/images/get_started/new_window_dark.png
   :class: only-dark


Loading Calculation Results
===========================

.. admonition:: **Step 1**: Load the calculation results
   :class: important

   Drag the :file:`NH3_BH3.rkf` file into the |PyOrbb| window. Alternatively, click the "Select a File" button and navigate to and select the file's location.


When a valid :file:`adf.rkf` (a result file from ADF) file is provided, |PyOrbb| will automatically analyse the contents of the file and present you with a new screen showing the results of the analysis. The screen shows you the main orbital interaction mechanism as predicted by |PyOrbb| and gives you various options to obtain information or manipulate the diagram shown.


.. raw:: html

   <style>
   .gui-wrap { position: relative; display: inline-block; }
   .gui-wrap a.region {
     position: absolute; display: block;
     background: rgba(99,102,241,0.08);
     border: 2px solid rgba(99,102,241,0.6);
     border-radius: 4px; cursor: pointer;
   }
   .gui-wrap a.region .tooltip {
     display: none; position: absolute; top: 105%; left: 0;
     background: #1e1e2e; color: #fff; padding: 8px 12px;
     border-radius: 6px; width: 220px; font-size: 0.85em; z-index: 10;
   }
   .gui-wrap a.region:hover { background: rgba(99,102,241,0.15); }
   .gui-wrap a.region:hover .tooltip { display: block; }
   </style>

   <div class="gui-wrap">
     <img src="_static/images/get_started/analysis_open.png" class="only-light" width="100%">
     <img src="_static/images/get_started/analysis_open_dark.png" class="only-dark" width="100%">
     <!-- position each overlay div with top/left/width/height as % of image -->

     <a class="region" data-tab="Diagram"
        style="top:14.6008%; left:7.3005%; width:60.0170%; height:61.8697%">
     </a>

     <a class="region" data-tab="Information Tabs"
        style="top:14.6008%; left:67.9117%; width:24.8727%; height:61.8697%">
     </a>

     <a class="region" data-tab="Sliders"
        style="top:76.8908%; left:7.3005%; width:66.65%; height:8.2983%">
     </a>

     <a class="region" data-tab="Filters & Options"
        style="top:76.8908%; left:74.4482%; width:18.4211%; height:8.2983%">
     </a>

     <a class="region" data-tab="Save Buttons"
        style="top:85.7143%; left:7.3005%; width:65.9593%; height:4.0966%">
     </a>
   </div>


.. tab-set::
   :class: gui-tabs

   .. tab-item:: Diagram

      **Main orbital interaction diagram generated by |PyOrbb|**

      This part of the GUI shows you the orbital interactions identified by |PyOrbb|.

      The small black horizontal lines are the energy-levels of the orbitals and are arranged by the molecular species they belong to. In this case the left and right columns are for the :abbr:`FMOs (Fragment molecular orbitals)` and the middle column is for the :abbr:`MOs (Molecular orbitals)`. The levels can be populated by 0, 1, or 2 electrons, indicated by the arrows, and the directions of the arrows indicate the spin they posses: pointing up corresponds to alpha-spin and down to beta-spin. 

      The lines between the FMOs and MOs indicate whether there is a contribution from the FMO to the MO. The brightness is determined by the Mulliken contribution between the orbitals, and the color of it indicates what kind of interaction it is. Red indicates a Pauli-repulsive interaction, green indicates an orbital interaction, grey indicates a connection participating in both Pauli-repulsive and orbital interactions, and purple indicates connections added during the santization step of the algorithm.


      .. admonition:: Interactive elements
         :class: seealso

         **Several elements are (double-)clickable in the diagram:**

         1. Scrolling and dragging allows you to zoom in or out and shift the diagram up or down, respectively. Right-clicking resets the diagram to its original state.
         2. The names of the columns are double-clickable and renamble. You can also drag and drop them to reorder the columns however you like.
         3. The y-axis can be double-clicked to manually set the axis limits.
         4. The orbital levels and connections are clickable and will show information about them and their interaction in the Information Tab. You can hold shift to select multiple levels or connections at once.
         5. If there are notices (warnings or errors) related to the orbitals they will have a small warning sign next to them. Clicking these will open the corresponding notice on the right side for you.


   .. tab-item:: Information Tabs

      **Main information sections**

      The information tabs show you information related to orbitals, molecules, the overall system, and any errors or warnings that were detected during loading of the calculation results. The information is organized in 3 tabs. The information can be viewed by clicking the headers inside the tabs.

      **Orbitals**

      When clicking an orbital or a connection in the main diagram, |PyOrbb| will display relevant information in this tab. This includes basic information such as orbital energies, overlaps, coefficients and Mulliken contributions and populations. If two interacting orbitals are selected (by using shift + click to select multiple objects at once), the details of the orbital interaction analysis are shown, including each term that went into calculating the orbital interaction or Pauli repulsive interaction ranking numbers.

      **System**

      |PyOrbb| provides information about the general system, the complex molecule and each of the fragments. This includes charges, spin-polarizations and coordinates of the molecules. |PyOrbb| also provides the energy terms from the energy decomposition analysis.

      **Notices**

      |PyOrbb| will give notice of any warnings or errors that it detected during the loading of a given :file:`adf.rkf` file. Clicking on any exclamation marks in the diagram will also highlight the error/warning message associated with it.

      .. seealso::
         For an overview of all warnings and errors that |PyOrbb| detects, please see `this page <notices.html>`_.

   .. tab-item:: Sliders

      **Setting orbital interaction ranking thresholds**

      The sliders are used to adjust the thresholds that |PyOrbb| uses to determine which interactions to include. The lower the threshold value is the more interactions are included in the main diagram.

      .. seealso::
         See Section 3.2 in the `main article <notices.html>`_ for more information about the orbital interaction ranking algorithm.


   .. tab-item:: Filters & Options

      **Draw Orbitals**

      When orbitals or connections are selected in the main diagram the Draw Orbitals button is activated. Clicking it will then show you a dropdown menu with several options for drawing the orbitals involved.

      **Filter**

      When one or more orbitals have been selected the Filter button is activated. If clicked, |PyOrbb| will ensure that all interactions drawn in the diagram involve the selected orbitals. Clicking the Filter button again deactivates the filter.

      **Energy Type**

      |PyOrbb| will attempt to gather various FMO energy types when loading the results of a calculation. By default the regular energies are used (*i.e.* the FMO energies in density of the complex), but other options are also available if they are present in the provided file. |PyOrbb| will also always provide the option to use approximate effective energies.

      .. seealso::
         See Section S1 in the `supporting information <notices.html>`_ for more information about the FMO energy types and their uses.

      **Orbitals**

      One can also manually include or exclude specific orbitals from the interaction. This also includes the option to include/exclude all orbitals of specific spin types or irreducible representations. |PyOrbb| also provides information about all orbitals included in the system and also gives the option to draw them.


   .. tab-item:: Save Buttons

      **Producing the main output of |PyOrbb|**

      When you are satisfied with the diagram shown you can export the main orbital interaction diagram using the Save Figure button. |PyOrbb| also provides the option to generate a spreadsheet containing an overview of information about the calculation which can be very usefull for manual analysis of the data.


Visualisation and Obtaining Data
================================

Having loaded the calculation, we can now start visualizing and obtaining data about the orbitals in our system.

**Drawing Orbitals**

Let's start by visualizing the orbitals involved in the mixing of the occupied NH\ :sub:`3`\ (3A\ :sub:`1`) and the virtual BH\ :sub:`3`\ (3A\ :sub:`1`) orbitals.

.. admonition:: **Step 2**: Visualize NH\ :sub:`3`\ (3A\ :sub:`1`) and BH\ :sub:`3`\ (3A\ :sub:`1`)
   :class: important

   Hold down the :kbd:`shift` key and click on the energy levels of the NH\ :sub:`3`\ (3A\ :sub:`1`) and BH\ :sub:`3`\ (3A\ :sub:`1`) orbitals. Click the "Draw Orbitals" button to open the visualization dropdown menu and select the bottom option with the green "`&`" sign.

.. note::
   To draw orbitals, |PyOrbb| needs access to the |densf| program provided by |AMS|. Set the path to your |AMS| installation using :menuselection:`Preferences --> Open Settings --> Densf --> AMS Application`


.. image:: _static/images/get_started/viewer_together.png
   :class: only-light

.. image:: _static/images/get_started/viewer_together_dark.png
   :class: only-dark

PyOrbb should open a window showing you the two overlaid orbitals. It should be obvious why this interaction was deemed the most important by |PyOrbb|, the orbitals clearly have a very overlap, especially in the region between the boron and nitrogen atoms. PyOrbb also gives the option to visualize the overlap directly.

**Drawing Orbital Overlap**

.. admonition:: **Step 3**: Visualize the overlap between NH\ :sub:`3`\ (3A\ :sub:`1`) and BH\ :sub:`3`\ (3A\ :sub:`1`)
   :class: important

   Again hold down the :kbd:`shift` key and click on the energy levels of the NH\ :sub:`3`\ (3A\ :sub:`1`) and BH\ :sub:`3`\ (3A\ :sub:`1`) orbitals. Click the "Draw Orbitals" button to open the visualization dropdown menu and select the one to last option with the brown "`S`" sign.


.. image:: _static/images/get_started/viewer_overlap.png
   :class: only-light

.. image:: _static/images/get_started/viewer_overlap_dark.png
   :class: only-dark

PyOrbb again should open a window, but this time shows the product of the selected orbitals. Purple shows regions with constructive overlap, while green shows destructive overlap. While there is both constructive and destructive overlap between the two orbitals, the constructive overlap between the boron and nitrogen atoms dominates, and should lead to a large value for the overlap.

**Obtaining the Orbital Overlap values**

PyOrbb also reports the actual value of the overlap integral between two orbitals of interest. In this case the overlap is equal to 0.353.

.. admonition:: **Step 4**: Obtain the overlap value between NH\ :sub:`3`\ (3A\ :sub:`1`) and BH\ :sub:`3`\ (3A\ :sub:`1`)
   :class: important

   Again hold down the :kbd:`shift` key and click on the energy levels of the NH\ :sub:`3`\ (3A\ :sub:`1`) and BH\ :sub:`3`\ (3A\ :sub:`1`) orbitals. On the right side click the "Orbitals" tab to view the information related to the selected orbitals. Click the header that states NH\ :sub:`3`\ (3A\ :sub:`1`) ± BH\ :sub:`3`\ (3A\ :sub:`1`). Observe the value given for ``Sij``.