jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

changes to Errors and Python doc pages

This commit is contained in:
Steven J. Plimpton 2018-07-25 14:10:00 -06:00
parent dff8977156
commit 1d9ad55796
33 changed files with 2130 additions and 2058 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
doc/src/Errors.txt Normal file
View File

@ -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.
<!-- RST
.. toctree::
Errors_common
Errors_bugs
Errors_messages
Errors_warnings
END_RST -->
<!-- HTML_ONLY -->
"Common problems"_Errors_common.html
"Reporting bugs"_Errors_bugs.html
"Error messages"_Errors_messages.html
"Warning messages"_Errors_warnings.html :all(b)
<!-- END_HTML_ONLY -->

35
doc/src/Errors_bugs.txt Normal file
View File

@ -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

123
doc/src/Errors_common.txt Normal file
View File

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

1097
doc/src/Section_errors.txt → doc/src/Errors_messages.txt
View File

File diff suppressed because it is too large Load Diff

934
doc/src/Errors_warnings.txt Normal file
View File

@ -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

6
doc/src/Examples.txt
View File

@ -2,12 +2,6 @@
"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
Section"_Section_perf.html :c
<!-- future sequence of sections:
"Previous Section"_Speed.html - "LAMMPS WWW Site"_lws -
"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
Section"_Python.html :c
-->
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

32
doc/src/Manual.txt
View File

@ -1,5 +1,5 @@
<!-- HTML_ONLY -->
<HEAD>
<
<TITLE>LAMMPS Users Manual</TITLE>
<META NAME="docnumber" CONTENT="16 Jul 2018 version">
<META NAME="author" CONTENT="http://lammps.sandia.gov - Sandia National Laboratories">
@ -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)
<!-- END_HTML_ONLY -->

14
doc/src/Modify.txt
View File

@ -1,12 +1,6 @@
"Previous Section"_Tools.html - "LAMMPS WWW Site"_lws -
"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
Section"_Section_python.html :c
<!-- future sequence of sections:
"Previous Section"_Tools.html - "LAMMPS WWW Site"_lws -
"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
Section"_Errors.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

79
doc/src/Python.txt Normal file
View File

@ -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.
<!-- RST
.. toctree::
Python_overview
.. toctree::
Python_run
Python_shlib
Python_install
Python_mpi
Python_test
Python_library
Python_pylammps
Python_examples
.. toctree::
Python_call
END_RST -->
<!-- HTML_ONLY -->
"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)
<!-- END_HTML_ONLY -->
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.

85
doc/src/Python_call.txt Normal file
View File

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

81
doc/src/Python_examples.txt Normal file
View File

@ -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)

74
doc/src/Python_install.txt Normal file
View File

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

256
doc/src/Python_library.txt Normal file
View File

@ -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

67
doc/src/Python_mpi.txt Normal file
View File

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

35
doc/src/Python_overview.txt Normal file
View File

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

14
doc/src/Python_pylammps.txt Normal file
View File

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

40
doc/src/Python_run.txt Normal file
View File

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

34
doc/src/Python_shlib.txt Normal file
View File

@ -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

131
doc/src/Python_test.txt Normal file
View File

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

2
doc/src/Section_commands.txt
View File

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

2
doc/src/Section_history.txt
View File

@ -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

22
doc/src/Section_howto.txt
View File

@ -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 **)

6
doc/src/Section_intro.txt
View File

@ -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

10
doc/src/Section_packages.txt
View File

@ -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

869
doc/src/Section_python.txt
View File

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

28
doc/src/Section_start.txt
View File

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

6
doc/src/Tools.txt
View File

@ -2,12 +2,6 @@
Documentation"_ld - "LAMMPS Commands"_lc - "Next
Section"_Modify.html :c
<!-- future sequence of sections:
"Previous Section"_Python.html - "LAMMPS WWW Site"_lws -
"LAMMPS 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)

3
doc/src/fix_external.txt
View File

@ -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

19
doc/src/lammps.book
View File

@ -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

28
doc/src/python.txt
View File

@ -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

10
doc/src/read_dump.txt
View File

@ -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}.

3
doc/src/read_restart.txt
View File

@ -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

6
src/pair.cpp
View File

@ -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");
}
/* -------------------------------------------------------------------