9
1
mirror of https://github.com/QuantumPackage/qp2.git synced 2024-12-23 12:03:30 +01:00
qp2/docs/source/users_guide/quickstart.rst
Anthony Scemama 4f332ee494
Fixed 6-31G and quickstart (#65)
* Fixed 6-31 basis sets

* Bug in quickstart
2019-10-01 10:38:29 +02:00

218 lines
6.2 KiB
ReStructuredText

=================
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.