Commit b93436e4 authored by sjplimp's avatar sjplimp
Browse files 

git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@1 f3b2605a-c512-4ea7-a41b-209d697bcdaa
parents

doc/2001/README.html

0 → 100644
+174 −0
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">

<HTML>

<HEAD>

    <META NAME="Generator" CONTENT="Cosmo Create 1.0.3">

</HEAD>

<BODY>

<H2>

LAMMPS</H2>

<P>

LAMMPS = Large-scale Atomic/Molecular Massively Parallel Simulator</P>

<P>

This is the documentation for the LAMMPS 2001 version, written in F90,

which has been superceded by more current versions.  See the <A

HREF="http://www.cs.sandia.gov/~sjplimp/lammps.html">LAMMPS WWW

Site</A> for more information.

<P>

LAMMPS is a classical molecular dynamics code designed for simulating 

molecular and atomic systems on parallel computers using 

spatial-decomposition techniques. It runs on any parallel platform that 

supports F90 and the MPI message-passing library or on single-processor 

workstations.</P>

<P>

LAMMPS 2001 is copyrighted code that is distributed freely as

open-source software under the GNU Public License (GPL).  See the

LICENSE file or <A HREF="http://www.gnu.org">www.gnu.org</A> for more

details.  Basically the GPL allows you as a user to use, modify, or

distribute LAMMPS however you wish, so long as any software you

distribute remains under the GPL.

<P>

Features of LAMMPS 2001 include:</P>

<UL>

    <LI>

    short-range pairwise Lennard-Jones and Coulombic interactions 

    <LI>

    long-range Coulombic interactions via Ewald or PPPM (particle-mesh 

    Ewald) 

    <LI>

    short-range harmonic bond potentials (bond, angle, torsion, improper) 

    <LI>

    short-range class II (cross-term) molecular potentials 

    <LI>

    NVE, NVT, NPT dynamics 

    <LI>

    constraints on atoms or groups of atoms 

    <LI>

    rRESPA long-timescale integrator 

    <LI>

    energy minimizer (Hessian-free truncated Newton method) 

</UL>

<P>

For users of LAMMPS 99, this version is written in F90 to take

advantage of dynamic memory allocation.  This means the user does not

have to fiddle with parameter settings and re-compile the code so

often for different problems.  This enhancment means there are new

rules for the ordering of commands in a LAMMPS input script, as well

as a few new commands to guide the memory allocator. Users should read

the beginning sections of the <A

HREF="input_commands.html">input_commands</A> file for an

explanation.</P>

<P>

More details about the code can be found <A

HREF="#_cch3_930958294">here</A>, in the HTML- or text-based

documentation.  The LAMMPS Web page is at <A

 HREF="http://www.cs.sandia.gov/~sjplimp/lammps.html">www.cs.sandia.gov/~sjplimp/lammps.html</A>

, which includes benchmark timings and a list of papers written using

LAMMPS results.  They illustrate the kinds of scientific problems that

can be modeled with LAMMPS.  These two papers describe the parallel

algorithms used in the code.  Please cite these if you incorporate

LAMMPS results in your work.  And if you send me citations for your

papers, I'll be pleased to add them to the LAMMPS WWW page.

</P>

<P>

S. J. Plimpton, R. Pollock, M. Stevens, &quot;Particle-Mesh Ewald and 

rRESPA for Parallel Molecular Dynamics Simulations&quot;, in Proc of 

the Eighth SIAM Conference on Parallel Processing for Scientific 

Computing, Minneapolis, MN, March 1997.</P>

<P>

S. J. Plimpton, "Fast Parallel Algorithms for Short-Range Molecular Dynamics", J Comp Phys, 117, 1-19 (1995).</P>

<P>

LAMMPS was originally developed as part of a 5-way CRADA collaboration 

between 3 industrial partners (Cray Research, Bristol-Myers Squibb, and 

Dupont) and 2 DoE laboratories (Sandia National Laboratories and 

Lawrence Livermore National Laboratories).</P>

