Programming in the Quantum Package

To program in the Quantum Package, it is required that you are familiar with the IRPF90 code generator. A GitBook can be found here, and programmers are encouraged to visit this manual.

IRPF90 makes programming very simple. The only information a programmer needs in order to write a new program is the name of the required IRPF90 entities which may already exist in other modules. For example, writing a program which prints the Hartree-Fock energy is as simple as:

program print_hf_energy
  implicit none
  BEGIN_DOC
! Program which prints the Hartree-Fock energy
! to the standard output
  END_DOC
  print *, 'HF energy = ', HF_energy
end

The only required information was the existence of a provider for HF_energy. A detailed list of all the providers, subroutines and functions of the Quantum Package can be found in the appendix of this manual.

Architecture

As IRPF90 is used, the programmer doesn’t have full control of the sequence of instructions in the produced Fortran code. This explains why the input data is stored in a database rather than in sequential text files. Consequently, the programmer can’t know in advance the order in which the files will be read, so a simple random access to persistent data is needed. The EZFIO library generator is a practical answer to this problem.

The Quantum Package uses a collection of programs inter-operating together. Each of these programs is reading and/or modifying information in the EZFIO database. This is done mostly using the command line or scripting.

Important

Each command modifies the state of the EZFIO database, so running the same program twice on the same database may have different behavior because of the state of the database. For reproducibility, users are encouraged to run scripts where a fresh new EZFIO database is created at the beginning of the script. This way of running the Quantum Package makes calculations reproducible.

The computational part Quantum Package is organized in modules. A module is a directory which contains multiple IRPF90 files, a README.rst and a NEED file.

The README.rst file contains documentation about the module, that is automatically included in the documentation of the Quantum Package. The documentation is generated by the Sphinx documentation builder, and it should be written using the RST format.

The NEED file contains the list of the modules which are needed for the current module. When a module is needed, it means that all the IRPF90 files it contains should be included in the current module. This is done automatically during the building process, by creating symbolic links in the current directory.

To compile the program, the Ninja build system is used, and all the building process is fully automated such that the programmer will never have to modify a file by hand. Running ninja inside a module will compile only the module, and running ninja at the root of the Quantum Package will build all the modules, as well as the tools.

Algorithms

The PhD thesis of Yann Garniron gives all the details about the implementation of:

  • The data structure for the two-electron integrals (utils/map_module.f)

  • The Davdison diagonalization (module davidson)

  • The CIPSI selection (module cipsi)

  • The hybrid stochastic/deterministic PT2 correction (module cipsi)

  • The hybrid stochastic/deterministic matrix dressing (module dress_zmq)

Extracting results for use with other codes

The AOs and MOs can be seen with qp_edit. We also provide a utility to create a file which can be read by molden for visualizing the MOs (see molden). For using external CI solvers, we provide a utility that generates a file containing the two-electron integrals in the MO basis set in the FCIDUMP format (see fcidump).

All the results are stored in the EZFIO directory, so users willing to fetch data such as the MOs or the CI coefficients should use the EZFIO API. There are multiple major ways to do this:

  • Write a script in Python or OCaml and use the Python EZFIO API. The script $QP_ROOT/bin/qp_convert_output_to_ezfio is a good example to understand how to use the EZFIO API in Python,

  • Write an independent program in Fortran or C, link it with the EZFIO library located at $QP_ROOT/external/ezfio/lib/libezfio.a and call directly the EZFIO routines,

  • Write a new module for the Quantum Package printing the desired quantities in a suitable text format. The program fcidump is an example of such a program.