Known difficulties

1. Matrix diagonalization bombs out. Increase diagsafety (section 5.3).
2. The double unit cell problems: If you run a supercell of twice the size of the real cell, i.e. if there are NONPRIMITIVE translations within the unit cell left, you will encounter complex charge density problems if you run k-point sets which include for instance the BZ boundaries. We believe this is due to artificial degeneracies that occur when the bands are folded back. The matrix diagonalization routine has trouble handling those degenerate cases: It superimposes them in a slightly incorrect fashion, thereby breaking the symmetry of the crystal, and leading to complex charge density. Unless the complex charge density is really large ( > 1e-6), don't worry about it. If you are worried, set the accuracy of the diagonalization routine higher.
3. Loss of symmetry: After many structural relaxation steps (say 15 or so), roundoff errors break the symmetry of the system, and lead to strange results. Often, the forces are symmetrized incorrectly, leading to termination of the code. Workaround: Restart from last step after explicitly symmetrizing the structural parameters.
4. Bad charge density: If the program bombs out, it is often because a bad initial charge density has been used. There is no sanity checks being done on the CD file! Workaround: Remove old charge density (the CD file), and retry.
5. Structural relaxation scheme does not converge: There can be several reasons. Often, the system is about to undergo a phase transition, and is just intrinsically instable. Another possibility is that the accuracy of the diagonalization is not good enough (see the corresponding section), or the potential convergence criterion is too large.
6. Negative charge density. Should only appear when the initial charge is set up from the atomic charge density, or if a nonlinear nonlinear core correction is used.
7. Complex charge density. Most of the times, this is because the coordinates of the atoms somewhat match the symmetry (say to 1e-8), but not quite. Fix: input lattice parameters and basis coordinates with very high accuracy, e.g. 1e-20. The gnu utility ``bc'' is very useful for this case, as it has arbitrary precision arithmetic.
8. NMR q problem: If the perturbation nmr_q for the NMR calculation is set too small, you will get wrong results unless the accuracy for the wave function is also cranked up. This affects mostly the susceptibility (G=0). An accuracy of 1e-12 for the wave function and a nmr_q of 0.01 is normally a good choice. In doubt, check if results are stable when nmr_q is varied.