<P>

The primary author of LAMMPS is Steve Plimpton, but others have written 

or worked on significant portions of the code:</P>

<UL>

    <LI>

    Roy Pollock (LLNL): Ewald, PPPM solvers 

    <LI>

    Mark Stevens (Sandia): rRESPA, NPT integrators 

    <LI>

    Eric Simon (Cray Research): class II force fields 

    <LI>

    Todd Plantenga (Sandia): energy minimizer 

    <LI>

    Steve Lustig (Dupont): msi2lmp tool 

    <LI>

    Mike Peachey (Cray Research): msi2lmp tool 

</UL>

<P>

Other CRADA partners involved in the design and testing of LAMMPS are </P>

<UL>

    <LI>

    John Carpenter (Cray Research) 

    <LI>

    Terry Stouch (Bristol-Myers Squibb) 

    <LI>

    Jim Belak (LLNL) 

</UL>

<P>

If you have questions about LAMMPS, please contact me:

</P>

<DL>

    <DT>

    Steve Plimpton

    <DD>

    sjplimp@sandia.gov 

    <DD>

    www.cs.sandia.gov/~sjplimp 

    <DD>

    Sandia National Labs 

    <DD>

    Albuquerque, NM 87185

</DL>

<HR>

<H3>

<A NAME="_cch3_930958294">More Information about LAMMPS</A></H3>

<DIR>

    <LI>

    <A HREF="basics.html">Basics</A> 

    <DIR>

        <LI>

        how to make, run, and test LAMMPS with the example problems 

    </DIR>

    <LI>

    <A HREF="input_commands.html">Input Commands</A> 

    <DIR>

        <LI>

        a complete listing of input commands used by LAMMPS 

    </DIR>

    <LI>

    <A HREF="data_format.html">Data Format</A> 

    <DIR>

        <LI>

        the data file format used by LAMMPS 

    </DIR>

    <LI>

    <A HREF="force_fields.html">Force Fields</A> 

    <DIR>

        <LI>

        the equations LAMMPS uses to compute force-fields 

    </DIR>

    <LI>

    <A HREF="units.html">Units</A> 

    <DIR>

        <LI>

        the input/output and internal units for LAMMPS variables 

    </DIR>

    <LI>

    <A HREF="history.html">History</A> 

    <DIR>

        <LI>

        a brief timeline of features added to LAMMPS 

    </DIR>

    <LI>

    <A HREF="deficiencies.html">Deficiencies</A> 

    <DIR>

        <LI>

        features LAMMPS does not (yet) have

    </DIR>

</DIR>

</BODY>

</HTML>

doc/2001/basics.html

0 → 100644
+224 −0
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">

<HTML>

<HEAD>

    <META NAME="Generator" CONTENT="Cosmo Create 1.0.3">

</HEAD>

<BODY>

<H2>

Basics of Using LAMMPS</H2>

<P>

<A HREF="README.html">Return</A> to top-level of LAMMPS documentation.</P>

<UL>

    <LI>

    <A HREF="#_cch3_931273040">Distribution</A> 

    <LI>

    <A HREF="#_cch3_930327142">Making LAMMPS</A> 

    <LI>

    <A HREF="#_cch3_930327155">Running LAMMPS</A> 

    <LI>

    <A HREF="#_cch3_930759879">Examples</A> 

    <LI>

    <A HREF="#_cch3_931282515">Other Tools</A> 

    <LI>

    <A HREF="#_cch3_931282000">Extending LAMMPS</A> 

</UL>

<HR>

<H3>

<A NAME="_cch3_931273040">Distribution</A></H3>

<P>

When you unzip/untar the LAMMPS distribution you should have several

directories: </P>

<UL>

    <LI>

    src = source files for LAMMPS 

    <LI>

    doc = HTML documentation 

    <LI>

    examples = sample problems with inputs and outputs 

    <LI>

    tools = serial program for creating and massaging LAMMPS data files 

    <LI>

    converters = msi2lmp, lmp2arc, amber = codes & scripts for converting

       between MSI/Discover, AMBER, and LAMMPS formats

