# 9. Spex FAQ¶

## 9.1. Configuration¶

Configuration stops with “MPI-3 compiler requested, but couldn’t use MPI-3.”

Your MPI compiler does not support the MPI-3 standard, which is required for the parallelized version. Make sure that the correct compiler is used. You can specify the compiler with the environment variables FC or MPIFC, e.g., directly on the command line ./configure --enable-mpi MPIFC=mpif90.

Configuration stops with “Could not compile with HDF5.”

This problem occurs quite often. It can be caused by one of the following reasons: (1) you do not have the HDF5 library, (2) you have HDF5, but it is not installed in a standard directory (then, use the option --with-hdf5 to specify the HDF5 root directory, e.g., ./configure --with-hdf5=<path-to-hdf5>, which should contain “<path-to-hdf5>/lib” and “<path-to-hdf5>/include”; alternatively, you can specify the location of the include file “hdf5.mod” with the option --with-includedir=<path-to-hdf5-include>), or (3) you have the HDF5 library, but it has been compiled with a different compiler than the one you are using for compiling Spex. In the latter case (3), please note that you might be using a different compiler than you think. (For example, even after loading a particular compiler module, some systems still use a different Fortran compiler, often GFortran, by default if you do not specify otherwise.) Then, you should use the environment variables FC or MPIFC as described before.

Configuration stops with “Could not link HDF5 library.”

The linker does not find the HDF5 library. This can happen if the HDF5 library is installed in a non-standard directory (as is the case with many computer systems). In this case, you can use the option --with-hdf5=<path-to-hdf5> (see above) or you specify the location of the HDF5 library with the option --with-libdir=<path-to-hdf5-lib>. Consult your system administrator to inquire about the correct path.

Configuration stops with “Could not link parallel HDF5 library.”

Your HDF5 library has been compiled without parallelization support. This is actually not an error anymore. Spex can be compiled with the serial HDF5 version.

You can get further information from the file “config.log”.

## 9.2. Compilation¶

My compiler fails to compile the source.

In case of compiler errors, the first thing to try is cleaning up with make clean before running make. If this does not solve the problem, please inform us. We have successfully compiled and run the code with the Intel Fortran compiler (since version 12.1.3), GFortran (since version 4.9), and NAG Fortran (since version 6.2 6214). As of May 2018, PGI compilers have a bug (TPR 23745) that prevents compilation of the Spex code. For the parallelized version, we have used Intel MPI, MPICH, and Open MPI.

My compiler fails to link the object files.

If the configuration step has run successfully (with the same system configuration), linking the object files should work. In any case, before reporting a problem, please try cleaning up before compilation: make clean ; make.

I want to interface Spex to my own DFT program.

The data transfer between the DFT program and Spex is controlled by the routines in “readwrite_PROG.f” (where PROG stands for the name of the DFT program). You will have to create this file (if it does not exist yet). A template file “readwrite_tmpl.f” with explanations is provided with the source. The new file “readwrite_PROG.f” is included in the build process by reconfiguring (./configure) with the option --with-dft=PROG.

## 9.3. Usage¶

Spex needs too much memory.

Try reducing the maximally allowed memory storage with the keyword MEM. Have a look at the parameters of your calculation. Too high parameters can easily exhaust the computer memory. For example, the calculation of spectra usually requires the storage of large (polarization) matrices for each frequency of the mesh. Dividing the large frequency mesh into several smaller ones (see Sec. Section 5.3) might help in this case. Furthermore, note that the keyword STOREBZ requires a lot of memory.

Degenerate quasiparticle states have slightly different energies or I get slightly different results at equivalent k points

There are several possible reasons for this:

• In your DFT output groups of degenerate states are cut at the top. Then you should specify NBAND explicitly.
• In the calculation of the susceptibility groups of degenerate states are split into different packets. This can only be avoided with a larger MEM if possible.
• The tetrahedron method breaks the symmetry. You can use GAUSS to test this.

My GW calculations converge badly wrt the k-point set.

This might be caused by using the keyword ZERO for systems with small band gaps (e.g. GaAs). In this case, try without ZERO, which should guarantee a smooth (but slower) convergence.

My calculations do not converge wrt the number of bands.

The parameters are not completely independent. If you increase the number of bands, you might need a higher G cutoff (GCUT in section MBASIS). You might also have to increase the number of frequencies for sampling the spectral function. Instead, you can also specify the value of the first nonzero frequency point as the first argument to FSPEC. Then the number of frequencies automatically increases as you increase the number of bands.

The real-space (reciprocal-space) summation in the routine structureconstant takes very long.

Increase (decrease) SCALE in section COULOMB.

There are jumps in the band structure.

Band structures should be calculated without the keyword ZERO. In the case of a metal a jagged band structure (especially in Hartree-Fock) might also be caused by the tetrahedron method. Then you must improve the k-point sampling. Alternatively, you may try the Gauss integration method (GAUSS).

## 9.4. Error Messages¶

