spex_faq.rst 11.2 KB
Newer Older
anoop chandran's avatar
anoop chandran committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
.. _spex_faq:

===============
Spex FAQ
===============

Configuration
---------------

**Configuration stops with "MPI-3 compiler requested, but couldn't use MPI-3."**    

.. highlights:: Your MPI compiler does not support the MPI-3 standard, which is required for the parallelized version.

**Configuration stops with "Could not link HDF5 library."**

.. highlights:: Either (1) you do not have the HDF5 library, or (2) you have HDF5 but it is not installed in a standard directory (then, use the environment variables ``LDFLAGS`` and ``FCFLAGS``), or (3) you have HDF5 but it has been compiled with a different compiler.

You can get further information from the file ``config.log``.

Installation
-------------

**I want to use my own DFT program instead of Fleur.**

25 26 27
.. highlights:: You will have to rewrite or modify the routines in ``read_write.f`` and ``Hwrapper.f`` according to 
   your output files and recompile the source. If you use a different radial mesh for the MT functions than Fleur/Spex,
   it is recommendable to transform to the other mesh by interpolation.
anoop chandran's avatar
anoop chandran committed
28 29 30

**My compiler fails to compile the source.**

31
.. highlights:: 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 IntelMPI and MPICH. In case of configuration or compilation problems, please inform us.
anoop chandran's avatar
anoop chandran committed
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47

Usage
-------

**Spex needs too much memory.**

.. highlights:: Try the options ``STOREIBZ`` and/or ``NOSTORE``. You can also reduce the maximally allowed memory storage with the keyword ``MEM``.

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

.. highlights:: 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.

48
**My GW calculations do not converge wrt the k-point set.**
anoop chandran's avatar
anoop chandran committed
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65

.. highlights:: In systems with small band gaps (e.g. GaAs) the default treatment of the point k=0 might lead to bad k-point convergence. In this case try the option ``NOZERO`` which guarantees a smooth (but slower) convergence. 

**My calculations do not converge wrt the number of bands.**

.. highlights:: 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.**

.. highlights:: Increase (decrease) ``SCALE`` in section ``COULOMB``.

**There are jumps in the band structure.**

.. highlights:: Band structures should not be calculated without the keyword ``NOZERO``. 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``). 

Error Messages
--------------
Christoph Friedrich's avatar
Christoph Friedrich committed
66 67 68 69
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 :numref:`spex.out`). 
In this case you should contact the programmers. 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.
anoop chandran's avatar
anoop chandran committed
70

71
**(read_write.f) k-point sets inconsistent (check ...)**
anoop chandran's avatar
anoop chandran committed
72

Christoph Friedrich's avatar
Christoph Friedrich committed
73
.. highlights:: This error usually occurs if the k-point set defined in "spex.inp" (keyword ``BZ``) conflicts with the one the DFT program has used
74 75 76 77
   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 :numref:`getting_started`). (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.
anoop chandran's avatar
anoop chandran committed
78

79
**(coulombmatrix.f) Negative eigenvalue.**
anoop chandran's avatar
anoop chandran committed
80

81 82 83 84 85
.. highlights:: 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``).
anoop chandran's avatar
anoop chandran committed
86

87 88
.. **intgrf: Negative exponent x in extrapolation a+c*r**x.**
   The first (nonzero) point of your radial MT mesh might be too far away from zero. Modify the mesh accordingly. You can also try to increase ``TOL`` in section ``MBASIS``.
anoop chandran's avatar
anoop chandran committed
89

90
**(global.f) argument not an element of k-point set.** 
anoop chandran's avatar
anoop chandran committed
91

92 93 94 95 96
.. highlights:: This message is caused by an inconsistency in the k-point set. Either the k-point set defined by ``BZ``
   and the one stored in the DFT output file are different or the k points defined by ``KPT`` are not elements of the set. 
   The latter happens, 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).
   In any case, it is recommended to use internal coordinates (such as ``KPT A=(0,0,1)``). See :numref:`KPT`.
anoop chandran's avatar
anoop chandran committed
97

98 99 100
**(getinput.f) Defective symmetry transformation matrix.**

.. highlights:: A calculated symmetry transformation matrix turned out to be non-unitary. This is usually caused by insufficient precision of
Christoph Friedrich's avatar
Christoph Friedrich committed
101 102
   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
103 104 105 106 107 108
   significant digits.

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

.. highlights:: 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
Christoph Friedrich's avatar
Christoph Friedrich committed
109
   is defined with sufficient precision in the DFT run.
110 111 112 113

| **(irreps.f) Broken unitarity ...**
| **(irreps.f) Deviation in characters; too large irrep threshold increase: ...**

Christoph Friedrich's avatar
Christoph Friedrich committed
114
.. highlights:: Both errors are caused by eigenstates (read from the DFT output) that are symmetry broken, i.e., they do not reflect sufficiently
115 116 117 118 119 120 121 122 123 124 125 126
   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, though, by setting the parameter ``irrep_threshold`` in "irreps.f" to 0, which might lead to slower calculations.
   
.. Found 2 states in subspace of eigenvalue  -2.12487 while expecting 4.
   Currently no solution to this error.
   
**(quasiparticle.f) Solution of quasiparticle equation did not converge after 5000 iterations.**

.. highlights:: 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`` (:numref:`SMOOTH`).
   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`` (:numref:`PLASMA`).
anoop chandran's avatar
anoop chandran committed
127

128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
**(Hwrapper.f) Fatal HDF5 error.**

.. highlights:: 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 (:numref:`getting_started` and :numref:`spex_and_fleur`).
   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**

.. highlights:: 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**

.. highlights:: 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
148 149
   (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 
150 151
   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.
152 153
   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.
154 155 156 157 158 159

.. .. highlights:: If this is caused by a too high memory demand you should try the option ``STOREIBZ`` (and ``NOSTORE``) or
   reduce the maximally allowed storage with the keyword ``MEM``. With some compilers this can 
   also happen, if the stack size is limited. In this case set the stack size to "unlimited" 
   (e.g., ``limit stacksize unlimited`` in csh). However, this is not possible with Mac computers. 
   In this case add "Wl,-stack_size,0x10000000,-stack_addr,0xc0000000" to LDFLAGS or "-heap-arrays" to FFLAGS in Makefile.
anoop chandran's avatar
anoop chandran committed
160