Merge pull request #1017 from lammps/doc-reorg-errors-python

# ------------------------------------------

clean-all:

clean-all: clean

	rm -rf $(BUILDDIR)/* utils/txt2html/txt2html.exe

clean:

	rm -rf $(RSTDIR) html

	rm -rf $(RSTDIR) html old epub

	rm -rf spelling

clean-spelling:

"Previous Section"_Python.html - "LAMMPS WWW Site"_lws -

"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next

Section"_Section_history.html :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

:line

Errors :h2

These doc pages describe the errors you can encounter when using

LAMMPS.  The common problems include conceptual issues.  The messages

and warnings doc pages give complete lists of all the messages the

code may generate (except those generated by USER packages), with

additional details for many of them.

<!-- RST

.. toctree::

   Errors_common

   Errors_bugs

   Errors_messages

   Errors_warnings

END_RST -->

<!-- HTML_ONLY -->

"Common problems"_Errors_common.html

"Reporting bugs"_Errors_bugs.html

"Error messages"_Errors_messages.html 

"Warning messages"_Errors_warnings.html :all(b)

<!-- END_HTML_ONLY -->

"Higher level section"_Errors.html - "LAMMPS WWW Site"_lws - "LAMMPS

Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

:line

Reporting bugs :h3

If you are confident that you have found a bug in LAMMPS, follow these

steps.

Check the "New features and bug

fixes"_http://lammps.sandia.gov/bug.html section of the "LAMMPS WWW

site"_lws to see if the bug has already been reported or fixed or the

"Unfixed bug"_http://lammps.sandia.gov/unbug.html to see if a fix is

pending.

Check the "mailing list"_http://lammps.sandia.gov/mail.html to see if

it has been discussed before.

If not, send an email to the mailing list describing the problem with

any ideas you have as to what is causing it or where in the code the

problem might be.  The developers will ask for more info if needed,

such as an input script or data files.

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 atoms 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.

NOTE: this page needs to have GitHub issues info added

"Higher level section"_Errors.html - "LAMMPS WWW Site"_lws - "LAMMPS

Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

:line

Common problems :h3

If two LAMMPS runs do not produce the exact 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 molecular dynamics

phase space trajectories within a few 100s or few 1000s of timesteps.

However, the statistical properties of the two runs (e.g. average

energy or temperature) should still be the same.

If the "velocity"_velocity.html command is used to set initial atom

velocities, a particular atom can be assigned a different velocity

when the problem is run on a different number of processors or on

different machines.  If this happens, the phase space trajectories of

the two simulations will rapidly diverge.  See the discussion of the

{loop} option in the "velocity"_velocity.html command for details and

options that avoid this issue.

Similarly, the "create_atoms"_create_atoms.html command generates a

lattice of atoms.  For the same physical system, the ordering and

numbering of atoms by atom ID may be different depending on the number

of processors.

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 "fix

langevin"_fix_langevin.html command for thermostatting.

A LAMMPS simulation typically has two stages, setup and run.  Most

LAMMPS errors are detected at setup time; others like a bond

stretching too far may not occur until the middle of a run.

LAMMPS tries to flag errors and print informative error messages so

you can fix the problem.  For most errors it will also print the last

input script command that it was processing.  Of course, LAMMPS cannot

figure out your physics or numerical mistakes, like choosing too big a

timestep, specifying erroneous force field coefficients, or putting 2

atoms on top of each other!  If you run into errors that LAMMPS

doesn't catch that you think it should flag, please send an email to

the "developers"_http://lammps.sandia.gov/authors.html.

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.lammps file or using the "echo command"_echo.html

to see it on the screen.  If you get an error like "Invalid ...

style", with ... being fix, compute, pair, etc, it means that you

mistyped the style name or that the command is part of an optional

package which was not compiled into your executable.  The list of

available styles in your executable can be listed by using "the -h

command-line argument"_Section_start.html#start_6.  The installation

and compilation of optional packages is explained in the "installation

instructions"_Section_start.html#start_3.

For a given command, LAMMPS expects certain arguments in a specified

order.  If you mess this up, LAMMPS will often flag the error, but it

may also simply 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 of 0.  Careful reading of the associated doc page

for the command should allow you to fix these problems. In most cases,

where LAMMPS expects to read a number, either integer or floating point,

it performs a stringent test on whether the provided input actually

is an integer or floating-point number, respectively, and reject the

input with an error message (for instance, when an integer is required,

but a floating-point number 1.0 is provided):

ERROR: Expected integer parameter in input script or data file :pre

Some commands allow for using variable references in place of numeric

constants so that the value can be evaluated and may change over the

course of a run.  This is typically done with the syntax {v_name} for a

parameter, where name is the name of the variable. On the other hand,

immediate variable expansion with the syntax ${name} is performed while

reading the input and before parsing commands,

NOTE: Using a variable reference (i.e. {v_name}) is only allowed if

the documentation of the corresponding command explicitly says it is.

Generally, LAMMPS 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 and logfile 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 thermodynamic output.  If LAMMPS

crashes or hangs without spitting out an error message first then it

could be a bug (see "this section"_#err_2) or one of the following

cases:

LAMMPS runs in the available memory a processor allows to be

allocated.  Most reasonable MD 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 LAMMPS doesn't trap on those errors.

Illegal arithmetic can cause LAMMPS to run slow or crash.  This is

typically due to invalid physics and numerics that your simulation is

computing.  If you see wild thermodynamic values or NaN values in your

LAMMPS output, something is wrong with your simulation.  If you

suspect this is happening, it is a good idea to print out

thermodynamic info frequently (e.g. every timestep) via the

"thermo"_thermo.html so you can monitor what is happening.

Visualizing the atom movement is also a good idea to insure your model

is behaving as you expect.

In parallel, one way LAMMPS can hang is due to how different MPI

implementations handle buffering of messages.  If the code hangs

without an error message, it may be that you need to specify an MPI

setting or two (usually via an environment variable) to enable

buffering or boost the sizes of messages that can be buffered.