</UL>

<HR>

<H3>

<A NAME="_cch3_930327142">Making LAMMPS</A></H3>

<P>

The src directory contains the F90 and C source files for LAMMPS as 

well as several sample Makefiles for different machines. To make LAMMPS 

for a specfic machine, you simply type</P>

<P>

make machine</P>

<P>

from within the src directoy. E.g. "make sgi" or "make t3e". This

should create an executable such as lmp_sgi or lmp_t3e.  For optimal

performance you'll want to use a good F90 compiler to make LAMMPS; on

Linux boxes I've been told the Leahy F90 compiler is a good choice.

(If you don't have an F90 compiler, I can give you an older F77-based

version of LAMMPS 99, but you'll lose the dynamic memory and some

other new features in LAMMPS 2001.)</P>

<P>

In the src directory, there is one top-level Makefile and several

low-level machine-specific files named Makefile.xxx where xxx = the

machine name. If a low-level Makefile exists for your platform, you do

not need to edit the top-level Makefile.  However you should check the

system-specific section of the low-level Makefile to insure the

various paths are correct for your environment. If a low-level

Makefile does not exist for your platform, you will need to add a

suitable target to the top-level Makefile. You will also need to

create a new low-level Makefile using one of the existing ones as a

template. If you wish to make LAMMPS for a single-processor

workstation that doesn't have an installed MPI library, you can

specify the "serial" target which uses a directory of MPI stubs to

link against - e.g. &quot;make serial&quot;. You will need to make the

stub library (type &quot;make&quot; in STUBS directory) for your

workstation before doing this.</P>

<P>

Note that the two-level Makefile system allows you to make LAMMPS for 

multiple platforms. Each target creates its own object directory for 

separate storage of its *.o files.</P>

<P>

There are a few compiler switches of interest which can be specified

in the low-level Makefiles.  If you use a F90FLAGS switch of -DSYNC

then synchronization calls will be made before the timing routines in

integrate.f. This may slow down the code slightly, but will make the

individual timings reported at the end of a run more accurate. The

F90FLAGS setting of -DSENDRECV will use MPI_Sendrecv calls for data

exchange between processors instead of MPI_Irecv, MPI_Send,

MPI_Wait. Sendrecv is often slower, but on some platforms can be

faster, so it is worth trying, particularly if your communication

timings seem slow.</P>

<P>

The CCFLAGS setting in the low-level Makefiles requires a FFT setting,

for example -DFFT_SGI or -DFFT_T3E. This is for inclusion of the

appropriate machine-specific native 1-d FFT libraries on various

platforms. Currently, the supported machines and switches (used in

fft_3d.c) are FFT_SGI, FFT_DEC, FFT_INTEL, FFT_T3E, and FFT_FFTW. The

latter is a publicly available portable FFT library, <A

HREF="http://www.fftw.org">FFTW</A>, which you can install on any

machine. If none of these options is suitable for your machine, please

contact me, and we'll discuss how to add the capability to call your

machine's native FFT library. You can also use FFT_NONE if you have no

need to use the PPPM option in LAMMPS.</P>

<P>

For Linux and T3E compilation, there is a also a CCFLAGS setting for KLUDGE

needed (see Makefile.linux and Makefile.t3e).  This is to enable F90 to

call C with appropriate underscores added to C function names.

<HR>

<H3>

<A NAME="_cch3_930327155">Running LAMMPS</A></H3>

<P>

LAMMPS is run by redirecting a text file (script) of input commands into it.</P>

<P>

lmp_sgi &lt; in.lj</P>

<P>

lmp_t3e &lt; in.lj</P>

<P>

The script file contains commands that specify the parameters for the 

simulation as well as to read other necessary files such as a data file 

that describes the initial atom positions, molecular topology, and 

force-field parameters. The <A HREF="input_commands.html">input_commands</A>

 page describes all the possible commands that can be used. The <A

 HREF="data_format.html">data_format</A> page describes the format of 

