Propogate the efaa4c67 changes to npair_ssa_kokkos from npair_kokkos that
support the new neigh_modify exclude molecule/intra and /inter options.
Note: npair_ssa_kokkos could inherit from npair_kokkos to avoid this kind
of missed change. Unfortunately, inheritance from templated classes is
both tricky and messy, and not worth the complexity in this case, IMHO.
Notable features are the umbrella-integration based free energy estimator for
eABF, and the traditional thermodynamic integration estimator now available
for umbrella sampling, SMD, metadynamics. Also included are several small fixes.
Below is a list of relevant commits in the Colvars repository since the last update.
321d06a 2017-10-10 Add macros to manage colvarscript commands [Giacomo Fiorin]
26c3bec 2017-10-09 Document coming availability of Lepton in LAMMPS [Giacomo Fiorin]
cc8f249 2017-10-04 Clarify that SMP depends on code build [Giacomo Fiorin]
0b2ffac 2017-10-04 Summarize colvar definition options, clarify some details [Giacomo Fiorin]
28002e0 2017-10-01 Separate writing of restart file from other output (e.g. PMFs) [Giacomo Fiorin]
92f7c1d 2017-10-01 Deprecate colvarsTrajAppend [Giacomo Fiorin]
12a707f 2017-09-26 Accurate Jacobian calculation for RMSD variants [Jérôme Hénin]
fe389c9 2017-09-21 Allow subtractAppliedForce with extended-L again [Jérôme Hénin]
c050ce0 2017-09-18 Silence compiler warnings, remove Tabs [Giacomo Fiorin]
cb41905 2017-01-11 Add base class for TI estimator in other biases than ABF [Giacomo Fiorin]
a1bc676 2017-09-14 Avoid writing to unopened traj file [Jérôme Hénin]
b58d8cd 2017-09-08 Function to check for overlapping groups [Jérôme Hénin]
1e5efec 2017-09-07 Check for overlapping groups in coordNum [Jérôme Hénin]
03a61a4 2017-04-06 Add UI-based estimator [fhh2626]
ae43754 2017-08-17 Fix outputCenters parsing [Josh Vermaas]
1619e0e 2017-08-14 Delete static feature arrays in cvm destructor [Jérôme Hénin]
- re-indent to 2 blanks
- white space cleanup
- use force->numeric() and force->inumeric() instead of atof() and atoi()
- include system headers before local LAMMPS headers
- move example folder to examples/USER/misc/
- comment out writing of trajectory files
- reduce run length (for easier testing for regressions)
- record example outputs for 1 and 4 MPI processes
- rename readme.md to README.md for visibility
Adding raw performance numbers for Skylake xeon server.
Fixes for using older Intel compilers and compiling without OpenMP.
Fix adding in hooks for using USER-INTEL w/ minimization.
- include the used tricubic functions directly as static functions
- silence compiler warnings
- define f2c.h imported data types directly or use C equivalents
- since the direct LAPACK API was called and not cLAPACK, declare LAPACK interface and depend only on LAPACK
- add proper dependencies
- disable automatic minor version number generation. step version manually.
- comment out optional spglib functionality by default
with this change, the USER-INTEL package can be installed and
compiled without having to alter makefiles for adding -lpthread.
All "intel optimized" makefiles have been updated to have the
LRT feature enabled. This change will allow us to include the
USER-INTEL package in several automated testing configurations
and thus allows to detect incompatibilities and compilation issus faster.
The library interface was extended to provide direct access to atom data using
numpy arrays. No data copies are made and numpy operations directly manipulate
memory of the native code.
To keep this numpy dependency optional, all functions are wrapped into the
lammps.numpy sub-object which is only loaded when accessed.
The Constant Energy DPD (DPDE) was our primary usage case, so only stubs
for the Constant Temperature case were included in Kokkos code so far.
The non-Kokkos version works fine for Constant Temperature DPD.
New function that allows for parallel tempering (replica exchange) in MD in LAMMPS in the isothermal-isobaric ensemble (NPT)
Similar to temper which works in the canonical (NVT) ensemble.
An example is included that uses temper_npt
Merge changes thru July 27, 2017 from master 6d0a2286 into USER-DPD_kokkos
Includes 67a0183b which partially reverted 7f9a331c (from May 16, 2017) in USER-DPD,
since SSA neighbor lists use ghost info, so they can't currently be used as "occasional" lists.
The default compiler flags in voro++'s config.mk file do not include
-fPIC, which makes it incompatible with building the shared object for
the python wrapper.
- build into local directory to replace existing installation is now default
- add wrapper function that calls curl in case python package has not ssl support
- have to specify -n flag to avoid wiping out the existing installation
- can specify -p to point to an existing kim-api installation (implies -n)
This example showcases the use of different 'special_bonds' settings for
different pair styles, so quip gets all the bonded neighbours but lj can
exclude them if it needs to.
The results have been checked against a pure quip implementation of the
potential; the expected lammps output is included.
DISCLAIMER: This example mixes parameters for methane and silane and is
NOT intended to be a realistic representation of either system.
this check currently only applies to rigid fixes and is needed
so that their respective enforce2d function is called _after_
the post force functions. this is required in combination with
commit a9ff593763 to allow rigid
fixes use the langevin option correctly for 2d systems
In #514 it has been raised that the switching function that
ensures a smooth transition to the cutoff is only correct if
cutlj = 3.0. This patch gives users an opportunity to configure
the switching function together with the cutoff by specifying
the start of the transition region. Behaviour in the default case
remaing unchanged.
This allows users to specify larger cutoffs than 3 (which used to
have no effect) and get correct cutoff behaviour for values less
then 3.
This change replaces the bondorderLJ() function with code provided
by Github user CF17, which is based on the bondorder() code.
It could be fixed with a shorter patch [1], but layering fix upon
fix seems to be unwise in this case.
While the code at this point departs from following the Fortran
code closely, the reason is that the bug is present in the Fortran
code as well.
Instead, the new code follows closely the bondorder() code that
already exists, which should be easier to maintain in the future.
This patch makes the two functions consistent with each other,
and makes outside contributions easier.
Since it uses a different approach to compute its value, some
explanation of that reasoning has been added on top.
1: e8c5c662b2
- use static/const
- return instead of ptr-parameter, &ref if more than one return
- replace macros from header with inline functions
- remove useless/old comments
rather than placing an if statement around every incidence of calling atom->check_mass() to ensure it is only called when per atom masses are not set, we place that check _inside_ Atom::check_mass(). This avoids unexpected error messages.
-DLMP_USE_LIBC_QSORT will use qsort() from libc to sort (requires static/global variables).
-DLMP_USE_MERGE_SORT will use a plain merge sort. slightly slower for expensive comparisons.
-DLMP_USE_HYBRID_SORT will use hybrid merge sort. faster than merge sort (no static/global variables)
The dump and irregular classes were using qsort() from the C-library
for sorting lists through custom comparison functions, which required
access to additional data, which was passed via static class variables,
i.e. globals. This collides with having multiple LAMMPS instances in
the same address space.
the calls to qsort() are replaced with a custom merge sort, which passes
a void pointer to the comparison functions, which can contain any kind
of desired information, e.g. a class handle or a list
with sparse and hybrid systems, Pair::ev_tally() may not be called on
every processor and thus the computes in USER-TALLY may hang during
reverse communication because of the error->all() call after checking
whether callback from Pair::ev_tally() has been called at least once.
To address this cleanly, a second callback function needs to be added,
which is run during Pair::ev_setup() and will now handle all memory
re-allocation and clearing of accumulators, just like it is done for
regular tallied data.
- fm_exp moved to math_special (exp2 was already there)
- use std::min/max template instead of macros
- use memory->create for dynamic arrays (still 1-indexed with macro)
- remove _ from function names, adjust method visibility
- move MEAM class into LAMMPS_NS namespace
- move inclusion of meam.h header to pair_meamc.cpp to reduce namespace pollution
- use forward declaration for MEAM class reference
- make that class reference a pointer and add a destructor
- replace MAX/MIN macros with versions compatible with older compilers
The code ignored the kronecker(ktype, 0) or kronecker(ltype, 0)
terms in the contributing terms to NconjtmpI and NconjtmpJ.
The issue was present both in ::bondorder and ::bondorderLJ and
led to energy conservation issues.
It has been fixed by checking for the atom type before entering
the offending calculations and adding clarifying comments.
- make all python potential classes derived from LAMMPSPairPotential
which contains shared functionality. We currently don't check
for supported atom types. may want to add that again later.
- keep track of skipped atom types in the C++ code.
- add test against units setting. must set self.units='...' in constructor
- make compute_force method consistent with Pair::single() in LAMMPS and return force/r instead of force.
- rename potentials.py to py_pot.py
- update test runs. some small tweaks.
with the single function, python pair styles can be massively
sped up and made compatible to accelerators, as one can translate
the analytic force and energy functions through LAMMPS into suitable
tables and then simply use the on-the-fly tables for production runs
Implements a class loader which takes a fully qualified Python class
name, loads the module and creates an object instance.
To add flexibility, the current working directory and the
directory specified by the LAMMPS_POTENTIALS environment variable are
added to the module search path.
- make i_to_potl() and ij_to_potl() functions inline and const
- don't dereference inside the functions, but cache, if possible in external variables
=> up to 15% speedup.
- use Force::open_potential()
- replace ftell()/fseek() with rewind()/fgets() which is safer on windows and other platforms with automatic CR/LF to LF conversion on text files
- make parser use properly NULL terminated strings through using strtok()
- put a note into the manual
- reorder contents of the README file
- request for information should be sent to lammps-users
- add list of known missing features
This enables support to both drive LAMMPS with a Python interpreter and
evaluating Python expressions inside of LAMMPS using that same interpreter.
Previously this has been avoided through an error message because the
binding code did not ensure that the necessary GIL (global interpreter lock)
structures exist (see issue #438).
All code paths which call Python C API functions must first acquire the
GIL through a call PyGILState_Ensure and release it with PyGILState_Release.
There were several clean_copy() calls in pair
styles *outside device code*.
They seem to have been left over from an abandoned
effort to copy the Kokkos neighbor list as
a member of the pair style, instead of copying
out the individual views needed.
These leftover clean_copy() calls were setting
pointers to NULL that had not been freed,
leading to large memory leaks.
I've removed the clean_copy() function entirely,
and replaced it with the copymode flag system used
in many other Kokkos objects.
The copymode flag is only set to one in
functors that hold copies of the neighbor list.
There were several clean_copy() calls in pair
styles *outside device code*.
They seem to have been left over from an abandoned
effort to copy the Kokkos neighbor list as
a member of the pair style, instead of copying
out the individual views needed.
These leftover clean_copy() calls were setting
pointers to NULL that had not been freed,
leading to large memory leaks.
I've removed the clean_copy() function entirely,
and replaced it with the copymode flag system used
in many other Kokkos objects.
The copymode flag is only set to one in
functors that hold copies of the neighbor list.
- Moved the particle loop inside a replica of getMixingWeights, getMixingWeightsVect,
and refactored to improve vectorization.
- Added OMP SIMD and OMP threading directly inside that function but will replace with
kokkos parallel_for and parallel_reduce methods later.
The interface of that function has changed and includes two additional
parameters, which haven't been added to the Python interface either.
This showed up by trying to run the simple.py example.
Normally, the gzip process would be pinned to the same core as the
MPI rank 0 process, which makes the pipe stay in one core's cache,
but forces the two process to fight for that core, slowing things down.
Note: "newton on" still required if using non-kokkos pair styles or fixes.
Non-kokkos pairs/fixes don't expect their half lists with newton off,
which happens if newton is turned off globally by kokkos via commandline.
Note2: Regardless, fix_shardlow* will still use half lists and newton on.
two sort functions with different
names but identical functionality.
making them the same function
until we descide to use a different
algorithm for atoms and ghosts
KOKKOS_LAMBDA doesn't quite work on CUDA,
you have to use LAMMPS_LAMBDA.
Also, if you do use LAMMPS_LAMBDA, you need
to run on the default device type,
i.e. no using lambdas to run on OpenMP
when LAMMPS has been compiled for CUDA.
Uses the sphinxcontrib-spelling extension and requires PyEnchant and
aspell-en to be installed.
Adds the optional make target 'spelling' which produces the file
spelling/output.txt. It contains all words it detects.
Due to the large number of false positives, words in
utils/sphinx-config/false_positives.txt are ignored.
Add support for lock-free and deterministic use of Random_XorShift*_Pool
by giving state_idx selection and lock responsibility up to the
application. Done by an overload of get_state() to take sate_idx as
an argument that the appplication guarantees is concurrently unique
and within the range of num_states that the application passed to init().
In other words, this allows the RNG state to be associated with some
application specific index, rather than a runtime arbitrary thread ID,
and thus the application can control which work is performed using
which RNG in a deterministic manner, regardless of which thread
performs the work.
Random_XorShift*_Pool<Kokkos::Cuda>::free_state() has two purposes:
1) update the state value kept in the pool
2) unlock the state
For a CUDA host thread, ONLY skip step 2, not both.
SSA atom binning algorithm was adjusted to do as much work in
parallel while preserving deterministic behavior. The final
step is done serially to preserve deterministic behavior.
An alternative would be to sort the contents of the bins so
that they are always in the same order.
ssa_update_dpde() hangs on first use of rand_gen.normal()
Switching to not using a pointer to PairDPDfdtEnergyKokkos's rand_pool
had no noticble effect.
Eliminates a special case version of a loop just for Subphase 0.
NOTE: pair evaluation order changes, causing numerical differences!
This changed the order that close neighbors of ghosts are processed.
NOTE: pair evaluation order changes, causing numerical differences!
Atom pair processing order is fully planned out in npair_half_bin_newton_ssa
Makes the SSA neighbor list structure very different. Do not use by others!
Each local is in ilist, numneigh, and firstneigh four times instead of once.
Changes LAMMPS core code that had been previously changed for USER-DPD/SSA:
Removes ssaAIR[] from class Atom as it is now unused.
Removes ndxAIR_ssa[] from class NeighList as it is now unused.
Increases length of ilist[], numneigh[], and firstneigh[] if SSA flag set.
NOTE: pair evaluation order changes, causing numerical differences!
This enables processing neighbors in subphase groups that enforce
a geometrical seperation of pairs, allowing greater parallelism
once fix_shardlow (SSA) is converted to Kokkos.
This removes the the distinction between pure and impure locals.
Pure and impure locals messed up the directionality of half neighbor lists,
which turns out is crucial to the approach for SSA with kokkos.
Since we compute dvdw as d vdw / d rij, we have to also compute
dslw as d slw / d rij. Currently, we compute -1/r d slw/d rij,
which leads to incorrect results when the two are later combined.
Alternatively, one could also modify dvdw to be -1/r d vdw/d rij,
which would be a more standard way to do LJ calculations, but this
way seems more consistent.
- Switched from using lambda functions to operator()'s with type tags
in FixRxKokkos. The lambda's were giving big problems in Cuda with
the memory objects. This required that all referenced views be members
of the FixRXKokkos class.
- Add copymode controls to solve_reactions() to avoid the destructor
freeing pointers carried forward from the copy constructor. Added
the same to FixRX since its called, too.
- Updated the function prototypes to include the necessary KOKKOS
macros for __host__ and __device__ functions and inlined functions.
- Changed several View definitions to match the disjoint memory spaces
that only come up with Cuda builds.
- Finished porting all scratch arrays to using the StridedArrayType
template.
- Created a single, large Kokkos device array and using that for all
scratch data passed into the StridedArrayType objects.
- Created an Array class that provides stride access for operator[]
w/o needing Kokkos views. This was designed to avoid the performance
issues encountered with Views and sub-views throughout the RHS and
ODE solver functions.
- Added the diagnostics performance analysis routine to FixRxKokkos
using Kokkos views.
TODO:
- Switch to using Kokkos data for the per-iteration scratch data.
How to allocate only enouch for each work-unit and not all
iterations? Can the shared-memory scratch memory work for this,
even for large sizes?
usage and calls to computeLocalTemperature.
- Created request for kokkos neighbor list for fix and switched to
that neighbor list datatype in computeLocalTemperature.
- Reconfigured pre_force and setup_pre_force to call a common
solve_reactions() method to avoid duplicate code.
TODO:
- Clean-up
- Provide per-problem scratch data within kokkos framework (instead
of C++ new/delete data).
- Added a kokkos version of setup_pre_force that only sets dvector
and then communicates that.
- Converted all for loops to parallel_for's in computeLocalTemperator()
and setup_pre_force.
- Added pack/unpack forward/reverse methods with Kokkos host views.
TODO:
- The Kokkos neighbor list is not working. Need to request a Kokkos
neighbor list in ::init(). Then, replace objects like list->ilist[]
with k_list->d_ilist().
Added kokkos dual-view datatypes used in computeLocalTemperature and
pre_force (e.g., dpdThetaLocal) but still using the original host
pointers for the pack/unpack operations.
TODO:
- The Kokkos neighbor list is not working. Need to request a Kokkos
neighbor list in ::init(). Then, replace objects like list->ilist[]
with k_list->d_ilist().
- Add another template parameter for HALFTHREAD and create (automatic)
atomic view of dpdThetaLocal and sumWeights.
- Add modify/sync comments and replace the host-only pointers in the
pack/unpack methods.
- Added templated computeLocalTemp<>() to FixRxKokkos but still
using the original host data pointers.
- Updated the copy-back to dvector operation to be the same with
RK4 and RKF45 per discussion with J. Larentzos.
TODO:
- Add kokkos data for computeLocalTemp and parallel_for loop.
- Updated the KOKKOS installer to include the fix_rx_kokkos.[cpp,h].
- Updated the USER-DPD version of fix_rx.[cpp,h] to sync with the Kokkos
version. Solves child->parent class dependencies.
- Added kokkos-managed parameter data for the kinetics equations.
- Removed dependencies in rhs() on atom and domain objects.
TODO:
1. Switch to using KOKKOS data for dvector.
2. Port ComputeLocalTemp(...) to Kokkos (needs pairing algorithm).
Initial port of USER-DPD/fix_rx.cpp to KOKKOS/fix_rx_kokkos.cpp.
Using parallel_reduce(...) but still using host-only data.
TODO:
1. Switch to KOKKOS datatypes for sparse-kinetics data; dense
is finished.
2. Switch to using KOKKOS data for dvector.
3. Remove dependencies in rhs(...) on atom. Store those consts
in UserData{} or as member constants.
4. Port ComputeLocalTemp(...) to Kokkos (needs pairing algorithm).
Overall improvements range from 2% to 18% on our benchmarks
1) Newton has to be turned on for SSA, so remove those conditionals
2) Rework the math in ssa_update() to eliminate many ops and temporaries
3) Split ssa_update() into two versions, based on DPD vs. DPDE
4) Reorder code in ssa_update_*() to reduce register pressure
The code tries to make this distinction between the real distance (r23) and the facticious one (rij), but does not do so very well.
It is better if those two variables have the same value everywhere, and apply the correction where necessary.
The current way to use the values is incorrrect.
Remove those calculations that effectively are derivatives w.r.t. |rij| (the facticious distance), is constant and thus the chained derivative (d|rij|/dRij) is always zero.
Apply the corrections due to drij/dRij in the sum omega term.
The bonderorderLJ function operates on a facticious distance |rij|, i.e. everything gets calculated "as if" atoms i and j were a given distance alpha apart.
Mathematically, bondorderLJ is a function of rij (a vector), that is (in terms of the real distance Rij) rij = alpha * Rij/|Rij|.
When we calculate the forces in bondorderLJ, we have to make sure to chain in this derivative whenever we calculate derivatives w.r.t. rij.
The right correction, as it turns our, is Fij = alpha / |Rij| * (Identity(3,3) - Rij * Rij^T / |Rij|^2) * fij.
This commit only fixes this for the p_ij^sigma pi terms, which were modified to separate out the d/drij derivative in the cosine calculation.
Now, derivatives are taken w.r.t. the connecting edges instead of the edge points.
Since Etmp (representing sum_kijl omega_kijl * w_ik * w_jl) is not reset between the forward and reverse pass, the value used by later calculation will be twice the expected values.
One could instead reset Etmp between these passes, but there really is no reason to calculate it twice.
because the verlet_kokkos system has
a "clever" optimization which will
alter the datamasks before calling sync/modify,
so the datamask framework must be
strictly obeyed for GPU correctness.
(the optimization is to concurrently
compute forces on the host and GPU,
and add them up at the end of an iteration.
calling your own sync will overwrite
the partial GPU forces with the
partial host forces).
this variable is only used when FFTW3
is enabled, so its declaration and
initialization should be protected
under the same conditions to avoid
compiler warnings
the variable (offset) is only
used in a subset of numerous
scenarios with #ifdef, it seems
better just to have each loop
declare it as needed.
(avoids compiler warnings)
this variable is only used when FFTW3
is enabled, so its declaration and
initialization should be protected
under the same conditions to avoid
compiler warnings
this #ifdef adds a return statement
for little endian machines, but leaves
the old one, which the compiler comlains
is unreachable. this commit combines
the conditionals so we can use #else
Added explicit initialization (to zero) for several variables inside the
inner j-loop to avoid using them uninitialized or from prior iterations
within rmOldij_12 == 0.
i suspect, this communication cutoff adjustment was included into the code before it was possible to separately set it via comm_modify. stopping with an error message printing the needed/current value is cleaner, in keeping with other modules in LAMMPS and much less problematic.
an alternate route to address this issue would be to allow an "ANY" setting for neighbor list requests and then query the neighbor list for newton setting instead of the force class.
The class params_lj_coul was copy-pasted
into many different pair styles, and only
one of them had the proper KOKKOS_INLINE_FUNCTION
annotations for CUDA.
created a header file for this class that
most of the pair styles now include.
One pair style did add extra members,
so it keeps a local copy of the class.
the main bug here is the use of a local
rho_i accumulator which later gets assigned
back to rho[i].
in parallel, atomic additions can happen to
rho[i] while the local accumulator is held;
those atomic additions are lost when
the accumulator is atomically assigned.
we instead initialize the accumulator to zero
and atomically add it back to rho[i].
this should help tracking down input file errors for many
common cases without having to repeat the run with -echo screen
and avoid having to explain how to use that feature all the time
one Kokkos kernel was not annotated consistently,
STACKPARAMS was essentially uninitialized and
confused with a local variable,
plus lots of variables were unused in some
of the Kokkos kernels.
During dynamic load balancing, the subdomains will not be uniform so the
bbox size test in USER-DPD/fix_shardlow.cpp may only be called by one rank.
Using error->one allows any rank to stop the simulation in this scenario.
Added rcut and bbox information to help in diagnostics.
Since the Group class is completely
unaware of Kokkos, the direct calls from
FixMomentumKokkos to Group methods
need to be preceded by atomKK->sync calls
for every atom variable that Group intends
to use.
fix_momentum_kokkos definitely does not
work on GPUs prior to this commit.
Significant code cleanup and several fixes (walls + extended Lagrangian)
New harmonicWalls bias to apply confining boundaries with time-dependent force
constant & integration
1) Added MY_EPSILON to handle machine precision checks
2) Removed error checks for DPD-RX; enabled use with DPD-E simulations
3) Expanded the EOS functional form to allow corrections
in the thermo file or on the command line
4) Updated naming convention from fraction to mixWtSite*
5) Changed the name of getParams() method to getMixingWeights()
6) getMixingWeights() now handles fractional and molecular weighting
7) Added optional argument (fractional or molecular) to pair_style command
8) Added argument to specify the exp6 parameter scaling method
NOTE: Requires additional arguments in the pair coefficients,
thus command line areguments are NOT backward-compatible.
it is not an lvalue reference in CUDA.
also, the previous code assumed contiguous
entries for one atom; now it should be
robust in the case of LayoutLeft.
This makes our results more closely match a vetted serial implementation.
NOTE: This does make the output different from any previous versions.
Patch by Jim Larentzos. Applied by Tim Mattox.
instead of having pair_dpd_fdt* make the SSA-neighbor list request for it.
Forces an "extra" list to be built, but now skip lists work properly.
Maybe we can detect if skip lists won't be used, and squash the extra list.
The following changes were made:
- the modifications to compute pressure were transferred to a derived class compute pressure/grem
- fix scaleforce was renamed to fix grem
- identifying the grem fix was simplified as fix grem passes an additional argument to compute pressure/grem
- dead code was removed in both files
- checking of arguments was tightened
according to the package author, lars pastewka, some machines
may have only parallel netcdf and not the serial netcdf installed.
hence both netcdf dump styles neet to be optional depending on
the compile time setting in lib/netcdf/Makefile.lammps
The makefile has been set up to auto-detect the necessary flags
for most regular and correct installations.
Thanks to Giacomo Fiorin for figuring this out with NAMD/Colvars.
This requires linking with -Xlinker -export-dynamic or equivalent,
which is the default when using python-config to provide linker flags.
We will fall back to loading the DSO in case the initial load fails.
Includes documentation and examples.
NOTE: VV requires very small timesteps under isoenergetic conditions.
Consider using fix_shardlow instead, since this VV support is
primarily for comparison purposes.
The return value of `lammps_get_last_error_message` now encodes if the last
error was recoverable or should cause an `MPI_Abort`. The driving code is
responsible of reacting to the error and calling `MPI_Abort` on the
communicator it passed to the LAMMPS instance.
Thank your for considering to contribute to the LAMMPS software project.
The following is a set of guidelines as well as explanations of policies and workflows for contributing to the LAMMPS molecular dynamics software project. These guidelines focus on submitting issues or pull requests on the LAMMPS GitHub project.
Thus please also have a look at:
* [The Section on submitting new features for inclusion in LAMMPS of the Manual](http://lammps.sandia.gov/doc/Section_modify.html#mod-15)
* [The LAMMPS GitHub Tutorial in the Manual](http://lammps.sandia.gov/doc/tutorial_github.html)
## Table of Contents
[I don't want to read this whole thing, I just have a question!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question)
[How Can I Contribute?](#how-can-i-contribute)
* [Discussing How To Use LAMMPS](#discussing-how-to-use-lammps)
## I don't want to read this whole thing I just have a question!
> **Note:** Please do not file an issue to ask a general question about LAMMPS, its features, how to use specific commands, or how perform simulations or analysis in LAMMPS. Instead post your question to the ['lammps-users' mailing list](http://lammps.sandia.gov/mail.html). You do not need to be subscribed to post to the list (but a mailing list subscription avoids having your post delayed until it is approved by a mailing list moderator). Most posts to the mailing list receive a response within less than 24 hours. Before posting to the mailing list, please read the [mailing list guidelines](http://lammps.sandia.gov/guidelines.html). Following those guidelines will help greatly to get a helpful response. Always mention which LAMMPS version you are using.
## How Can I Contribute?
There are several ways how you can actively contribute to the LAMMPS project: you can discuss compiling and using LAMMPS, and solving LAMMPS related problems with other LAMMPS users on the lammps-users mailing list, you can report bugs or suggest enhancements by creating issues on GitHub (or posting them to the lammps-users mailing list), and you can contribute by submitting pull requests on GitHub or e-mail your code
to one of the [LAMMPS core developers](http://lammps.sandia.gov/authors.html). As you may see from the aforementioned developer page, the LAMMPS software package includes the efforts of a very large number of contributors beyond the principal authors and maintainers.
### Discussing How To Use LAMMPS
The LAMMPS mailing list is hosted at SourceForge. The mailing list began in 2005, and now includes tens of thousands of messages in thousands of threads. LAMMPS developers try to respond to posted questions in a timely manner, but there are no guarantees. Please consider that people live in different timezone and may not have time to answer e-mails outside of their work hours.
You can post to list by sending your email to lammps-users at lists.sourceforge.net (no subscription required), but before posting, please read the [mailing list guidelines](http://lammps.sandia.gov/guidelines.html) to maximize your chances to receive a helpful response.
Anyone can browse/search previous questions/answers in the archives. You do not have to subscribe to the list to post questions, receive answers (to your questions), or browse/search the archives. You **do** need to subscribe to the list if you want emails for **all** the posts (as individual messages or in digest form), or to answer questions yourself. Feel free to sign up and help us out! Answering questions from fellow LAMMPS users is a great way to pay back the community for providing you a useful tool for free, and to pass on the advice you have received yourself to others. It improves your karma and helps you understand your own research better.
If you post a message and you are a subscriber, your message will appear immediately. If you are not a subscriber, your message will be moderated, which typically takes one business day. Either way, when someone replies the reply will usually be sent to both, your personal email address and the mailing list. When replying to people, that responded to your post to the list, please always included the mailing list in your replies (i.e. use "Reply All" and **not** "Reply"). Responses will appear on the list in a few minutes, but it can take a few hours for postings and replies to show up in the SourceForge archive. Sending replies also to the mailing list is important, so that responses are archived and people with a similar issue can search for possible solutions in the mailing list archive.
### Reporting Bugs
While developers writing code for LAMMPS are careful to test their code, LAMMPS is such a large and complex software, that it is impossible to test for all combinations of features under all normal and not so normal circumstances. Thus bugs do happen, and if you suspect, that you have encountered one, please try to document it and report it as an [Issue](https://github.com/lammps/lammps/issues) on the LAMMPS GitHub project web page. However, before reporting a bug, you need to check whether this is something that may have already been corrected. The [Latest Features and Bug Fixes in LAMMPS](http://lammps.sandia.gov/bug.html) web page lists all significant changes to LAMMPS over the years. It also tells you what the current latest development version of LAMMPS is, and you should test whether your issue still applies to that version.
When you click on the green "New Issue" button, you will be provided with a text field, where you can enter your message. That text field with contain a template with several headlines and some descriptions. Keep the headlines that are relevant to your reported potential bug and replace the descriptions with the information as suggested by the descriptions.
You can also attach small text files (please add the file name extension `.txt` or it will be rejected), images, or small compressed text files (using gzip, do not use RAR or 7-ZIP or similar tools that are uncommon outside of Windows machines). In many cases, bugs are best illustrated by providing a small input deck (do **not** attach your entire production input, but remove everything that is not required to reproduce the issue, and scale down your system size, that the resulting calculation runs fast and can be run on small desktop quickly).
To be able to submit an issue on GitHub, you have to register for an account (for GitHub in general). If you do not want to do that, or have other reservations against submitting an issue there, you can - as an alternative and in decreasing preference - either send an e-mail to the lammps-users mailing list, the original authors of the feature that you suspect to be affected, or one or more of the core LAMMPS developers.
### Suggesting Enhancements
The LAMMPS developers welcome suggestions for enhancements or new features. These should be submitted using the [GitHub Issue Tracker](https://github.com/lammps/lammps/issues) of the LAMMPS project. This is particularly recommended, when you plan to implement the feature or enhancement yourself, as this allows to coordinate in case there are other similar or conflicting ongoing developments.
The LAMMPS developers will review your submission and consider implementing it. Whether this will actually happen depends on many factors: how difficult it would be, how much effort it would take, how many users would benefit from it, how well the individual developer would understand the underlying physics of the feature, and whether this is a feature that would fit into a software like LAMMPS, or would be better implemented as a separate tool. Because of these factors, it matters how well the suggested enhancement is formulated and the overall benefit is argued convincingly.
To be able to submit an issue on GitHub, you have to register for an account (for GitHub in general). If you do not want to do that, or have other reservations against submitting an issue there, you can - as an alternative - send an e-mail to the lammps-users mailing list.
### Contributing Code
We encourage users to submit new features or modifications for LAMMPS to the core developers so they can be added to the LAMMPS distribution. The preferred way to manage and coordinate this is by submitting a pull request at the LAMMPS project on GitHub. For any larger modifications or programming project, you are encouraged to contact the LAMMPS developers ahead of time, in order to discuss implementation strategies and coding guidelines, that will make it easier to integrate your contribution and result in less work for everybody involved. You are also encouraged to search through the list of open issues on GitHub and submit a new issue for a planned feature, so you would not duplicate the work of others (and possibly get scooped by them) or have your work duplicated by others.
How quickly your contribution will be integrated depends largely on how much effort it will cause to integrate and test it, how much it requires changes to the core code base, and of how much interest it is to the larger LAMMPS community. Please see below for a checklist of typical requirements. Once you have prepared everything, see [this tutorial](http://lammps.sandia.gov/doc/tutorial_github.html)
for instructions on how to submit your changes or new files through a GitHub pull request
Here is a checklist of steps you need to follow to submit a single file or user package for our consideration. Following these steps will save both you and us time. See existing files in packages in the source directory for examples. If you are uncertain, please ask on the lammps-users mailing list.
* All source files you provide must compile with the most current version of LAMMPS with multiple configurations. In particular you need to test compiling LAMMPS from scratch with `-DLAMMPS_BIGBIG` set in addition to the default `-DLAMMPS_SMALLBIG` setting. Your code will need to work correctly in serial and in parallel using MPI.
* For consistency with the rest of LAMMPS and especially, if you want your contribution(s) to be added to main LAMMPS code or one of its standard packages, it needs to be written in a style compatible with other LAMMPS source files. This means: 2-character indentation per level, no tabs, no lines over 80 characters. I/O is done via the C-style stdio library, class header files should not import any system headers outside <stdio.h>, STL containers should be avoided in headers, and forward declarations used where possible or needed. All added code should be placed into the LAMMPS_NS namespace or a sub-namespace; global or static variables should be avoided, as they conflict with the modular nature of LAMMPS and the C++ class structure. Header files must not import namespaces with using. This all is so the developers can more easily understand, integrate, and maintain your contribution and reduce conflicts with other parts of LAMMPS. This basically means that the code accesses data structures, performs its operations, and is formatted similar to other LAMMPS source files, including the use of the error class for error and warning messages.
* If you want your contribution to be added as a user-contributed feature, and it is a single file (actually a `<name>.cpp` and `<name>.h` file) it can be rapidly added to the USER-MISC directory. Include the one-line entry to add to the USER-MISC/README file in that directory, along with the 2 source files. You can do this multiple times if you wish to contribute several individual features.
* If you want your contribution to be added as a user-contribution and it is several related features, it is probably best to make it a user package directory with a name like USER-FOO. In addition to your new files, the directory should contain a README text file. The README should contain your name and contact information and a brief description of what your new package does. If your files depend on other LAMMPS style files also being installed (e.g. because your file is a derived class from the other LAMMPS class), then an Install.sh file is also needed to check for those dependencies. See other README and Install.sh files in other USER directories as examples. Send us a tarball of this USER-FOO directory.
* Your new source files need to have the LAMMPS copyright, GPL notice, and your name and email address at the top, like other user-contributed LAMMPS source files. They need to create a class that is inside the LAMMPS namespace. If the file is for one of the USER packages, including USER-MISC, then we are not as picky about the coding style (see above). I.e. the files do not need to be in the same stylistic format and syntax as other LAMMPS files, though that would be nice for developers as well as users who try to read your code.
* You **must** also create or extend a documentation file for each new command or style you are adding to LAMMPS. For simplicity and convenience, the documentation of groups of closely related commands or styles may be combined into a single file. This will be one file for a single-file feature. For a package, it might be several files. These are simple text files with a specific markup language, that are then auto-converted to HTML and PDF. The tools for this conversion are included in the source distribution, and the translation can be as simple as doing "make html pdf" in the doc folder. Thus the documentation source files must be in the same format and style as other `<name>.txt` files in the lammps/doc/src directory for similar commands and styles; use one or more of them as a starting point. A description of the markup can also be found in `lammps/doc/utils/txt2html/README.html` As appropriate, the text files can include links to equations (see doc/Eqs/*.tex for examples, we auto-create the associated JPG files), or figures (see doc/JPG for examples), or even additional PDF files with further details (see doc/PDF for examples). The doc page should also include literature citations as appropriate; see the bottom of doc/fix_nh.txt for examples and the earlier part of the same file for how to format the cite itself. The "Restrictions" section of the doc page should indicate that your command is only available if LAMMPS is built with the appropriate USER-MISC or USER-FOO package. See other user package doc files for examples of how to do this. The prerequisite for building the HTML format files are Python 3.x and virtualenv, the requirement for generating the PDF format manual is the htmldoc software. Please run at least "make html" and carefully inspect and proofread the resulting HTML format doc page before submitting your code.
* For a new package (or even a single command) you should include one or more example scripts demonstrating its use. These should run in no more than a couple minutes, even on a single processor, and not require large data files as input. See directories under examples/USER for examples of input scripts other users provided for their packages. These example inputs are also required for validating memory accesses and testing for memory leaks with valgrind
* If there is a paper of yours describing your feature (either the algorithm/science behind the feature itself, or its initial usage, or its implementation in LAMMPS), you can add the citation to the *.cpp source file. See src/USER-EFF/atom_vec_electron.cpp for an example. A LaTeX citation is stored in a variable at the top of the file and a single line of code that references the variable is added to the constructor of the class. Whenever a user invokes your feature from their input script, this will cause LAMMPS to output the citation to a log.cite file and prompt the user to examine the file. Note that you should only use this for a paper you or your group authored. E.g. adding a cite in the code for a paper by Nose and Hoover if you write a fix that implements their integrator is not the intended usage. That kind of citation should just be in the doc page you provide.
Finally, as a general rule-of-thumb, the more clear and self-explanatory you make your documentation and README files, and the easier you make it for people to get started, e.g. by providing example scripts, the more likely it is that users will try out your new feature.
If the new features/files are broadly useful we may add them as core files to LAMMPS or as part of a standard package. Else we will add them as a user-contributed file or package. Examples of user packages are in src sub-directories that start with USER. The USER-MISC package is simply a collection of (mostly) unrelated single files, which is the simplest way to have your contribution quickly added to the LAMMPS distribution. You can see a list of the both standard and user packages by typing "make package" in the LAMMPS src directory.
Note that by providing us files to release, you are agreeing to make them open-source, i.e. we can release them under the terms of the GPL, used as a license for the rest of LAMMPS. See Section 1.4 for details.
With user packages and files, all we are really providing (aside from the fame and fortune that accompanies having your name in the source code and on the Authors page of the LAMMPS WWW site), is a means for you to distribute your work to the LAMMPS user community, and a mechanism for others to easily try out your new feature. This may help you find bugs or make contact with new collaborators. Note that you are also implicitly agreeing to support your code which means answer questions, fix bugs, and maintain it if LAMMPS changes in some way that breaks it (an unusual event).
To be able to submit an issue on GitHub, you have to register for an account (for GitHub in general). If you do not want to do that, or have other reservations or difficulties to submit a pull request, you can - as an alternative - contact one or more of the core LAMMPS developers and ask if one of them would be interested in manually merging your code into LAMMPS and send them your source code. Since the effort to merge a pull request is a small fraction of the effort of integrating source code manually (which would usually be done by converting the contribution into a pull request), your chances to have your new code included quickly are the best with a pull request.
If you prefer to submit patches or full files, you should first make certain, that your code works correctly with the latest patch-level version of LAMMPS and contains all bug fixes from it. Then create a gzipped tar file of all changed or added files or a corresponding patch file using 'diff -u' or 'diff -c' and compress it with gzip. Please only use gzip compression, as this works well on all platforms.
## GitHub Workflows
This section briefly summarizes the steps that will happen **after** you have submitted either an issue or a pull request on the LAMMPS GitHub project page.
### Issues
After submitting an issue, one or more of the LAMMPS developers will review it and categorize it by assigning labels. Confirmed bug reports will be labeled `bug`; if the bug report also contains a suggestion for how to fix it, it will be labeled `bugfix`; if the issue is a feature request, it will be labeled `enhancement`. Other labels may be attached as well, depending on which parts of the LAMMPS code are affected. If the assessment is, that the issue does not warrant any changes, the `wontfix` label will be applied and if the submission is incorrect or something that should not be submitted as an issue, the `invalid` label will be applied. In both of the last two cases, the issue will then be closed without further action.
For feature requests, what happens next is that developers may comment on the viability or relevance of the request, discuss and make suggestions for how to implement it. If a LAMMPS developer or user is planning to implement the feature, the issue will be assigned to that developer. For developers, that are not yet listed as LAMMPS project collaborators, they will receive an invitation to be added to the LAMMPS project as a collaborator so they can get assigned. If the requested feature or enhancement is implemented, it will usually be submitted as a pull request, which will contain a reference to the issue number. And once the pull request is reviewed and accepted for inclusion into LAMMPS, the issue will be closed. For details on how pull requests are processed, please see below.
For bug reports, the next step is that one of the core LAMMPS developers will self-assign to the issue and try to confirm the bug. If confirmed, the `bug` label and potentially other labels are added to classify the issue and its impact to LAMMPS. Before confirming, further questions may be asked or requests for providing additional input files or details about the steps required to reproduce the issue. Any bugfix is likely to be submitted as a pull request (more about that below) and since most bugs require only local changes, the bugfix may be included in a pull request specifically set up to collect such local bugfixes or small enhancements. Once the bugfix is included in the master branch, the issue will be closed.
### Pull Requests
For submitting pull requests, there is a [detailed tutorial](http://lammps.sandia.gov/doc/tutorial_github.html) in the LAMMPS manual. Thus only a brief breakdown of the steps is presented here.
Immediately after the submission, the LAMMPS continuing integration server at ci.lammps.org will download your submitted branch and perform a simple compilation test, i.e. will test whether your submitted code can be compiled under various conditions. It will also do a check on whether your included documentation translates cleanly. Whether these tests are successful or fail will be recorded. If a test fails, please inspect the corresponding output on the CI server and take the necessary steps, if needed, so that the code can compile cleanly again. The test will be re-run each the pull request is updated with a push to the remote branch on GitHub.
Next a LAMMPS core developer will self-assign and do an overall technical assessment of the submission. If you are not yet registered as a LAMMPS collaborator, you will receive an invitation for that.
You may also receive comments and suggestions on the overall submission or specific details. If permitted, additional changes may be pushed into your pull request branch or a pull request may be filed in your LAMMPS fork on GitHub to include those changes.
The LAMMPS developer may then decide to assign the pull request to another developer (e.g. when that developer is more knowledgeable about the submitted feature or enhancement or has written the modified code). It may also happen, that additional developers are requested to provide a review and approve the changes. For submissions, that may change the general behavior of LAMMPS, or where a possibility of unwanted side effects exists, additional tests may be requested by the assigned developer.
If the assigned developer is satisfied and considers the submission ready for inclusion into LAMMPS, the pull request will be assigned to the LAMMPS lead developer, Steve Plimpton (@sjplimp), who will then have the final decision on whether the submission will be included, additional changes are required or it will be ultimately rejected. After the pull request is merged, you may delete the pull request branch in your personal LAMMPS fork.
Since the learning curve for git is quite steep for efficiently managing remote repositories, local and remote branches, pull requests and more, do not hesitate to ask questions, if you are not sure about how to do certain steps that are asked of you. Even if the changes asked of you do not make sense to you, they may be important for the LAMMPS developers. Please also note, that these all are guidelines and not set in stone.
_Is this a 'Bug Report' or a 'Suggestion for an Enhancement'?_
## Detailed Description (Enhancement Suggestion)
_Explain how you would like to see LAMMPS enhanced, what feature(s) you are looking for, provide references to relevant background information, and whether you are willing to implement the enhancement yourself or would like to participate in the implementation_
## LAMMPS Version (Bug Report)
_Please specify which LAMMPS version this issue was detected with. If this is not the latest development version, please stop and test that version, too, and report it here if the bug persists_
## Expected Behavior (Bug Report)
_Describe the expected behavior. Quote from the LAMMPS manual where needed or explain why the expected behavior is meaningful, especially when it differs from the manual_
## Actual Behavior (Bug Report)
_Describe the actual behavior, how it differs from the expected behavior, and how this can be observed. Try to be specific and do **not* use vague terms like "doesn't work" or "wrong result". Do not assume that the person reading this has any experience with or knowledge of your specific research._
## Steps to Reproduce (Bug Report)
_Describe the steps required to quickly reproduce the issue. You can attach (small) files to the section below or add URLs where to download an archive with all necessary files. Please try to create input that are as small as possible and run as fast as possible. NOTE: the less effort and time it takes to reproduce your issue, the more likely, that somebody will look into it._
## Further Information, Files, and Links
_Put any additional information here, attach relevant text or image files and URLs to external sites, e.g. relevant publications_
_Briefly describe the new feature(s), enhancement(s), or bugfix(es) included in this pull request. If this addresses an open GitHub Issue, mention the issue number, e.g. with `fixes #221` or `closes #135`, so that issue will be automatically closed when the pull request is merged_
## Author(s)
_Please state name and affiliation of the author or authors that should be credited with the changes in this pull request_
## Backward Compatibility
_Please state whether any changes in the pull request break backward compatibility for inputs, and - if yes - explain what has been changed and why_
## Implementation Notes
_Provide any relevant details about how the changes are implemented, how correctness was verified, how other features - if any - in LAMMPS are affected_
## Post Submission Checklist
_Please check the fields below as they are completed_
- [ ] The feature or features in this pull request is complete
- [ ] Suitable new documentation files and/or updates to the existing docs are included
- [ ] One or more example input decks are included
- [ ] The source code follows the LAMMPS formatting guidelines
## Further Information, Files, and Links
_Put any additional information here, attach relevant text or image files, and URLs to external sites (e.g. DOIs or webpages)_
set(LAMMPS_MEMALIGN"64"CACHESTRING"enables the use of the posix_memalign() call instead of malloc() when large chunks or memory are allocated by LAMMPS")
<p>The LAMMPS “version” is the date when it was released, such as 1 May
2010. LAMMPS is updated continuously. Whenever we fix a bug or add a
feature, we release it immediately, and post a notice on <aclass="reference external"href="http://lammps.sandia.gov/bug.html">this page of the WWW site</a>. Every 2-4 months one of the incremental releases
is subjected to more thorough testing and labeled as a <em>stable</em> version.</p>
<p>Each dated copy of LAMMPS contains all the
features and bug-fixes up to and including that version date. The
version date is printed to the screen and logfile every time you run
LAMMPS. It is also in the file src/version.h and in the LAMMPS
directory name created when you unpack a tarball, and at the top of
the first page of the manual (this page).</p>
<ulclass="simple">
<li>If you browse the HTML doc pages on the LAMMPS WWW site, they always
describe the most current version of LAMMPS.</li>
<li>If you browse the HTML doc pages included in your tarball, they
describe the version you have.</li>
<li>The <aclass="reference external"href="Manual.pdf">PDF file</a> on the WWW site or in the tarball is updated
about once per month. This is because it is large, and we don’t want
it to be part of every patch.</li>
<li>There is also a <aclass="reference external"href="Developer.pdf">Developer.pdf</a> file in the doc
directory, which describes the internal structure and algorithms of
LAMMPS.</li>
</ul>
<p>LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel
Simulator.</p>
<p>LAMMPS is a classical molecular dynamics simulation code designed to
run efficiently on parallel computers. It was developed at Sandia
National Laboratories, a US Department of Energy facility, with
funding from the DOE. It is an open-source code, distributed freely
under the terms of the GNU Public License (GPL).</p>
<p>The current core group of LAMMPS developers is at Sandia National
Labs and Temple University:</p>
<ulclass="simple">
<li><aclass="reference external"href="http://www.sandia.gov/~sjplimp">Steve Plimpton</a>, sjplimp at sandia.gov</li>
<li>Aidan Thompson, athomps at sandia.gov</li>
<li>Stan Moore, stamoore at sandia.gov</li>
<li><aclass="reference external"href="http://goo.gl/1wk0">Axel Kohlmeyer</a>, akohlmey at gmail.com</li>
</ul>
<p>Past core developers include Paul Crozier, Ray Shan and Mark Stevens,
all at Sandia. The <strong>LAMMPS home page</strong> at
<aclass="reference external"href="http://lammps.sandia.gov">http://lammps.sandia.gov</a> has more information
about the code and its uses. Interaction with external LAMMPS developers,
bug reports and feature requests are mainly coordinated through the
<aclass="reference external"href="https://github.com/lammps/lammps">LAMMPS project on GitHub.</a>
The lammps.org domain, currently hosting <aclass="reference external"href="https://ci.lammps.org/job/lammps/">public continuous integration testing</a> and <aclass="reference external"href="http://rpm.lammps.org">precompiled Linux RPM and Windows installer packages</a> is located
at Temple University and managed by Richard Berger,
richard.berger at temple.edu.</p>
<hrclass="docutils"/>
<p>The LAMMPS documentation is organized into the following sections. If
you find errors or omissions in this manual or have suggestions for
useful information to add, please send an email to the developers so
we can improve the LAMMPS documentation.</p>
<p>Once you are familiar with LAMMPS, you may want to bookmark <aclass="reference internal"href="Section_commands.html#comm"><spanclass="std std-ref">this page</span></a> at Section_commands.html#comm since
it gives quick access to documentation for all LAMMPS commands.</p>
<p><aclass="reference external"href="Manual.pdf">PDF file</a> of the entire manual, generated by
<liclass="toctree-l2"><aclass="reference internal"href="Section_start.html#what-s-in-the-lammps-distribution">2.1. What’s in the LAMMPS distribution</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_start.html#making-lammps">2.2. Making LAMMPS</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_start.html#making-lammps-with-optional-packages">2.3. Making LAMMPS with optional packages</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_start.html#building-lammps-via-the-make-py-tool">2.4. Building LAMMPS via the Make.py tool</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_start.html#building-lammps-as-a-library">2.5. Building LAMMPS as a library</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_start.html#tips-for-users-of-previous-lammps-versions">2.9. Tips for users of previous LAMMPS versions</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_accelerate.html#general-strategies">5.2. General strategies</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_accelerate.html#packages-with-optimized-styles">5.3. Packages with optimized styles</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_accelerate.html#comparison-of-various-accelerator-packages">5.4. Comparison of various accelerator packages</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_howto.html#charmm-amber-and-dreiding-force-fields">6.3. CHARMM, AMBER, and DREIDING force fields</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_howto.html#running-multiple-simulations-from-one-input-script">6.4. Running multiple simulations from one input script</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_howto.html#tip3p-water-model">6.7. TIP3P water model</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_howto.html#tip4p-water-model">6.8. TIP4P water model</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_howto.html#spc-water-model">6.9. SPC water model</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_howto.html#coupling-lammps-to-other-codes">6.10. Coupling LAMMPS to other codes</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_howto.html#calculating-a-diffusion-coefficient">6.22. Calculating a diffusion coefficient</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_howto.html#using-chunks-to-calculate-system-properties">6.23. Using chunks to calculate system properties</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_howto.html#setting-parameters-for-the-kspace-style-pppm-disp-command">6.24. Setting parameters for the <codeclass="docutils literal"><spanclass="pre">kspace_style</span><spanclass="pre">pppm/disp</span></code> command</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_modify.html#submitting-new-features-for-inclusion-in-lammps">10.15. Submitting new features for inclusion in LAMMPS</a></li>
</ul>
</li>
<liclass="toctree-l1"><aclass="reference internal"href="Section_python.html">11. Python interface to LAMMPS</a><ul>
<liclass="toctree-l2"><aclass="reference internal"href="Section_python.html#overview-of-running-lammps-from-python">11.1. Overview of running LAMMPS from Python</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_python.html#overview-of-using-python-from-a-lammps-script">11.2. Overview of using Python from a LAMMPS script</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_python.html#building-lammps-as-a-shared-library">11.3. Building LAMMPS as a shared library</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_python.html#installing-the-python-wrapper-into-python">11.4. Installing the Python wrapper into Python</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_python.html#extending-python-with-mpi-to-run-in-parallel">11.5. Extending Python with MPI to run in parallel</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_python.html#testing-the-python-lammps-interface">11.6. Testing the Python-LAMMPS interface</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_python.html#using-lammps-from-python">11.7. Using LAMMPS from Python</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="Section_python.html#example-python-scripts-that-use-lammps">11.8. Example Python scripts that use LAMMPS</a></li>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
<liclass="toctree-l2"><aclass="reference internal"href="#comparison-of-various-accelerator-packages">5.4. Comparison of various accelerator packages</a></li>
<p>Before trying to make your simulation run faster, you should
understand how it currently performs and where the bottlenecks are.</p>
<p>The best way to do this is run the your system (actual number of
atoms) for a modest number of timesteps (say 100 steps) on several
different processor counts, including a single processor if possible.
Do this for an equilibrium version of your system, so that the
100-step timings are representative of a much longer run. There is
typically no need to run for 1000s of timesteps to get accurate
timings; you can simply extrapolate from short runs.</p>
<p>For the set of runs, look at the timing data printed to the screen and
log file at the end of each LAMMPS run. <aclass="reference internal"href="Section_start.html#start-8"><spanclass="std std-ref">This section</span></a> of the manual has an overview.</p>
<p>Running on one (or a few processors) should give a good estimate of
the serial performance and what portions of the timestep are taking
the most time. Running the same problem on a few different processor
counts should give an estimate of parallel scalability. I.e. if the
simulation runs 16x faster on 16 processors, its 100% parallel
efficient; if it runs 8x faster on 16 processors, it’s 50% efficient.</p>
<p>The most important data to look at in the timing info is the timing
breakdown and relative percentages. For example, trying different
options for speeding up the long-range solvers will have little impact
if they only consume 10% of the run time. If the pairwise time is
dominating, you may want to look at GPU or OMP versions of the pair
style, as discussed below. Comparing how the percentages change as
you increase the processor count gives you a sense of how different
operations within the timestep are scaling. Note that if you are
running with a Kspace solver, there is additional output on the
breakdown of the Kspace time. For PPPM, this includes the fraction
spent on FFTs, which can be communication intensive.</p>
<p>Another important detail in the timing info are the histograms of
atoms counts and neighbor counts. If these vary widely across
processors, you have a load-imbalance issue. This often results in
inaccurate relative timing data, because processors have to wait when
communication occurs for other processors to catch up. Thus the
reported times for “Communication” or “Other” may be higher than they
really are, due to load-imbalance. If this is an issue, you can
uncomment the MPI_Barrier() lines in src/timer.cpp, and recompile
LAMMPS, to obtain synchronized timings.</p>
<hrclass="docutils"/>
</div>
<divclass="section"id="general-strategies">
<spanid="acc-2"></span><h2>5.2. General strategies</h2>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">this section 5.2 is still a work in progress</p>
</div>
<p>Here is a list of general ideas for improving simulation performance.
Most of them are only applicable to certain models and certain
bottlenecks in the current performance, so let the timing data you
generate be your guide. It is hard, if not impossible, to predict how
much difference these options will make, since it is a function of
problem size, number of processors used, and your machine. There is
no substitute for identifying performance bottlenecks, and trying out
various options.</p>
<ulclass="simple">
<li>rRESPA</li>
<li>2-FFT PPPM</li>
<li>Staggered PPPM</li>
<li>single vs double PPPM</li>
<li>partial charge PPPM</li>
<li>verlet/split run style</li>
<li>processor command for proc layout and numa layout</li>
<li>load-balancing: balance and fix balance</li>
</ul>
<p>2-FFT PPPM, also called <em>analytic differentiation</em> or <em>ad</em> PPPM, uses
2 FFTs instead of the 4 FFTs used by the default <em>ik differentiation</em>
PPPM. However, 2-FFT PPPM also requires a slightly larger mesh size to
achieve the same accuracy as 4-FFT PPPM. For problems where the FFT
cost is the performance bottleneck (typically large problems running
on many processors), 2-FFT PPPM may be faster than 4-FFT PPPM.</p>
<p>Staggered PPPM performs calculations using two different meshes, one
shifted slightly with respect to the other. This can reduce force
aliasing errors and increase the accuracy of the method, but also
doubles the amount of work required. For high relative accuracy, using
staggered PPPM allows one to half the mesh size in each dimension as
compared to regular PPPM, which can give around a 4x speedup in the
kspace time. However, for low relative accuracy, using staggered PPPM
gives little benefit and can be up to 2x slower in the kspace
time. For example, the rhodopsin benchmark was run on a single
processor, and results for kspace time vs. relative accuracy for the
different methods are shown in the figure below. For this system,
staggered PPPM (using ik differentiation) becomes useful when using a
relative accuracy of slightly greater than 1e-5 and above.</p>
<spanid="acc-3"></span><h2>5.3. Packages with optimized styles</h2>
<p>Accelerated versions of various <aclass="reference internal"href="pair_style.html"><spanclass="doc">pair_style</span></a>,
<aclass="reference internal"href="fix.html"><spanclass="doc">fixes</span></a>, <aclass="reference internal"href="compute.html"><spanclass="doc">computes</span></a>, and other commands have
been added to LAMMPS, which will typically run faster than the
standard non-accelerated versions. Some require appropriate hardware
to be present on your system, e.g. GPUs or Intel Xeon Phi
coprocessors.</p>
<p>All of these commands are in packages provided with LAMMPS. An
overview of packages is give in <aclass="reference internal"href="Section_packages.html"><spanclass="doc">Section packages</span></a>.</p>
<p>These are the accelerator packages
currently in LAMMPS, either as standard or user packages:</p>
<trclass="row-even"><td>enable specific accelerator support via ‘-k on’<aclass="reference internal"href="Section_start.html#start-7"><spanclass="std std-ref">command-line switch</span></a>,</td>
<td>only needed for KOKKOS package</td>
</tr>
<trclass="row-odd"><td>set any needed options for the package via “-pk”<aclass="reference internal"href="Section_start.html#start-7"><spanclass="std std-ref">command-line switch</span></a> or <aclass="reference internal"href="package.html"><spanclass="doc">package</span></a> command,</td>
<td>only if defaults need to be changed</td>
</tr>
<trclass="row-even"><td>use accelerated styles in your input via “-sf”<aclass="reference internal"href="Section_start.html#start-7"><spanclass="std std-ref">command-line switch</span></a> or <aclass="reference internal"href="suffix.html"><spanclass="doc">suffix</span></a> command</td>
<td>lmp_machine -in in.script -sf gpu</td>
</tr>
</tbody>
</table>
<p>Note that the first 4 steps can be done as a single command, using the
src/Make.py tool. This tool is discussed in <aclass="reference internal"href="Section_start.html#start-4"><spanclass="std std-ref">Section 2.4</span></a> of the manual, and its use is
illustrated in the individual accelerator sections. Typically these
steps only need to be done once, to create an executable that uses one
or more accelerator packages.</p>
<p>The last 4 steps can all be done from the command-line when LAMMPS is
launched, without changing your input script, as illustrated in the
individual accelerator sections. Or you can add
<aclass="reference internal"href="package.html"><spanclass="doc">package</span></a> and <aclass="reference internal"href="suffix.html"><spanclass="doc">suffix</span></a> commands to your input
script.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">With a few exceptions, you can build a single LAMMPS executable
with all its accelerator packages installed. Note however that the
USER-INTEL and KOKKOS packages require you to choose one of their
hardware options when building for a specific platform. I.e. CPU or
Phi option for the USER-INTEL package. Or the OpenMP, Cuda, or Phi
option for the KOKKOS package.</p>
</div>
<p>These are the exceptions. You cannot build a single executable with:</p>
<ulclass="simple">
<li>both the USER-INTEL Phi and KOKKOS Phi options</li>
<li>the USER-INTEL Phi or Kokkos Phi option, and the GPU package</li>
</ul>
<p>See the examples/accelerate/README and make.list files for sample
Make.py commands that build LAMMPS with any or all of the accelerator
packages. As an example, here is a command that builds with all the
GPU related packages installed (GPU, KOKKOS with Cuda), including
settings to build the needed auxiliary GPU libraries for Kepler GPUs:</p>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
<p>The LAMMPS distribution includes an examples sub-directory with many
sample problems. Many are 2d models that run quickly are are
straightforward to visualize, requiring at most a couple of minutes to
run on a desktop machine. Each problem has an input script (in.*) and
produces a log file (log.*) when it runs. Some use a data file
(data.*) of initial coordinates as additional input. A few sample log
file run on different machines and different numbers of processors are
included in the directories to compare your answers to. E.g. a log
file like log.date.crack.foo.P means the “crack” example was run on P
processors of machine “foo” on that date (i.e. with that version of
LAMMPS).</p>
<p>Many of the input files have commented-out lines for creating dump
files and image files.</p>
<p>If you uncomment the <aclass="reference internal"href="dump.html"><spanclass="doc">dump</span></a> command in the input script, a
text dump file will be produced, which can be animated by various
<aclass="reference external"href="http://lammps.sandia.gov/viz.html">visualization programs</a>. It can
also be animated using the xmovie tool described in the <aclass="reference internal"href="Section_tools.html"><spanclass="doc">Additional Tools</span></a> section of the LAMMPS documentation.</p>
<p>If you uncomment the <aclass="reference internal"href="dump.html"><spanclass="doc">dump image</span></a> command in the input
script, and assuming you have built LAMMPS with a JPG library, JPG
snapshot images will be produced when the simulation runs. They can
be quickly post-processed into a movie using commands described on the
<p>Animations of many of the examples can be viewed on the Movies section
of the <aclass="reference external"href="http://lammps.sandia.gov">LAMMPS web site</a>.</p>
<p>There are two kinds of sub-directories in the examples dir. Lowercase
dirs contain one or a few simple, quick-to-run problems. Uppercase
dirs contain up to several complex scripts that illustrate a
particular kind of simulation method or model. Some of these run for
longer times, e.g. to measure a particular quantity.</p>
<p>Lists of both kinds of directories are given below.</p>
<hrclass="docutils"/>
<divclass="section"id="lowercase-directories">
<h2>7.1. Lowercase directories</h2>
<tableborder="1"class="docutils">
<colgroup>
<colwidth="16%"/>
<colwidth="84%"/>
</colgroup>
<tbodyvalign="top">
<trclass="row-odd"><td>accelerate</td>
<td>run with various acceleration options (OpenMP, GPU, Phi)</td>
</tr>
<trclass="row-even"><td>balance</td>
<td>dynamic load balancing, 2d system</td>
</tr>
<trclass="row-odd"><td>body</td>
<td>body particles, 2d system</td>
</tr>
<trclass="row-even"><td>colloid</td>
<td>big colloid particles in a small particle solvent, 2d system</td>
</tr>
<trclass="row-odd"><td>comb</td>
<td>models using the COMB potential</td>
</tr>
<trclass="row-even"><td>coreshell</td>
<td>core/shell model using CORESHELL package</td>
</tr>
<trclass="row-odd"><td>crack</td>
<td>crack propagation in a 2d solid</td>
</tr>
<trclass="row-even"><td>deposit</td>
<td>deposit atoms and molecules on a surface</td>
</tr>
<trclass="row-odd"><td>dipole</td>
<td>point dipolar particles, 2d system</td>
</tr>
<trclass="row-even"><td>dreiding</td>
<td>methanol via Dreiding FF</td>
</tr>
<trclass="row-odd"><td>eim</td>
<td>NaCl using the EIM potential</td>
</tr>
<trclass="row-even"><td>ellipse</td>
<td>ellipsoidal particles in spherical solvent, 2d system</td>
</tr>
<trclass="row-odd"><td>flow</td>
<td>Couette and Poiseuille flow in a 2d channel</td>
</tr>
<trclass="row-even"><td>friction</td>
<td>frictional contact of spherical asperities between 2d surfaces</td>
</tr>
<trclass="row-odd"><td>hugoniostat</td>
<td>Hugoniostat shock dynamics</td>
</tr>
<trclass="row-even"><td>indent</td>
<td>spherical indenter into a 2d solid</td>
</tr>
<trclass="row-odd"><td>kim</td>
<td>use of potentials in Knowledge Base for Interatomic Models (KIM)</td>
</tr>
<trclass="row-even"><td>meam</td>
<td>MEAM test for SiC and shear (same as shear examples)</td>
</tr>
<trclass="row-odd"><td>melt</td>
<td>rapid melt of 3d LJ system</td>
</tr>
<trclass="row-even"><td>micelle</td>
<td>self-assembly of small lipid-like molecules into 2d bilayers</td>
</tr>
<trclass="row-odd"><td>min</td>
<td>energy minimization of 2d LJ melt</td>
</tr>
<trclass="row-even"><td>msst</td>
<td>MSST shock dynamics</td>
</tr>
<trclass="row-odd"><td>nb3b</td>
<td>use of nonbonded 3-body harmonic pair style</td>
</tr>
<trclass="row-even"><td>neb</td>
<td>nudged elastic band (NEB) calculation for barrier finding</td>
</tr>
<trclass="row-odd"><td>nemd</td>
<td>non-equilibrium MD of 2d sheared system</td>
</tr>
<trclass="row-even"><td>obstacle</td>
<td>flow around two voids in a 2d channel</td>
</tr>
<trclass="row-odd"><td>peptide</td>
<td>dynamics of a small solvated peptide chain (5-mer)</td>
</tr>
<trclass="row-even"><td>peri</td>
<td>Peridynamic model of cylinder impacted by indenter</td>
</tr>
<trclass="row-odd"><td>pour</td>
<td>pouring of granular particles into a 3d box, then chute flow</td>
</tr>
<trclass="row-even"><td>prd</td>
<td>parallel replica dynamics of vacancy diffusion in bulk Si</td>
</tr>
<trclass="row-odd"><td>python</td>
<td>using embedded Python in a LAMMPS input script</td>
</tr>
<trclass="row-even"><td>qeq</td>
<td>use of the QEQ package for charge equilibration</td>
</tr>
<trclass="row-odd"><td>reax</td>
<td>RDX and TATB models using the ReaxFF</td>
</tr>
<trclass="row-even"><td>rigid</td>
<td>rigid bodies modeled as independent or coupled</td>
</tr>
<trclass="row-odd"><td>shear</td>
<td>sideways shear applied to 2d solid, with and without a void</td>
</tr>
<trclass="row-even"><td>snap</td>
<td>NVE dynamics for BCC tantalum crystal using SNAP potential</td>
</tr>
<trclass="row-odd"><td>srd</td>
<td>stochastic rotation dynamics (SRD) particles as solvent</td>
</tr>
<trclass="row-even"><td>streitz</td>
<td>use of Streitz/Mintmire potential with charge equilibration</td>
</tr>
<trclass="row-odd"><td>tad</td>
<td>temperature-accelerated dynamics of vacancy diffusion in bulk Si</td>
</tr>
<trclass="row-even"><td>vashishta</td>
<td>use of the Vashishta potential</td>
</tr>
</tbody>
</table>
<p>Here is how you can run and visualize one of the sample problems:</p>
<preclass="literal-block">
cd indent
cp ../../src/lmp_linux . # copy LAMMPS executable to this dir
lmp_linux -in in.indent # run the problem
</pre>
<p>Running the simulation produces the files <em>dump.indent</em> and
<em>log.lammps</em>. You can visualize the dump file of snapshots with a
variety of 3rd-party tools highlighted on the
<aclass="reference external"href="http://lammps.sandia.gov/viz.html">Visualization</a> page of the LAMMPS
web site.</p>
<p>If you uncomment the <aclass="reference internal"href="dump_image.html"><spanclass="doc">dump image</span></a> line(s) in the input
script a series of JPG images will be produced by the run (assuming
you built LAMMPS with JPG support; see <aclass="reference internal"href="Section_start.html"><spanclass="doc">Section start 2.2</span></a> for details). These can be viewed
individually or turned into a movie or animated by tools like
ImageMagick or QuickTime or various Windows-based tools. See the
<aclass="reference internal"href="dump_image.html"><spanclass="doc">dump image</span></a> doc page for more details. E.g. this
Imagemagick command would create a GIF file suitable for viewing in a
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
<p>As of summer 2016 we are using the <aclass="reference external"href="https://github.com/lammps/lammps/issues">LAMMPS project issue tracker on GitHub</a> for keeping
track of suggested, planned or pending new features. This includes
discussions of how to best implement them, or why they would be
useful. Especially if a planned or proposed feature is non-trivial
to add, e.g. because it requires changes to some of the core
classes of LAMMPS, people planning to contribute a new feature to
LAMMS are encouraged to submit an issue about their planned
implementation this way in order to receive feedback from the
LAMMPS core developers. They will provide suggestions about
the validity of the proposed approach and possible improvements,
pitfalls or alternatives.</p>
<p>Please see some of the closed issues for examples of how to
suggest code enhancements, submit proposed changes, or report
elated issues and how they are resoved.</p>
<p>As an alternative to using GitHub, you may e-mail the
<aclass="reference external"href="http://lammps.sandia.gov/authors.html">core developers</a> or send
an e-mail to the <aclass="reference external"href="http://lammps.sandia.gov/mail.html">LAMMPS Mail list</a>
if you want to have your suggestion added to the list.</p>
<hrclass="docutils"/>
</div>
<divclass="section"id="past-versions">
<spanid="hist-2"></span><h2>13.2. Past versions</h2>
<p>LAMMPS development began in the mid 1990s under a cooperative research
& development agreement (CRADA) between two DOE labs (Sandia and LLNL)
and 3 companies (Cray, Bristol Myers Squibb, and Dupont). The goal was
to develop a large-scale parallel classical MD code; the coding effort
was led by Steve Plimpton at Sandia.</p>
<p>After the CRADA ended, a final F77 version, LAMMPS 99, was
released. As development of LAMMPS continued at Sandia, its memory
management was converted to F90; a final F90 version was released as
LAMMPS 2001.</p>
<p>The current LAMMPS is a rewrite in C++ and was first publicly released
as an open source code in 2004. It includes many new features beyond
those in LAMMPS 99 or 2001. It also includes features from older
parallel MD codes written at Sandia, namely ParaDyn, Warp, and
GranFlow (see below).</p>
<p>In late 2006 we began merging new capabilities into LAMMPS that were
developed by Aidan Thompson at Sandia for his MD code GRASP, which has
a parallel framework similar to LAMMPS. Most notably, these have
included many-body potentials - Stillinger-Weber, Tersoff, ReaxFF -
and the associated charge-equilibration routines needed for ReaxFF.</p>
<p>The <aclass="reference external"href="http://lammps.sandia.gov/history.html">History link</a> on the
LAMMPS WWW page gives a timeline of features added to the
C++ open-source version of LAMMPS over the last several years.</p>
<p>These older codes are available for download from the <aclass="reference external"href="http://lammps.sandia.gov">LAMMPS WWW site</a>, except for Warp & GranFlow which were primarily used
internally. A brief listing of their features is given here.</p>
<p>LAMMPS 2001</p>
<ulclass="simple">
<li>F90 + MPI</li>
<li>dynamic memory</li>
<li>spatial-decomposition parallelism</li>
<li>NVE, NVT, NPT, NPH, rRESPA integrators</li>
<li>LJ and Coulombic pairwise force fields</li>
<li>all-atom, united-atom, bead-spring polymer force fields</li>
<li>CHARMM-compatible force fields</li>
<li>class 2 force fields</li>
<li>3d/2d Ewald & PPPM</li>
<li>various force and temperature constraints</li>
<li>SHAKE</li>
<li>Hessian-free truncated-Newton minimizer</li>
<li>user-defined diagnostics</li>
</ul>
<p>LAMMPS 99</p>
<ulclass="simple">
<li>F77 + MPI</li>
<li>static memory allocation</li>
<li>spatial-decomposition parallelism</li>
<li>most of the LAMMPS 2001 features with a few exceptions</li>
<li>no 2d Ewald & PPPM</li>
<li>molecular force fields are missing a few CHARMM terms</li>
<li>no SHAKE</li>
</ul>
<p>Warp</p>
<ulclass="simple">
<li>F90 + MPI</li>
<li>spatial-decomposition parallelism</li>
<li>embedded atom method (EAM) metal potentials + LJ</li>
<li>lattice and grain-boundary atom creation</li>
<li>NVE, NVT integrators</li>
<li>boundary conditions for applying shear stresses</li>
<li>temperature controls for actively sheared systems</li>
<li>per-atom energy and centro-symmetry computation and output</li>
</ul>
<p>ParaDyn</p>
<ulclass="simple">
<li>F77 + MPI</li>
<li>atom- and force-decomposition parallelism</li>
<li>embedded atom method (EAM) metal potentials</li>
<li>lattice atom creation</li>
<li>NVE, NVT, NPT integrators</li>
<li>all serial DYNAMO features for controls and constraints</li>
</ul>
<p>GranFlow</p>
<ulclass="simple">
<li>F90 + MPI</li>
<li>spatial-decomposition parallelism</li>
<li>frictional granular potentials</li>
<li>NVE integrator</li>
<li>boundary conditions for granular flow and packing and walls</li>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
<li>force-field compatibility with common CHARMM, AMBER, DREIDING, OPLS, GROMACS, COMPASS options</li>
<li>access to <aclass="reference external"href="http://openkim.org">KIM archive</a> of potentials via <aclass="reference internal"href="pair_kim.html"><spanclass="doc">pair kim</span></a></li>
<li>hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can be used in one simulation</li>
<li>overlaid potentials: superposition of multiple pair potentials</li>
<li>energy minimization via conjugate gradient or steepest descent relaxation</li>
<li>rRESPA hierarchical timestepping</li>
<li>rerun command for post-processing of dump files</li>
</ul>
</div>
<divclass="section"id="diagnostics">
<h3>1.2.7. Diagnostics</h3>
<ulclass="simple">
<li>see the various flavors of the <aclass="reference internal"href="fix.html"><spanclass="doc">fix</span></a> and <aclass="reference internal"href="compute.html"><spanclass="doc">compute</span></a> commands</li>
<li>Various pre- and post-processing serial tools are packaged
with LAMMPS; see these <aclass="reference internal"href="Section_tools.html"><spanclass="doc">doc pages</span></a>.</li>
<li>Our group has also written and released a separate toolkit called
<aclass="reference external"href="http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</a> which provides tools for doing setup, analysis,
plotting, and visualization for LAMMPS simulations. Pizza.py is
written in <aclass="reference external"href="http://www.python.org">Python</a> and is available for download from <aclass="reference external"href="http://www.sandia.gov/~sjplimp/pizza.html">the Pizza.py WWW site</a>.</li>
</ul>
</div>
<divclass="section"id="specialized-features">
<h3>1.2.11. Specialized features</h3>
<p>These are LAMMPS capabilities which you may not think of as typical
molecular dynamics options:</p>
<ulclass="simple">
<li><aclass="reference internal"href="balance.html"><spanclass="doc">static</span></a> and <aclass="reference internal"href="fix_balance.html"><spanclass="doc">dynamic load-balancing</span></a></li>
<li><aclass="reference internal"href="fix_ipi.html"><spanclass="doc">path-integral molecular dynamics (PIMD)</span></a> and <aclass="reference internal"href="fix_pimd.html"><spanclass="doc">this as well</span></a></li>
<li>Monte Carlo via <aclass="reference internal"href="fix_gcmc.html"><spanclass="doc">GCMC</span></a> and <aclass="reference internal"href="fix_tfmc.html"><spanclass="doc">tfMC</span></a><aclass="reference internal"href="fix_atom_swap.html"><spanclass="doc">atom swapping</span></a> and <aclass="reference internal"href="fix_bond_swap.html"><spanclass="doc">bond swapping</span></a></li>
<li><aclass="reference internal"href="pair_dsmc.html"><spanclass="doc">Direct Simulation Monte Carlo</span></a> for low-density fluids</li>
<li>perform sophisticated analyses of your MD simulation</li>
<li>visualize your MD simulation</li>
<li>plot your output data</li>
</ul>
<p>A few tools for pre- and post-processing tasks are provided as part of
the LAMMPS package; they are described in <aclass="reference internal"href="Section_tools.html"><spanclass="doc">this section</span></a>. However, many people use other codes or
write their own tools for these tasks.</p>
<p>As noted above, our group has also written and released a separate
toolkit called <aclass="reference external"href="http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</a> which addresses some of the listed
bullets. It provides tools for doing setup, analysis, plotting, and
visualization for LAMMPS simulations. Pizza.py is written in
<aclass="reference external"href="http://www.python.org">Python</a> and is available for download from <aclass="reference external"href="http://www.sandia.gov/~sjplimp/pizza.html">the Pizza.py WWW site</a>.</p>
<p>LAMMPS requires as input a list of initial atom coordinates and types,
molecular topology information, and force-field coefficients assigned
to all atoms and bonds. LAMMPS will not build molecular systems and
assign force-field parameters for you.</p>
<p>For atomic systems LAMMPS provides a <aclass="reference internal"href="create_atoms.html"><spanclass="doc">create_atoms</span></a>
command which places atoms on solid-state lattices (fcc, bcc,
user-defined, etc). Assigning small numbers of force field
coefficients can be done via the <aclass="reference internal"href="pair_coeff.html"><spanclass="doc">pair coeff</span></a>, <aclass="reference internal"href="bond_coeff.html"><spanclass="doc">bond coeff</span></a>, <aclass="reference internal"href="angle_coeff.html"><spanclass="doc">angle coeff</span></a>, etc commands.
For molecular systems or more complicated simulation geometries, users
typically use another code as a builder and convert its output to
LAMMPS input format, or write their own code to generate atom
coordinate and molecular topology for LAMMPS to read in.</p>
<p>For complicated molecular systems (e.g. a protein), a multitude of
topology information and hundreds of force-field coefficients must
typically be specified. We suggest you use a program like
<aclass="reference external"href="http://www.scripps.edu/brooks">CHARMM</a> or <aclass="reference external"href="http://amber.scripps.edu">AMBER</a> or other molecular builders to setup
such problems and dump its information to a file. You can then
reformat the file as LAMMPS input. Some of the tools in <aclass="reference internal"href="Section_tools.html"><spanclass="doc">this section</span></a> can assist in this process.</p>
<p>Similarly, LAMMPS creates output files in a simple format. Most users
post-process these files with their own analysis tools or re-format
them for input into other programs, including visualization packages.
If you are convinced you need to compute something on-the-fly as
LAMMPS runs, see <aclass="reference internal"href="Section_modify.html"><spanclass="doc">Section 10</span></a> for a discussion
of how you can use the <aclass="reference internal"href="dump.html"><spanclass="doc">dump</span></a> and <aclass="reference internal"href="compute.html"><spanclass="doc">compute</span></a> and
<aclass="reference internal"href="fix.html"><spanclass="doc">fix</span></a> commands to print out data of your choosing. Keep in
mind that complicated computations can slow down the molecular
dynamics timestepping, particularly if the computations are not
parallel, so it is often better to leave such analysis to
post-processing codes.</p>
<p>A very simple (yet fast) visualizer is provided with the LAMMPS
package - see the <aclass="reference internal"href="Section_tools.html#xmovie"><spanclass="std std-ref">xmovie</span></a> tool in <aclass="reference internal"href="Section_tools.html"><spanclass="doc">this section</span></a>. It creates xyz projection views of
atomic coordinates and animates them. We find it very useful for
debugging purposes. For high-quality visualization we recommend the
<p>CHARMM, AMBER, NAMD, NWCHEM, and Tinker are designed primarily for
modeling biological molecules. CHARMM and AMBER use
atom-decomposition (replicated-data) strategies for parallelism; NAMD
and NWCHEM use spatial-decomposition approaches, similar to LAMMPS.
Tinker is a serial code. DL_POLY includes potentials for a variety of
biological and non-biological materials; both a replicated-data and
spatial-decomposition version exist.</p>
<hrclass="docutils"/>
</div>
<divclass="section"id="open-source-distribution">
<spanid="intro-4"></span><h2>1.4. Open source distribution</h2>
<p>LAMMPS comes with no warranty of any kind. As each source file states
in its header, it is a copyrighted code that is distributed free-of-
charge, under the terms of the <aclass="reference external"href="http://www.gnu.org/copyleft/gpl.html">GNU Public License</a> (GPL). This
is often referred to as open-source distribution - see
<aclass="reference external"href="http://www.gnu.org">www.gnu.org</a> or <aclass="reference external"href="http://www.opensource.org">www.opensource.org</a> for more
details. The legal text of the GPL is in the LICENSE file that is
included in the LAMMPS distribution.</p>
<p>Here is a summary of what the GPL means for LAMMPS users:</p>
<p>(1) Anyone is free to use, modify, or extend LAMMPS in any way they
choose, including for commercial purposes.</p>
<p>(2) If you distribute a modified version of LAMMPS, it must remain
open-source, meaning you distribute it under the terms of the GPL.
You should clearly annotate such a code as a derivative version of
LAMMPS.</p>
<p>(3) If you release any code that includes LAMMPS source code, then it
must also be open-sourced, meaning you distribute it under the terms
of the GPL.</p>
<p>(4) If you give LAMMPS files to someone else, the GPL LICENSE file and
source file headers (including the copyright and GPL notices) should
remain part of the code.</p>
<p>In the spirit of an open-source code, these are various ways you can
contribute to making LAMMPS better. You can send email to the
<aclass="reference external"href="http://lammps.sandia.gov/authors.html">developers</a> on any of these
items.</p>
<ulclass="simple">
<li>Point prospective users to the <aclass="reference external"href="http://lammps.sandia.gov">LAMMPS WWW Site</a>. Mention it in
talks or link to it from your WWW site.</li>
<li>If you find an error or omission in this manual or on the <aclass="reference external"href="http://lammps.sandia.gov">LAMMPS WWW Site</a>, or have a suggestion for something to clarify or include,
<li>If you find a bug, <aclass="reference internal"href="Section_errors.html#err-2"><spanclass="std std-ref">Section 12.2</span></a>
describes how to report it.</li>
<li>If you publish a paper using LAMMPS results, send the citation (and
any cool pictures or movies if you like) to add to the Publications,
Pictures, and Movies pages of the <aclass="reference external"href="http://lammps.sandia.gov">LAMMPS WWW Site</a>, with links
and attributions back to you.</li>
<li>Create a new Makefile.machine that can be added to the src/MAKE
directory.</li>
<li>The tools sub-directory of the LAMMPS distribution has various
stand-alone codes for pre- and post-processing of LAMMPS data. More
details are given in <aclass="reference internal"href="Section_tools.html"><spanclass="doc">Section 9</span></a>. If you write
a new tool that users will find useful, it can be added to the LAMMPS
distribution.</li>
<li>LAMMPS is designed to be easy to extend with new code for features
like potentials, boundary conditions, diagnostic computations, etc.
<aclass="reference internal"href="Section_modify.html"><spanclass="doc">This section</span></a> gives details. If you add a
feature of general interest, it can be added to the LAMMPS
distribution.</li>
<li>The Benchmark page of the <aclass="reference external"href="http://lammps.sandia.gov">LAMMPS WWW Site</a> lists LAMMPS
performance on various platforms. The files needed to run the
benchmarks are part of the LAMMPS distribution. If your machine is
sufficiently different from those listed, your timing data can be
added to the page.</li>
<li>You can send feedback for the User Comments page of the <aclass="reference external"href="http://lammps.sandia.gov">LAMMPS WWW Site</a>. It might be added to the page. No promises.</li>
<li>Cash. Small denominations, unmarked bills preferred. Paper sack OK.
Leave on desk. VISA also accepted. Chocolate chip cookies
<spanid="intro-5"></span><h2>1.5. Acknowledgments and citations</h2>
<p>LAMMPS development has been funded by the <aclass="reference external"href="http://www.doe.gov">US Department of Energy</a> (DOE), through its CRADA, LDRD, ASCI, and Genomes-to-Life
programs and its <aclass="reference external"href="http://www.sc.doe.gov/ascr/home.html">OASCR</a> and <aclass="reference external"href="http://www.er.doe.gov/production/ober/ober_top.html">OBER</a> offices.</p>
<p>Specifically, work on the latest version was funded in part by the US
Department of Energy’s Genomics:GTL program
(<aclass="reference external"href="http://www.doegenomestolife.org">www.doegenomestolife.org</a>) under the <aclass="reference external"href="http://www.genomes2life.org">project</a>, “Carbon
Sequestration in Synechococcus Sp.: From Molecular Machines to
Hierarchical Modeling”.</p>
<p>The following paper describe the basic parallel algorithms used in
LAMMPS. If you use LAMMPS results in your published work, please cite
this paper and include a pointer to the <aclass="reference external"href="http://lammps.sandia.gov">LAMMPS WWW Site</a>
<p>Other papers describing specific algorithms used in LAMMPS are listed
under the <aclass="reference external"href="http://lammps.sandia.gov/cite.html">Citing LAMMPS link</a> of
the LAMMPS WWW page.</p>
<p>The <aclass="reference external"href="http://lammps.sandia.gov/papers.html">Publications link</a> on the
LAMMPS WWW page lists papers that have cited LAMMPS. If your paper is
not listed there for some reason, feel free to send us the info. If
the simulations in your paper produced cool pictures or animations,
we’ll be pleased to add them to the
<aclass="reference external"href="http://lammps.sandia.gov/pictures.html">Pictures</a> or
<aclass="reference external"href="http://lammps.sandia.gov/movies.html">Movies</a> pages of the LAMMPS WWW
site.</p>
<p>The core group of LAMMPS developers is at Sandia National Labs:</p>
<ulclass="simple">
<li>Steve Plimpton, sjplimp at sandia.gov</li>
<li>Aidan Thompson, athomps at sandia.gov</li>
<li>Paul Crozier, pscrozi at sandia.gov</li>
</ul>
<p>The following folks are responsible for significant contributions to
the code, or other aspects of the LAMMPS development effort. Many of
the packages they have written are somewhat unique to LAMMPS and the
code would not be as general-purpose as it is without their expertise
and efforts.</p>
<ulclass="simple">
<li>Axel Kohlmeyer (Temple U), akohlmey at gmail.com, SVN and Git repositories, indefatigable mail list responder, USER-CG-CMM and USER-OMP packages</li>
<li>Roy Pollock (LLNL), Ewald and PPPM solvers</li>
<li>Mike Brown (ORNL), brownw at ornl.gov, GPU package</li>
<li>Greg Wagner (Sandia), gjwagne at sandia.gov, MEAM package for MEAM potential</li>
<li>Mike Parks (Sandia), mlparks at sandia.gov, PERI package for Peridynamics</li>
<li>Rudra Mukherjee (JPL), Rudranarayan.M.Mukherjee at jpl.nasa.gov, POEMS package for articulated rigid body motion</li>
<li>Reese Jones (Sandia) and collaborators, rjones at sandia.gov, USER-ATC package for atom/continuum coupling</li>
<li>Ilya Valuev (JIHT), valuev at physik.hu-berlin.de, USER-AWPMD package for wave-packet MD</li>
<li>Christian Trott (U Tech Ilmenau), christian.trott at tu-ilmenau.de, USER-CUDA package</li>
<li>Andres Jaramillo-Botero (Caltech), ajaramil at wag.caltech.edu, USER-EFF package for electron force field</li>
<li>Christoph Kloss (JKU), Christoph.Kloss at jku.at, USER-LIGGGHTS package for granular models and granular/fluid coupling</li>
<li>Metin Aktulga (LBL), hmaktulga at lbl.gov, USER-REAXC package for C version of ReaxFF</li>
<li>Georg Gunzenmuller (EMI), georg.ganzenmueller at emi.fhg.de, USER-SPH package</li>
</ul>
<p>As discussed in <aclass="reference internal"href="Section_history.html"><spanclass="doc">Section 13</span></a>, LAMMPS
originated as a cooperative project between DOE labs and industrial
partners. Folks involved in the design and testing of the original
version of LAMMPS were the following:</p>
<ulclass="simple">
<li>John Carpenter (Mayo Clinic, formerly at Cray Research)</li>
<li>Terry Stouch (Lexicon Pharmaceuticals, formerly at Bristol Myers Squibb)</li>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
File diff suppressed because it is too large
Load Diff
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
