walter-feng / hartree-fock-in-cpp

Hartree-Fock code written in full C++ standard

Hartree-Fock-in-CPP

=============================================================================

Three years ago, there was a Hartree Fock program written in C (https://github.com/Walter-Feng/Hartree-Fock). During that time, I only learned C, so I needed to write all the structures myself - tons of pointers, stupid recursion, and so on. The code was super inefficient, buggy, maybe with some memory leaks.

Things changed. I learned C++ and software engineering practice, read some good code, wrote a lot more code in different languages. Externally, C is no longer popular among undergraduates. Therefore, reviewing the original C-style Hartree-Fock code, I thought instantly "hey this code need a complete reconstruction", so making it a lot easier for newcomers to understand the math, run the code, and get a taste of what good code is.

"Well... but you could have used Python which is more friendly"

No. I refuse to use python for this project. Learn some static programming!

=============================================================================

Back to the topic, this is a Hartree-Fock program that aims to show how Hartree-Fock really works in every process, but in full C++ standard. (Hopefully) it is well documented with good variable names so that you can read the code without much effort and understand what is going on. A good tex document that illustrates the mathematics and C++ features is (probably) on the way.

As a comparison, the features in this program are:

1. The programming style is completely in C++ - OOP, templates, but no more pointers.

2. Tons of dependencies, including,

Ones you need to install yourself:

    Boost
    
    Armadillo 
    
    GSL - GNU Scientific Library

and others I help you fetch and compile:

    sunqm/libcint (but only using its rys quadrature roots generator)
    
    catchorg/Catch2
    
    Taywee/args
    
    fmtlib/fmt
    
    nlohmann/json

3. It is (in principle) able to use all the bases that have been published in Basis Set Exchange (https://www.basissetexchange.org).

4. No special trick is used generally, but some C++ tricks may need to be learned.

5. Templates may prevent understanding the code via some debug techniques.

And something good:

1. GOOOOOOD PROGRAMMING STYLE

2. The output is mostly handled by printer functions, so easier to mess around.

To clone the repository, don't forget to add "--recursive" to include all the dependencies,

git clone --recursive https://github.com/Walter-Feng/Hartree-Fock-in-CPP.git

CMake is used to generate the executable:

Hartree-Fock-in-CPP-repo-directory: $ mkdir build 
Hartree-Fock-in-CPP-repo-directory/build: $ cmake ..
Hartree-Fock-in-CPP-repo-directory/build: $ make

But you might have installed the external dependencies, e.g. Armadillo, elsewhere. In this case, you may need to specify the directory to these dependencies using keyword

$ cmake -DCMAKE_PREFIX_PATH=/dir/to/dependency ..

to correctly link the libraries.

Type

./hfincpp -h

to unlock all options.

To run the example:

Hartree-Fock-in-CPP-repo-directory/build: $ ./hfincpp ../example/H2_6_31g.json

The output should be something like:

============================================================
|Iter|        Time / s |   Energy / a.u. |     Energy Diff |
============================================================
     0                 0       -0.90365255                 0
     1        2.0781e-05       -0.91596619      -0.012313641
     2        3.5345e-05       -0.91626362    -0.00029743166
     3        4.6462e-05       -0.91627108    -7.4536724e-06
     4        5.6896e-05       -0.91627126    -1.8785583e-07
============================================================

Total time elapsed: 0.032478466 s

Json file format is used for input, and due to lack of default parameters, any missing keywords will generate a non-trackable error. So for now it is advised to only change the values in example json input file.

Now the code also supports calculating gradient and perform a BFGS optimization. An example of optimizing H2O is shown below:

Performing SCF ...
============================================================
|Iter|        Time / s |   Energy / a.u. |     Energy Diff |
============================================================
     0                 0        -73.320014                 0
     1        3.8087e-05        -74.813641        -1.4936266
     2        6.4239e-05        -74.896802      -0.083161128
     3        8.6848e-05        -74.902545     -0.0057425592
     4       0.000108737        -74.903398    -0.00085350827
     5       0.000129691        -74.903606    -0.00020763838
     6       0.000149666         -74.90366    -5.3901557e-05
     7       0.000169352        -74.903674    -1.4139079e-05
     8       0.000188594        -74.903677    -3.7127233e-06
     9       0.000207793        -74.903678    -9.7514321e-07
============================================================

Calculating gradient ...
============================================================
|Atom| X / (Ha / bohr) | Y / (Ha / bohr) | Z / (Ha / bohr) |
============================================================
     H        -0.1256186     0.00088870278                 0
     O    -1.5781543e-12     -0.0017774056                 0
     H         0.1256186     0.00088870278                 0
============================================================

Performing optmization ...
============================================================
|Iter|        Time / s |   Energy / a.u. |     Grad / a.u. |
============================================================
     0                 0        -74.903678         0.1256186
     1       0.084930816        -74.920302        0.10866145
     2        0.17214759        -74.944935        0.06184493
     3        0.72308432        -74.953628       0.093235889
     4         0.8116638        -74.965104       0.015954198
     5         1.2036186        -74.965662        0.01045005
     6         1.2902973        -74.965866      0.0038400685
     7         1.7879789          -74.9659     0.00072399627
============================================================

Optimized geometry:
============================================================
|Atom|    X / Angstrom |    Y / Angstrom |    Z / Angstrom |
============================================================
     H        0.45780056      -0.086193387                 0
     O          1.889726         1.1172498                 0
     H         3.3216514      -0.086193387                 0
============================================================
Total time elapsed: 1.989305952 s

Process finished with exit code 0

hartree-fock-in-cpp's Issues

About the obara saika integral method

While the implementation of overlap and nuclear_attration integrals are following the recursive relations in the original 1985 paper, the implementation of kinetic and electron_repulsion integrals seem not to be exactly aligned. i.e. instead of computing recursively, they are both expanded into summing over all the pairs.

Does this implementation lead to fewer FLOPS compared to the original RR? Is there any reference that derives this alternative form?

BTW, it is mentioned here that the implementation has some error, has this been fixed?

Is the symbols t & u aligned with the 1982 paper?

I notice in the code that t_squared=u/(1+u), however, in (27) of the 1982 paper, it is t_squared=u/(rho + u). But the other parts, i.e. the recursion relations as I verified are aligned with the paper. Am I missing anything here?