the data file. </P>

<P>

LAMMPS can be run on any number of processors, including a single 

processor. In principle you should get identical answers on any number 

of processors and on any machine. In practice, numerical round-off can 

cause slight differences and eventual divergence of dynamical 

trajectories. </P>

<P>

When LAMMPS runs, it estimates the array sizes it should allocate based 

on the problem you are simulating and the number of processors you 

are running on. If you run out of physical memory, you will get a F90 

allocation error and the code should hang or crash. The only thing you 

can do about this is run on more processors or run a smaller problem. If 

you get an error message to the screen about &quot;boosting&quot; 

something, it means LAMMPS under-estimated the size needed for one (or 

more) data arrays. The &quot;extra memory&quot; command can be used in 

the input script to augment these sizes at run time. A few arrays are 

hard-wired to sizes that should be sufficient for most users. These are 

specified with parameter settings in the global.f file. If you get a 

message to &quot;boost&quot; one of these parameters you will have to 

change it and re-compile LAMMPS.</P>

<P>

Some LAMMPS errors are detected at setup; others like neighbor list

overflow may not occur until the middle of a run. Except for F90

allocation errors which may cause the code to hang (with an error

message) since only one processor may incur the error, LAMMPS should

always print a message to the screen and exit gracefully when it

encounters a fatal error. If the code ever crashes or hangs without

spitting out an error message first, it's probably a bug, so let me

know about it. Of course this applies to algorithmic or parallelism

issues, not to physics mistakes, like specifying too big a timestep or

putting 2 atoms on top of each other! One exception is that different

MPI implementations handle buffering of messages differently.  If the

code hangs without an error message, it may be that you need to

specify an MPI setting or two (usually via an environment variable) to

enable buffering or boost the sizes of messages that can be

buffered.</P>

<HR>

<H3>

<A NAME="_cch3_930759879">Examples</A></H3>

<P>

There are several directories of sample problems in the examples

directory. All of them use an input file (in.*) of commands and a data

file (data.*) of initial atomic coordinates and produce one or more

output files. Sample outputs on different machines and numbers of

processors are included to compare your answers to.  See the README

file in the examples sub-directory for more information on what LAMMPS

features the examples illustrate.</P>

<P>

(1) lj = atomic simulations of Lennard-Jones systems.

<P>

(2) class2 = phenyalanine molecule using the DISCOVER cff95 class 2

force field.

<P>

(3) lc = liquid crystal molecules with various Coulombic options and

periodicity settings.

<P>

(4) flow = 2d flow of Lennard-Jones atoms in a channel using various

constraint options.

<P>

(5) polymer = bead-spring polymer models with one or two chain types.

</P>

<HR>

<H3>

<A NAME="_cch3_931282515">Other Tools</A></H3>

<P>

The converters directory has source code and scripts for tools that

perform input/output file conversions between MSI Discover, AMBER, and

LAMMPS formats.  See the README files for the individual tools for

additional information.

<P>

The tools directory has several serial programs that create and

massage LAMMPS data files.

<P>

(1) setup_chain.f = create a data file of polymer bead-spring chains

<P>

(2) setup_lj.f = create a data file of an atomic LJ mixture of species

<P>

(3) setup_flow_2d.f = create a 2d data file of LJ particles with walls for

	a flow simulation

<P>

(4) replicate.c = replicate or scale an existing data file into a new one

<P>

(5) peek_restart.f = print-out info from a binary LAMMPS restart file

<P>

(6) restart2data.f = convert a binary LAMMPS restart file into a text data file

<P>

See the comments at the top of each source file for information on how

to use the tool.

<HR>

<H3>

<A NAME="_cch3_931282000">Extending LAMMPS</A></H3>

<P>

User-written routines can be compiled and linked with LAMMPS, then

invoked with the "diagnostic" command as LAMMPS runs.  These routines

can be used for on-the-fly diagnostics or a variety of other purposes.