This is not a complete list of errors. In many error messages a possible solution is already indicated. These are not listed. The program might also stop at places where this is not supposed to happen. Then, the error message starts with SPEX-BUG (see Section 3.3). In this case you should contact the developers. Error messages have the form SPEX-ERROR (source.f:0123) Error message, where “source.f” is the name of the source file and 0123 is the respective line where the error occurred. We shorten this to (source.f) Error message in this list.

(read_write.f) k-point sets inconsistent (check …)

This error usually occurs if the k-point set defined in “spex.inp” (keyword BZ) conflicts with the one the DFT program has used for writing the input data. Make sure that the k-point sets are identical by generating the k-point set with Spex and running the one-shot DFT calculation in the proper order (steps 2 and 3 in Section 2). (Only for older versions:) The error can also be caused by the internal structure of the direct-access binary file containing the wavefunction data. Make sure that Spex and the DFT code are compiled in such a way that these files are treated identically.

(global.f) argument not an element of k-point set.

This error can be caused by inconsistent k-point sets, too. (See previous error message!) The error might also occur if the k points defined by KPT are not elements of the set (labels other than +), for example, if you use a definition with square brackets (such as KPT A=[1,1,0]), but the lattice constant is not properly defined (such definitions are interpreted with respect to the lattice constant). It is recommended to use internal coordinates (such as KPT A=(0,0,1)). See Section 5.1.2.

(coulombmatrix.f) Negative eigenvalue.

Your Coulomb matrix seems to be underconverged. Try to increase the parameter LEXP. If this does not solve the problem, the reason might be that the LAPACK routine fails to solve the general eigenvalue problem because of a nearly singular overlap matrix. Then you might try the option CUTZERO which removes linear dependencies from the overlap matrix and reattempts the diagonalization. The accuracy of the Coulomb matrix can be tested with the (undocumented) keywords CHKCOUL, TSTCOUL, and STEPRAD (all in section COULOMB).

(getinput.f) Defective symmetry transformation matrix.

A calculated symmetry transformation matrix turned out to be non-unitary. This is usually caused by insufficient precision of the lattice basis vectors provided by the DFT program. The obvious solution is to make sure that the lattice basis vectors are defined with sufficient precision in the DFT calculation. In particular, they have to conform to the crystal symmetries with a precision of at least twelve significant digits.

(getinput.f) Symmetry operation … rotates spin quantization axis.

Similarly to the previous one, this error is caused by insufficient precision: Spex expects the spin-quantization axis to be invariant with respect to the crystal symmetries in the case of non-collinear magnetism. Obvious solution: Make sure that the spin-quantization axis is defined with sufficient precision in the DFT run.
(irreps.f) Broken unitarity …
(irreps.f) Deviation in characters; too large irrep threshold increase: …
Both errors are caused by eigenstates (read from the DFT output) that are symmetry broken, i.e., they do not reflect sufficiently the crystal symmetries. This could be a problem of the DFT code. At the moment, there is no general solution to this problem. The second error can be circumvented by setting the parameter irrep_threshold in “irreps.f” to 0, which might lead to slower calculations. As a last resort, you can set the keyword NOSYM (Section 4.2.10), which switches off usage of symmetry.

(quasiparticle.f) Solution of quasiparticle equation did not converge after 5000 iterations.

If you use analytic continuation (CONTINUE), you probably have poles very close to the real frequency axis (normally with a small weight). Usually a slight change of parameters solves the problem. You can also try to use the keyword SMOOTH (Section 5.1.9). In the case of contour integration (CONTOUR), strong spectral structure in the self-energy can cause this problem. For example in metallic systems, a small Drude frequency can give rise to a delta-like peak in the self-energy. A possible solution in this case is to use PLASMA METAL (Section 5.2.3).

(Hwrapper.f) Fatal HDF5 error.

An error in the HDF5 library has occurred. There will be more informative error messages issued by the library itself. A possible reason could be that the HDF5 file misses a particular data set or attribute. In this case, make sure that the DFT program and Spex are called in the proper order (Section 2 and Section 8). If this does not solve the problem, please report the error. (Note that the same error can also occur in the source files “read_write.f”, “correlation.f”, and “correlation_wannier.f”.)

The following error messages are displayed when the program run was terminated abnormally by the operating system.

error while loading shared libraries: lib…: cannot open shared object file: No such file or directory

The library “lib…” is not found in standard directories. In this case, the location of the library has to be defined in the environment variable LD_LIBRARY_PATH of the shell. (Consult your Unix or Linux manual.)

Segmentation fault

A forbidden area of memory was accessed during the program run. First, you should make sure that the operating system allows unlimited size of stack memory. You can set the stack size from the shell (BASH: ulimit -s unlimited, CSH: limit stacksize unlimited). As an alternative, some compilers provide options to prevent the usage of stack memory (e.g., -heap-arrays in the Intel Fortran Compiler). If this does not solve the problem, it is possible that the error is caused by a real bug in the Spex code. Please report such an error. You can help the developers by running the same calculation again with a Spex executable that has been compiled with make ADD=-DCHECK (slower execution). Please send the resulting output. Unfortunately, compilers and libraries can have bugs themselves. It is not unlikely that the “segfault” is caused by such a bug. Therefore, it is worthwhile to recompile with different compilers and/or libraries and run the program again.