Quick-start guide
This tutorial should teach you everything you need to get started with the the basics of the Quantum Package. 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:
Hands on
Important
Before using the Quantum Package, it is required to load the environment variables relatives to the Quantum Package or to be in the Quantum Package Shell mode.
Please execute in the current shell:
${QP_ROOT}/bin/qpsh
where ${QP_ROOT} is the path to the source files of the Quantum Package installed on your architecture.
The Quantum Package Shell mode: a Bash-like experience for quantum chemistry
The Quantum Package 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 Quantum Package (see for instance qp_edit or qp_run) which help in handling useful data or running executables (see for instance scf or fci).
All commands designed within the Quantum Package begin with qp, and there are two ways of running a command:
running the executable associated with the command:
qp_command
or executing the qp shell command which calls the executable qp_command:
qp command
Usually, when using the qp command, the name of the EZFIO database is omitted.
The advantage of using qp command is that you can, just like in Bash, have:
the Tab key for the auto-completion for basically any command of the Quantum Package
man pages with -h, –help or qp man
Just try, for instance:
qp
and then use the auto-completion. You will show appear all possible commands that you can run:
convert_output_to_ezfio -h plugins unset_file
create_ezfio man set_file update
Then, try, still with the auto-completion,
qp create
You will see appear all the options for the 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 qp_edit provided with the Quantum Package.
First, create an xyz file containing the coordinates of the molecule.
The 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 qp_create_ezfio command to create an EZFIO database with the 6-31G basis set:
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:
$ 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
If you need to run using an already existing EZFIO database, use
qp set_file hcn
Run a Hartree-Fock calculation
The program qp_run is the driver program of the Quantum Package. To run a SCF calculation, just run
qp run scf
The expected energy is -92.827856698 au.
See also
The documentation of the hartree_fock module and that of the scf program.
This creates the MOs in the EZFIO database that will be used to in any other post-SCF method. The Quantum Package 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 qp_set_frozen_core does this automatically:
qp set_frozen_core
The general command to specify core and active orbitals is 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:
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.
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 \(\hat H\) to be also an eigenstate of \(\widehat{S^2}\)
Diagonalize \(\hat H\) in the enlarged internal space
Compute (stochastically) the second-order perturbative contribution to the energy
Extrapolate the variational energy by fitting \(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 \(10^{-4}\) au.
To have a pictural illustration of the convergence of the CIPSI algorithm, just run
qp_e_conv_fci
This will create the files hcn.fci.out.conv containing the data of the
convergence of the energy that can be plotted, together with the file
hcn.fci.out.conv.1.eps which is obtained from the gnuplot plot file
hcn.fci.out.conv.plt.
The estimated FCI energy of HCN is -93.0501 au.