The examples/lc directory shows an example of using the diagnostic

command with the in.lc.big.fixes input script.  A sample diagnostic

routine is given there also: diagnostic_temp_molecules.f.

</BODY>

</HTML>

doc/2001/data_format.html

0 → 100644
+250 −0
Original line number Diff line number Diff line 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">

<HTML>

<HEAD>

    <META NAME="Generator" CONTENT="Cosmo Create 1.0.3">

</HEAD>

<BODY>

<H2>

LAMMPS Data Format</H2>

<P>

<A HREF="README.html">Return</A> to top-level of LAMMPS documentation</P>

<P>

This file describes the format of the data file read into LAMMPS with 

the &quot;read data&quot; command. The data file contains basic 

information about the size of the problem to be run, the initial atomic 

coordinates, molecular topology, and (optionally) force-field 

coefficients. It will be easiest to understand this file if you read it 

while looking at a sample data file from the examples.</P>

<P>

This page has 2 sections:</P>

<UL>

    <LI>

    <A HREF="#_cch3_930958962">Rules for formatting the Data File</A> 

    <LI>

    <A HREF="#_cch3_930958969">Sample file with Annotations</A> 

</UL>

<HR>

<H3>

<A NAME="_cch3_930958962">Rules for formatting the Data File: </A></H3>

<P>

Blank lines are important. After the header section, new entries are 

separated by blank lines. </P>

<P>

Indentation and space between words/numbers on one line is not 

important except that keywords (e.g. Masses, Bond Coeffs) must be 

left-justified and capitalized as shown. </P>

<P>

The header section (thru box bounds) must appear first in the file, the 

remaining entries (Masses, various Coeffs, Atoms, Bonds, etc) can come 

in any order. </P>

<P>

These entries must be in the file: header section, Masses, Atoms. </P>

<P>

These entries must be in the file if there are a non-zero number of

them: Bonds, Angles, Dihedrals, Impropers. Force field coefficients

can be specified in the input script, so do not have to appear in the

data file.  The one exception to this is class 2 force field

coefficients which can only be specified in the data file.

<P>

The Nonbond Coeffs entry contains one line for each atom type. These 

are the coefficients for an interaction between 2 atoms of the same 

type. The cross-type coeffs are computed by the appropriate class I or 

class II mixing rules, or can be specified explicitly using the 

&quot;nonbond coeff&quot; command in the input command script. See the <A

 HREF="force_fields.html">force_fields</A> page for more information. </P>

<P>

In the Atoms entry, the atoms can be in any order so long as there are 

N entries. The 1st number on the line is the atom-tag (number from 1 to 

N) which is used to identify the atom throughout the simulation. The 

molecule-tag is a second identifier which is attached to the atom; it 

can be 0, or a counter for the molecule the atom is part of, or any 

other number you wish. The q value is the charge of the atom in 

electron units (e.g. +1 for a proton). The xyz values are the initial 

position of the atom. For 2-d simulations specify z as 0.0.</P>

<P>

The final 3 nx,ny,nz values on a line of the Atoms entry are optional. 

LAMMPS only reads them if the &quot;true flag&quot; command is 

specified in the input command script. Otherwise they are initialized 

to 0 by LAMMPS. Their meaning, for each dimension, is that 

&quot;n&quot; box-lengths are added to xyz to get the atom's 

&quot;true&quot; un-remapped position. This can be useful in pre- or 

post-processing to enable the unwrapping of long-chained molecules 

which wind thru the periodic box one or more times. The value of 

&quot;n&quot; can be positive, negative, or zero. For 2-d simulations 

specify nz as 0. </P>

<P>

Atom velocities are initialized to 0.0 if there is no Velocities entry. 

In the Velocities entry, the atoms can be in any order so long as there 

are N entries. The 1st number on the line is the atom-tag (number from 

1 to N) which is used to identify the atom which the given velocity 

will be assigned to.</P>

<P>

Entries for Velocities, Bonds, Angles, Dihedrals, Impropers must appear 

