On occasion, the code may fail to perform the function you desire. It might crash, or it might give (unpleasantly) surprising results. This page tells you how to set up a useful bug report, one that will result in getting you up and running again as quickly as possible.
The elements of a bug report:
If you have an unexplained crash (i.e., it is not apparently a failure due to the compute platform – i.e., power, disk outage), and you are unable to resolve the problem (i.e., the code output does not tell you what went wrong), collect the following elements for a bug report:
- What are you trying to do?
- What is the nature of the failure?
- What is the input file?
- What does the code tell you?
- Did you do any troubleshooting?
- What code version?
- Where did you run the calculation?
- Compare to known bugs and their workarounds and send it as a bug report to us.
What are you trying to do?
What kind of calculation are you trying to run, and what result are you trying to get out of it?
It is easier to diagnose what a problem might be, if we know what it is that you are trying to accomplish with the code. An example: “I was trying to do an NEB calculation of a transition state barrier energy for an hydrogen atom migrating through alpha quartz.”
Return to Top
What is the nature of the failure?
What went wrong?
Did the code die unexpectedly (where)?
Did the code give answers that were nonsense (how so)?
Did the code not parse your input file well (what)?
Did the code complain about something (what)?
How did the code not do what you hoped it would do?
Return to Top
What is the input file?
If possible, include the input file in the message.
On occasion, it may make sense to also send the atom files, too.
The most common error in running the code is in setting up the input file, and inspection often reveals the problem. If the code stopped during reading the input file, it is almost certain that you have a format error in the input file. The code will have echoed the most recent line it read, and that is most likely the error in the input file. The code will attempt to speculate about the nature of the error, based on what it was trying to do at the moment, but certainly at that point or immediately above that in the input file is your error.
If inspection does not reveal the problem, if we have the input file we can do independent tests to reproduce your problem locally and diagnose the cause.
Return to Top
What does the code tell you?
If possible, send the tail of the output file that contains at least the error message (if the code gives one) back to the last timing statement in the output file.
Even better, rerun the calculation with more timing diagnostics, i.e., set the output level to “3” in the command options section to increase the number of timing statements and thereby narrow the location in the code where the failure occurred.
The code is very good at trapping problems and often errors can be isolated and diagnosed from the error message. If the code crashed, having the tail back to the final reported timing statement at least isolates the location of the failure better.
Return to Top
Did you do any troubleshooting first?
What did you try to correct the problem, if anything?
Most of the Input Manuals have troubleshooting suggestions. Many common problems and how to deal with them is described in specific sections. What did you try to get around the problem, if anything? If so, what happened?
Return to Top
What version of the code are you using?
Include the version of the code in the message.
The code version (and code dimensions) are listed at the top of every output file.
Return to Top
Where did you run, where did you get the executable?
What kind of machine are you running on, are you running in serial or parallel (how many processors?), etc?
Where did you get the executable (who built it)?
A simple “I was running the task-parallel code on an mpi-cluster with 12 procs using version 2.59(b)” is the kind of information that should be included in every bug report.
Send all bug reports to this address.
Some known bugs
- ODD2FFT (Oct-2013) – serious (faulty results without warning)
Faulty results (without crashing) for large calculations when *second* grid dimension is odd (e.g. 46 x 73 x 400)
Status: unresolved, localized to use of FFT in code
Workaround: avoid odd grid size in second dimension - COREPHANTOM (Oct-2013) – minor (minimal numeric effect)
By code inspection, correction term for phantom force/stress from atomic core-valence appear incorrect
Status: solved, but not installed (not yet verified and tested) - KGESSER (Oct-2013) – failed scf with guessing
The code can do scf guessing, to accelerate SCF convergence in geometry relaxations. For systems with non-Gamma k-points, the guess is faulty IF an atom crosses a supercell boundary (a bad phase gets introduced into the construction of the gues Hamiltonian.
Status: Unsolved.
Workaround: By default, the guess is turned OFF for calculations with non-Gamma k-posint (as of 2.66, previously it was on). The default for gamma-point calculations remains ON. Use the do/no ges facility in the run phase section to change from the default setting.