qp2/docs/source/users_guide/quickstart.rst

=================
Quick-start guide
=================

This tutorial should teach you everything you need to get started with
the the basics of the |qp|. As an example, we will run a frozen core
|CIPSI| calculation on the HCN molecule in the 6-31G basis set.


Demo video
==========

This tutorial can be directly watched at: 


`<https://www.youtube.com/watch?v=4nmdCAPkZlc>`_


Hands on
========

.. important::

   Before using the |qp|, it is required to load the environment variables 
   relatives to the |QP| or to be in the |qpsh| mode. 


Please execute in the current shell: 

.. code:: bash 

  ${QP_ROOT}/bin/qpsh 

where :code:`${QP_ROOT}` is the path to the source files of the |QP| installed on your architecture.  

The |QPSH| mode: a Bash-like experience for quantum chemistry
-------------------------------------------------------------

The |QP| has been designed pretty much as an *interactive* environment for quantum-chemistry calculations, 
in order to facilitate the user experience. 

Just like in Bash, there are many commands in the |QP| (see for instance :ref:`qp_edit` or :ref:`qp_run`) 
which help in handling useful data or running executables (see for instance :ref:`scf` or :ref:`fci`). 

All commands designed within the |qp| **begin** with `qp`, and there are two ways of running a **command**: 

* running the *executable* associated with the command: 

.. code:: bash

  qp_command 

or executing the *qp* shell command which calls the *executable* :code:`qp_command`: 

.. code:: bash

  qp command 

Usually, when using the :command:`qp` command, the name of the |EZFIO| database is omitted.

The advantage of using :code:`qp command` is that you can, just like in Bash, have: 

* the :kbd:`Tab` key for the auto-completion for basically any command of the |QP| 

* man pages with -h, --help or qp man 


Just try, for instance: 

.. code:: bash 

  qp 

and then use the auto-completion. You will show appear all possible commands that you can run: 


.. code:: bash 

  convert_output_to_ezfio  -h                       plugins                  unset_file               
  create_ezfio             man                      set_file                 update            

Then, try, still with the auto-completion, 

.. code:: bash

  qp create

You will see appear all the options for the :ref:`qp_create_ezfio` commands. 


Create the EZFIO database
-------------------------

The data relative to calculations are stored in an |EZFIO| database.
|EZFIO| is a hierarchical data format which uses the hierarchy of the
file system to organize the data, as files stored in a directory. The
data in the |EZFIO| directory are stored as plain text files, so it can
be opened with any text editor.
To access the data of the |EZFIO| database, the APIs (Fortran, |Python|,
|OCaml| or Bash) provided by |EZFIO| should be used, or tools using
these APIs such as :ref:`qp_edit` provided with the |qp|.

First, create an `xyz` file containing the coordinates of the molecule.
The file :file:`hcn.xyz` contains::

   3
   HCN molecule
   C    0.0    0.0    0.0
   H    0.0    0.0    1.064
   N    0.0    0.0    -1.156


This xyz file is now used with the :ref:`qp_create_ezfio` command to
create an |EZFIO| database with the 6-31G basis set:

.. code:: bash

  qp create_ezfio -b "6-31g" hcn.xyz -o hcn

The EZFIO database now contains data relative to the nuclear coordinates
and the atomic basis set:

.. code:: bash

  $ ls hcn
  ao_basis           becke_numerical_grid  dft_keywords  mo_one_e_ints      perturbation
  ao_one_e_ints      davidson              dressing      mo_two_e_erf_ints  pseudo
  ao_two_e_erf_ints  density_for_dft       electrons     mo_two_e_ints      scf_utils
  ao_two_e_ints      determinants          ezfio         nuclei             work


Run a Hartree-Fock calculation
------------------------------

The program :ref:`qp_run` is the driver program of the |qp|. To run a
|scf| calculation, just run

.. code:: bash

    qp run scf

The expected energy is ``-92.827856698`` au.

.. seealso:: 

    The documentation of the :ref:`module_hartree_fock` module and that of the
    :ref:`scf` program.

This creates the |MOs| in the |EZFIO| database that will be used to
in any other post-SCF method. The |qp| does not handle symmetry and
the |MOs| are stored by increasing order of Fock energies.


Choose the target |MO| space
----------------------------

Now, we will modify the |EZFIO| database to make a |CIPSI| calculation only in the
full set of valence |MOs|, keeping the core |MOs| frozen. The simple
command :ref:`qp_set_frozen_core` does this automatically:

.. code:: bash

    qp set_frozen_core


The general command to specify core and active orbitals is :ref:`qp_set_mo_class`. 
In the case of HCN molecule in the 631G basis, one has 20 |MOs| in total and the two first orbitals are frozen:

.. code::

    qp set_mo_class --core="[1-2]" --act="[3-20]"



Run the |CIPSI| calculation
----------------------------

We will now use the |CIPSI| algorithm to estimate the |FCI| energy.

.. code::

    qp run fci | tee hcn.fci.out 


The program will start with a single determinant and will iteratively:

* Select the most important determinants from the external space and add them to the
  internal space
* Add all the necessary determinants to allow the eigenvector of |H| to be
  also an eigenstate of |S^2|
* Diagonalize |H| in the enlarged internal space
* Compute (stochastically) the second-order perturbative contribution to the energy 
* Extrapolate the variational energy by fitting
  :math:`E=E_\text{FCI} - \alpha\, E_\text{PT2}`

By default, the program will stop when more than one million determinants have
entered in the internal space, or when the |PT2| energy is below :math:`10^{-4}` au.

To have a pictural illustration of the convergence of the |CIPSI| algorithm, just run 

.. code::

    qp_e_conv_fci

This will create the files :file:`hcn.fci.out.conv` containing the data of the
convergence of the energy that can be plotted, together with the file
:file:`hcn.fci.out.conv.1.eps` which is obtained from the gnuplot plot file
:file:`hcn.fci.out.conv.plt`. 


The estimated |FCI| energy of HCN is ``-93.0501`` au.

.. seealso:: 

    The documentation of the :ref:`module_fci` module and that of the :ref:`fci` program.