in the file after an Atoms entry.</P>

<P>

For simulations with periodic boundary conditions, xyz coords are

remapped into the periodic box (from as far away as needed), so the

initial coordinates need not be inside the box. The nx,ny,nz values

(as read in or as set to zero by LAMMPS) are appropriately adjusted by

this remapping. </P>

<P>

The number of coefficients specified on each line of coefficient

entries (Nonbond Coeffs, Bond Coeffs, etc) depends on the

&quot;style&quot; of interaction. This must be specified in the input

command script before the "read data" command is issued, unless the

default is used. See the <A

 HREF="input_commands.html">input_commands</A> page for a description 

of the various style options. The <A HREF="input_commands.html">input_commands</A>

 and <A HREF="force_fields.html">force_fields</A> pages explain the 

meaning and valid values for each of the coefficients. </P>

<HR>

<H3>

<A NAME="_cch3_930958969">Sample file with Annotations</A></H3>

<P>

Here is a sample file with annotations in parenthesis and lengthy 

sections replaced by dots (...). Note that the blank lines are 

important in this example.</P>

<PRE>



LAMMPS Description           (1st line of file)



100 atoms         (this must be the 3rd line, 1st 2 lines are ignored)

95 bonds                (# of bonds to be simulated)

50 angles               (include these lines even if number = 0)

30 dihedrals

20 impropers



5 atom types           (# of nonbond atom types)

10 bond types          (# of bond types = sets of bond coefficients)

18 angle types         

20 dihedral types      (do not include a bond,angle,dihedral,improper type

2 improper types             line if number of bonds,angles,etc is 0)



-0.5 0.5 xlo xhi       (for periodic systems this is box size,

-0.5 0.5 ylo yhi        for non-periodic it is min/max extent of atoms)

-0.5 0.5 zlo zhi       (do not include this line for 2-d simulations)



Masses



  1 mass

  ...

  N mass                           (N = # of atom types)



Nonbond Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of atom types)



Bond Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of bond types)



Angle Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of angle types)



Dihedral Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of dihedral types)



Improper Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of improper types)



BondBond Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of angle types)



BondAngle Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of angle types)



MiddleBondTorsion Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of dihedral types)



EndBondTorsion Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of dihedral types)



AngleTorsion Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of dihedral types)



AngleAngleTorsion Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of dihedral types)



BondBond13 Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of dihedral types)



AngleAngle Coeffs



  1 coeff1 coeff2 ...

  ...

  N coeff1 coeff2 ...              (N = # of improper types)



Atoms



  1 molecule-tag atom-type q x y z nx ny nz  (nx,ny,nz are optional -

  ...                                    see &quot;true flag&quot; input command)

  ...                

  N molecule-tag atom-type q x y z nx ny nz  (N = # of atoms)



Velocities



  1 vx vy vz

  ...

  ...                

  N vx vy vz                        (N = # of atoms)



Bonds



  1 bond-type atom-1 atom-2

  ...

  N bond-type atom-1 atom-2         (N = # of bonds)



Angles



  1 angle-type atom-1 atom-2 atom-3  (atom-2 is the center atom in angle)

  ...

  N angle-type atom-1 atom-2 atom-3  (N = # of angles)



Dihedrals



  1 dihedral-type atom-1 atom-2 atom-3 atom-4  (atoms 2-3 form central bond)

  ...

  N dihedral-type atom-1 atom-2 atom-3 atom-4  (N = # of dihedrals)



Impropers



  1 improper-type atom-1 atom-2 atom-3 atom-4  (atom-2 is central atom)

  ...

  N improper-type atom-1 atom-2 atom-3 atom-4  (N = # of impropers)

</PRE>

</BODY>

</HTML>

doc/2001/deficiencies.html

0 → 100644
+0 −0

File added.

Preview size limit exceeded, changes collapsed.

doc/2001/force_fields.html

0 → 100644
+0 −0

File added.

Preview size limit exceeded, changes collapsed.

CRA Git | Maintained and supported by SUSTech CRA and CCSE