1.5 Running FHI-aims

As a simple test run to establish the correct functioning of FHI-aims and also to familiarize yourself with the basic structure of the input and output files, we suggest you change directories to the testcases/H2O-relaxation/ directory. The test run provided there relaxes a simple H₂O molecule from an initial (distorted) structure to the stable one, and computes total energies, eigenvalues etc. along the way. Notice that the key convergence settings (basis sets and grids) in this example are chosen to be fast. The results (particularly the relaxed geometry) are still trustworthy, but we encourage you already here to explore more stringent convergence settings later. In fact, always explore the impact of critical convergence settings on the accuracy of key results in your own project.

In the testcases/H2O-relaxation/ directory, type

../../bin/aims.version < /dev/null | tee H2O_test.own

at the command line. For “version”, you must insert the code version stamp that was actually downloaded and built (for example, 171221 or whichever code version you are building).¹¹ 1 The FHI-aims version stamp can be modified to whatever you wish in version_stamp.txt in the src/ directory.

For faster execution, you should use the appropriate binary including the necessary mpi command instead. On many (but not all) platforms, that command will be mpirun, and will also require you to specify the number of processors to be used by a flag. For 20 CPU cores, this could look like

mpirun -np 20 ../../src/aims.version < /dev/null | tee H2O_test.own

The result will be an output stream on your computer screen (created by “tee”) which is also captured in an output file H2O_test.own. Any critical information regarding computational settings, results (total energies, forces, geometries, …), errors etc. should be contained in this file, which we encourage you to look at (yes, it is meant to contain human-readable and useful explanations). Any other output files are only written if requested, and will be covered in the later sections of this text.

The standard output stream or file contains any and all output that FHI-aims writes by default. For later use, you must save this output stream to disk in some way, using standard Unix redirections such as the tee command above or a simple redirect.

Apart from the first expression given above, such redirections might look like this:

mpirun ../../bin/aims.version.scalapack.mpi.x < /dev/null > H2O_test.own

or even like this:

nohup mpirun ../../src/aims.version < /dev/null > H2O_test.own 2>&1 &

The latter version decouples the FHI-aims run completely from your current login shell and additionally saves any system error messages to the standard output file as well. With the above command sequence, you may safely log out from the computer in question, the code should keep running in the background.

Take care to monitor your running processes using the ps Unix command. For instance, it is highly unadvisable to run ten instances of FHI-aims at once in the background on a single CPU and expect any reasonable performance of the computer at all. The above hints are just examples of general Unix command-line sequences. For a complete treatment, we recommend that beginners read a separate Unix textbook, or—often feasible—learn by doing and Google.

If successful (otherwise, consider the warnings three paragraphs below), you may wish to compare your results to those contained in our own output from this run, which is contained in the file H2O.reference.out. You should obtain exactly the same total energies, forces, and geometries as given in this file. Any information regarding timing is, of course, specific to your computer environment, and not necessarily the same.

The directory testcases/H2O-relaxation/ contains two more files, control.in and geometry.in. These are the sole two input files required by FHI-aims, and are the most important files to learn about in the rest of this documentation. In brief, geometry.in contains any information related directly to a system’s geometry – normally, this will be atomic positions (in Å) and perhaps lattice vectors for periodic calculations, but no more. Any other, method-related, input information is part of control.in.

In practice, we attempt to strike a balance between the information needed by control.in, and information set to safe defaults unless specified explicitly. For example, you must specify the level of theory (e.g., the fact that PBE exchange-correlation is used) and also the basis set and other numerical settings employed. While it is highly useful to have this relevant information openly accessible, this would also create the need to personally edit a large amount of input before ever tackling the first run. For any information tied to the actual element (or “species”; arguably the most complex information required), we therefore provide ready-made template files for all elements (1-102) in the species_defaults directory. They are ready for copy-paste into control.in. These files will still benefit from some adjustment to your personal needs (for instance, the provided integration grids are set rather on the safe side, at the expense of more CPU time), but should greatly simplify the task.

Two final, important warnings regarding the execution of FHI-aims that are beyond our direct control:

•
FHI-aims requires that the execution stack size available to you be large enough for some initial internal operations. Spare us the details (ample explanation of the meaning of the “stack” in Unix can be found elsewhere), but for reasons unbeknownst to us, some vendors limit the default user stack size to $\approx$ 5 MB at a time when the typical available system memory per processor is 2 GB or more. If too little stack is available, your FHI-aims run will segfault shortly after the command was launched. To avoid this, always type:
```
        ulimit -s unlimited
    
```
(when using the bash shell or similar), or
```
        limit stacksize unlimited
    
```
(when using the tcsh or similar).
```
        echo $SHELL
    
```
will tell you which shell you are using. Ideally, this same setting should be specified in your .profile, .bashrc, or .cshrc login profiles. If “unlimited” is prohibited by your computer (e.g., on MacOS), try setting a large value instead, e.g., ulimit -s 500000.
•
An important system settings for parallel execution is the environment variable
```
      export OMP_NUM_THREADS=1
    
```
(the syntax is correct for the bash shell). When using Intel’s mkl, you should additionally set MKL_NUM_THREADS to 1 and MKL_DYNAMIC to FALSE.
•

Do not try to use OpenMP with FHI-aims unless you know exactly why you are doing this. FHI-aims is very efficiently MPI-parallelized and large portions of the code do not support OpenMP at all. (And they do not need to – MPI is simple as effective or more effective on practically all platforms in our experience.)

After startup, the first messages contain information about your computer’s environment: Code version, compiler information, host names, environment variables which turned out to be useful and which should be set on your system (e.g. OMP_NUM_THREADS), etc. The complete input files control.in and geometry.in are also repeated verbatim. Any FHI-aims run should thus be completely reproducible based on the standard output stream alone.

Should you encounter further issues, consider also the troubleshooting information documented in Appendix A.

All this said, after successfully running the test run, you should now be ready to go with FHI-aims. The remainder of this document is about the details – available options, how to run aims most efficiently, etc. Happy computing!