Errors

This section describes how errors and warnings are displayed and how you can report them to the developers at DCS Computing.

Common problems 

Aspherix shows slightly different results on differents machines

If two Aspherix® runs do not produce the same answer on different machines or different numbers of processors, this is typically not a bug. In theory you should get identical answers on any number of processors and on any machine. In practice, numerical round-off can cause slight differences and eventual divergence of granular phase space trajectories within a few 100s or few 1000s of timesteps. However, the statistical properties of the two runs (e.g. average energy) should still be the same.

Some commands use random number generators which may be setup to produce different random number streams on each processor and hence will produce different effects when run on different numbers of processors. A commonly-used example is the insertion command for inserting particles.

Error detected by Aspherix

An Aspherix® simulation typically has two stages, setup and run. Most Aspherix® errors are detected at setup time; others like a bond stretching too far may not occur until the middle of a run.

Aspherix® tries to flag errors and print informative error messages so you can fix the problem. Of course, Aspherix® cannot figure out your physics or numerical mistakes, like choosing too big a timestep, specifying erroneous material parameters, or putting two particles on top of each other. If you run into errors that Aspherix® doesn’t catch that you think it should flag, please open a support ticket.

Aspherix gives an error message about an invalid command

If you get an error message about an invalid command in your input script, you can determine what command is causing the problem by looking in the log_aspherix.txt file or using the echo command to see it on the screen. For a given command, Aspherix® expects certain arguments in a specified order. If you mess this up, Aspherix® will often flag the error, but it may read a bogus argument and assign a value that is valid, but not what you wanted. E.g. trying to read the string “abc” as an integer value and assigning the associated variable a value of 0.

Generally, Aspherix® will print a message to the screen and logfile and exit gracefully when it encounters a fatal error. Sometimes it will print a WARNING to the screen, the logfile and the warnings file and continue on; you can decide if the WARNING is important or not. A WARNING message that is generated in the middle of a run is only printed to the screen, not to the logfile, to avoid cluttering up status output. If any warnings are encountered, Aspherix® will print a message at the end such as:

>> Simulation produced 2 warnings. See the warnings file (default: warnings_aspherix.txt) for details. <<

to indicate that the user should check the warnings file.

Aspherix® crashes or hangs without an error message

If Aspherix® crashes or hangs without spitting out an error message first then it could be a bug (see this section) or one of the following cases:

Aspherix® runs in the available memory a processor allows to be allocated. Most reasonable DEM runs are compute limited, not memory limited, so this shouldn’t be a bottleneck on most platforms. Almost all large memory allocations in the code are done via C-style malloc’s which will generate an error message if you run out of memory.Smaller chunks of memory are allocated via C++ “new” statements. If you are unlucky you could run out of memory just when one of these small requests is made, in which case the code will crash or hang (in parallel), since Aspherix® doesn’t trap on those errors.
Illegal arithmetic can cause Aspherix® to run slow or crash. This is typically due to invalid physics and numerics that your simulation is computing. If you see wild kinetic energy values or NaN values in your Aspherix® output, something is wrong with your simulation. Visualizing the particle movement is a good idea to ensure your model is behaving as you expect.

Reporting errors 

If you are think that you have found a bug, omission or error in Aspherix® (including this documentation), please open a support ticket and provide as much detail as you can. Please make sure to include the log file (default name: log_aspherix.txt) and the warnings file (default name: warnings_aspherix.txt) as they contain more information than just the output. Ideally you can provide the developers with an input script and data files that reproduce the issue.

If you want to help us even more the most useful thing you can do to help us fix the bug is to isolate the problem. Run it on the smallest number of particles and fewest number of processors and with the simplest input script that reproduces the bug and try to identify what command or combination of commands is causing the problem.