From 1d9ad557967507181f71f34c5dec7d76dda9177c Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Wed, 25 Jul 2018 14:10:00 -0600 Subject: [PATCH] changes to Errors and Python doc pages --- doc/src/Errors.txt | 37 + doc/src/Errors_bugs.txt | 35 + doc/src/Errors_common.txt | 123 ++ ...Section_errors.txt => Errors_messages.txt} | 1097 +---------------- doc/src/Errors_warnings.txt | 934 ++++++++++++++ doc/src/Examples.txt | 6 - doc/src/Manual.txt | 32 +- doc/src/Modify.txt | 14 +- doc/src/Python.txt | 79 ++ doc/src/Python_call.txt | 85 ++ doc/src/Python_examples.txt | 81 ++ doc/src/Python_install.txt | 74 ++ doc/src/Python_library.txt | 256 ++++ doc/src/Python_mpi.txt | 67 + doc/src/Python_overview.txt | 35 + doc/src/Python_pylammps.txt | 14 + doc/src/Python_run.txt | 40 + doc/src/Python_shlib.txt | 34 + doc/src/Python_test.txt | 131 ++ doc/src/Section_commands.txt | 2 +- doc/src/Section_history.txt | 2 +- doc/src/Section_howto.txt | 22 +- doc/src/Section_intro.txt | 6 +- doc/src/Section_packages.txt | 10 +- doc/src/Section_python.txt | 869 ------------- doc/src/Section_start.txt | 28 +- doc/src/Tools.txt | 6 - doc/src/fix_external.txt | 3 +- doc/src/lammps.book | 19 +- doc/src/python.txt | 28 +- doc/src/read_dump.txt | 10 +- doc/src/read_restart.txt | 3 +- src/pair.cpp | 6 +- 33 files changed, 2130 insertions(+), 2058 deletions(-) create mode 100644 doc/src/Errors.txt create mode 100644 doc/src/Errors_bugs.txt create mode 100644 doc/src/Errors_common.txt rename doc/src/{Section_errors.txt => Errors_messages.txt} (87%) create mode 100644 doc/src/Errors_warnings.txt create mode 100644 doc/src/Python.txt create mode 100644 doc/src/Python_call.txt create mode 100644 doc/src/Python_examples.txt create mode 100644 doc/src/Python_install.txt create mode 100644 doc/src/Python_library.txt create mode 100644 doc/src/Python_mpi.txt create mode 100644 doc/src/Python_overview.txt create mode 100644 doc/src/Python_pylammps.txt create mode 100644 doc/src/Python_run.txt create mode 100644 doc/src/Python_shlib.txt create mode 100644 doc/src/Python_test.txt delete mode 100644 doc/src/Section_python.txt diff --git a/doc/src/Errors.txt b/doc/src/Errors.txt new file mode 100644 index 0000000000..8e10cb6ae4 --- /dev/null +++ b/doc/src/Errors.txt @@ -0,0 +1,37 @@ +"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 :h3 + +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. + + + + + +"Common problems"_Errors_common.html +"Reporting bugs"_Errors_bugs.html +"Error messages"_Errors_messages.html +"Warning messages"_Errors_warnings.html :all(b) + + diff --git a/doc/src/Errors_bugs.txt b/doc/src/Errors_bugs.txt new file mode 100644 index 0000000000..c0a94c7a44 --- /dev/null +++ b/doc/src/Errors_bugs.txt @@ -0,0 +1,35 @@ +"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 diff --git a/doc/src/Errors_common.txt b/doc/src/Errors_common.txt new file mode 100644 index 0000000000..86a25f7e7d --- /dev/null +++ b/doc/src/Errors_common.txt @@ -0,0 +1,123 @@ +"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. diff --git a/doc/src/Section_errors.txt b/doc/src/Errors_messages.txt similarity index 87% rename from doc/src/Section_errors.txt rename to doc/src/Errors_messages.txt index 95482b06dc..1563e02901 100644 --- a/doc/src/Section_errors.txt +++ b/doc/src/Errors_messages.txt @@ -1,6 +1,5 @@ -"Previous Section"_Section_python.html - "LAMMPS WWW Site"_lws - -"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next -Section"_Section_history.html :c +"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) @@ -8,185 +7,27 @@ Section"_Section_history.html :c :line -12. Errors :h2 +Error messages :h3 -This section describes the errors you can encounter when using LAMMPS, -either conceptually, or as printed out by the program. +This is an alphabetic list of the ERROR messages LAMMPS prints out and +the reason why. If the explanation here is not sufficient, the +documentation for the offending command may help. Error messages also +list the source file and line number where the error was generated. +For example, a message like this: -12.1 "Common problems"_#err_1 -12.2 "Reporting bugs"_#err_2 -12.3 "Error & warning messages"_#err_3 :all(b) - -:line -:line - -12.1 Common problems :link(err_1),h4 - -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. - -:line - -12.2 Reporting bugs :link(err_2),h4 - -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. - -As a last resort, you can send an email directly to the -"developers"_http://lammps.sandia.gov/authors.html. - -:line - -12.3 Error & warning messages :h3,link(err_3) - -These are two alphabetic lists of the "ERROR"_#error and -"WARNING"_#warn messages LAMMPS prints out and the reason why. If the -explanation here is not sufficient, the documentation for the -offending command may help. -Error and warning messages also list the source file and line number -where the error was generated. For example, this message - -ERROR: Illegal velocity command (velocity.cpp:78) +ERROR: Illegal velocity command (velocity.cpp:78) :pre means that line #78 in the file src/velocity.cpp generated the error. Looking in the source code may help you figure out what went wrong. Note that error messages from "user-contributed -packages"_Section_start.html#start_3 are not listed here. If such an -error occurs and is not self-explanatory, you'll need to look in the -source code or contact the author of the package. +packages"_Section_package.html#table_user are not listed here. If +such an error occurs and is not self-explanatory, you'll need to look +in the source code or contact the author of the package. -Errors: :h3,link(error) +Doc page with "WARNING messages"_Errors_warnings.html + +:line :dlb @@ -803,13 +644,6 @@ lo value must be less than the hi value for all 3 dimensions. :dd The box command cannot be used after a read_data, read_restart, or create_box command. :dd -{BUG: restartinfo=1 but no restart support in pair style} :dt - -The pair style has a bug, where it does not support reading -and writing information to a restart file, but does not set -the member variable restartinfo to 0 as required in that case. :dd - - {CPU neighbor lists must be used for ellipsoid/sphere mix.} :dt When using Gay-Berne or RE-squared pair styles with both ellipsoidal and @@ -11003,904 +10837,3 @@ Self-explanatory. :dd Self-explanatory. :dd :dle - -Warnings: :h3,link(warn) - -:dlb - -{Adjusting Coulombic cutoff for MSM, new cutoff = %g} :dt - -The adjust/cutoff command is turned on and the Coulombic cutoff has been -adjusted to match the user-specified accuracy. :dd - -{Angle atoms missing at step %ld} :dt - -One or more of 3 atoms needed to compute a particular angle are -missing on this processor. Typically this is because the pairwise -cutoff is set too short or the angle has blown apart and an atom is -too far away. :dd - -{Angle style in data file differs from currently defined angle style} :dt - -Self-explanatory. :dd - -{Atom style in data file differs from currently defined atom style} :dt - -Self-explanatory. :dd - -{Bond atom missing in box size check} :dt - -The 2nd atoms needed to compute a particular bond is missing on this -processor. Typically this is because the pairwise cutoff is set too -short or the bond has blown apart and an atom is too far away. :dd - -{Bond atom missing in image check} :dt - -The 2nd atom in a particular bond is missing on this processor. -Typically this is because the pairwise cutoff is set too short or the -bond has blown apart and an atom is too far away. :dd - -{Bond atoms missing at step %ld} :dt - -The 2nd atom needed to compute a particular bond is missing on this -processor. Typically this is because the pairwise cutoff is set too -short or the bond has blown apart and an atom is too far away. :dd - -{Bond style in data file differs from currently defined bond style} :dt - -Self-explanatory. :dd - -{Bond/angle/dihedral extent > half of periodic box length} :dt - -This is a restriction because LAMMPS can be confused about which image -of an atom in the bonded interaction is the correct one to use. -"Extent" in this context means the maximum end-to-end length of the -bond/angle/dihedral. LAMMPS computes this by taking the maximum bond -length, multiplying by the number of bonds in the interaction (e.g. 3 -for a dihedral) and adding a small amount of stretch. :dd - -{Both groups in compute group/group have a net charge; the Kspace boundary correction to energy will be non-zero} :dt - -Self-explanatory. :dd - -{Calling write_dump before a full system init.} :dt - -The write_dump command is used before the system has been fully -initialized as part of a 'run' or 'minimize' command. Not all dump -styles and features are fully supported at this point and thus the -command may fail or produce incomplete or incorrect output. Insert -a "run 0" command, if a full system init is required. :dd - -{Cannot count rigid body degrees-of-freedom before bodies are fully initialized} :dt - -This means the temperature associated with the rigid bodies may be -incorrect on this timestep. :dd - -{Cannot count rigid body degrees-of-freedom before bodies are initialized} :dt - -This means the temperature associated with the rigid bodies may be -incorrect on this timestep. :dd - -{Cannot include log terms without 1/r terms; setting flagHI to 1} :dt - -Self-explanatory. :dd - -{Cannot include log terms without 1/r terms; setting flagHI to 1.} :dt - -Self-explanatory. :dd - -{Charges are set, but coulombic solver is not used} :dt - -Self-explanatory. :dd - -{Charges did not converge at step %ld: %lg} :dt - -Self-explanatory. :dd - -{Communication cutoff is too small for SNAP micro load balancing, increased to %lf} :dt - -Self-explanatory. :dd - -{Compute cna/atom cutoff may be too large to find ghost atom neighbors} :dt - -The neighbor cutoff used may not encompass enough ghost atoms -to perform this operation correctly. :dd - -{Computing temperature of portions of rigid bodies} :dt - -The group defined by the temperature compute does not encompass all -the atoms in one or more rigid bodies, so the change in -degrees-of-freedom for the atoms in those partial rigid bodies will -not be accounted for. :dd - -{Create_bonds max distance > minimum neighbor cutoff} :dt - -This means atom pairs for some atom types may not be in the neighbor -list and thus no bond can be created between them. :dd - -{Delete_atoms cutoff > minimum neighbor cutoff} :dt - -This means atom pairs for some atom types may not be in the neighbor -list and thus an atom in that pair cannot be deleted. :dd - -{Dihedral atoms missing at step %ld} :dt - -One or more of 4 atoms needed to compute a particular dihedral are -missing on this processor. Typically this is because the pairwise -cutoff is set too short or the dihedral has blown apart and an atom is -too far away. :dd - -{Dihedral problem} :dt - -Conformation of the 4 listed dihedral atoms is extreme; you may want -to check your simulation geometry. :dd - -{Dihedral problem: %d %ld %d %d %d %d} :dt - -Conformation of the 4 listed dihedral atoms is extreme; you may want -to check your simulation geometry. :dd - -{Dihedral style in data file differs from currently defined dihedral style} :dt - -Self-explanatory. :dd - -{Dump dcd/xtc timestamp may be wrong with fix dt/reset} :dt - -If the fix changes the timestep, the dump dcd file will not -reflect the change. :dd - -{Energy due to X extra global DOFs will be included in minimizer energies} :dt - -When using fixes like box/relax, the potential energy used by the minimizer -is augmented by an additional energy provided by the fix. Thus the printed -converged energy may be different from the total potential energy. :dd - -{Energy tally does not account for 'zero yes'} :dt - -The energy removed by using the 'zero yes' flag is not accounted -for in the energy tally and thus energy conservation cannot be -monitored in this case. :dd - -{Estimated error in splitting of dispersion coeffs is %g} :dt - -Error is greater than 0.0001 percent. :dd - -{Ewald/disp Newton solver failed, using old method to estimate g_ewald} :dt - -Self-explanatory. Choosing a different cutoff value may help. :dd - -{FENE bond too long} :dt - -A FENE bond has stretched dangerously far. It's interaction strength -will be truncated to attempt to prevent the bond from blowing up. :dd - -{FENE bond too long: %ld %d %d %g} :dt - -A FENE bond has stretched dangerously far. It's interaction strength -will be truncated to attempt to prevent the bond from blowing up. :dd - -{FENE bond too long: %ld %g} :dt - -A FENE bond has stretched dangerously far. It's interaction strength -will be truncated to attempt to prevent the bond from blowing up. :dd - -{Fix SRD walls overlap but fix srd overlap not set} :dt - -You likely want to set this in your input script. :dd - -{Fix bond/swap will ignore defined angles} :dt - -See the doc page for fix bond/swap for more info on this -restriction. :dd - -{Fix deposit near setting < possible overlap separation %g} :dt - -This test is performed for finite size particles with a diameter, not -for point particles. The near setting is smaller than the particle -diameter which can lead to overlaps. :dd - -{Fix evaporate may delete atom with non-zero molecule ID} :dt - -This is probably an error, since you should not delete only one atom -of a molecule. :dd - -{Fix gcmc using full_energy option} :dt - -Fix gcmc has automatically turned on the full_energy option since it -is required for systems like the one specified by the user. User input -included one or more of the following: kspace, triclinic, a hybrid -pair style, an eam pair style, or no "single" function for the pair -style. :dd - -{Fix property/atom mol or charge w/out ghost communication} :dt - -A model typically needs these properties defined for ghost atoms. :dd - -{Fix qeq CG convergence failed (%g) after %d iterations at %ld step} :dt - -Self-explanatory. :dd - -{Fix qeq has non-zero lower Taper radius cutoff} :dt - -Absolute value must be <= 0.01. :dd - -{Fix qeq has very low Taper radius cutoff} :dt - -Value should typically be >= 5.0. :dd - -{Fix qeq/dynamic tolerance may be too small for damped dynamics} :dt - -Self-explanatory. :dd - -{Fix qeq/fire tolerance may be too small for damped fires} :dt - -Self-explanatory. :dd - -{Fix rattle should come after all other integration fixes} :dt - -This fix is designed to work after all other integration fixes change -atom positions. Thus it should be the last integration fix specified. -If not, it will not satisfy the desired constraints as well as it -otherwise would. :dd - -{Fix recenter should come after all other integration fixes} :dt - -Other fixes may change the position of the center-of-mass, so -fix recenter should come last. :dd - -{Fix srd SRD moves may trigger frequent reneighboring} :dt - -This is because the SRD particles may move long distances. :dd - -{Fix srd grid size > 1/4 of big particle diameter} :dt - -This may cause accuracy problems. :dd - -{Fix srd particle moved outside valid domain} :dt - -This may indicate a problem with your simulation parameters. :dd - -{Fix srd particles may move > big particle diameter} :dt - -This may cause accuracy problems. :dd - -{Fix srd viscosity < 0.0 due to low SRD density} :dt - -This may cause accuracy problems. :dd - -{Fix thermal/conductivity comes before fix ave/spatial} :dt - -The order of these 2 fixes in your input script is such that fix -thermal/conductivity comes first. If you are using fix ave/spatial to -measure the temperature profile induced by fix viscosity, then this -may cause a glitch in the profile since you are averaging immediately -after swaps have occurred. Flipping the order of the 2 fixes -typically helps. :dd - -{Fix viscosity comes before fix ave/spatial} :dt - -The order of these 2 fixes in your input script is such that -fix viscosity comes first. If you are using fix ave/spatial -to measure the velocity profile induced by fix viscosity, then -this may cause a glitch in the profile since you are averaging -immediately after swaps have occurred. Flipping the order -of the 2 fixes typically helps. :dd - -{Fixes cannot send data in Kokkos communication, switching to classic communication} :dt - -This is current restriction with Kokkos. :dd - -{For better accuracy use 'pair_modify table 0'} :dt - -The user-specified force accuracy cannot be achieved unless the table -feature is disabled by using 'pair_modify table 0'. :dd - -{Geometric mixing assumed for 1/r^6 coefficients} :dt - -Self-explanatory. :dd - -{Group for fix_modify temp != fix group} :dt - -The fix_modify command is specifying a temperature computation that -computes a temperature on a different group of atoms than the fix -itself operates on. This is probably not what you want to do. :dd - -{H matrix size has been exceeded: m_fill=%d H.m=%d\n} :dt - -This is the size of the matrix. :dd - -{Ignoring unknown or incorrect info command flag} :dt - -Self-explanatory. An unknown argument was given to the info command. -Compare your input with the documentation. :dd - -{Improper atoms missing at step %ld} :dt - -One or more of 4 atoms needed to compute a particular improper are -missing on this processor. Typically this is because the pairwise -cutoff is set too short or the improper has blown apart and an atom is -too far away. :dd - -{Improper problem: %d %ld %d %d %d %d} :dt - -Conformation of the 4 listed improper atoms is extreme; you may want -to check your simulation geometry. :dd - -{Improper style in data file differs from currently defined improper style} :dt - -Self-explanatory. :dd - -{Inconsistent image flags} :dt - -The image flags for a pair on bonded atoms appear to be inconsistent. -Inconsistent means that when the coordinates of the two atoms are -unwrapped using the image flags, the two atoms are far apart. -Specifically they are further apart than half a periodic box length. -Or they are more than a box length apart in a non-periodic dimension. -This is usually due to the initial data file not having correct image -flags for the 2 atoms in a bond that straddles a periodic boundary. -They should be different by 1 in that case. This is a warning because -inconsistent image flags will not cause problems for dynamics or most -LAMMPS simulations. However they can cause problems when such atoms -are used with the fix rigid or replicate commands. Note that if you -have an infinite periodic crystal with bonds then it is impossible to -have fully consistent image flags, since some bonds will cross -periodic boundaries and connect two atoms with the same image -flag. :dd - -{KIM Model does not provide 'energy'; Potential energy will be zero} :dt - -Self-explanatory. :dd - -{KIM Model does not provide 'forces'; Forces will be zero} :dt - -Self-explanatory. :dd - -{KIM Model does not provide 'particleEnergy'; energy per atom will be zero} :dt - -Self-explanatory. :dd - -{KIM Model does not provide 'particleVirial'; virial per atom will be zero} :dt - -Self-explanatory. :dd - -{Kspace_modify slab param < 2.0 may cause unphysical behavior} :dt - -The kspace_modify slab parameter should be larger to insure periodic -grids padded with empty space do not overlap. :dd - -{Less insertions than requested} :dt - -The fix pour command was unsuccessful at finding open space -for as many particles as it tried to insert. :dd - -{Library error in lammps_gather_atoms} :dt - -This library function cannot be used if atom IDs are not defined -or are not consecutively numbered. :dd - -{Library error in lammps_scatter_atoms} :dt - -This library function cannot be used if atom IDs are not defined or -are not consecutively numbered, or if no atom map is defined. See the -atom_modify command for details about atom maps. :dd - -{Lost atoms via change_box: original %ld current %ld} :dt - -The command options you have used caused atoms to be lost. :dd - -{Lost atoms via displace_atoms: original %ld current %ld} :dt - -The command options you have used caused atoms to be lost. :dd - -{Lost atoms: original %ld current %ld} :dt - -Lost atoms are checked for each time thermo output is done. See the -thermo_modify lost command for options. Lost atoms usually indicate -bad dynamics, e.g. atoms have been blown far out of the simulation -box, or moved further than one processor's sub-domain away before -reneighboring. :dd - -{MSM mesh too small, increasing to 2 points in each direction} :dt - -Self-explanatory. :dd - -{Mismatch between velocity and compute groups} :dt - -The temperature computation used by the velocity command will not be -on the same group of atoms that velocities are being set for. :dd - -{Mixing forced for lj coefficients} :dt - -Self-explanatory. :dd - -{Molecule attributes do not match system attributes} :dt - -An attribute is specified (e.g. diameter, charge) that is -not defined for the specified atom style. :dd - -{Molecule has bond topology but no special bond settings} :dt - -This means the bonded atoms will not be excluded in pair-wise -interactions. :dd - -{Molecule template for create_atoms has multiple molecules} :dt - -The create_atoms command will only create molecules of a single type, -i.e. the first molecule in the template. :dd - -{Molecule template for fix gcmc has multiple molecules} :dt - -The fix gcmc command will only create molecules of a single type, -i.e. the first molecule in the template. :dd - -{Molecule template for fix shake has multiple molecules} :dt - -The fix shake command will only recognize molecules of a single -type, i.e. the first molecule in the template. :dd - -{More than one compute centro/atom} :dt - -It is not efficient to use compute centro/atom more than once. :dd - -{More than one compute cluster/atom} :dt - -It is not efficient to use compute cluster/atom more than once. :dd - -{More than one compute cna/atom defined} :dt - -It is not efficient to use compute cna/atom more than once. :dd - -{More than one compute contact/atom} :dt - -It is not efficient to use compute contact/atom more than once. :dd - -{More than one compute coord/atom} :dt - -It is not efficient to use compute coord/atom more than once. :dd - -{More than one compute damage/atom} :dt - -It is not efficient to use compute ke/atom more than once. :dd - -{More than one compute dilatation/atom} :dt - -Self-explanatory. :dd - -{More than one compute erotate/sphere/atom} :dt - -It is not efficient to use compute erorate/sphere/atom more than once. :dd - -{More than one compute hexorder/atom} :dt - -It is not efficient to use compute hexorder/atom more than once. :dd - -{More than one compute ke/atom} :dt - -It is not efficient to use compute ke/atom more than once. :dd - -{More than one compute orientorder/atom} :dt - -It is not efficient to use compute orientorder/atom more than once. :dd - -{More than one compute plasticity/atom} :dt - -Self-explanatory. :dd - -{More than one compute sna/atom} :dt - -Self-explanatory. :dd - -{More than one compute snad/atom} :dt - -Self-explanatory. :dd - -{More than one compute snav/atom} :dt - -Self-explanatory. :dd - -{More than one fix poems} :dt - -It is not efficient to use fix poems more than once. :dd - -{More than one fix rigid} :dt - -It is not efficient to use fix rigid more than once. :dd - -{Neighbor exclusions used with KSpace solver may give inconsistent Coulombic energies} :dt - -This is because excluding specific pair interactions also excludes -them from long-range interactions which may not be the desired effect. -The special_bonds command handles this consistently by insuring -excluded (or weighted) 1-2, 1-3, 1-4 interactions are treated -consistently by both the short-range pair style and the long-range -solver. This is not done for exclusions of charged atom pairs via the -neigh_modify exclude command. :dd - -{New thermo_style command, previous thermo_modify settings will be lost} :dt - -If a thermo_style command is used after a thermo_modify command, the -settings changed by the thermo_modify command will be reset to their -default values. This is because the thermo_modify command acts on -the currently defined thermo style, and a thermo_style command creates -a new style. :dd - -{No Kspace calculation with verlet/split} :dt - -The 2nd partition performs a kspace calculation so the kspace_style -command must be used. :dd - -{No automatic unit conversion to XTC file format conventions possible for units lj} :dt - -This means no scaling will be performed. :dd - -{No fixes defined, atoms won't move} :dt - -If you are not using a fix like nve, nvt, npt then atom velocities and -coordinates will not be updated during timestepping. :dd - -{No joints between rigid bodies, use fix rigid instead} :dt - -The bodies defined by fix poems are not connected by joints. POEMS -will integrate the body motion, but it would be more efficient to use -fix rigid. :dd - -{Not using real units with pair reax} :dt - -This is most likely an error, unless you have created your own ReaxFF -parameter file in a different set of units. :dd - -{Number of MSM mesh points changed to be a multiple of 2} :dt - -MSM requires that the number of grid points in each direction be a multiple -of two and the number of grid points in one or more directions have been -adjusted to meet this requirement. :dd - -{OMP_NUM_THREADS environment is not set.} :dt - -This environment variable must be set appropriately to use the -USER-OMP package. :dd - -{One or more atoms are time integrated more than once} :dt - -This is probably an error since you typically do not want to -advance the positions or velocities of an atom more than once -per timestep. :dd - -{One or more chunks do not contain all atoms in molecule} :dt - -This may not be what you intended. :dd - -{One or more dynamic groups may not be updated at correct point in timestep} :dt - -If there are other fixes that act immediately after the initial stage -of time integration within a timestep (i.e. after atoms move), then -the command that sets up the dynamic group should appear after those -fixes. This will insure that dynamic group assignments are made -after all atoms have moved. :dd - -{One or more respa levels compute no forces} :dt - -This is computationally inefficient. :dd - -{Pair COMB charge %.10f with force %.10f hit max barrier} :dt - -Something is possibly wrong with your model. :dd - -{Pair COMB charge %.10f with force %.10f hit min barrier} :dt - -Something is possibly wrong with your model. :dd - -{Pair brownian needs newton pair on for momentum conservation} :dt - -Self-explanatory. :dd - -{Pair dpd needs newton pair on for momentum conservation} :dt - -Self-explanatory. :dd - -{Pair dsmc: num_of_collisions > number_of_A} :dt - -Collision model in DSMC is breaking down. :dd - -{Pair dsmc: num_of_collisions > number_of_B} :dt - -Collision model in DSMC is breaking down. :dd - -{Pair style in data file differs from currently defined pair style} :dt - -Self-explanatory. :dd - -{Particle deposition was unsuccessful} :dt - -The fix deposit command was not able to insert as many atoms as -needed. The requested volume fraction may be too high, or other atoms -may be in the insertion region. :dd - -{Proc sub-domain size < neighbor skin, could lead to lost atoms} :dt - -The decomposition of the physical domain (likely due to load -balancing) has led to a processor's sub-domain being smaller than the -neighbor skin in one or more dimensions. Since reneighboring is -triggered by atoms moving the skin distance, this may lead to lost -atoms, if an atom moves all the way across a neighboring processor's -sub-domain before reneighboring is triggered. :dd - -{Reducing PPPM order b/c stencil extends beyond nearest neighbor processor} :dt - -This may lead to a larger grid than desired. See the kspace_modify overlap -command to prevent changing of the PPPM order. :dd - -{Reducing PPPMDisp Coulomb order b/c stencil extends beyond neighbor processor} :dt - -This may lead to a larger grid than desired. See the kspace_modify overlap -command to prevent changing of the PPPM order. :dd - -{Reducing PPPMDisp dispersion order b/c stencil extends beyond neighbor processor} :dt - -This may lead to a larger grid than desired. See the kspace_modify overlap -command to prevent changing of the PPPM order. :dd - -{Replacing a fix, but new group != old group} :dt - -The ID and style of a fix match for a fix you are changing with a fix -command, but the new group you are specifying does not match the old -group. :dd - -{Replicating in a non-periodic dimension} :dt - -The parameters for a replicate command will cause a non-periodic -dimension to be replicated; this may cause unwanted behavior. :dd - -{Resetting reneighboring criteria during PRD} :dt - -A PRD simulation requires that neigh_modify settings be delay = 0, -every = 1, check = yes. Since these settings were not in place, -LAMMPS changed them and will restore them to their original values -after the PRD simulation. :dd - -{Resetting reneighboring criteria during TAD} :dt - -A TAD simulation requires that neigh_modify settings be delay = 0, -every = 1, check = yes. Since these settings were not in place, -LAMMPS changed them and will restore them to their original values -after the PRD simulation. :dd - -{Resetting reneighboring criteria during minimization} :dt - -Minimization requires that neigh_modify settings be delay = 0, every = -1, check = yes. Since these settings were not in place, LAMMPS -changed them and will restore them to their original values after the -minimization. :dd - -{Restart file used different # of processors} :dt - -The restart file was written out by a LAMMPS simulation running on a -different number of processors. Due to round-off, the trajectories of -your restarted simulation may diverge a little more quickly than if -you ran on the same # of processors. :dd - -{Restart file used different 3d processor grid} :dt - -The restart file was written out by a LAMMPS simulation running on a -different 3d grid of processors. Due to round-off, the trajectories -of your restarted simulation may diverge a little more quickly than if -you ran on the same # of processors. :dd - -{Restart file used different boundary settings, using restart file values} :dt - -Your input script cannot change these restart file settings. :dd - -{Restart file used different newton bond setting, using restart file value} :dt - -The restart file value will override the setting in the input script. :dd - -{Restart file used different newton pair setting, using input script value} :dt - -The input script value will override the setting in the restart file. :dd - -{Restrain problem: %d %ld %d %d %d %d} :dt - -Conformation of the 4 listed dihedral atoms is extreme; you may want -to check your simulation geometry. :dd - -{Running PRD with only one replica} :dt - -This is allowed, but you will get no parallel speed-up. :dd - -{SRD bin shifting turned on due to small lamda} :dt - -This is done to try to preserve accuracy. :dd - -{SRD bin size for fix srd differs from user request} :dt - -Fix SRD had to adjust the bin size to fit the simulation box. See the -cubic keyword if you want this message to be an error vs warning. :dd - -{SRD bins for fix srd are not cubic enough} :dt - -The bin shape is not within tolerance of cubic. See the cubic -keyword if you want this message to be an error vs warning. :dd - -{SRD particle %d started inside big particle %d on step %ld bounce %d} :dt - -See the inside keyword if you want this message to be an error vs -warning. :dd - -{SRD particle %d started inside wall %d on step %ld bounce %d} :dt - -See the inside keyword if you want this message to be an error vs -warning. :dd - -{Shake determinant < 0.0} :dt - -The determinant of the quadratic equation being solved for a single -cluster specified by the fix shake command is numerically suspect. LAMMPS -will set it to 0.0 and continue. :dd - -{Shell command '%s' failed with error '%s'} :dt - -Self-explanatory. :dd - -{Shell command returned with non-zero status} :dt - -This may indicate the shell command did not operate as expected. :dd - -{Should not allow rigid bodies to bounce off relecting walls} :dt - -LAMMPS allows this, but their dynamics are not computed correctly. :dd - -{Should not use fix nve/limit with fix shake or fix rattle} :dt - -This will lead to invalid constraint forces in the SHAKE/RATTLE -computation. :dd - -{Simulations might be very slow because of large number of structure factors} :dt - -Self-explanatory. :dd - -{Slab correction not needed for MSM} :dt - -Slab correction is intended to be used with Ewald or PPPM and is not needed by MSM. :dd - -{System is not charge neutral, net charge = %g} :dt - -The total charge on all atoms on the system is not 0.0. -For some KSpace solvers this is only a warning. :dd - -{Table inner cutoff >= outer cutoff} :dt - -You specified an inner cutoff for a Coulombic table that is longer -than the global cutoff. Probably not what you wanted. :dd - -{Temperature for MSST is not for group all} :dt - -User-assigned temperature to MSST fix does not compute temperature for -all atoms. Since MSST computes a global pressure, the kinetic energy -contribution from the temperature is assumed to also be for all atoms. -Thus the pressure used by MSST could be inaccurate. :dd - -{Temperature for NPT is not for group all} :dt - -User-assigned temperature to NPT fix does not compute temperature for -all atoms. Since NPT computes a global pressure, the kinetic energy -contribution from the temperature is assumed to also be for all atoms. -Thus the pressure used by NPT could be inaccurate. :dd - -{Temperature for fix modify is not for group all} :dt - -The temperature compute is being used with a pressure calculation -which does operate on group all, so this may be inconsistent. :dd - -{Temperature for thermo pressure is not for group all} :dt - -User-assigned temperature to thermo via the thermo_modify command does -not compute temperature for all atoms. Since thermo computes a global -pressure, the kinetic energy contribution from the temperature is -assumed to also be for all atoms. Thus the pressure printed by thermo -could be inaccurate. :dd - -{The fix ave/spatial command has been replaced by the more flexible fix ave/chunk and compute chunk/atom commands -- fix ave/spatial will be removed in the summer of 2015} :dt - -Self-explanatory. :dd - -{The minimizer does not re-orient dipoles when using fix efield} :dt - -This means that only the atom coordinates will be minimized, -not the orientation of the dipoles. :dd - -{Too many common neighbors in CNA %d times} :dt - -More than the maximum # of neighbors was found multiple times. This -was unexpected. :dd - -{Too many inner timesteps in fix ttm} :dt - -Self-explanatory. :dd - -{Too many neighbors in CNA for %d atoms} :dt - -More than the maximum # of neighbors was found multiple times. This -was unexpected. :dd - -{Triclinic box skew is large} :dt - -The displacement in a skewed direction is normally required to be less -than half the box length in that dimension. E.g. the xy tilt must be -between -half and +half of the x box length. You have relaxed the -constraint using the box tilt command, but the warning means that a -LAMMPS simulation may be inefficient as a result. :dd - -{Use special bonds = 0,1,1 with bond style fene} :dt - -Most FENE models need this setting for the special_bonds command. :dd - -{Use special bonds = 0,1,1 with bond style fene/expand} :dt - -Most FENE models need this setting for the special_bonds command. :dd - -{Using a manybody potential with bonds/angles/dihedrals and special_bond exclusions} :dt - -This is likely not what you want to do. The exclusion settings will -eliminate neighbors in the neighbor list, which the manybody potential -needs to calculated its terms correctly. :dd - -{Using compute temp/deform with inconsistent fix deform remap option} :dt - -Fix nvt/sllod assumes deforming atoms have a velocity profile provided -by "remap v" or "remap none" as a fix deform option. :dd - -{Using compute temp/deform with no fix deform defined} :dt - -This is probably an error, since it makes little sense to use -compute temp/deform in this case. :dd - -{Using fix srd with box deformation but no SRD thermostat} :dt - -The deformation will heat the SRD particles so this can -be dangerous. :dd - -{Using kspace solver on system with no charge} :dt - -Self-explanatory. :dd - -{Using largest cut-off for lj/long/dipole/long long long} :dt - -Self-explanatory. :dd - -{Using largest cutoff for buck/long/coul/long} :dt - -Self-explanatory. :dd - -{Using largest cutoff for lj/long/coul/long} :dt - -Self-explanatory. :dd - -{Using largest cutoff for pair_style lj/long/tip4p/long} :dt - -Self-explanatory. :dd - -{Using package gpu without any pair style defined} :dt - -Self-explanatory. :dd - -{Using pair potential shift with pair_modify compute no} :dt - -The shift effects will thus not be computed. :dd - -{Using pair tail corrections with nonperiodic system} :dt - -This is probably a bogus thing to do, since tail corrections are -computed by integrating the density of a periodic system out to -infinity. :dd - -{Using pair tail corrections with pair_modify compute no} :dt - -The tail corrections will thus not be computed. :dd - -{pair style reax is now deprecated and will soon be retired. Users should switch to pair_style reax/c} :dt - -Self-explanatory. :dd - -:dle - diff --git a/doc/src/Errors_warnings.txt b/doc/src/Errors_warnings.txt new file mode 100644 index 0000000000..0324f563b6 --- /dev/null +++ b/doc/src/Errors_warnings.txt @@ -0,0 +1,934 @@ +"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 + +Warning messages :h3 + +This is an alphabetic list of the WARNING messages LAMMPS prints out +and the reason why. If the explanation here is not sufficient, the +documentation for the offending command may help. Warning messages +also list the source file and line number where the warning was +generated. For example, a message lile this: + +WARNING: Bond atom missing in box size check (domain.cpp:187) :pre + +means that line #187 in the file src/domain.cpp generated the error. +Looking in the source code may help you figure out what went wrong. + +Note that warning messages from "user-contributed +packages"_Section_start.html#table_user are not listed here. If such +a warning occurs and is not self-explanatory, you'll need to look in +the source code or contact the author of the package. + +Doc page with "ERROR messages"_Errors_messages.html + +:line + +:dlb + +{Adjusting Coulombic cutoff for MSM, new cutoff = %g} :dt + +The adjust/cutoff command is turned on and the Coulombic cutoff has been +adjusted to match the user-specified accuracy. :dd + +{Angle atoms missing at step %ld} :dt + +One or more of 3 atoms needed to compute a particular angle are +missing on this processor. Typically this is because the pairwise +cutoff is set too short or the angle has blown apart and an atom is +too far away. :dd + +{Angle style in data file differs from currently defined angle style} :dt + +Self-explanatory. :dd + +{Atom style in data file differs from currently defined atom style} :dt + +Self-explanatory. :dd + +{Bond atom missing in box size check} :dt + +The 2nd atoms needed to compute a particular bond is missing on this +processor. Typically this is because the pairwise cutoff is set too +short or the bond has blown apart and an atom is too far away. :dd + +{Bond atom missing in image check} :dt + +The 2nd atom in a particular bond is missing on this processor. +Typically this is because the pairwise cutoff is set too short or the +bond has blown apart and an atom is too far away. :dd + +{Bond atoms missing at step %ld} :dt + +The 2nd atom needed to compute a particular bond is missing on this +processor. Typically this is because the pairwise cutoff is set too +short or the bond has blown apart and an atom is too far away. :dd + +{Bond style in data file differs from currently defined bond style} :dt + +Self-explanatory. :dd + +{Bond/angle/dihedral extent > half of periodic box length} :dt + +This is a restriction because LAMMPS can be confused about which image +of an atom in the bonded interaction is the correct one to use. +"Extent" in this context means the maximum end-to-end length of the +bond/angle/dihedral. LAMMPS computes this by taking the maximum bond +length, multiplying by the number of bonds in the interaction (e.g. 3 +for a dihedral) and adding a small amount of stretch. :dd + +{Both groups in compute group/group have a net charge; the Kspace boundary correction to energy will be non-zero} :dt + +Self-explanatory. :dd + +{Calling write_dump before a full system init.} :dt + +The write_dump command is used before the system has been fully +initialized as part of a 'run' or 'minimize' command. Not all dump +styles and features are fully supported at this point and thus the +command may fail or produce incomplete or incorrect output. Insert +a "run 0" command, if a full system init is required. :dd + +{Cannot count rigid body degrees-of-freedom before bodies are fully initialized} :dt + +This means the temperature associated with the rigid bodies may be +incorrect on this timestep. :dd + +{Cannot count rigid body degrees-of-freedom before bodies are initialized} :dt + +This means the temperature associated with the rigid bodies may be +incorrect on this timestep. :dd + +{Cannot include log terms without 1/r terms; setting flagHI to 1} :dt + +Self-explanatory. :dd + +{Cannot include log terms without 1/r terms; setting flagHI to 1.} :dt + +Self-explanatory. :dd + +{Charges are set, but coulombic solver is not used} :dt + +Self-explanatory. :dd + +{Charges did not converge at step %ld: %lg} :dt + +Self-explanatory. :dd + +{Communication cutoff is too small for SNAP micro load balancing, increased to %lf} :dt + +Self-explanatory. :dd + +{Compute cna/atom cutoff may be too large to find ghost atom neighbors} :dt + +The neighbor cutoff used may not encompass enough ghost atoms +to perform this operation correctly. :dd + +{Computing temperature of portions of rigid bodies} :dt + +The group defined by the temperature compute does not encompass all +the atoms in one or more rigid bodies, so the change in +degrees-of-freedom for the atoms in those partial rigid bodies will +not be accounted for. :dd + +{Create_bonds max distance > minimum neighbor cutoff} :dt + +This means atom pairs for some atom types may not be in the neighbor +list and thus no bond can be created between them. :dd + +{Delete_atoms cutoff > minimum neighbor cutoff} :dt + +This means atom pairs for some atom types may not be in the neighbor +list and thus an atom in that pair cannot be deleted. :dd + +{Dihedral atoms missing at step %ld} :dt + +One or more of 4 atoms needed to compute a particular dihedral are +missing on this processor. Typically this is because the pairwise +cutoff is set too short or the dihedral has blown apart and an atom is +too far away. :dd + +{Dihedral problem} :dt + +Conformation of the 4 listed dihedral atoms is extreme; you may want +to check your simulation geometry. :dd + +{Dihedral problem: %d %ld %d %d %d %d} :dt + +Conformation of the 4 listed dihedral atoms is extreme; you may want +to check your simulation geometry. :dd + +{Dihedral style in data file differs from currently defined dihedral style} :dt + +Self-explanatory. :dd + +{Dump dcd/xtc timestamp may be wrong with fix dt/reset} :dt + +If the fix changes the timestep, the dump dcd file will not +reflect the change. :dd + +{Energy due to X extra global DOFs will be included in minimizer energies} :dt + +When using fixes like box/relax, the potential energy used by the minimizer +is augmented by an additional energy provided by the fix. Thus the printed +converged energy may be different from the total potential energy. :dd + +{Energy tally does not account for 'zero yes'} :dt + +The energy removed by using the 'zero yes' flag is not accounted +for in the energy tally and thus energy conservation cannot be +monitored in this case. :dd + +{Estimated error in splitting of dispersion coeffs is %g} :dt + +Error is greater than 0.0001 percent. :dd + +{Ewald/disp Newton solver failed, using old method to estimate g_ewald} :dt + +Self-explanatory. Choosing a different cutoff value may help. :dd + +{FENE bond too long} :dt + +A FENE bond has stretched dangerously far. It's interaction strength +will be truncated to attempt to prevent the bond from blowing up. :dd + +{FENE bond too long: %ld %d %d %g} :dt + +A FENE bond has stretched dangerously far. It's interaction strength +will be truncated to attempt to prevent the bond from blowing up. :dd + +{FENE bond too long: %ld %g} :dt + +A FENE bond has stretched dangerously far. It's interaction strength +will be truncated to attempt to prevent the bond from blowing up. :dd + +{Fix SRD walls overlap but fix srd overlap not set} :dt + +You likely want to set this in your input script. :dd + +{Fix bond/swap will ignore defined angles} :dt + +See the doc page for fix bond/swap for more info on this +restriction. :dd + +{Fix deposit near setting < possible overlap separation %g} :dt + +This test is performed for finite size particles with a diameter, not +for point particles. The near setting is smaller than the particle +diameter which can lead to overlaps. :dd + +{Fix evaporate may delete atom with non-zero molecule ID} :dt + +This is probably an error, since you should not delete only one atom +of a molecule. :dd + +{Fix gcmc using full_energy option} :dt + +Fix gcmc has automatically turned on the full_energy option since it +is required for systems like the one specified by the user. User input +included one or more of the following: kspace, triclinic, a hybrid +pair style, an eam pair style, or no "single" function for the pair +style. :dd + +{Fix property/atom mol or charge w/out ghost communication} :dt + +A model typically needs these properties defined for ghost atoms. :dd + +{Fix qeq CG convergence failed (%g) after %d iterations at %ld step} :dt + +Self-explanatory. :dd + +{Fix qeq has non-zero lower Taper radius cutoff} :dt + +Absolute value must be <= 0.01. :dd + +{Fix qeq has very low Taper radius cutoff} :dt + +Value should typically be >= 5.0. :dd + +{Fix qeq/dynamic tolerance may be too small for damped dynamics} :dt + +Self-explanatory. :dd + +{Fix qeq/fire tolerance may be too small for damped fires} :dt + +Self-explanatory. :dd + +{Fix rattle should come after all other integration fixes} :dt + +This fix is designed to work after all other integration fixes change +atom positions. Thus it should be the last integration fix specified. +If not, it will not satisfy the desired constraints as well as it +otherwise would. :dd + +{Fix recenter should come after all other integration fixes} :dt + +Other fixes may change the position of the center-of-mass, so +fix recenter should come last. :dd + +{Fix srd SRD moves may trigger frequent reneighboring} :dt + +This is because the SRD particles may move long distances. :dd + +{Fix srd grid size > 1/4 of big particle diameter} :dt + +This may cause accuracy problems. :dd + +{Fix srd particle moved outside valid domain} :dt + +This may indicate a problem with your simulation parameters. :dd + +{Fix srd particles may move > big particle diameter} :dt + +This may cause accuracy problems. :dd + +{Fix srd viscosity < 0.0 due to low SRD density} :dt + +This may cause accuracy problems. :dd + +{Fix thermal/conductivity comes before fix ave/spatial} :dt + +The order of these 2 fixes in your input script is such that fix +thermal/conductivity comes first. If you are using fix ave/spatial to +measure the temperature profile induced by fix viscosity, then this +may cause a glitch in the profile since you are averaging immediately +after swaps have occurred. Flipping the order of the 2 fixes +typically helps. :dd + +{Fix viscosity comes before fix ave/spatial} :dt + +The order of these 2 fixes in your input script is such that +fix viscosity comes first. If you are using fix ave/spatial +to measure the velocity profile induced by fix viscosity, then +this may cause a glitch in the profile since you are averaging +immediately after swaps have occurred. Flipping the order +of the 2 fixes typically helps. :dd + +{Fixes cannot send data in Kokkos communication, switching to classic communication} :dt + +This is current restriction with Kokkos. :dd + +{For better accuracy use 'pair_modify table 0'} :dt + +The user-specified force accuracy cannot be achieved unless the table +feature is disabled by using 'pair_modify table 0'. :dd + +{Geometric mixing assumed for 1/r^6 coefficients} :dt + +Self-explanatory. :dd + +{Group for fix_modify temp != fix group} :dt + +The fix_modify command is specifying a temperature computation that +computes a temperature on a different group of atoms than the fix +itself operates on. This is probably not what you want to do. :dd + +{H matrix size has been exceeded: m_fill=%d H.m=%d\n} :dt + +This is the size of the matrix. :dd + +{Ignoring unknown or incorrect info command flag} :dt + +Self-explanatory. An unknown argument was given to the info command. +Compare your input with the documentation. :dd + +{Improper atoms missing at step %ld} :dt + +One or more of 4 atoms needed to compute a particular improper are +missing on this processor. Typically this is because the pairwise +cutoff is set too short or the improper has blown apart and an atom is +too far away. :dd + +{Improper problem: %d %ld %d %d %d %d} :dt + +Conformation of the 4 listed improper atoms is extreme; you may want +to check your simulation geometry. :dd + +{Improper style in data file differs from currently defined improper style} :dt + +Self-explanatory. :dd + +{Inconsistent image flags} :dt + +The image flags for a pair on bonded atoms appear to be inconsistent. +Inconsistent means that when the coordinates of the two atoms are +unwrapped using the image flags, the two atoms are far apart. +Specifically they are further apart than half a periodic box length. +Or they are more than a box length apart in a non-periodic dimension. +This is usually due to the initial data file not having correct image +flags for the 2 atoms in a bond that straddles a periodic boundary. +They should be different by 1 in that case. This is a warning because +inconsistent image flags will not cause problems for dynamics or most +LAMMPS simulations. However they can cause problems when such atoms +are used with the fix rigid or replicate commands. Note that if you +have an infinite periodic crystal with bonds then it is impossible to +have fully consistent image flags, since some bonds will cross +periodic boundaries and connect two atoms with the same image +flag. :dd + +{KIM Model does not provide 'energy'; Potential energy will be zero} :dt + +Self-explanatory. :dd + +{KIM Model does not provide 'forces'; Forces will be zero} :dt + +Self-explanatory. :dd + +{KIM Model does not provide 'particleEnergy'; energy per atom will be zero} :dt + +Self-explanatory. :dd + +{KIM Model does not provide 'particleVirial'; virial per atom will be zero} :dt + +Self-explanatory. :dd + +{Kspace_modify slab param < 2.0 may cause unphysical behavior} :dt + +The kspace_modify slab parameter should be larger to insure periodic +grids padded with empty space do not overlap. :dd + +{Less insertions than requested} :dt + +The fix pour command was unsuccessful at finding open space +for as many particles as it tried to insert. :dd + +{Library error in lammps_gather_atoms} :dt + +This library function cannot be used if atom IDs are not defined +or are not consecutively numbered. :dd + +{Library error in lammps_scatter_atoms} :dt + +This library function cannot be used if atom IDs are not defined or +are not consecutively numbered, or if no atom map is defined. See the +atom_modify command for details about atom maps. :dd + +{Lost atoms via change_box: original %ld current %ld} :dt + +The command options you have used caused atoms to be lost. :dd + +{Lost atoms via displace_atoms: original %ld current %ld} :dt + +The command options you have used caused atoms to be lost. :dd + +{Lost atoms: original %ld current %ld} :dt + +Lost atoms are checked for each time thermo output is done. See the +thermo_modify lost command for options. Lost atoms usually indicate +bad dynamics, e.g. atoms have been blown far out of the simulation +box, or moved further than one processor's sub-domain away before +reneighboring. :dd + +{MSM mesh too small, increasing to 2 points in each direction} :dt + +Self-explanatory. :dd + +{Mismatch between velocity and compute groups} :dt + +The temperature computation used by the velocity command will not be +on the same group of atoms that velocities are being set for. :dd + +{Mixing forced for lj coefficients} :dt + +Self-explanatory. :dd + +{Molecule attributes do not match system attributes} :dt + +An attribute is specified (e.g. diameter, charge) that is +not defined for the specified atom style. :dd + +{Molecule has bond topology but no special bond settings} :dt + +This means the bonded atoms will not be excluded in pair-wise +interactions. :dd + +{Molecule template for create_atoms has multiple molecules} :dt + +The create_atoms command will only create molecules of a single type, +i.e. the first molecule in the template. :dd + +{Molecule template for fix gcmc has multiple molecules} :dt + +The fix gcmc command will only create molecules of a single type, +i.e. the first molecule in the template. :dd + +{Molecule template for fix shake has multiple molecules} :dt + +The fix shake command will only recognize molecules of a single +type, i.e. the first molecule in the template. :dd + +{More than one compute centro/atom} :dt + +It is not efficient to use compute centro/atom more than once. :dd + +{More than one compute cluster/atom} :dt + +It is not efficient to use compute cluster/atom more than once. :dd + +{More than one compute cna/atom defined} :dt + +It is not efficient to use compute cna/atom more than once. :dd + +{More than one compute contact/atom} :dt + +It is not efficient to use compute contact/atom more than once. :dd + +{More than one compute coord/atom} :dt + +It is not efficient to use compute coord/atom more than once. :dd + +{More than one compute damage/atom} :dt + +It is not efficient to use compute ke/atom more than once. :dd + +{More than one compute dilatation/atom} :dt + +Self-explanatory. :dd + +{More than one compute erotate/sphere/atom} :dt + +It is not efficient to use compute erorate/sphere/atom more than once. :dd + +{More than one compute hexorder/atom} :dt + +It is not efficient to use compute hexorder/atom more than once. :dd + +{More than one compute ke/atom} :dt + +It is not efficient to use compute ke/atom more than once. :dd + +{More than one compute orientorder/atom} :dt + +It is not efficient to use compute orientorder/atom more than once. :dd + +{More than one compute plasticity/atom} :dt + +Self-explanatory. :dd + +{More than one compute sna/atom} :dt + +Self-explanatory. :dd + +{More than one compute snad/atom} :dt + +Self-explanatory. :dd + +{More than one compute snav/atom} :dt + +Self-explanatory. :dd + +{More than one fix poems} :dt + +It is not efficient to use fix poems more than once. :dd + +{More than one fix rigid} :dt + +It is not efficient to use fix rigid more than once. :dd + +{Neighbor exclusions used with KSpace solver may give inconsistent Coulombic energies} :dt + +This is because excluding specific pair interactions also excludes +them from long-range interactions which may not be the desired effect. +The special_bonds command handles this consistently by insuring +excluded (or weighted) 1-2, 1-3, 1-4 interactions are treated +consistently by both the short-range pair style and the long-range +solver. This is not done for exclusions of charged atom pairs via the +neigh_modify exclude command. :dd + +{New thermo_style command, previous thermo_modify settings will be lost} :dt + +If a thermo_style command is used after a thermo_modify command, the +settings changed by the thermo_modify command will be reset to their +default values. This is because the thermo_modify command acts on +the currently defined thermo style, and a thermo_style command creates +a new style. :dd + +{No Kspace calculation with verlet/split} :dt + +The 2nd partition performs a kspace calculation so the kspace_style +command must be used. :dd + +{No automatic unit conversion to XTC file format conventions possible for units lj} :dt + +This means no scaling will be performed. :dd + +{No fixes defined, atoms won't move} :dt + +If you are not using a fix like nve, nvt, npt then atom velocities and +coordinates will not be updated during timestepping. :dd + +{No joints between rigid bodies, use fix rigid instead} :dt + +The bodies defined by fix poems are not connected by joints. POEMS +will integrate the body motion, but it would be more efficient to use +fix rigid. :dd + +{Not using real units with pair reax} :dt + +This is most likely an error, unless you have created your own ReaxFF +parameter file in a different set of units. :dd + +{Number of MSM mesh points changed to be a multiple of 2} :dt + +MSM requires that the number of grid points in each direction be a multiple +of two and the number of grid points in one or more directions have been +adjusted to meet this requirement. :dd + +{OMP_NUM_THREADS environment is not set.} :dt + +This environment variable must be set appropriately to use the +USER-OMP package. :dd + +{One or more atoms are time integrated more than once} :dt + +This is probably an error since you typically do not want to +advance the positions or velocities of an atom more than once +per timestep. :dd + +{One or more chunks do not contain all atoms in molecule} :dt + +This may not be what you intended. :dd + +{One or more dynamic groups may not be updated at correct point in timestep} :dt + +If there are other fixes that act immediately after the initial stage +of time integration within a timestep (i.e. after atoms move), then +the command that sets up the dynamic group should appear after those +fixes. This will insure that dynamic group assignments are made +after all atoms have moved. :dd + +{One or more respa levels compute no forces} :dt + +This is computationally inefficient. :dd + +{Pair COMB charge %.10f with force %.10f hit max barrier} :dt + +Something is possibly wrong with your model. :dd + +{Pair COMB charge %.10f with force %.10f hit min barrier} :dt + +Something is possibly wrong with your model. :dd + +{Pair brownian needs newton pair on for momentum conservation} :dt + +Self-explanatory. :dd + +{Pair dpd needs newton pair on for momentum conservation} :dt + +Self-explanatory. :dd + +{Pair dsmc: num_of_collisions > number_of_A} :dt + +Collision model in DSMC is breaking down. :dd + +{Pair dsmc: num_of_collisions > number_of_B} :dt + +Collision model in DSMC is breaking down. :dd + +{Pair style in data file differs from currently defined pair style} :dt + +Self-explanatory. :dd + +{Pair style restartinfo set but has no restart support} :dt + +This pair style has a bug, where it does not support reading and +writing information to a restart file, but does not set the member +variable "restartinfo" to 0 as required in that case. :dd + +{Particle deposition was unsuccessful} :dt + +The fix deposit command was not able to insert as many atoms as +needed. The requested volume fraction may be too high, or other atoms +may be in the insertion region. :dd + +{Proc sub-domain size < neighbor skin, could lead to lost atoms} :dt + +The decomposition of the physical domain (likely due to load +balancing) has led to a processor's sub-domain being smaller than the +neighbor skin in one or more dimensions. Since reneighboring is +triggered by atoms moving the skin distance, this may lead to lost +atoms, if an atom moves all the way across a neighboring processor's +sub-domain before reneighboring is triggered. :dd + +{Reducing PPPM order b/c stencil extends beyond nearest neighbor processor} :dt + +This may lead to a larger grid than desired. See the kspace_modify overlap +command to prevent changing of the PPPM order. :dd + +{Reducing PPPMDisp Coulomb order b/c stencil extends beyond neighbor processor} :dt + +This may lead to a larger grid than desired. See the kspace_modify overlap +command to prevent changing of the PPPM order. :dd + +{Reducing PPPMDisp dispersion order b/c stencil extends beyond neighbor processor} :dt + +This may lead to a larger grid than desired. See the kspace_modify overlap +command to prevent changing of the PPPM order. :dd + +{Replacing a fix, but new group != old group} :dt + +The ID and style of a fix match for a fix you are changing with a fix +command, but the new group you are specifying does not match the old +group. :dd + +{Replicating in a non-periodic dimension} :dt + +The parameters for a replicate command will cause a non-periodic +dimension to be replicated; this may cause unwanted behavior. :dd + +{Resetting reneighboring criteria during PRD} :dt + +A PRD simulation requires that neigh_modify settings be delay = 0, +every = 1, check = yes. Since these settings were not in place, +LAMMPS changed them and will restore them to their original values +after the PRD simulation. :dd + +{Resetting reneighboring criteria during TAD} :dt + +A TAD simulation requires that neigh_modify settings be delay = 0, +every = 1, check = yes. Since these settings were not in place, +LAMMPS changed them and will restore them to their original values +after the PRD simulation. :dd + +{Resetting reneighboring criteria during minimization} :dt + +Minimization requires that neigh_modify settings be delay = 0, every = +1, check = yes. Since these settings were not in place, LAMMPS +changed them and will restore them to their original values after the +minimization. :dd + +{Restart file used different # of processors} :dt + +The restart file was written out by a LAMMPS simulation running on a +different number of processors. Due to round-off, the trajectories of +your restarted simulation may diverge a little more quickly than if +you ran on the same # of processors. :dd + +{Restart file used different 3d processor grid} :dt + +The restart file was written out by a LAMMPS simulation running on a +different 3d grid of processors. Due to round-off, the trajectories +of your restarted simulation may diverge a little more quickly than if +you ran on the same # of processors. :dd + +{Restart file used different boundary settings, using restart file values} :dt + +Your input script cannot change these restart file settings. :dd + +{Restart file used different newton bond setting, using restart file value} :dt + +The restart file value will override the setting in the input script. :dd + +{Restart file used different newton pair setting, using input script value} :dt + +The input script value will override the setting in the restart file. :dd + +{Restrain problem: %d %ld %d %d %d %d} :dt + +Conformation of the 4 listed dihedral atoms is extreme; you may want +to check your simulation geometry. :dd + +{Running PRD with only one replica} :dt + +This is allowed, but you will get no parallel speed-up. :dd + +{SRD bin shifting turned on due to small lamda} :dt + +This is done to try to preserve accuracy. :dd + +{SRD bin size for fix srd differs from user request} :dt + +Fix SRD had to adjust the bin size to fit the simulation box. See the +cubic keyword if you want this message to be an error vs warning. :dd + +{SRD bins for fix srd are not cubic enough} :dt + +The bin shape is not within tolerance of cubic. See the cubic +keyword if you want this message to be an error vs warning. :dd + +{SRD particle %d started inside big particle %d on step %ld bounce %d} :dt + +See the inside keyword if you want this message to be an error vs +warning. :dd + +{SRD particle %d started inside wall %d on step %ld bounce %d} :dt + +See the inside keyword if you want this message to be an error vs +warning. :dd + +{Shake determinant < 0.0} :dt + +The determinant of the quadratic equation being solved for a single +cluster specified by the fix shake command is numerically suspect. LAMMPS +will set it to 0.0 and continue. :dd + +{Shell command '%s' failed with error '%s'} :dt + +Self-explanatory. :dd + +{Shell command returned with non-zero status} :dt + +This may indicate the shell command did not operate as expected. :dd + +{Should not allow rigid bodies to bounce off relecting walls} :dt + +LAMMPS allows this, but their dynamics are not computed correctly. :dd + +{Should not use fix nve/limit with fix shake or fix rattle} :dt + +This will lead to invalid constraint forces in the SHAKE/RATTLE +computation. :dd + +{Simulations might be very slow because of large number of structure factors} :dt + +Self-explanatory. :dd + +{Slab correction not needed for MSM} :dt + +Slab correction is intended to be used with Ewald or PPPM and is not needed by MSM. :dd + +{System is not charge neutral, net charge = %g} :dt + +The total charge on all atoms on the system is not 0.0. +For some KSpace solvers this is only a warning. :dd + +{Table inner cutoff >= outer cutoff} :dt + +You specified an inner cutoff for a Coulombic table that is longer +than the global cutoff. Probably not what you wanted. :dd + +{Temperature for MSST is not for group all} :dt + +User-assigned temperature to MSST fix does not compute temperature for +all atoms. Since MSST computes a global pressure, the kinetic energy +contribution from the temperature is assumed to also be for all atoms. +Thus the pressure used by MSST could be inaccurate. :dd + +{Temperature for NPT is not for group all} :dt + +User-assigned temperature to NPT fix does not compute temperature for +all atoms. Since NPT computes a global pressure, the kinetic energy +contribution from the temperature is assumed to also be for all atoms. +Thus the pressure used by NPT could be inaccurate. :dd + +{Temperature for fix modify is not for group all} :dt + +The temperature compute is being used with a pressure calculation +which does operate on group all, so this may be inconsistent. :dd + +{Temperature for thermo pressure is not for group all} :dt + +User-assigned temperature to thermo via the thermo_modify command does +not compute temperature for all atoms. Since thermo computes a global +pressure, the kinetic energy contribution from the temperature is +assumed to also be for all atoms. Thus the pressure printed by thermo +could be inaccurate. :dd + +{The fix ave/spatial command has been replaced by the more flexible fix ave/chunk and compute chunk/atom commands -- fix ave/spatial will be removed in the summer of 2015} :dt + +Self-explanatory. :dd + +{The minimizer does not re-orient dipoles when using fix efield} :dt + +This means that only the atom coordinates will be minimized, +not the orientation of the dipoles. :dd + +{Too many common neighbors in CNA %d times} :dt + +More than the maximum # of neighbors was found multiple times. This +was unexpected. :dd + +{Too many inner timesteps in fix ttm} :dt + +Self-explanatory. :dd + +{Too many neighbors in CNA for %d atoms} :dt + +More than the maximum # of neighbors was found multiple times. This +was unexpected. :dd + +{Triclinic box skew is large} :dt + +The displacement in a skewed direction is normally required to be less +than half the box length in that dimension. E.g. the xy tilt must be +between -half and +half of the x box length. You have relaxed the +constraint using the box tilt command, but the warning means that a +LAMMPS simulation may be inefficient as a result. :dd + +{Use special bonds = 0,1,1 with bond style fene} :dt + +Most FENE models need this setting for the special_bonds command. :dd + +{Use special bonds = 0,1,1 with bond style fene/expand} :dt + +Most FENE models need this setting for the special_bonds command. :dd + +{Using a manybody potential with bonds/angles/dihedrals and special_bond exclusions} :dt + +This is likely not what you want to do. The exclusion settings will +eliminate neighbors in the neighbor list, which the manybody potential +needs to calculated its terms correctly. :dd + +{Using compute temp/deform with inconsistent fix deform remap option} :dt + +Fix nvt/sllod assumes deforming atoms have a velocity profile provided +by "remap v" or "remap none" as a fix deform option. :dd + +{Using compute temp/deform with no fix deform defined} :dt + +This is probably an error, since it makes little sense to use +compute temp/deform in this case. :dd + +{Using fix srd with box deformation but no SRD thermostat} :dt + +The deformation will heat the SRD particles so this can +be dangerous. :dd + +{Using kspace solver on system with no charge} :dt + +Self-explanatory. :dd + +{Using largest cut-off for lj/long/dipole/long long long} :dt + +Self-explanatory. :dd + +{Using largest cutoff for buck/long/coul/long} :dt + +Self-explanatory. :dd + +{Using largest cutoff for lj/long/coul/long} :dt + +Self-explanatory. :dd + +{Using largest cutoff for pair_style lj/long/tip4p/long} :dt + +Self-explanatory. :dd + +{Using package gpu without any pair style defined} :dt + +Self-explanatory. :dd + +{Using pair potential shift with pair_modify compute no} :dt + +The shift effects will thus not be computed. :dd + +{Using pair tail corrections with nonperiodic system} :dt + +This is probably a bogus thing to do, since tail corrections are +computed by integrating the density of a periodic system out to +infinity. :dd + +{Using pair tail corrections with pair_modify compute no} :dt + +The tail corrections will thus not be computed. :dd + +{pair style reax is now deprecated and will soon be retired. Users should switch to pair_style reax/c} :dt + +Self-explanatory. :dd + +:dle diff --git a/doc/src/Examples.txt b/doc/src/Examples.txt index 4935c96257..08afca8b20 100644 --- a/doc/src/Examples.txt +++ b/doc/src/Examples.txt @@ -2,12 +2,6 @@ "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_perf.html :c - - :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) diff --git a/doc/src/Manual.txt b/doc/src/Manual.txt index 18ae1c4b61..4481c911a0 100644 --- a/doc/src/Manual.txt +++ b/doc/src/Manual.txt @@ -1,5 +1,5 @@ - +< LAMMPS Users Manual @@ -118,8 +118,8 @@ it gives quick access to documentation for all LAMMPS commands. Section_perf Tools Modify - Section_python - Section_errors + Python + Errors Section_history .. toctree:: @@ -212,19 +212,8 @@ END_RST --> "Performance & scalability"_Section_perf.html :l "Auxiliary tools"_Tools.html :l "Modify & extend LAMMPS"_Modify.html :l -"Python interface"_Section_python.html :l - 11.1 "Overview of running LAMMPS from Python"_py_1 :ulb,b - 11.2 "Overview of using Python from a LAMMPS script"_py_2 :b - 11.3 "Building LAMMPS as a shared library"_py_3 :b - 11.4 "Installing the Python wrapper into Python"_py_4 :b - 11.5 "Extending Python with MPI to run in parallel"_py_5 :b - 11.6 "Testing the Python-LAMMPS interface"_py_6 :b - 11.7 "Using LAMMPS from Python"_py_7 :b - 11.8 "Example Python scripts that use LAMMPS"_py_8 :ule,b -"Errors"_Section_errors.html :l - 12.1 "Common problems"_err_1 :ulb,b - 12.2 "Reporting bugs"_err_2 :b - 12.3 "Error & warning messages"_err_3 :ule,b +"Use Python with LAMMPS"_Python.html :l +"Errors"_Errors.html :l "Future and history"_Section_history.html :l 13.1 "Coming attractions"_hist_1 :ulb,b 13.2 "Past versions"_hist_2 :ule,b @@ -287,17 +276,6 @@ END_RST --> :link(howto_26,Section_howto.html#howto_26) :link(howto_27,Section_howto.html#howto_27) -:link(py_1,Section_python.html#py_1) -:link(py_2,Section_python.html#py_2) -:link(py_3,Section_python.html#py_3) -:link(py_4,Section_python.html#py_4) -:link(py_5,Section_python.html#py_5) -:link(py_6,Section_python.html#py_6) - -:link(err_1,Section_errors.html#err_1) -:link(err_2,Section_errors.html#err_2) -:link(err_3,Section_errors.html#err_3) - :link(hist_1,Section_history.html#hist_1) :link(hist_2,Section_history.html#hist_2) diff --git a/doc/src/Modify.txt b/doc/src/Modify.txt index 4b16ad781b..ae0b0dc6bd 100644 --- a/doc/src/Modify.txt +++ b/doc/src/Modify.txt @@ -1,12 +1,6 @@ "Previous Section"_Tools.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next -Section"_Section_python.html :c - - +Section"_Python.html :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) @@ -34,6 +28,8 @@ contribute"_Modify_contribute.html doc page. Modify_overview Modify_contribute +.. toctree:: + Modify_atom Modify_pair Modify_bond @@ -41,12 +37,16 @@ contribute"_Modify_contribute.html doc page. Modify_fix Modify_command +.. toctree:: + Modify_dump Modify_kspace Modify_min Modify_region Modify_body +.. toctree:: + Modify_thermo Modify_variable diff --git a/doc/src/Python.txt b/doc/src/Python.txt new file mode 100644 index 0000000000..94a2e88f5e --- /dev/null +++ b/doc/src/Python.txt @@ -0,0 +1,79 @@ +"Previous Section"_Modify.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next +Section"_Errors.html :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Section_commands.html#comm) + +:line + +Use Python with LAMMPS :h3 + +These doc pages describe various ways that LAMMPS and Python can be +used together. + + + + + +"Overview of Python and LAMMPS"_Python_overview.html :all(b) + +"Run LAMMPS from Python"_Python_run.html +"Build LAMMPS as a shared library"_Python_shlib.html +"Install LAMMPS in Python"_Python_install.html +"Extend Python to run in parallel"_Python_mpi.html +"Test the Python/LAMMPS interface"_Python_test.html +"Python library interface"_Python_library.html +"PyLammps interface"_Python_pylammps.html +"Example Python scripts that use LAMMPS"_Python_examples.html :all(b) + +"Call Python from a LAMMPS input script"_Python_call.html :all(b) + + + +If you're not familiar with "Python"_http://www.python.org, it's a +powerful scripting and programming language which can do most +everything that lower-level languages like C or C++ can do in fewer +lines of code. The only drawback is slower execution speed. Python +is also easy to use as a "glue" language to drive a program through +its library interface, or to hook multiple pieces of software +together, such as a simulation code plus a visualization tool, or to +run a coupled multiscale or multiphysics model. + +See the "Howto_couple"_Howto_couple.html doc page for more ideas about +coupling LAMMPS to other codes. See the "Howto +library"_Howto_library.html doc page for a description of the LAMMPS +library interface provided in src/library.h and src/library.h. That +interface is exposed to Python either when calling LAMMPS from Python +or when calling Python from a LAMMPS input script and then calling +back to LAMMPS from Python code. The library interface is designed to +be easy to add funcionality to. Thus the Python interface to LAMMPS +is also easy to extend as well. + +If you create interesting Python scripts that run LAMMPS or +interesting Python functions that can be called from a LAMMPS input +script, that you think would be genearlly useful, please post them as +a pull request to our "GitHub site"_https://github.com/lammps/lammps, +and they can be added to the LAMMPS distribution or webpage. diff --git a/doc/src/Python_call.txt b/doc/src/Python_call.txt new file mode 100644 index 0000000000..3e30a5a7c7 --- /dev/null +++ b/doc/src/Python_call.txt @@ -0,0 +1,85 @@ +"Higher level section"_Python.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 + +Call Python from a LAMMPS input script :h3 + +LAMMPS has several commands which can be used to invoke Python +code directly from an input script: + +"python"_python.html +"variable python"_variable.html +"fix python/invoke"_fix_python_invoke.html +"pair_style python"_pair_python.html :ul + +The "python"_python.html command which can be used to define and +execute a Python function that you write the code for. The Python +function can also be assigned to a LAMMPS python-style variable via +the "variable"_variable.html command. Each time the variable is +evaluated, either in the LAMMPS input script itself, or by another +LAMMPS command that uses the variable, this will trigger the Python +function to be invoked. + +The Python code for the function can be included directly in the input +script or in an auxiliary file. The function can have arguments which +are mapped to LAMMPS variables (also defined in the input script) and +it can return a value to a LAMMPS variable. This is thus a mechanism +for your input script to pass information to a piece of Python code, +ask Python to execute the code, and return information to your input +script. + +Note that a Python function can be arbitrarily complex. It can import +other Python modules, instantiate Python classes, call other Python +functions, etc. The Python code that you provide can contain more +code than the single function. It can contain other functions or +Python classes, as well as global variables or other mechanisms for +storing state between calls from LAMMPS to the function. + +The Python function you provide can consist of "pure" Python code that +only performs operations provided by standard Python. However, the +Python function can also "call back" to LAMMPS through its +Python-wrapped library interface, in the manner described in the +"Python run"_Python_run.html doc page. This means it can issue LAMMPS +input script commands or query and set internal LAMMPS state. As an +example, this can be useful in an input script to create a more +complex loop with branching logic, than can be created using the +simple looping and branching logic enabled by the "next"_next.html and +"if"_if.html commands. + +See the "python"_python.html doc page and the "variable"_variable.html +doc page for its python-style variables for more info, including +examples of Python code you can write for both pure Python operations +and callbacks to LAMMPS. + +The "fix python/invoke"_fix_python_invoke.html command can execute +Python code at selected timesteps during a simulation run. + +The "pair_style python"_pair_python command allows you to define +pairwise potentials as python code which encodes a single pairwise +interaction. This is useful for rapid-developement and debugging of a +new potential. + +To use any of these commands, you only need to build LAMMPS with the +PYTHON package installed: + +make yes-python +make machine :pre + +Note that this will link LAMMPS with the Python library on your +system, which typically requires several auxiliary system libraries to +also be linked. The list of these libraries and the paths to find +them are specified in the lib/python/Makefile.lammps file. You need +to insure that file contains the correct information for your version +of Python and your machine to successfully build LAMMPS. See the +lib/python/README file for more info. + +If you want to write Python code with callbacks to LAMMPS, then you +must also follow the steps overviewed in the "Python +run"_Python_run.html doc page. I.e. you must build LAMMPS as a shared +library and insure that Python can find the python/lammps.py file and +the shared library. diff --git a/doc/src/Python_examples.txt b/doc/src/Python_examples.txt new file mode 100644 index 0000000000..fbca381e8b --- /dev/null +++ b/doc/src/Python_examples.txt @@ -0,0 +1,81 @@ +"Higher level section"_Python.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 + +Example Python scripts that use LAMMPS :h3 + +These are the Python scripts included as demos in the python/examples +directory of the LAMMPS distribution, to illustrate the kinds of +things that are possible when Python wraps LAMMPS. If you create your +own scripts, send them to us and we can include them in the LAMMPS +distribution. + +trivial.py, read/run a LAMMPS input script thru Python, +demo.py, invoke various LAMMPS library interface routines, +simple.py, run in parallel, similar to examples/COUPLE/simple/simple.cpp, +split.py, same as simple.py but running in parallel on a subset of procs, +gui.py, GUI go/stop/temperature-slider to control LAMMPS, +plot.py, real-time temperature plot with GnuPlot via Pizza.py, +viz_tool.py, real-time viz via some viz package, +vizplotgui_tool.py, combination of viz_tool.py and plot.py and gui.py :tb(c=2) + +:line + +For the viz_tool.py and vizplotgui_tool.py commands, replace "tool" +with "gl" or "atomeye" or "pymol" or "vmd", depending on what +visualization package you have installed. + +Note that for GL, you need to be able to run the Pizza.py GL tool, +which is included in the pizza sub-directory. See the "Pizza.py doc +pages"_pizza for more info: + +:link(pizza,http://www.sandia.gov/~sjplimp/pizza.html) + +Note that for AtomEye, you need version 3, and there is a line in the +scripts that specifies the path and name of the executable. See the +AtomEye WWW pages "here"_atomeye or "here"_atomeye3 for more details: + +http://mt.seas.upenn.edu/Archive/Graphics/A +http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html :pre + +:link(atomeye,http://mt.seas.upenn.edu/Archive/Graphics/A) +:link(atomeye3,http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html) + +The latter link is to AtomEye 3 which has the scriping +capability needed by these Python scripts. + +Note that for PyMol, you need to have built and installed the +open-source version of PyMol in your Python, so that you can import it +from a Python script. See the PyMol WWW pages "here"_pymolhome or +"here"_pymolopen for more details: + +http://www.pymol.org +http://sourceforge.net/scm/?type=svn&group_id=4546 :pre + +:link(pymolhome,http://www.pymol.org) +:link(pymolopen,http://sourceforge.net/scm/?type=svn&group_id=4546) + +The latter link is to the open-source version. + +Note that for VMD, you need a fairly current version (1.8.7 works for +me) and there are some lines in the pizza/vmd.py script for 4 PIZZA +variables that have to match the VMD installation on your system. + +:line + +See the python/README file for instructions on how to run them and the +source code for individual scripts for comments about what they do. + +Here are screenshots of the vizplotgui_tool.py script in action for +different visualization package options. Click to see larger images: + +:image(JPG/screenshot_gl_small.jpg,JPG/screenshot_gl.jpg) +:image(JPG/screenshot_atomeye_small.jpg,JPG/screenshot_atomeye.jpg) +:image(JPG/screenshot_pymol_small.jpg,JPG/screenshot_pymol.jpg) +:image(JPG/screenshot_vmd_small.jpg,JPG/screenshot_vmd.jpg) + diff --git a/doc/src/Python_install.txt b/doc/src/Python_install.txt new file mode 100644 index 0000000000..631f6c4a7f --- /dev/null +++ b/doc/src/Python_install.txt @@ -0,0 +1,74 @@ +"Higher level section"_Python.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 + +Installing LAMMPS in Python :h3 + +For Python to invoke LAMMPS, there are 2 files it needs to know about: + +python/lammps.py +src/liblammps.so :ul + +Lammps.py is the Python wrapper on the LAMMPS library interface. +Liblammps.so is the shared LAMMPS library that Python loads, as +described above. + +You can insure Python can find these files in one of two ways: + +set two environment variables +run the python/install.py script :ul + +If you set the paths to these files as environment variables, you only +have to do it once. For the csh or tcsh shells, add something like +this to your ~/.cshrc file, one line for each of the two files: + +setenv PYTHONPATH $\{PYTHONPATH\}:/home/sjplimp/lammps/python +setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre + +If you use the python/install.py script, you need to invoke it every +time you rebuild LAMMPS (as a shared library) or make changes to the +python/lammps.py file. + +You can invoke install.py from the python directory as + +% python install.py \[libdir\] \[pydir\] :pre + +The optional libdir is where to copy the LAMMPS shared library to; the +default is /usr/local/lib. The optional pydir is where to copy the +lammps.py file to; the default is the site-packages directory of the +version of Python that is running the install script. + +Note that libdir must be a location that is in your default +LD_LIBRARY_PATH, like /usr/local/lib or /usr/lib. And pydir must be a +location that Python looks in by default for imported modules, like +its site-packages dir. If you want to copy these files to +non-standard locations, such as within your own user space, you will +need to set your PYTHONPATH and LD_LIBRARY_PATH environment variables +accordingly, as above. + +If the install.py script does not allow you to copy files into system +directories, prefix the python command with "sudo". If you do this, +make sure that the Python that root runs is the same as the Python you +run. E.g. you may need to do something like + +% sudo /usr/local/bin/python install.py \[libdir\] \[pydir\] :pre + +You can also invoke install.py from the make command in the src +directory as + +% make install-python :pre + +In this mode you cannot append optional arguments. Again, you may +need to prefix this with "sudo". In this mode you cannot control +which Python is invoked by root. + +Note that if you want Python to be able to load different versions of +the LAMMPS shared library (see "this section"_#py_5 below), you will +need to manually copy files like liblammps_g++.so into the appropriate +system directory. This is not needed if you set the LD_LIBRARY_PATH +environment variable as described above. diff --git a/doc/src/Python_library.txt b/doc/src/Python_library.txt new file mode 100644 index 0000000000..4babbb746c --- /dev/null +++ b/doc/src/Python_library.txt @@ -0,0 +1,256 @@ +"Higher level section"_Python.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 + +Python library interface :h3 + +As described previously, the Python interface to LAMMPS consists of a +Python "lammps" module, the source code for which is in +python/lammps.py, which creates a "lammps" object, with a set of +methods that can be invoked on that object. The sample Python code +below assumes you have first imported the "lammps" module in your +Python script, as follows: + +from lammps import lammps :pre + +These are the methods defined by the lammps module. If you look at +the files src/library.cpp and src/library.h you will see they +correspond one-to-one with calls you can make to the LAMMPS library +from a C++ or C or Fortran program, and which are described in +"Section 6.19"_Section_howto.html#howto_19 of the manual. + +The python/examples directory has Python scripts which show how Python +can run LAMMPS, grab data, change it, and put it back into LAMMPS. + +lmp = lammps() # create a LAMMPS object using the default liblammps.so library + # 4 optional args are allowed: name, cmdargs, ptr, comm +lmp = lammps(ptr=lmpptr) # use lmpptr as previously created LAMMPS object +lmp = lammps(comm=split) # create a LAMMPS object with a custom communicator, requires mpi4py 2.0.0 or later +lmp = lammps(name="g++") # create a LAMMPS object using the liblammps_g++.so library +lmp = lammps(name="g++",cmdargs=list) # add LAMMPS command-line args, e.g. list = \["-echo","screen"\] :pre + +lmp.close() # destroy a LAMMPS object :pre + +version = lmp.version() # return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902 :pre + +lmp.file(file) # run an entire input script, file = "in.lj" +lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100" +lmp.commands_list(cmdlist) # invoke commands in cmdlist = ["run 10", "run 20"] +lmp.commands_string(multicmd) # invoke commands in multicmd = "run 10\nrun 20" :pre + +size = lmp.extract_setting(name) # return data type info :pre + +xlo = lmp.extract_global(name,type) # extract a global quantity + # name = "boxxlo", "nlocal", etc + # type = 0 = int + # 1 = double :pre + +boxlo,boxhi,xy,yz,xz,periodicity,box_change = lmp.extract_box() # extract box info :pre + +coords = lmp.extract_atom(name,type) # extract a per-atom quantity + # name = "x", "type", etc + # type = 0 = vector of ints + # 1 = array of ints + # 2 = vector of doubles + # 3 = array of doubles :pre + +eng = lmp.extract_compute(id,style,type) # extract value(s) from a compute +v3 = lmp.extract_fix(id,style,type,i,j) # extract value(s) from a fix + # id = ID of compute or fix + # style = 0 = global data + # 1 = per-atom data + # 2 = local data + # type = 0 = scalar + # 1 = vector + # 2 = array + # i,j = indices of value in global vector or array :pre + +var = lmp.extract_variable(name,group,flag) # extract value(s) from a variable + # name = name of variable + # group = group ID (ignored for equal-style variables) + # flag = 0 = equal-style variable + # 1 = atom-style variable :pre + +value = lmp.get_thermo(name) # return current value of a thermo keyword +natoms = lmp.get_natoms() # total # of atoms as int :pre + +flag = lmp.set_variable(name,value) # set existing named string-style variable to value, flag = 0 if successful +lmp.reset_box(boxlo,boxhi,xy,yz,xz) # reset the simulation box size :pre + +data = lmp.gather_atoms(name,type,count) # return per-atom property of all atoms gathered into data, ordered by atom ID + # name = "x", "charge", "type", etc +data = lmp.gather_atoms_concat(name,type,count) # ditto, but concatenated atom values from each proc (unordered) +data = lmp.gather_atoms_subset(name,type,count,ndata,ids) # ditto, but for subset of Ndata atoms with IDs :pre + +lmp.scatter_atoms(name,type,count,data) # scatter per-atom property to all atoms from data, ordered by atom ID + # name = "x", "charge", "type", etc + # count = # of per-atom values, 1 or 3, etc :pre +lmp.scatter_atoms_subset(name,type,count,ndata,ids,data) # ditto, but for subset of Ndata atoms with IDs :pre + +lmp.create_atoms(n,ids,types,x,v,image,shrinkexceed) # create N atoms with IDs, types, x, v, and image flags :pre + +:line + +The lines + +from lammps import lammps +lmp = lammps() :pre + +create an instance of LAMMPS, wrapped in a Python class by the lammps +Python module, and return an instance of the Python class as lmp. It +is used to make all subsequent calls to the LAMMPS library. + +Additional arguments to lammps() can be used to tell Python the name +of the shared library to load or to pass arguments to the LAMMPS +instance, the same as if LAMMPS were launched from a command-line +prompt. + +If the ptr argument is set like this: + +lmp = lammps(ptr=lmpptr) :pre + +then lmpptr must be an argument passed to Python via the LAMMPS +"python"_python.html command, when it is used to define a Python +function that is invoked by the LAMMPS input script. This mode of +calling Python from LAMMPS is described in the "Python +call"_Python_call.html doc page. The variable lmpptr refers to the +instance of LAMMPS that called the embedded Python interpreter. Using +it as an argument to lammps() allows the returned Python class +instance "lmp" to make calls to that instance of LAMMPS. See the +"python"_python.html command doc page for examples using this syntax. + +Note that you can create multiple LAMMPS objects in your Python +script, and coordinate and run multiple simulations, e.g. + +from lammps import lammps +lmp1 = lammps() +lmp2 = lammps() +lmp1.file("in.file1") +lmp2.file("in.file2") :pre + +The file(), command(), commands_list(), commands_string() methods +allow an input script, a single command, or multiple commands to be +invoked. + +The extract_setting(), extract_global(), extract_box(), +extract_atom(), extract_compute(), extract_fix(), and +extract_variable() methods return values or pointers to data +structures internal to LAMMPS. + +For extract_global() see the src/library.cpp file for the list of +valid names. New names could easily be added. A double or integer is +returned. You need to specify the appropriate data type via the type +argument. + +For extract_atom(), a pointer to internal LAMMPS atom-based data is +returned, which you can use via normal Python subscripting. See the +extract() method in the src/atom.cpp file for a list of valid names. +Again, new names could easily be added if the property you want is not +listed. A pointer to a vector of doubles or integers, or a pointer to +an array of doubles (double **) or integers (int **) is returned. You +need to specify the appropriate data type via the type argument. + +For extract_compute() and extract_fix(), the global, per-atom, or +local data calculated by the compute or fix can be accessed. What is +returned depends on whether the compute or fix calculates a scalar or +vector or array. For a scalar, a single double value is returned. If +the compute or fix calculates a vector or array, a pointer to the +internal LAMMPS data is returned, which you can use via normal Python +subscripting. The one exception is that for a fix that calculates a +global vector or array, a single double value from the vector or array +is returned, indexed by I (vector) or I and J (array). I,J are +zero-based indices. The I,J arguments can be left out if not needed. +See "Section 6.15"_Section_howto.html#howto_15 of the manual for a +discussion of global, per-atom, and local data, and of scalar, vector, +and array data types. See the doc pages for individual +"computes"_compute.html and "fixes"_fix.html for a description of what +they calculate and store. + +For extract_variable(), an "equal-style or atom-style +variable"_variable.html is evaluated and its result returned. + +For equal-style variables a single double value is returned and the +group argument is ignored. For atom-style variables, a vector of +doubles is returned, one value per atom, which you can use via normal +Python subscripting. The values will be zero for atoms not in the +specified group. + +The get_thermo() method returns returns the current value of a thermo +keyword as a float. + +The get_natoms() method returns the total number of atoms in the +simulation, as an int. + +The set_variable() methosd sets an existing string-style variable to a +new string value, so that subsequent LAMMPS commands can access the +variable. + +The reset_box() emthods resets the size and shape of the simulation +box, e.g. as part of restoring a previously extracted and saved state +of a simulation. + +The gather methods collect peratom info of the requested type (atom +coords, atom types, forces, etc) from all processors, and returns the +same vector of values to each callling processor. The scatter +functions do the inverse. They distribute a vector of peratom values, +passed by all calling processors, to invididual atoms, which may be +owned by different processos. + +Note that the data returned by the gather methods, +e.g. gather_atoms("x"), is different from the data structure returned +by extract_atom("x") in four ways. (1) Gather_atoms() returns a +vector which you index as x\[i\]; extract_atom() returns an array +which you index as x\[i\]\[j\]. (2) Gather_atoms() orders the atoms +by atom ID while extract_atom() does not. (3) Gather_atoms() returns +a list of all atoms in the simulation; extract_atoms() returns just +the atoms local to each processor. (4) Finally, the gather_atoms() +data structure is a copy of the atom coords stored internally in +LAMMPS, whereas extract_atom() returns an array that effectively +points directly to the internal data. This means you can change +values inside LAMMPS from Python by assigning a new values to the +extract_atom() array. To do this with the gather_atoms() vector, you +need to change values in the vector, then invoke the scatter_atoms() +method. + +For the scatter methods, the array of coordinates passed to must be a +ctypes vector of ints or doubles, allocated and initialized something +like this: + +from ctypes import * +natoms = lmp.get_natoms() +n3 = 3*natoms +x = (n3*c_double)() +x\[0\] = x coord of atom with ID 1 +x\[1\] = y coord of atom with ID 1 +x\[2\] = z coord of atom with ID 1 +x\[3\] = x coord of atom with ID 2 +... +x\[n3-1\] = z coord of atom with ID natoms +lmp.scatter_atoms("x",1,3,x) :pre + +Alternatively, you can just change values in the vector returned by +the gather methods, since they are also ctypes vectors. + +:line + +As noted above, these Python class methods correspond one-to-one with +the functions in the LAMMPS library interface in src/library.cpp and +library.h. This means you can extend the Python wrapper via the +following steps: + +Add a new interface function to src/library.cpp and +src/library.h. :ulb,l + +Rebuild LAMMPS as a shared library. :l + +Add a wrapper method to python/lammps.py for this interface +function. :l + +You should now be able to invoke the new interface function from a +Python script. :l +:ule diff --git a/doc/src/Python_mpi.txt b/doc/src/Python_mpi.txt new file mode 100644 index 0000000000..8377bbb3d0 --- /dev/null +++ b/doc/src/Python_mpi.txt @@ -0,0 +1,67 @@ +"Higher level section"_Python.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 + +Extending Python to run in parallel :h3 + +If you wish to run LAMMPS in parallel from Python, you need to extend +your Python with an interface to MPI. This also allows you to +make MPI calls directly from Python in your script, if you desire. + +We recommend use of mpi4py: + +"PyPar"_https://github.com/daleroberts/pypar :ul + +As of version 2.0.0 it allows passing a custom MPI communicator to +the LAMMPS constructor, which means one can easily run one or more +LAMMPS instances on subsets of the total MPI ranks. + +To install mpi4py (version mpi4py-2.0.0 as of Oct 2015), unpack it +and from its main directory, type + +python setup.py build +sudo python setup.py install :pre + +Again, the "sudo" is only needed if required to copy mpi4py files into +your Python distribution's site-packages directory. To install with +user privilege into the user local directory type + +python setup.py install --user :pre + +If you have successfully installed mpi4py, you should be able to run +Python and type + +from mpi4py import MPI :pre + +without error. You should also be able to run python in parallel +on a simple test script + +% mpirun -np 4 python test.py :pre + +where test.py contains the lines + +from mpi4py import MPI +comm = MPI.COMM_WORLD +print "Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size()) :pre + +and see one line of output for each processor you run on. + +NOTE: To use mpi4py and LAMMPS in parallel from Python, you must +insure both are using the same version of MPI. If you only have one +MPI installed on your system, this is not an issue, but it can be if +you have multiple MPIs. Your LAMMPS build is explicit about which MPI +it is using, since you specify the details in your lo-level +src/MAKE/Makefile.foo file. Mpi4py uses the "mpicc" command to find +information about the MPI it uses to build against. And it tries to +load "libmpi.so" from the LD_LIBRARY_PATH. This may or may not find +the MPI library that LAMMPS is using. If you have problems running +both mpi4py and LAMMPS together, this is an issue you may need to +address, e.g. by moving other MPI installations so that mpi4py finds +the right one. + + diff --git a/doc/src/Python_overview.txt b/doc/src/Python_overview.txt new file mode 100644 index 0000000000..a5d6a469ff --- /dev/null +++ b/doc/src/Python_overview.txt @@ -0,0 +1,35 @@ +"Previous Section"_Examples.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next +Section"_Tools.html :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands.html#comm) + +:line + +Overview of Python and LAMMPS :h3 + +LAMMPS can work together with Python in three ways. First, Python can +wrap LAMMPS through the its "library interface"_Howto_library.html, so +that a Python script can create one or more instances of LAMMPS and +launch one or more simulations. In Python lingo, this is "extending" +Python with LAMMPS. + +Second, a lower-level Python interface can be used indirectly through +provided PyLammps and IPyLammps wrapper classes, written in Python. +These wrappers try to simplify the usage of LAMMPS in Python by +providing an object-based interface to common LAMMPS functionality. +They also reduces the amount of code necessary to parameterize LAMMPS +scripts through Python and make variables and computes directly +accessible. + +Third, LAMMPS can use the Python interpreter, so that a LAMMPS +input script can invoke Python code directly, and pass information +back-and-forth between the input script and Python functions you +write. This Python code can also callback to LAMMPS to query or change +its attributes. In Python lingo, this is "embedding" Python in +LAMMPS. When used in this mode, Python can perform operations that +the simple LAMMPS input script syntax cannot. + + diff --git a/doc/src/Python_pylammps.txt b/doc/src/Python_pylammps.txt new file mode 100644 index 0000000000..ad5ed192ee --- /dev/null +++ b/doc/src/Python_pylammps.txt @@ -0,0 +1,14 @@ +"Higher level section"_Python.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 + +PyLammps interface :h3 + +PyLammps is a Python wrapper class which can be created on its own or +use an existing lammps Python object. It has its own "PyLammps +Tutorial"_tutorial_pylammps.html doc page. diff --git a/doc/src/Python_run.txt b/doc/src/Python_run.txt new file mode 100644 index 0000000000..03ab2ed3d7 --- /dev/null +++ b/doc/src/Python_run.txt @@ -0,0 +1,40 @@ +"Higher level section"_Python.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 + +Run LAMMPS from Python :h3 + +The LAMMPS distribution includes a python directory with all you need +to run LAMMPS from Python. The python/lammps.py file wraps the LAMMPS +library interface, with one wrapper function per LAMMPS library +function. This file makes it is possible to do the following either +from a Python script, or interactively from a Python prompt: create +one or more instances of LAMMPS, invoke LAMMPS commands or give it an +input script, run LAMMPS incrementally, extract LAMMPS results, an +modify internal LAMMPS variables. From a Python script you can do +this in serial or parallel. Running Python interactively in parallel +does not generally work, unless you have a version of Python that +extends Python to enable multiple instances of Python to read what you +type. + +To do all of this, you must first build LAMMPS as a shared library, +then insure that your Python can find the python/lammps.py file and +the shared library. + +Two advantages of using Python to run LAMMPS are how concise the +language is, and that it can be run interactively, enabling rapid +development and debugging. If you use it to mostly invoke costly +operations within LAMMPS, such as running a simulation for a +reasonable number of timesteps, then the overhead cost of invoking +LAMMPS thru Python will be negligible. + +The Python wrapper for LAMMPS uses the "ctypes" package in Python, +which auto-generates the interface code needed between Python and a +set of C-style library functions. Ctypes is part of standard Python +for versions 2.5 and later. You can check which version of Python you +have by simply typing "python" at a shell prompt. diff --git a/doc/src/Python_shlib.txt b/doc/src/Python_shlib.txt new file mode 100644 index 0000000000..1aafbe2e84 --- /dev/null +++ b/doc/src/Python_shlib.txt @@ -0,0 +1,34 @@ +"Higher level section"_Python.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 + +Build LAMMPS as a shared library :h3 + +Instructions on how to build LAMMPS as a shared library are given in +"Section 2.4"_Section_start.html#start_4. A shared library is one +that is dynamically loadable, which is what Python requires to wrap +LAMMPS. On Linux this is a library file that ends in ".so", not ".a". + +From the src directory, type + +make foo mode=shlib :pre + +where foo is the machine target name, such as mpi or serial. +This should create the file liblammps_foo.so in the src directory, as +well as a soft link liblammps.so, which is what the Python wrapper will +load by default. Note that if you are building multiple machine +versions of the shared library, the soft link is always set to the +most recently built version. + +NOTE: If you are building LAMMPS with an MPI or FFT library or other +auxiliary libraries (used by various packages), then all of these +extra libraries must also be shared libraries. If the LAMMPS +shared-library build fails with an error complaining about this, see +"Section 2.4"_Section_start.html#start_4 for more details. + +Also include CMake info on this diff --git a/doc/src/Python_test.txt b/doc/src/Python_test.txt new file mode 100644 index 0000000000..5f361a500b --- /dev/null +++ b/doc/src/Python_test.txt @@ -0,0 +1,131 @@ +"Higher level section"_Python.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 + +Test the Python/LAMMPS interface :h3 + +To test if LAMMPS is callable from Python, launch Python interactively +and type: + +>>> from lammps import lammps +>>> lmp = lammps() :pre + +If you get no errors, you're ready to use LAMMPS from Python. If the +2nd command fails, the most common error to see is + +OSError: Could not load LAMMPS dynamic library :pre + +which means Python was unable to load the LAMMPS shared library. This +typically occurs if the system can't find the LAMMPS shared library or +one of the auxiliary shared libraries it depends on, or if something +about the library is incompatible with your Python. The error message +should give you an indication of what went wrong. + +You can also test the load directly in Python as follows, without +first importing from the lammps.py file: + +>>> from ctypes import CDLL +>>> CDLL("liblammps.so") :pre + +If an error occurs, carefully go thru the steps in "Section +2.4"_Section_start.html#start_4 and above about building a shared +library and about insuring Python can find the necessary two files +it needs. + +[Test LAMMPS and Python in serial:] :h4 + +To run a LAMMPS test in serial, type these lines into Python +interactively from the bench directory: + +>>> from lammps import lammps +>>> lmp = lammps() +>>> lmp.file("in.lj") :pre + +Or put the same lines in the file test.py and run it as + +% python test.py :pre + +Either way, you should see the results of running the in.lj benchmark +on a single processor appear on the screen, the same as if you had +typed something like: + +lmp_g++ -in in.lj :pre + +[Test LAMMPS and Python in parallel:] :h4 + +To run LAMMPS in parallel, assuming you have installed the +"PyPar"_https://github.com/daleroberts/pypar package as discussed +above, create a test.py file containing these lines: + +import pypar +from lammps import lammps +lmp = lammps() +lmp.file("in.lj") +print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp +pypar.finalize() :pre + +To run LAMMPS in parallel, assuming you have installed the +"mpi4py"_https://bitbucket.org/mpi4py/mpi4py package as discussed +above, create a test.py file containing these lines: + +from mpi4py import MPI +from lammps import lammps +lmp = lammps() +lmp.file("in.lj") +me = MPI.COMM_WORLD.Get_rank() +nprocs = MPI.COMM_WORLD.Get_size() +print "Proc %d out of %d procs has" % (me,nprocs),lmp +MPI.Finalize() :pre + +You can either script in parallel as: + +% mpirun -np 4 python test.py :pre + +and you should see the same output as if you had typed + +% mpirun -np 4 lmp_g++ -in in.lj :pre + +Note that if you leave out the 3 lines from test.py that specify PyPar +commands you will instantiate and run LAMMPS independently on each of +the P processors specified in the mpirun command. In this case you +should get 4 sets of output, each showing that a LAMMPS run was made +on a single processor, instead of one set of output showing that +LAMMPS ran on 4 processors. If the 1-processor outputs occur, it +means that PyPar is not working correctly. + +Also note that once you import the PyPar module, PyPar initializes MPI +for you, and you can use MPI calls directly in your Python script, as +described in the PyPar documentation. The last line of your Python +script should be pypar.finalize(), to insure MPI is shut down +correctly. + +[Running Python scripts:] :h4 + +Note that any Python script (not just for LAMMPS) can be invoked in +one of several ways: + +% python foo.script +% python -i foo.script +% foo.script :pre + +The last command requires that the first line of the script be +something like this: + +#!/usr/local/bin/python +#!/usr/local/bin/python -i :pre + +where the path points to where you have Python installed, and that you +have made the script file executable: + +% chmod +x foo.script :pre + +Without the "-i" flag, Python will exit when the script finishes. +With the "-i" flag, you will be left in the Python interpreter when +the script finishes, so you can type subsequent commands. As +mentioned above, you can only run Python interactively when running +Python on a single processor, not in parallel. diff --git a/doc/src/Section_commands.txt b/doc/src/Section_commands.txt index a44013f5f1..7b9349a233 100644 --- a/doc/src/Section_commands.txt +++ b/doc/src/Section_commands.txt @@ -67,7 +67,7 @@ values are not desired, the "processors"_processors.html and tell LAMMPS how to map processors to the simulation box. Many input script errors are detected by LAMMPS and an ERROR or -WARNING message is printed. "This section"_Section_errors.html gives +WARNING message is printed. The "Errors"_Errors.html doc page gives more information on what errors mean. The documentation for each command lists restrictions on how the command can be used. diff --git a/doc/src/Section_history.txt b/doc/src/Section_history.txt index 7b90410628..6bbd1e4d99 100644 --- a/doc/src/Section_history.txt +++ b/doc/src/Section_history.txt @@ -1,4 +1,4 @@ -"Previous Section"_Section_errors.html - "LAMMPS WWW Site"_lws - +"Previous Section"_Errors.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Manual.html :c diff --git a/doc/src/Section_howto.txt b/doc/src/Section_howto.txt index 0a31fc2b48..3c5fe47057 100644 --- a/doc/src/Section_howto.txt +++ b/doc/src/Section_howto.txt @@ -731,10 +731,10 @@ any other language that supports a vanilla C-like interface). For example, from C++ you could create one (or more) "instances" of LAMMPS, pass it an input script to process, or execute individual commands, all by invoking the correct class methods in LAMMPS. From C -or Fortran you can make function calls to do the same things. See -"Section 11"_Section_python.html of the manual for a description -of the Python wrapper provided with LAMMPS that operates through the -LAMMPS library interface. +or Fortran you can make function calls to do the same things. See the +"Python"_Python.html doc page for a description of the Python wrapper +provided with LAMMPS that operates through the LAMMPS library +interface. The files src/library.cpp and library.h contain the C-style interface to LAMMPS. See "Section 6.19"_Section_howto.html#howto_19 of the @@ -1843,10 +1843,10 @@ converge and requires careful post-processing "(Shinoda)"_#Shinoda1 6.19 Library interface to LAMMPS :link(howto_19),h4 -As described in "Section 2.5"_Section_start.html#start_5, LAMMPS -can be built as a library, so that it can be called by another code, -used in a "coupled manner"_Section_howto.html#howto_10 with other -codes, or driven through a "Python interface"_Section_python.html. +As described in "Section 2.5"_Section_start.html#start_5, LAMMPS can +be built as a library, so that it can be called by another code, used +in a "coupled manner"_Section_howto.html#howto_10 with other codes, or +driven through a "Python interface"_Python.html. All of these methodologies use a C-style interface to LAMMPS that is provided in the files src/library.cpp and src/library.h. The @@ -1869,9 +1869,9 @@ details. NOTE: You can write code for additional functions as needed to define how your code talks to LAMMPS and add them to src/library.cpp and -src/library.h, as well as to the "Python -interface"_Section_python.html. The added functions can access or -change any internal LAMMPS data you wish. +src/library.h, as well as to the "Python interface"_Python.html. The +added functions can access or change any internal LAMMPS data you +wish. void lammps_open(int, char **, MPI_Comm, void **) void lammps_open_no_mpi(int, char **, void **) diff --git a/doc/src/Section_intro.txt b/doc/src/Section_intro.txt index fa2ab0e768..c7cf5bf8d2 100644 --- a/doc/src/Section_intro.txt +++ b/doc/src/Section_intro.txt @@ -1,4 +1,6 @@ -"Previous Section"_Manual.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_start.html :c +"Previous Section"_Manual.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc - "Next +Section"_Section_start.html :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) @@ -429,7 +431,7 @@ Site"_lws, or have a suggestion for something to clarify or include, send an email to the "developers"_http://lammps.sandia.gov/authors.html. :l -If you find a bug, "Section 12.2"_Section_errors.html#err_2 +If you find a bug, the "Errors bugs"_Errors_bugs.html doc page describes how to report it. :l If you publish a paper using LAMMPS results, send the citation (and diff --git a/doc/src/Section_packages.txt b/doc/src/Section_packages.txt index 77f56d273c..340a77310d 100644 --- a/doc/src/Section_packages.txt +++ b/doc/src/Section_packages.txt @@ -1178,10 +1178,10 @@ PYTHON package :link(PYTHON),h4 A "python"_python.html command which allow you to execute Python code from a LAMMPS input script. The code can be in a separate file or -embedded in the input script itself. See "Section -11.2"_Section_python.html#py_2 for an overview of using Python from -LAMMPS in this manner and the entire section for other ways to use -LAMMPS and Python together. +embedded in the input script itself. See the "Python +call"_Python_call.html doc page for an overview of using Python from +LAMMPS in this manner and the "Python"_Python.html doc page for other +ways to use LAMMPS and Python together. [Install or un-install:] @@ -1202,7 +1202,7 @@ to Makefile.lammps) if the LAMMPS build fails. [Supporting info:] src/PYTHON: filenames -> commands -"Section 11"_Section_python.html +"Python call"_Python_call.html lib/python/README examples/python :ul diff --git a/doc/src/Section_python.txt b/doc/src/Section_python.txt deleted file mode 100644 index c9b0bd8b2e..0000000000 --- a/doc/src/Section_python.txt +++ /dev/null @@ -1,869 +0,0 @@ -"Previous Section"_Modify.html - "LAMMPS WWW Site"_lws - "LAMMPS -Documentation"_ld - "LAMMPS Commands"_lc - "Next -Section"_Section_errors.html :c - -:link(lws,http://lammps.sandia.gov) -:link(ld,Manual.html) -:link(lc,Section_commands.html#comm) - -:line - -11. Python interface to LAMMPS :h2 - -LAMMPS can work together with Python in three ways. First, Python can -wrap LAMMPS through the "LAMMPS library -interface"_Section_howto.html#howto_19, so that a Python script can -create one or more instances of LAMMPS and launch one or more -simulations. In Python lingo, this is "extending" Python with LAMMPS. - -Second, the low-level Python interface can be used indirectly through the -PyLammps and IPyLammps wrapper classes in Python. These wrappers try to -simplify the usage of LAMMPS in Python by providing an object-based interface -to common LAMMPS functionality. It also reduces the amount of code necessary to -parameterize LAMMPS scripts through Python and makes variables and computes -directly accessible. See "PyLammps interface"_#py_9 for more details. - -Third, LAMMPS can use the Python interpreter, so that a LAMMPS input -script can invoke Python code, and pass information back-and-forth -between the input script and Python functions you write. The Python -code can also callback to LAMMPS to query or change its attributes. -In Python lingo, this is "embedding" Python in LAMMPS. - -This section describes how to use these three approaches. - -11.1 "Overview of running LAMMPS from Python"_#py_1 -11.2 "Overview of using Python from a LAMMPS script"_#py_2 -11.3 "Building LAMMPS as a shared library"_#py_3 -11.4 "Installing the Python wrapper into Python"_#py_4 -11.5 "Extending Python with MPI to run in parallel"_#py_5 -11.6 "Testing the Python-LAMMPS interface"_#py_6 -11.7 "Using LAMMPS from Python"_#py_7 -11.8 "Example Python scripts that use LAMMPS"_#py_8 -11.9 "PyLammps interface"_#py_9 :ul - -If you are not familiar with it, "Python"_http://www.python.org is a -powerful scripting and programming language which can essentially do -anything that faster, lower-level languages like C or C++ can do, but -typically with much fewer lines of code. When used in embedded mode, -Python can perform operations that the simplistic LAMMPS input script -syntax cannot. Python can be also be used as a "glue" language to -drive a program through its library interface, or to hook multiple -pieces of software together, such as a simulation package plus a -visualization package, or to run a coupled multiscale or multiphysics -model. - -See "Section 6.10"_Section_howto.html#howto_10 of the manual and -the couple directory of the distribution for more ideas about coupling -LAMMPS to other codes. See "Section -6.19"_Section_howto.html#howto_19 for a description of the LAMMPS -library interface provided in src/library.cpp and src/library.h, and -how to extend it for your needs. As described below, that interface -is what is exposed to Python either when calling LAMMPS from Python or -when calling Python from a LAMMPS input script and then calling back -to LAMMPS from Python code. The library interface is designed to be -easy to add functions to. Thus the Python interface to LAMMPS is also -easy to extend as well. - -If you create interesting Python scripts that run LAMMPS or -interesting Python functions that can be called from a LAMMPS input -script, that you think would be useful to other users, please "email -them to the developers"_http://lammps.sandia.gov/authors.html. We can -include them in the LAMMPS distribution. - -:line -:line - -11.1 Overview of running LAMMPS from Python :link(py_1),h4 - -The LAMMPS distribution includes a python directory with all you need -to run LAMMPS from Python. The python/lammps.py file wraps the LAMMPS -library interface, with one wrapper function per LAMMPS library -function. This file makes it is possible to do the following either -from a Python script, or interactively from a Python prompt: create -one or more instances of LAMMPS, invoke LAMMPS commands or give it an -input script, run LAMMPS incrementally, extract LAMMPS results, an -modify internal LAMMPS variables. From a Python script you can do -this in serial or parallel. Running Python interactively in parallel -does not generally work, unless you have a version of Python that -extends standard Python to enable multiple instances of Python to read -what you type. - -To do all of this, you must first build LAMMPS as a shared library, -then insure that your Python can find the python/lammps.py file and -the shared library. These steps are explained in subsequent sections -11.3 and 11.4. Sections 11.5 and 11.6 discuss using MPI from a -parallel Python program and how to test that you are ready to use -LAMMPS from Python. Section 11.7 lists all the functions in the -current LAMMPS library interface and how to call them from Python. - -Section 11.8 gives some examples of coupling LAMMPS to other tools via -Python. For example, LAMMPS can easily be coupled to a GUI or other -visualization tools that display graphs or animations in real time as -LAMMPS runs. Examples of such scripts are included in the python -directory. - -Two advantages of using Python to run LAMMPS are how concise the -language is, and that it can be run interactively, enabling rapid -development and debugging of programs. If you use it to mostly invoke -costly operations within LAMMPS, such as running a simulation for a -reasonable number of timesteps, then the overhead cost of invoking -LAMMPS thru Python will be negligible. - -The Python wrapper for LAMMPS uses the amazing and magical (to me) -"ctypes" package in Python, which auto-generates the interface code -needed between Python and a set of C interface routines for a library. -Ctypes is part of standard Python for versions 2.5 and later. You can -check which version of Python you have installed, by simply typing -"python" at a shell prompt. - -:line - -11.2 Overview of using Python from a LAMMPS script :link(py_2),h4 - -LAMMPS has several commands which can be used to invoke Python -code directly from an input script: - -"python"_python.html -"variable python"_variable.html -"fix python/invoke"_fix_python_invoke.html -"pair_style python"_pair_python.html :ul - -The "python"_python.html command which can be used to define and -execute a Python function that you write the code for. The Python -function can also be assigned to a LAMMPS python-style variable via -the "variable"_variable.html command. Each time the variable is -evaluated, either in the LAMMPS input script itself, or by another -LAMMPS command that uses the variable, this will trigger the Python -function to be invoked. - -The Python code for the function can be included directly in the input -script or in an auxiliary file. The function can have arguments which -are mapped to LAMMPS variables (also defined in the input script) and -it can return a value to a LAMMPS variable. This is thus a mechanism -for your input script to pass information to a piece of Python code, -ask Python to execute the code, and return information to your input -script. - -Note that a Python function can be arbitrarily complex. It can import -other Python modules, instantiate Python classes, call other Python -functions, etc. The Python code that you provide can contain more -code than the single function. It can contain other functions or -Python classes, as well as global variables or other mechanisms for -storing state between calls from LAMMPS to the function. - -The Python function you provide can consist of "pure" Python code that -only performs operations provided by standard Python. However, the -Python function can also "call back" to LAMMPS through its -Python-wrapped library interface, in the manner described in the -previous section 11.1. This means it can issue LAMMPS input script -commands or query and set internal LAMMPS state. As an example, this -can be useful in an input script to create a more complex loop with -branching logic, than can be created using the simple looping and -branching logic enabled by the "next"_next.html and "if"_if.html -commands. - -See the "python"_python.html doc page and the "variable"_variable.html -doc page for its python-style variables for more info, including -examples of Python code you can write for both pure Python operations -and callbacks to LAMMPS. - -The "fix python/invoke"_fix_python_invoke.html command can execute -Python code at selected timesteps during a simulation run. - -The "pair_style python"_pair_python command allows you to define -pairwise potentials as python code which encodes a single pairwise -interaction. This is useful for rapid-developement and debugging of a -new potential. - -To use any of these commands, you only need to build LAMMPS with the -PYTHON package installed: - -make yes-python -make machine :pre - -Note that this will link LAMMPS with the Python library on your -system, which typically requires several auxiliary system libraries to -also be linked. The list of these libraries and the paths to find -them are specified in the lib/python/Makefile.lammps file. You need -to insure that file contains the correct information for your version -of Python and your machine to successfully build LAMMPS. See the -lib/python/README file for more info. - -If you want to write Python code with callbacks to LAMMPS, then you -must also follow the steps overviewed in the preceding section (11.1) -for running LAMMPS from Python. I.e. you must build LAMMPS as a -shared library and insure that Python can find the python/lammps.py -file and the shared library. - -:line - -11.3 Building LAMMPS as a shared library :link(py_3),h4 - -Instructions on how to build LAMMPS as a shared library are given in -"Section 2.4"_Section_start.html#start_4. A shared library is one -that is dynamically loadable, which is what Python requires to wrap -LAMMPS. On Linux this is a library file that ends in ".so", not ".a". - -From the src directory, type - -make foo mode=shlib :pre - -where foo is the machine target name, such as linux or g++ or serial. -This should create the file liblammps_foo.so in the src directory, as -well as a soft link liblammps.so, which is what the Python wrapper will -load by default. Note that if you are building multiple machine -versions of the shared library, the soft link is always set to the -most recently built version. - -NOTE: If you are building LAMMPS with an MPI or FFT library or other -auxiliary libraries (used by various packages), then all of these -extra libraries must also be shared libraries. If the LAMMPS -shared-library build fails with an error complaining about this, see -"Section 2.4"_Section_start.html#start_4 for more details. - -:line - -11.4 Installing the Python wrapper into Python :link(py_4),h4 - -For Python to invoke LAMMPS, there are 2 files it needs to know about: - -python/lammps.py -src/liblammps.so :ul - -Lammps.py is the Python wrapper on the LAMMPS library interface. -Liblammps.so is the shared LAMMPS library that Python loads, as -described above. - -You can insure Python can find these files in one of two ways: - -set two environment variables -run the python/install.py script :ul - -If you set the paths to these files as environment variables, you only -have to do it once. For the csh or tcsh shells, add something like -this to your ~/.cshrc file, one line for each of the two files: - -setenv PYTHONPATH $\{PYTHONPATH\}:/home/sjplimp/lammps/python -setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre - -If you use the python/install.py script, you need to invoke it every -time you rebuild LAMMPS (as a shared library) or make changes to the -python/lammps.py file. - -You can invoke install.py from the python directory as - -% python install.py \[libdir\] \[pydir\] :pre - -The optional libdir is where to copy the LAMMPS shared library to; the -default is /usr/local/lib. The optional pydir is where to copy the -lammps.py file to; the default is the site-packages directory of the -version of Python that is running the install script. - -Note that libdir must be a location that is in your default -LD_LIBRARY_PATH, like /usr/local/lib or /usr/lib. And pydir must be a -location that Python looks in by default for imported modules, like -its site-packages dir. If you want to copy these files to -non-standard locations, such as within your own user space, you will -need to set your PYTHONPATH and LD_LIBRARY_PATH environment variables -accordingly, as above. - -If the install.py script does not allow you to copy files into system -directories, prefix the python command with "sudo". If you do this, -make sure that the Python that root runs is the same as the Python you -run. E.g. you may need to do something like - -% sudo /usr/local/bin/python install.py \[libdir\] \[pydir\] :pre - -You can also invoke install.py from the make command in the src -directory as - -% make install-python :pre - -In this mode you cannot append optional arguments. Again, you may -need to prefix this with "sudo". In this mode you cannot control -which Python is invoked by root. - -Note that if you want Python to be able to load different versions of -the LAMMPS shared library (see "this section"_#py_5 below), you will -need to manually copy files like liblammps_g++.so into the appropriate -system directory. This is not needed if you set the LD_LIBRARY_PATH -environment variable as described above. - -:line - -11.5 Extending Python with MPI to run in parallel :link(py_5),h4 - -If you wish to run LAMMPS in parallel from Python, you need to extend -your Python with an interface to MPI. This also allows you to -make MPI calls directly from Python in your script, if you desire. - -There are several Python packages available that purport to wrap MPI -as a library and allow MPI functions to be called from Python. However, -development on most of them seems to be halted except on: - -"mpi4py"_https://bitbucket.org/mpi4py/mpi4py -"PyPar"_https://github.com/daleroberts/pypar :ul - -Both packages, PyPar and mpi4py have been successfully tested with -LAMMPS. PyPar is simpler and easy to set up and use, but supports -only a subset of MPI. Mpi4py is more MPI-feature complete, but also a -bit more complex to use. As of version 2.0.0, mpi4py is the only -python MPI wrapper that allows passing a custom MPI communicator to -the LAMMPS constructor, which means one can easily run one or more -LAMMPS instances on subsets of the total MPI ranks. - -:line - -PyPar requires the ubiquitous "Numpy package"_http://numpy.scipy.org -be installed in your Python. After launching Python, type - -import numpy :pre - -to see if it is installed. If not, here is how to install it (version -1.3.0b1 as of April 2009). Unpack the numpy tarball and from its -top-level directory, type - -python setup.py build -sudo python setup.py install :pre - -The "sudo" is only needed if required to copy Numpy files into your -Python distribution's site-packages directory. - -To install PyPar (version pypar-2.1.4_94 as of Aug 2012), unpack it -and from its "source" directory, type - -python setup.py build -sudo python setup.py install :pre - -Again, the "sudo" is only needed if required to copy PyPar files into -your Python distribution's site-packages directory. - -If you have successfully installed PyPar, you should be able to run -Python and type - -import pypar :pre - -without error. You should also be able to run python in parallel -on a simple test script - -% mpirun -np 4 python test.py :pre - -where test.py contains the lines - -import pypar -print "Proc %d out of %d procs" % (pypar.rank(),pypar.size()) :pre - -and see one line of output for each processor you run on. - -NOTE: To use PyPar and LAMMPS in parallel from Python, you must insure -both are using the same version of MPI. If you only have one MPI -installed on your system, this is not an issue, but it can be if you -have multiple MPIs. Your LAMMPS build is explicit about which MPI it -is using, since you specify the details in your lo-level -src/MAKE/Makefile.foo file. PyPar uses the "mpicc" command to find -information about the MPI it uses to build against. And it tries to -load "libmpi.so" from the LD_LIBRARY_PATH. This may or may not find -the MPI library that LAMMPS is using. If you have problems running -both PyPar and LAMMPS together, this is an issue you may need to -address, e.g. by moving other MPI installations so that PyPar finds -the right one. - -:line - -To install mpi4py (version mpi4py-2.0.0 as of Oct 2015), unpack it -and from its main directory, type - -python setup.py build -sudo python setup.py install :pre - -Again, the "sudo" is only needed if required to copy mpi4py files into -your Python distribution's site-packages directory. To install with -user privilege into the user local directory type - -python setup.py install --user :pre - -If you have successfully installed mpi4py, you should be able to run -Python and type - -from mpi4py import MPI :pre - -without error. You should also be able to run python in parallel -on a simple test script - -% mpirun -np 4 python test.py :pre - -where test.py contains the lines - -from mpi4py import MPI -comm = MPI.COMM_WORLD -print "Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size()) :pre - -and see one line of output for each processor you run on. - -NOTE: To use mpi4py and LAMMPS in parallel from Python, you must -insure both are using the same version of MPI. If you only have one -MPI installed on your system, this is not an issue, but it can be if -you have multiple MPIs. Your LAMMPS build is explicit about which MPI -it is using, since you specify the details in your lo-level -src/MAKE/Makefile.foo file. Mpi4py uses the "mpicc" command to find -information about the MPI it uses to build against. And it tries to -load "libmpi.so" from the LD_LIBRARY_PATH. This may or may not find -the MPI library that LAMMPS is using. If you have problems running -both mpi4py and LAMMPS together, this is an issue you may need to -address, e.g. by moving other MPI installations so that mpi4py finds -the right one. - -:line - -11.6 Testing the Python-LAMMPS interface :link(py_6),h4 - -To test if LAMMPS is callable from Python, launch Python interactively -and type: - ->>> from lammps import lammps ->>> lmp = lammps() :pre - -If you get no errors, you're ready to use LAMMPS from Python. If the -2nd command fails, the most common error to see is - -OSError: Could not load LAMMPS dynamic library :pre - -which means Python was unable to load the LAMMPS shared library. This -typically occurs if the system can't find the LAMMPS shared library or -one of the auxiliary shared libraries it depends on, or if something -about the library is incompatible with your Python. The error message -should give you an indication of what went wrong. - -You can also test the load directly in Python as follows, without -first importing from the lammps.py file: - ->>> from ctypes import CDLL ->>> CDLL("liblammps.so") :pre - -If an error occurs, carefully go thru the steps in "Section -2.4"_Section_start.html#start_4 and above about building a shared -library and about insuring Python can find the necessary two files -it needs. - -[Test LAMMPS and Python in serial:] :h4 - -To run a LAMMPS test in serial, type these lines into Python -interactively from the bench directory: - ->>> from lammps import lammps ->>> lmp = lammps() ->>> lmp.file("in.lj") :pre - -Or put the same lines in the file test.py and run it as - -% python test.py :pre - -Either way, you should see the results of running the in.lj benchmark -on a single processor appear on the screen, the same as if you had -typed something like: - -lmp_g++ -in in.lj :pre - -[Test LAMMPS and Python in parallel:] :h4 - -To run LAMMPS in parallel, assuming you have installed the -"PyPar"_https://github.com/daleroberts/pypar package as discussed -above, create a test.py file containing these lines: - -import pypar -from lammps import lammps -lmp = lammps() -lmp.file("in.lj") -print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp -pypar.finalize() :pre - -To run LAMMPS in parallel, assuming you have installed the -"mpi4py"_https://bitbucket.org/mpi4py/mpi4py package as discussed -above, create a test.py file containing these lines: - -from mpi4py import MPI -from lammps import lammps -lmp = lammps() -lmp.file("in.lj") -me = MPI.COMM_WORLD.Get_rank() -nprocs = MPI.COMM_WORLD.Get_size() -print "Proc %d out of %d procs has" % (me,nprocs),lmp -MPI.Finalize() :pre - -You can either script in parallel as: - -% mpirun -np 4 python test.py :pre - -and you should see the same output as if you had typed - -% mpirun -np 4 lmp_g++ -in in.lj :pre - -Note that if you leave out the 3 lines from test.py that specify PyPar -commands you will instantiate and run LAMMPS independently on each of -the P processors specified in the mpirun command. In this case you -should get 4 sets of output, each showing that a LAMMPS run was made -on a single processor, instead of one set of output showing that -LAMMPS ran on 4 processors. If the 1-processor outputs occur, it -means that PyPar is not working correctly. - -Also note that once you import the PyPar module, PyPar initializes MPI -for you, and you can use MPI calls directly in your Python script, as -described in the PyPar documentation. The last line of your Python -script should be pypar.finalize(), to insure MPI is shut down -correctly. - -[Running Python scripts:] :h4 - -Note that any Python script (not just for LAMMPS) can be invoked in -one of several ways: - -% python foo.script -% python -i foo.script -% foo.script :pre - -The last command requires that the first line of the script be -something like this: - -#!/usr/local/bin/python -#!/usr/local/bin/python -i :pre - -where the path points to where you have Python installed, and that you -have made the script file executable: - -% chmod +x foo.script :pre - -Without the "-i" flag, Python will exit when the script finishes. -With the "-i" flag, you will be left in the Python interpreter when -the script finishes, so you can type subsequent commands. As -mentioned above, you can only run Python interactively when running -Python on a single processor, not in parallel. - -:line -:line - -11.7 Using LAMMPS from Python :link(py_7),h4 - -As described above, the Python interface to LAMMPS consists of a -Python "lammps" module, the source code for which is in -python/lammps.py, which creates a "lammps" object, with a set of -methods that can be invoked on that object. The sample Python code -below assumes you have first imported the "lammps" module in your -Python script, as follows: - -from lammps import lammps :pre - -These are the methods defined by the lammps module. If you look at -the files src/library.cpp and src/library.h you will see they -correspond one-to-one with calls you can make to the LAMMPS library -from a C++ or C or Fortran program, and which are described in -"Section 6.19"_Section_howto.html#howto_19 of the manual. - -The python/examples directory has Python scripts which show how Python -can run LAMMPS, grab data, change it, and put it back into LAMMPS. - -lmp = lammps() # create a LAMMPS object using the default liblammps.so library - # 4 optional args are allowed: name, cmdargs, ptr, comm -lmp = lammps(ptr=lmpptr) # use lmpptr as previously created LAMMPS object -lmp = lammps(comm=split) # create a LAMMPS object with a custom communicator, requires mpi4py 2.0.0 or later -lmp = lammps(name="g++") # create a LAMMPS object using the liblammps_g++.so library -lmp = lammps(name="g++",cmdargs=list) # add LAMMPS command-line args, e.g. list = \["-echo","screen"\] :pre - -lmp.close() # destroy a LAMMPS object :pre - -version = lmp.version() # return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902 :pre - -lmp.file(file) # run an entire input script, file = "in.lj" -lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100" -lmp.commands_list(cmdlist) # invoke commands in cmdlist = ["run 10", "run 20"] -lmp.commands_string(multicmd) # invoke commands in multicmd = "run 10\nrun 20" :pre - -size = lmp.extract_setting(name) # return data type info :pre - -xlo = lmp.extract_global(name,type) # extract a global quantity - # name = "boxxlo", "nlocal", etc - # type = 0 = int - # 1 = double :pre - -boxlo,boxhi,xy,yz,xz,periodicity,box_change = lmp.extract_box() # extract box info :pre - -coords = lmp.extract_atom(name,type) # extract a per-atom quantity - # name = "x", "type", etc - # type = 0 = vector of ints - # 1 = array of ints - # 2 = vector of doubles - # 3 = array of doubles :pre - -eng = lmp.extract_compute(id,style,type) # extract value(s) from a compute -v3 = lmp.extract_fix(id,style,type,i,j) # extract value(s) from a fix - # id = ID of compute or fix - # style = 0 = global data - # 1 = per-atom data - # 2 = local data - # type = 0 = scalar - # 1 = vector - # 2 = array - # i,j = indices of value in global vector or array :pre - -var = lmp.extract_variable(name,group,flag) # extract value(s) from a variable - # name = name of variable - # group = group ID (ignored for equal-style variables) - # flag = 0 = equal-style variable - # 1 = atom-style variable :pre - -value = lmp.get_thermo(name) # return current value of a thermo keyword -natoms = lmp.get_natoms() # total # of atoms as int :pre - -flag = lmp.set_variable(name,value) # set existing named string-style variable to value, flag = 0 if successful -lmp.reset_box(boxlo,boxhi,xy,yz,xz) # reset the simulation box size :pre - -data = lmp.gather_atoms(name,type,count) # return per-atom property of all atoms gathered into data, ordered by atom ID - # name = "x", "charge", "type", etc -data = lmp.gather_atoms_concat(name,type,count) # ditto, but concatenated atom values from each proc (unordered) -data = lmp.gather_atoms_subset(name,type,count,ndata,ids) # ditto, but for subset of Ndata atoms with IDs :pre - -lmp.scatter_atoms(name,type,count,data) # scatter per-atom property to all atoms from data, ordered by atom ID - # name = "x", "charge", "type", etc - # count = # of per-atom values, 1 or 3, etc :pre -lmp.scatter_atoms_subset(name,type,count,ndata,ids,data) # ditto, but for subset of Ndata atoms with IDs :pre - -lmp.create_atoms(n,ids,types,x,v,image,shrinkexceed) # create N atoms with IDs, types, x, v, and image flags :pre - -:line - -The lines - -from lammps import lammps -lmp = lammps() :pre - -create an instance of LAMMPS, wrapped in a Python class by the lammps -Python module, and return an instance of the Python class as lmp. It -is used to make all subsequent calls to the LAMMPS library. - -Additional arguments to lammps() can be used to tell Python the name -of the shared library to load or to pass arguments to the LAMMPS -instance, the same as if LAMMPS were launched from a command-line -prompt. - -If the ptr argument is set like this: - -lmp = lammps(ptr=lmpptr) :pre - -then lmpptr must be an argument passed to Python via the LAMMPS -"python"_python.html command, when it is used to define a Python -function that is invoked by the LAMMPS input script. This mode of -using Python with LAMMPS is described above in 11.2. The variable -lmpptr refers to the instance of LAMMPS that called the embedded -Python interpreter. Using it as an argument to lammps() allows the -returned Python class instance "lmp" to make calls to that instance of -LAMMPS. See the "python"_python.html command doc page for examples -using this syntax. - -Note that you can create multiple LAMMPS objects in your Python -script, and coordinate and run multiple simulations, e.g. - -from lammps import lammps -lmp1 = lammps() -lmp2 = lammps() -lmp1.file("in.file1") -lmp2.file("in.file2") :pre - -The file(), command(), commands_list(), commands_string() methods -allow an input script, a single command, or multiple commands to be -invoked. - -The extract_setting(), extract_global(), extract_box(), -extract_atom(), extract_compute(), extract_fix(), and -extract_variable() methods return values or pointers to data -structures internal to LAMMPS. - -For extract_global() see the src/library.cpp file for the list of -valid names. New names could easily be added. A double or integer is -returned. You need to specify the appropriate data type via the type -argument. - -For extract_atom(), a pointer to internal LAMMPS atom-based data is -returned, which you can use via normal Python subscripting. See the -extract() method in the src/atom.cpp file for a list of valid names. -Again, new names could easily be added if the property you want is not -listed. A pointer to a vector of doubles or integers, or a pointer to -an array of doubles (double **) or integers (int **) is returned. You -need to specify the appropriate data type via the type argument. - -For extract_compute() and extract_fix(), the global, per-atom, or -local data calculated by the compute or fix can be accessed. What is -returned depends on whether the compute or fix calculates a scalar or -vector or array. For a scalar, a single double value is returned. If -the compute or fix calculates a vector or array, a pointer to the -internal LAMMPS data is returned, which you can use via normal Python -subscripting. The one exception is that for a fix that calculates a -global vector or array, a single double value from the vector or array -is returned, indexed by I (vector) or I and J (array). I,J are -zero-based indices. The I,J arguments can be left out if not needed. -See "Section 6.15"_Section_howto.html#howto_15 of the manual for a -discussion of global, per-atom, and local data, and of scalar, vector, -and array data types. See the doc pages for individual -"computes"_compute.html and "fixes"_fix.html for a description of what -they calculate and store. - -For extract_variable(), an "equal-style or atom-style -variable"_variable.html is evaluated and its result returned. - -For equal-style variables a single double value is returned and the -group argument is ignored. For atom-style variables, a vector of -doubles is returned, one value per atom, which you can use via normal -Python subscripting. The values will be zero for atoms not in the -specified group. - -The get_thermo() method returns returns the current value of a thermo -keyword as a float. - -The get_natoms() method returns the total number of atoms in the -simulation, as an int. - -The set_variable() methosd sets an existing string-style variable to a -new string value, so that subsequent LAMMPS commands can access the -variable. - -The reset_box() emthods resets the size and shape of the simulation -box, e.g. as part of restoring a previously extracted and saved state -of a simulation. - -The gather methods collect peratom info of the requested type (atom -coords, atom types, forces, etc) from all processors, and returns the -same vector of values to each callling processor. The scatter -functions do the inverse. They distribute a vector of peratom values, -passed by all calling processors, to invididual atoms, which may be -owned by different processos. - -Note that the data returned by the gather methods, -e.g. gather_atoms("x"), is different from the data structure returned -by extract_atom("x") in four ways. (1) Gather_atoms() returns a -vector which you index as x\[i\]; extract_atom() returns an array -which you index as x\[i\]\[j\]. (2) Gather_atoms() orders the atoms -by atom ID while extract_atom() does not. (3) Gather_atoms() returns -a list of all atoms in the simulation; extract_atoms() returns just -the atoms local to each processor. (4) Finally, the gather_atoms() -data structure is a copy of the atom coords stored internally in -LAMMPS, whereas extract_atom() returns an array that effectively -points directly to the internal data. This means you can change -values inside LAMMPS from Python by assigning a new values to the -extract_atom() array. To do this with the gather_atoms() vector, you -need to change values in the vector, then invoke the scatter_atoms() -method. - -For the scatter methods, the array of coordinates passed to must be a -ctypes vector of ints or doubles, allocated and initialized something -like this: - -from ctypes import * -natoms = lmp.get_natoms() -n3 = 3*natoms -x = (n3*c_double)() -x\[0\] = x coord of atom with ID 1 -x\[1\] = y coord of atom with ID 1 -x\[2\] = z coord of atom with ID 1 -x\[3\] = x coord of atom with ID 2 -... -x\[n3-1\] = z coord of atom with ID natoms -lmp.scatter_atoms("x",1,3,x) :pre - -Alternatively, you can just change values in the vector returned by -the gather methods, since they are also ctypes vectors. - -:line - -As noted above, these Python class methods correspond one-to-one with -the functions in the LAMMPS library interface in src/library.cpp and -library.h. This means you can extend the Python wrapper via the -following steps: - -Add a new interface function to src/library.cpp and -src/library.h. :ulb,l - -Rebuild LAMMPS as a shared library. :l - -Add a wrapper method to python/lammps.py for this interface -function. :l - -You should now be able to invoke the new interface function from a -Python script. Isn't ctypes amazing? :l -:ule - -:line -:line - -11.8 Example Python scripts that use LAMMPS :link(py_8),h4 - -These are the Python scripts included as demos in the python/examples -directory of the LAMMPS distribution, to illustrate the kinds of -things that are possible when Python wraps LAMMPS. If you create your -own scripts, send them to us and we can include them in the LAMMPS -distribution. - -trivial.py, read/run a LAMMPS input script thru Python, -demo.py, invoke various LAMMPS library interface routines, -simple.py, run in parallel, similar to examples/COUPLE/simple/simple.cpp, -split.py, same as simple.py but running in parallel on a subset of procs, -gui.py, GUI go/stop/temperature-slider to control LAMMPS, -plot.py, real-time temperature plot with GnuPlot via Pizza.py, -viz_tool.py, real-time viz via some viz package, -vizplotgui_tool.py, combination of viz_tool.py and plot.py and gui.py :tb(c=2) - -:line - -For the viz_tool.py and vizplotgui_tool.py commands, replace "tool" -with "gl" or "atomeye" or "pymol" or "vmd", depending on what -visualization package you have installed. - -Note that for GL, you need to be able to run the Pizza.py GL tool, -which is included in the pizza sub-directory. See the "Pizza.py doc -pages"_pizza for more info: - -:link(pizza,http://www.sandia.gov/~sjplimp/pizza.html) - -Note that for AtomEye, you need version 3, and there is a line in the -scripts that specifies the path and name of the executable. See the -AtomEye WWW pages "here"_atomeye or "here"_atomeye3 for more details: - -http://mt.seas.upenn.edu/Archive/Graphics/A -http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html :pre - -:link(atomeye,http://mt.seas.upenn.edu/Archive/Graphics/A) -:link(atomeye3,http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html) - -The latter link is to AtomEye 3 which has the scriping -capability needed by these Python scripts. - -Note that for PyMol, you need to have built and installed the -open-source version of PyMol in your Python, so that you can import it -from a Python script. See the PyMol WWW pages "here"_pymolhome or -"here"_pymolopen for more details: - -http://www.pymol.org -http://sourceforge.net/scm/?type=svn&group_id=4546 :pre - -:link(pymolhome,http://www.pymol.org) -:link(pymolopen,http://sourceforge.net/scm/?type=svn&group_id=4546) - -The latter link is to the open-source version. - -Note that for VMD, you need a fairly current version (1.8.7 works for -me) and there are some lines in the pizza/vmd.py script for 4 PIZZA -variables that have to match the VMD installation on your system. - -:line - -See the python/README file for instructions on how to run them and the -source code for individual scripts for comments about what they do. - -Here are screenshots of the vizplotgui_tool.py script in action for -different visualization package options. Click to see larger images: - -:image(JPG/screenshot_gl_small.jpg,JPG/screenshot_gl.jpg) -:image(JPG/screenshot_atomeye_small.jpg,JPG/screenshot_atomeye.jpg) -:image(JPG/screenshot_pymol_small.jpg,JPG/screenshot_pymol.jpg) -:image(JPG/screenshot_vmd_small.jpg,JPG/screenshot_vmd.jpg) - -11.9 PyLammps interface :link(py_9),h4 - -Please see the "PyLammps Tutorial"_tutorial_pylammps.html. diff --git a/doc/src/Section_start.txt b/doc/src/Section_start.txt index 7d456171dc..d8f340b179 100644 --- a/doc/src/Section_start.txt +++ b/doc/src/Section_start.txt @@ -1,4 +1,6 @@ -"Previous Section"_Section_intro.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_commands.html :c +"Previous Section"_Section_intro.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next +Section"_Section_commands.html :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) @@ -930,8 +932,8 @@ Makefile.opt :ul LAMMPS can be built as either a static or shared library, which can then be called from another application or a scripting language. See "this section"_Section_howto.html#howto_10 for more info on coupling -LAMMPS to other codes. See "this section"_Section_python.html for -more info on wrapping and running LAMMPS from Python. +LAMMPS to other codes. See the "Python"_Python.html doc page for more +info on wrapping and running LAMMPS from Python. Static library :h4 @@ -955,15 +957,15 @@ dynamically loaded, e.g. from Python, type make foo mode=shlib :pre where foo is the machine name. This kind of library is required when -wrapping LAMMPS with Python; see "Section 11"_Section_python.html -for details. This will use the SHFLAGS and SHLIBFLAGS settings in +wrapping LAMMPS with Python; see the "Python"_Python.html doc page for +details. This will use the SHFLAGS and SHLIBFLAGS settings in src/MAKE/Makefile.foo and perform the build in the directory Obj_shared_foo. This is so that each file can be compiled with the -fPIC flag which is required for inclusion in a shared library. The build will create the file liblammps_foo.so which another application -can link to dynamically. It will also create a soft link liblammps.so, -which will point to the most recently built shared library. This is -the file the Python wrapper loads by default. +can link to dynamically. It will also create a soft link +liblammps.so, which will point to the most recently built shared +library. This is the file the Python wrapper loads by default. Note that for a shared library to be usable by a calling program, all the auxiliary libraries it depends on must also exist as shared @@ -1035,10 +1037,10 @@ src/library.cpp and src/library.h. See the sample codes in examples/COUPLE/simple for examples of C++ and C and Fortran codes that invoke LAMMPS thru its library interface. There are other examples as well in the COUPLE directory which are -discussed in "Section 6.10"_Section_howto.html#howto_10 of the -manual. See "Section 11"_Section_python.html of the manual for a -description of the Python wrapper provided with LAMMPS that operates -through the LAMMPS library interface. +discussed in "Section 6.10"_Section_howto.html#howto_10 of the manual. +See the "Python"_Python.html doc page for a description of the Python +wrapper provided with LAMMPS that operates through the LAMMPS library +interface. The files src/library.cpp and library.h define the C-style API for using LAMMPS as a library. See "Section @@ -1177,7 +1179,7 @@ than your working directory, which is probably not what you want. If LAMMPS encounters errors in the input script or while running a simulation it will print an ERROR message and stop or a WARNING -message and continue. See "Section 12"_Section_errors.html for a +message and continue. See the "Errors"_Errors.html doc page for a discussion of the various kinds of errors LAMMPS can or can't detect, a list of all ERROR and WARNING messages, and what to do about them. diff --git a/doc/src/Tools.txt b/doc/src/Tools.txt index 60b92f0f2e..4c5fbbd453 100644 --- a/doc/src/Tools.txt +++ b/doc/src/Tools.txt @@ -2,12 +2,6 @@ Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Modify.html :c - - :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) diff --git a/doc/src/fix_external.txt b/doc/src/fix_external.txt index b28d33446f..30e34b4858 100644 --- a/doc/src/fix_external.txt +++ b/doc/src/fix_external.txt @@ -34,8 +34,7 @@ This fix allows external programs that are running LAMMPS through its "library interface"_Section_howto.html#howto_19 to modify certain LAMMPS properties on specific timesteps, similar to the way other fixes do. The external driver can be a "C/C++ or Fortran -program"_Section_howto.html#howto_19 or a "Python -script"_Section_python.html. +program"_Section_howto.html#howto_19 or a "Python script"_Python.html. :line diff --git a/doc/src/lammps.book b/doc/src/lammps.book index ff8fe68ff1..4924ec8027 100644 --- a/doc/src/lammps.book +++ b/doc/src/lammps.book @@ -31,9 +31,22 @@ Modify_region.html Modify_body.html Modify_thermo.html Modify_variable.html - -Section_python.html -Section_errors.html +Python.html +Python_overview.txt +Python_run.txt +Python_shlib.txt +Python_install.txt +Python_mpi.txt +Python_test.txt +Python_library.txt +Python_pylammps.txt +Python_examples.txt +Python_call.txt +Errors.html +Errors_common.txt +Errors_bugs.txt +Errors_messages.txt +Errors_warnings.txt Section_history.html lammps_tutorials.html diff --git a/doc/src/python.txt b/doc/src/python.txt index 1ac2b48528..d670fcc77f 100644 --- a/doc/src/python.txt +++ b/doc/src/python.txt @@ -99,10 +99,9 @@ They can be substituted for directly in an input script. Or they can be passed to various commands as arguments, so that the variable is evaluated during a simulation run. -A broader overview of how Python can be used with LAMMPS is -given in "Section 11"_Section_python.html. There is an -examples/python directory which illustrates use of the python -command. +A broader overview of how Python can be used with LAMMPS is given on +the "Python"_Python.html doc page. There is an examples/python +directory which illustrates use of the python command. :line @@ -331,9 +330,9 @@ to the screen and log file. Note that since the LAMMPS print command itself takes a string in quotes as its argument, the Python string must be delimited with a different style of quotes. -"Section 11.7"_Section_python.html#py_7 describes the syntax for how -Python wraps the various functions included in the LAMMPS library -interface. +The "Pytnon library"_Python_library.html doc page describes the syntax +for how Python wraps the various functions included in the LAMMPS +library interface. A more interesting example is in the examples/python/in.python script which loads and runs the following function from examples/python/funcs.py: @@ -484,15 +483,16 @@ building LAMMPS. LAMMPS must also be built as a shared library and your Python function must be able to to load the Python module in python/lammps.py that wraps the LAMMPS library interface. These are the same steps required to use Python by itself to wrap LAMMPS. -Details on these steps are explained in "Section -python"_Section_python.html. Note that it is important that the -stand-alone LAMMPS executable and the LAMMPS shared library be -consistent (built from the same source code files) in order for this -to work. If the two have been built at different times using -different source files, problems may occur. +Details on these steps are explained on the "Python"_Python.html doc +page. Note that it is important that the stand-alone LAMMPS +executable and the LAMMPS shared library be consistent (built from the +same source code files) in order for this to work. If the two have +been built at different times using different source files, problems +may occur. [Related commands:] -"shell"_shell.html, "variable"_variable.html, "fix python/invoke"_fix_python_invoke.html +"shell"_shell.html, "variable"_variable.html, "fix +python/invoke"_fix_python_invoke.html [Default:] none diff --git a/doc/src/read_dump.txt b/doc/src/read_dump.txt index 23f6274582..21c6df5017 100644 --- a/doc/src/read_dump.txt +++ b/doc/src/read_dump.txt @@ -282,11 +282,11 @@ conditions are applied to remap an atom back into the simulation box. NOTE: If you get a warning about inconsistent image flags after reading in a dump snapshot, it means one or more pairs of bonded atoms -now have inconsistent image flags. As discussed in "Section -errors"_Section_errors.html this may or may not cause problems for -subsequent simulations, One way this can happen is if you read image -flag fields from the dump file but do not also use the dump file box -parameters. +now have inconsistent image flags. As discussed on the "Errors +common"_Errors_common.html doc page this may or may not cause problems +for subsequent simulations. One way this can happen is if you read +image flag fields from the dump file but do not also use the dump file +box parameters. LAMMPS knows how to compute unscaled and remapped coordinates for the snapshot column labels discussed above, e.g. {x}, {xs}, {xu}, {xsu}. diff --git a/doc/src/read_restart.txt b/doc/src/read_restart.txt index a5a2bfcc97..6f6a828229 100644 --- a/doc/src/read_restart.txt +++ b/doc/src/read_restart.txt @@ -76,8 +76,7 @@ different than if the run had continued. These pair styles include If a restarted run is immediately different than the run which produced the restart file, it could be a LAMMPS bug, so consider -"reporting it"_Section_errors.html#err_2 if you think the behavior is -wrong. +"reporting it"_Errors_bugs.html if you think the behavior is a bug. Because restart files are binary, they may not be portable to other machines. In this case, you can use the "-restart command-line diff --git a/src/pair.cpp b/src/pair.cpp index 9bb1ad212f..5c308cc7ce 100644 --- a/src/pair.cpp +++ b/src/pair.cpp @@ -693,17 +693,19 @@ void Pair::compute_dummy(int eflag, int vflag) } /* ---------------------------------------------------------------------- */ + void Pair::read_restart(FILE *) { if (comm->me == 0) - error->warning(FLERR,"BUG: restartinfo=1 but no restart support in pair style"); + error->warning(FLERR,"Pair style restartinfo set but has no restart support"); } /* ---------------------------------------------------------------------- */ + void Pair::write_restart(FILE *) { if (comm->me == 0) - error->warning(FLERR,"BUG: restartinfo=1 but no restart support in pair style"); + error->warning(FLERR,"Pair style restartinfo set but has no restart support"); } /* -------------------------------------------------------------------