lammps/doc/Section_intro.txt

"Previous Section"_Manual.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_start.html :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

1. Introduction :h3

These sections provide an overview of what LAMMPS can and can't do,
describe what it means for LAMMPS to be an open-source code, and
acknowledge the funding and people who have contributed to LAMMPS over
the years.

1.1 "What is LAMMPS"_#1_1
1.2 "LAMMPS features"_#1_2
1.3 "LAMMPS non-features"_#1_3
1.4 "Open source distribution"_#1_4
1.5 "Acknowledgments and citations"_#1_5 :all(b)

:line

1.1 What is LAMMPS :link(1_1),h4

LAMMPS is a classical molecular dynamics code that models an ensemble
of particles in a liquid, solid, or gaseous state.  It can model
atomic, polymeric, biological, metallic, granular, and coarse-grained
systems using a variety of force fields and boundary conditions.

For examples of LAMMPS simulations, see the Publications page of the
"LAMMPS WWW Site"_lws.

LAMMPS runs efficiently on single-processor desktop or laptop
machines, but is designed for parallel computers.  It will run on any
parallel machine that compiles C++ and supports the "MPI"_mpi
message-passing library.  This includes distributed- or shared-memory
parallel machines and Beowulf-style clusters.

:link(mpi,http://www-unix.mcs.anl.gov/mpi)

LAMMPS can model systems with only a few particles up to millions or
billions.  See "this section"_Section_perf.html for information on LAMMPS
performance and scalability, or the Benchmarks section of the "LAMMPS
WWW Site"_lws.

LAMMPS is a freely-available open-source code, distributed under the
terms of the "GNU Public License"_gnu, which means you can use or
modify the code however you wish.  See "this section"_#1_4 for a brief
discussion of the open-source philosophy.

:link(gnu,http://www.gnu.org/copyleft/gpl.html)

LAMMPS is designed to be easy to modify or extend with new
capabilities, such as new force fields, atom types, boundary
conditions, or diagnostics.  See "this section"_Section_modify.html for
more details.

The current version of LAMMPS is written in C++.  Earlier versions
were written in F77 and F90.  See "this section"_Section_history.html
for more information on different versions.  All versions can be
downloaded from the "LAMMPS WWW Site"_lws.

LAMMPS was originally developed under a US Department of Energy CRADA
(Cooperative Research and Development Agreement) between two DOE labs
and 3 companies.  It is distributed by "Sandia National Labs"_snl.
See "this section"_#1_5 for more information on LAMMPS funding and
individuals who have contributed to LAMMPS.

:link(snl,http://www.sandia.gov)

In the most general sense, LAMMPS integrates Newton's equations of
motion for collections of atoms, molecules, or macroscopic particles
that interact via short- or long-range forces with a variety of
initial and/or boundary conditions.  For computational efficiency
LAMMPS uses neighbor lists to keep track of nearby particles.  The
lists are optimized for systems with particles that are repulsive at
short distances, so that the local density of particles never becomes
too large.  On parallel machines, LAMMPS uses spatial-decomposition
techniques to partition the simulation domain into small 3d
sub-domains, one of which is assigned to each processor.  Processors
communicate and store "ghost" atom information for atoms that border
their sub-domain.  LAMMPS is most efficient (in a parallel sense) for
systems whose particles fill a 3d rectangular box with roughly uniform
density.  Papers with technical details of the algorithms used in
LAMMPS are listed in "this section"_#1_5.

:line

1.2 LAMMPS features :link(1_2),h4

This section highlights LAMMPS features, with pointers to specific
commands which give more details.  If LAMMPS doesn't have your
favorite interatomic potential, boundary condition, or atom type, see
"this section"_Section_modify.html, which describes how you can add it to
LAMMPS.

Kinds of systems LAMMPS can simulate: :h4
("atom style"_atom_style.html command)

  atomic (e.g. box of Lennard-Jonesium)
  bead-spring polymers
  united-atom polymers or organic molecules
  all-atom polymers, organic molecules, proteins, DNA
  metals
  granular materials
  coarse-grained mesoscale models
  hybrid systems :ul

Force fields: :h4
("pair style"_pair_style.html, "bond style"_bond_style.html,
"angle style"_angle_style.html, "dihedral style"_dihedral_style.html,
"improper style"_improper_style.html, "kspace style"_kspace_style.html
commands)

  pairwise potentials: Lennard-Jones, Coulombic, Buckingham, Morse, \
    Yukawa, frictional granular, Debye, soft, DPD, class 2 (COMPASS), \
    tabulated, hybrid
  manybody potentials: EAM, Finnis/Sinclair, modified EAM (MEAM), \
    Stillinger-Weber, Tersoff
  bond potentials: harmonic, FENE, Morse, nonlinear, class 2, \
    quartic (breakable), hybrid
  angle potentials: harmonic, CHARMM, cosine, cosine/squared, \
    class 2 (COMPASS), hybrid
  dihedral potentials: harmonic, CHARMM, multi-harmonic, helix, \
    class 2 (COMPASS), OPLS, hybrid	 
  improper potentials: harmonic, cvff, class 2 (COMPASS), hybrid
  polymer potentials: all-atom, united-atom, bead-spring, breakable
  water potentials: TIP3P, TIP4P, SPC
  long-range Coulombics: Ewald, PPPM (similar to particle-mesh Ewald)
  CHARMM, AMBER, OPLS force-field compatibility :ul

Creation of atoms: :h4
("read_data"_read_data.html, "lattice"_lattice.html,
"create_atoms"_create_atoms.html, "delete_atoms"_delete_atoms.html,
"displace_atoms"_displace_atoms.html commands)

  read in atom coords from files
  create atoms on one or more lattices (e.g. grain boundaries)
  delete geometric or logical groups of atoms (e.g. voids)
  displace atoms :ul

Ensembles, constraints, and boundary conditions: :h4
("fix"_fix.html command) 

  constant NVE, NVT, NPT, NPH integrators
  thermostatting options for groups and geometric regions of atoms
  pressure control via Nose/Hoover barostatting in 1 to 3 dimensions
  volume rescaling
  altered motion via velocity and force constraints
  harmonic (umbrella) constraint forces
  dragging of atoms to new positions
  independent or coupled rigid body integration
  SHAKE bond and angle constraints
  wall constraints of various kinds
  targeted molecular dynamics (TMD) constraints
  gravity :ul

Integrators: :h4
("run"_run.html, "run_style"_run_style.html, "temper"_temper.html commands) 

  velocity-Verlet integrator
  Brownian dynamics
  energy minimization via conjugate gradient relaxation
  rRESPA hierarchical timestepping
  parallel tempering (replica exchange)
  multiple independent simulations simultaneously :ul

Output: :h4
("dump"_dump.html, "restart"_restart.html commands) 

  binary restart files
  text dump files of atom coords, velocities, other per-atom attributes
  atom snapshots in native, XYZ, XTC, DCD formats
  per-atom energy, stress, centro-symmetry parameter :ul

Pre- and post-processing: :h4

Our group has also written and released a separate toolkit called
"Pizza.py"_pizza which provides tools for doing setup, analysis,
plotting, and visualization for LAMMPS simulations.  Pizza.py is
written in "Python"_python and is available for download from "the
Pizza.py WWW site"_pizza.

:link(pizza,http://www.cs.sandia.gov/~sjplimp/pizza.html)
:link(python,http://www.python.org)

:line

1.3 LAMMPS non-features :link(1_3),h4

LAMMPS is designed to efficiently compute Newton's equations of motion
for a system of interacting particles.  Many of the tools needed to
pre- and post-process the data for such simulations are not included
in the LAMMPS kernel for several reasons:

the desire to keep LAMMPS simple
they are not parallel operations
other codes already do them
limited development resources :ul

Specifically, LAMMPS itself does not:

run thru a GUI
build molecular systems
assign force-field coefficients automagically
perform sophisticated analyses of your MD simulation
visualize your MD simulation
plot your output data :ul

A few tools for pre- and post-processing tasks are provided as part of
the LAMMPS package; they are described in "this
section"_Section_tools.html.  However, many people use other codes or
write their own tools for these tasks.

As noted above, our group has also written and released a separate
toolkit called "Pizza.py"_pizza 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
"Python"_python and is available for download from "the Pizza.py WWW
site"_pizza.

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.

For atomic systems LAMMPS provides a "create_atoms"_create_atoms.html
command which places atoms on solid-state lattices (fcc, bcc, etc).
Assigning small numbers of force field coefficients can be done via
the "pair coeff"_pair_coeff.html, "bond coeff"_bond_coeff.html, "angle
coeff"_angle_coeff.html, 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.

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
"CHARMM"_charmm or "AMBER"_amber 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 "this
section"_Section_tools.html can assist in this process.

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 "this section"_Section_modify.html for a discussion of how you
can use the "dump"_dump.html and "fix"_fix.html 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.

A very simple (yet fast) visualizer is provided with the LAMMPS
package - see the "xmovie"_Section_tools.html#xmovie tool in "this
section"_Section_tools.html.  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
following packages:

"Raster3d"_http://www.bmsc.washington.edu/raster3d/raster3d.html
"RasMol"_http://www.openrasmol.org
"VMD"_http://www.ks.uiuc.edu/Research/vmd
"AtomEye"_http://164.107.79.177/Archive/Graphics/A :ul

Other features that LAMMPS does not yet (and may never) support are
discussed in "this section"_Section_history.html.

Finally, these are freely-available molecular dynamics codes, most of
them parallel, which may be well-suited to the problems you want to
model.  They can also be used in conjunction with LAMMPS to perform
complementary modeling tasks.

"CHARMM"_charmm
"AMBER"_amber
"NAMD"_namd
"NWCHEM"_nwchem
"DL_POLY"_dlpoly
"Tinker"_tinker :ul

:link(charmm,http://www.scripps.edu/brooks)
:link(amber,http://amber.scripps.edu)
:link(namd,http://www.ks.uiuc.edu/Research/namd/)
:link(nwchem,http://www.emsl.pnl.gov/docs/nwchem/nwchem.html)
:link(dlpoly,http://www.cse.clrc.ac.uk/msi/software/DL_POLY)
:link(tinker,http://dasher.wustl.edu/tinker)

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.

:line

1.4 Open source distribution :link(1_4),h4

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 "GNU Public License"_gnu (GPL).  This
is often referred to as open-source distribution - see
"www.gnu.org"_gnuorg or "www.opensource.org"_opensource for more
details.  The legal text of the GPL is in the LICENSE file that is
included in the LAMMPS distribution.

:link(gnuorg,http://www.gnu.org)
:link(opensource,http://www.opensource.org)

Here is a summary of what the GPL means for LAMMPS users:

(1) Anyone is free to use, modify, or extend LAMMPS in any way they
choose, including for commercial purposes.

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

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

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

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
"developers"_http://lammps.sandia.gov/authors.html on any of these
items.

Point prospective users to the "LAMMPS WWW Site"_lws.  Mention it in
talks or link to it from your WWW site. :ulb,l

If you find an error or omission in this manual or on the "LAMMPS WWW
Site"_lws, or have a suggestion for something to clarify or include,
send an email to the
"developers"_http://lammps.sandia.gov/authors.html. :l

If you find a bug, "this section"_Section_errors.html#9_2 describes
how to report it. :l

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 "LAMMPS WWW Site"_lws, with links
and attributions back to you. :l

Create a new Makefile.machine that can be added to the src/MAKE
directory. :l

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 "this section"_Section_tools.html.  If you write
a new tool that users will find useful, it can be added to the LAMMPS
distribution. :l

LAMMPS is designed to be easy to extend with new code for features
like potentials, boundary conditions, diagnostic computations, etc.
"This section"_Section_modify.html gives details.  If you add a
feature of general interest, it can be added to the LAMMPS
distribution. :l

The Benchmark page of the "LAMMPS WWW Site"_lws 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. :l

You can send feedback for the User Comments page of the "LAMMPS WWW
Site"_lws.  It might be added to the page.  No promises. :l

Cash.  Small denominations, unmarked bills preferred.  Paper sack OK.
Leave on desk.  VISA also accepted.  Chocolate chip cookies
encouraged. :ule,l

:line

1.5 Acknowledgments and citations :h4,link(1_5)

LAMMPS development has been funded by the "US Department of
Energy"_doe (DOE), through its CRADA, LDRD, ASCI, and Genomes-to-Life
programs and its "OASCR"_oascr and "OBER"_ober offices.

Specifically, work on the latest version was funded in part by the US
Department of Energy's Genomics:GTL program
("www.doegenomestolife.org"_gtl) under the "project"_ourgtl, "Carbon
Sequestration in Synechococcus Sp.: From Molecular Machines to
Hierarchical Modeling".

:link(doe,http://www.doe.gov)
:link(gtl,http://www.doegenomestolife.org)
:link(ourgtl,http://www.genomes2life.org)
:link(oascr,http://www.sc.doe.gov/ascr/home.html)
:link(ober,http://www.er.doe.gov/production/ober/ober_top.html)

The following papers describe the parallel algorithms used in LAMMPS.

S. J. Plimpton, [Fast Parallel Algorithms for Short-Range Molecular
Dynamics], J Comp Phys, 117, 1-19 (1995).

S. J. Plimpton, R. Pollock, M. Stevens, [Particle-Mesh Ewald and
rRESPA for Parallel Molecular Dynamics Simulations], in Proc of the
Eighth SIAM Conference on Parallel Processing for Scientific
Computing, Minneapolis, MN (March 1997).

If you use LAMMPS results in your published work, please cite the J
Comp Phys reference and include a pointer to the "LAMMPS WWW Site"_lws
(http://lammps.sandia.gov).  A paper describing the latest version of
LAMMPS is in the works; when it appears in print, you can check the
"LAMMPS WWW Site"_lws for a more current citation.

If you send me information about your publication, I'll be pleased to
add it to the Publications page of the "LAMMPS WWW Site"_lws.  Ditto
for a picture or movie for the Pictures or Movies pages.

The core group of LAMMPS developers is at Sandia National Labs.  They
include "Steve Plimpton"_sjp, Paul Crozier, and Aidan Thompson and can
be contacted via email: sjplimp, pscrozi, athomps at sandia.gov.

Here are various folks who have made significant contributions to
features in LAMMPS:

:link(sjp,http://www.cs.sandia.gov/~sjplimp)

Ewald and PPPM solvers: Roy Pollock (LLNL)
rRESPA: Mark Stevens & Paul Crozier (Sandia)
NVT/NPT integrators: Mark Stevens (Sandia)
class 2 force fields: Eric Simon (Cray)
HTFN energy minimizer: Todd Plantenga (Sandia)
msi2lmp tool: Steve Lustig (Dupont), Mike Peachey & John Carpenter (Cray)
CHARMM force fields: Paul Crozier (Sandia)
2d Ewald/PPPM: Paul Crozier (Sandia)
granular force fields and BC: Leo Silbert & Gary Grest (Sandia)
multi-harmonic dihedral potential: Mathias Putz (Sandia)
EAM potentials: Stephen Foiles (Sandia)
parallel tempering: Mark Sears (Sandia)
lmp2cfg and lmp2traj tools: Ara Kooser, Jeff Greathouse, Andrey Kalinichev (Sandia)
FFT support for SGI SCLS (Altix): Jim Shepherd (Ga Tech)
targeted molecular dynamics (TMD): Paul Crozier (Sandia), Christian Burisch (Bochum University, Germany)
force tables for long-range Coulombics: Paul Crozier (Sandia)
radial distribution functions: Paul Crozier & Jeff Greathouse (Sandia)
Morse bond potential: Jeff Greathouse (Sandia)
CHARMM <-> LAMMPS tool: Pieter in't Veld and Paul Crozier (Sandia)
AMBER <-> LAMMPS tool: Keir Novik (Univ College London) and Vikas Varshney (U Akron)
electric field fix: Christina Payne (Vanderbilt U)
cylindrical indenter fix: Ravi Agrawal (Northwestern U)
compressed dump files: Erik Luijten (U Illinois)
thermodynamics enhanced by fix quantities: Aidan Thompson (Sandia)
uniaxial strain fix: Carsten Svaneborg (Max Planck Institute)
TIP4P potential (4-site water): Ahmed Ismail and Amalie Frischknecht (Sandia)
dissipative particle dynamics (DPD) potentials: Kurt Smith (U Pitt) and \
  Frank van Swol (Sandia)
Finnis/Sinclair EAM: Tim Lau (MIT)
helix dihedral potential : Naveen Michaud-Agrawal (Johns Hopkins U) and \
  Mark Stevens (Sandia)
cosine/squared angle potential : Naveen Michaud-Agrawal (Johns Hopkins U)
EAM CoAl and AlCu potentials : Kwang-Reoul Lee (KIST, Korea)
self spring fix : Naveen Michaud-Agrawal (Johns Hopkins U)
radius-of-gyration spring fix : Naveen Michaud-Agrawal (Johns Hopkins U) and \
  Paul Crozier (Sandia)
lj/smooth pair potential : Craig Maloney (UCSB) 
grain boundary orientation fix : Koenraad Janssens and David Olmsted (SNL)
DCD and XTC dump styles: Naveen Michaud-Agrawal (Johns Hopkins U)
breakable bond quartic potential: Chris Lorenz and Mark Stevens (SNL)
faster pair hybrid potential: James Fischer \
  (High Performance Technologies, Inc), Vincent Natoli and \
  David Richie (Stone Ridge Technology)
POEMS coupled rigid body integrator: Rudranarayan Mukherjee (RPI)
OPLS dihedral potential: Mark Stevens (Sandia)
multi-letter variable names : Naveen Michaud-Agrawal (Johns Hopkins U)
fix momentum and recenter : Naveen Michaud-Agrawal (Johns Hopkins U)
LJ tail corrections for energy/pressure : Paul Crozier (Sandia)
region prism : Pieter in't Veld (Sandia)
Stillinger-Weber and Tersoff potentials : Aidan Thompson (Sandia)
fix wall/lj126 : Mark Stevens (Sandia)
optimized pair potentials for lj/cut, charmm/long, eam, morse : James Fischer (High Performance Tech), David Richie and Vincent Natol (Stone Ridge Technologies)
MEAM potential : Greg Wagner (Sandia) :tb(s=:)

Other CRADA partners involved in the design and testing of LAMMPS were
    
John Carpenter (Mayo Clinic, formerly at Cray Research)
Terry Stouch (Lexicon Pharmaceuticals, formerly at Bristol Myers Squibb)
Steve Lustig (Dupont)
Jim Belak (LLNL) :ul