forked from marble234/LAMMPS
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathSection_start.html
1383 lines (1329 loc) · 61.7 KB
/
Section_start.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<HTML>
<CENTER><A HREF = "Section_intro.html">Previous Section</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> - <A HREF = "Section_commands.html">Next Section</A>
</CENTER>
<HR>
<H3>2. Getting Started
</H3>
<P>This section describes how to build and run LAMMPS, for both new and
experienced users.
</P>
2.1 <A HREF = "#start_1">What's in the LAMMPS distribution</A><BR>
2.2 <A HREF = "#start_2">Making LAMMPS</A><BR>
2.3 <A HREF = "#start_3">Making LAMMPS with optional packages</A><BR>
2.4 <A HREF = "#start_4">Building LAMMPS via the Make.py script</A><BR>
2.5 <A HREF = "#start_5">Building LAMMPS as a library</A><BR>
2.6 <A HREF = "#start_6">Running LAMMPS</A><BR>
2.7 <A HREF = "#start_7">Command-line options</A><BR>
2.8 <A HREF = "#start_8">Screen output</A><BR>
2.9 <A HREF = "#start_9">Tips for users of previous versions</A> <BR>
<HR>
<HR>
<H4><A NAME = "start_1"></A>2.1 What's in the LAMMPS distribution
</H4>
<P>When you download LAMMPS you will need to unzip and untar the
downloaded file with the following commands, after placing the file in
an appropriate directory.
</P>
<PRE>gunzip lammps*.tar.gz
tar xvf lammps*.tar
</PRE>
<P>This will create a LAMMPS directory containing two files and several
sub-directories:
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >README</TD><TD > text file</TD></TR>
<TR><TD >LICENSE</TD><TD > the GNU General Public License (GPL)</TD></TR>
<TR><TD >bench</TD><TD > benchmark problems</TD></TR>
<TR><TD >doc</TD><TD > documentation</TD></TR>
<TR><TD >examples</TD><TD > simple test problems</TD></TR>
<TR><TD >potentials</TD><TD > embedded atom method (EAM) potential files</TD></TR>
<TR><TD >src</TD><TD > source files</TD></TR>
<TR><TD >tools</TD><TD > pre- and post-processing tools
</TD></TR></TABLE></DIV>
<P>If you download one of the Windows executables from the download page,
then you just get a single file:
</P>
<PRE>lmp_windows.exe
</PRE>
<P>Skip to the <A HREF = "#start_6">Running LAMMPS</A> sections for info on how to
launch these executables on a Windows box.
</P>
<P>The Windows executables for serial or parallel only include certain
packages and bug-fixes/upgrades listed on <A HREF = "http://lammps.sandia.gov/bug.html">this
page</A> up to a certain date, as
stated on the download page. If you want something with more packages
or that is more current, you'll have to download the source tarball
and build it yourself from source code using Microsoft Visual Studio,
as described in the next section.
</P>
<HR>
<H4><A NAME = "start_2"></A>2.2 Making LAMMPS
</H4>
<P>This section has the following sub-sections:
</P>
<UL><LI><A HREF = "#start_2_1">Read this first</A>
<LI><A HREF = "#start_2_2">Steps to build a LAMMPS executable</A>
<LI><A HREF = "#start_2_3">Common errors that can occur when making LAMMPS</A>
<LI><A HREF = "#start_2_4">Additional build tips</A>
<LI><A HREF = "#start_2_5">Building for a Mac</A>
<LI><A HREF = "#start_2_6">Building for Windows</A>
</UL>
<HR>
<A NAME = "start_2_1"></A><B><I>Read this first:</I></B>
<P>Building LAMMPS can be non-trivial. You may need to edit a makefile,
there are compiler options to consider, additional libraries can be
used (MPI, FFT, JPEG), LAMMPS packages may be included or excluded,
some of these packages use auxiliary libraries which need to be
pre-built, etc.
</P>
<P>Please read this section carefully. If you are not comfortable with
makefiles, or building codes on a Unix platform, or running an MPI job
on your machine, please find a local expert to help you. Many
compiling, linking, and run problems that users have are often not
LAMMPS issues - they are peculiar to the user's system, compilers,
libraries, etc. Such questions are better answered by a local expert.
</P>
<P>If you have a build problem that you are convinced is a LAMMPS issue
(e.g. the compiler complains about a line of LAMMPS source code), then
please post a question to the <A HREF = "http://lammps.sandia.gov/mail.html">LAMMPS mail
list</A>.
</P>
<P>If you succeed in building LAMMPS on a new kind of machine, for which
there isn't a similar Makefile for in the src/MAKE directory, send it
to the developers and we can include it in the LAMMPS distribution.
</P>
<HR>
<A NAME = "start_2_2"></A><B><I>Steps to build a LAMMPS executable:</I></B>
<P><B>Step 0</B>
</P>
<P>The src directory contains the C++ source and header files for LAMMPS.
It also contains a top-level Makefile and a MAKE sub-directory with
low-level Makefile.* files for many machines. From within the src
directory, type "make" or "gmake". You should see a list of available
choices. If one of those is the machine and options you want, you can
type a command like:
</P>
<PRE>make linux
or
gmake mac
</PRE>
<P>Note that on a multi-processor or multi-core platform you can launch a
parallel make, by using the "-j" switch with the make command, which
will build LAMMPS more quickly.
</P>
<P>If you get no errors and an executable like lmp_linux or lmp_mac is
produced, you're done; it's your lucky day.
</P>
<P>Note that by default only a few of LAMMPS optional packages are
installed. To build LAMMPS with optional packages, see <A HREF = "#start_3">this
section</A> below.
</P>
<P><B>Step 1</B>
</P>
<P>If Step 0 did not work, you will need to create a low-level Makefile
for your machine, like Makefile.foo. You should make a copy of an
existing src/MAKE/Makefile.* as a starting point. The only portions
of the file you need to edit are the first line, the "compiler/linker
settings" section, and the "LAMMPS-specific settings" section.
</P>
<P><B>Step 2</B>
</P>
<P>Change the first line of src/MAKE/Makefile.foo to list the word "foo"
after the "#", and whatever other options it will set. This is the
line you will see if you just type "make".
</P>
<P><B>Step 3</B>
</P>
<P>The "compiler/linker settings" section lists compiler and linker
settings for your C++ compiler, including optimization flags. You can
use g++, the open-source GNU compiler, which is available on all Unix
systems. You can also use mpicc which will typically be available if
MPI is installed on your system, though you should check which actual
compiler it wraps. Vendor compilers often produce faster code. On
boxes with Intel CPUs, we suggest using the commercial Intel icc
compiler, which can be downloaded from <A HREF = "http://www.intel.com/software/products/noncom">Intel's compiler site</A>.
</P>
<P>If building a C++ code on your machine requires additional libraries,
then you should list them as part of the LIB variable.
</P>
<P>The DEPFLAGS setting is what triggers the C++ compiler to create a
dependency list for a source file. This speeds re-compilation when
source (*.cpp) or header (*.h) files are edited. Some compilers do
not support dependency file creation, or may use a different switch
than -D. GNU g++ works with -D. If your compiler can't create
dependency files, then you'll need to create a Makefile.foo patterned
after Makefile.storm, which uses different rules that do not involve
dependency files. Note that when you build LAMMPS for the first time
on a new platform, a long list of *.d files will be printed out
rapidly. This is not an error; it is the Makefile doing its normal
creation of dependencies.
</P>
<P><B>Step 4</B>
</P>
<P>The "system-specific settings" section has several parts. Note that
if you change any -D setting in this section, you should do a full
re-compile, after typing "make clean" (which will describe different
clean options).
</P>
<P>The LMP_INC variable is used to include options that turn on ifdefs
within the LAMMPS code. The options that are currently recogized are:
</P>
<UL><LI>-DLAMMPS_GZIP
<LI>-DLAMMPS_JPEG
<LI>-DLAMMPS_MEMALIGN
<LI>-DLAMMPS_XDR
<LI>-DLAMMPS_SMALLBIG
<LI>-DLAMMPS_BIGBIG
<LI>-DLAMMPS_SMALLSMALL
<LI>-DLAMMPS_LONGLONG_TO_LONG
<LI>-DPACK_ARRAY
<LI>-DPACK_POINTER
<LI>-DPACK_MEMCPY
</UL>
<P>The read_data and dump commands will read/write gzipped files if you
compile with -DLAMMPS_GZIP. It requires that your Unix support the
"popen" command.
</P>
<P>If you use -DLAMMPS_JPEG, the <A HREF = "dump.html">dump image</A> command will be
able to write out JPEG image files. If not, it will only be able to
write out text-based PPM image files. For JPEG files, you must also
link LAMMPS with a JPEG library, as described below.
</P>
<P>Using -DLAMMPS_MEMALIGN=<bytes> enables the use of the
posix_memalign() call instead of malloc() when large chunks or memory
are allocated by LAMMPS. This can help to make more efficient use of
vector instructions of modern CPUS, since dynamically allocated memory
has to be aligned on larger than default byte boundaries (e.g. 16
bytes instead of 8 bytes on x86 type platforms) for optimal
performance.
</P>
<P>If you use -DLAMMPS_XDR, the build will include XDR compatibility
files for doing particle dumps in XTC format. This is only necessary
if your platform does have its own XDR files available. See the
Restrictions section of the <A HREF = "dump.html">dump</A> command for details.
</P>
<P>Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG,
-D-DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG.
These settings refer to use of 4-byte (small) vs 8-byte (big) integers
within LAMMPS, as specified in src/lmptype.h. The only reason to use
the BIGBIG setting is to enable simulation of huge molecular systems
with more than 2 billion atoms or to allow moving atoms to wrap back
through a periodic box more than 512 times. The only reason to use
the SMALLSMALL setting is if your machine does not support 64-bit
integers. See the <A HREF = "#start_2_4">Additional build tips</A> section below
for more details.
</P>
<P>The -DLAMMPS_LONGLONG_TO_LONG setting may be needed if your system or
MPI version does not recognize "long long" data types. In this case a
"long" data type is likely already 64-bits, in which case this setting
will convert to that data type.
</P>
<P>Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY
options can make for faster parallel FFTs (in the PPPM solver) on some
platforms. The -DPACK_ARRAY setting is the default. See the
<A HREF = "kspace_style.html">kspace_style</A> command for info about PPPM. See
Step 6 below for info about building LAMMPS with an FFT library.
</P>
<P><B>Step 5</B>
</P>
<P>The 3 MPI variables are used to specify an MPI library to build LAMMPS
with.
</P>
<P>If you want LAMMPS to run in parallel, you must have an MPI library
installed on your platform. If you use an MPI-wrapped compiler, such
as "mpicc" to build LAMMPS, you should be able to leave these 3
variables blank; the MPI wrapper knows where to find the needed files.
If not, and MPI is installed on your system in the usual place (under
/usr/local), you also may not need to specify these 3 variables. On
some large parallel machines which use "modules" for their
compile/link environements, you may simply need to include the correct
module in your build environment. Or the parallel machine may have a
vendor-provided MPI which the compiler has no trouble finding.
</P>
<P>Failing this, with these 3 variables you can specify where the mpi.h
file (MPI_INC) and the MPI library file (MPI_PATH) are found and the
name of the library file (MPI_LIB).
</P>
<P>If you are installing MPI yourself, we recommend Argonne's MPICH2
or OpenMPI. MPICH can be downloaded from the <A HREF = "http://www.mcs.anl.gov/research/projects/mpich2/">Argonne MPI
site</A>. OpenMPI can
be downloaded from the <A HREF = "http://www.open-mpi.org">OpenMPI site</A>.
Other MPI packages should also work. If you are running on a big
parallel platform, your system people or the vendor should have
already installed a version of MPI, which is likely to be faster
than a self-installed MPICH or OpenMPI, so find out how to build
and link with it. If you use MPICH or OpenMPI, you will have to
configure and build it for your platform. The MPI configure script
should have compiler options to enable you to use the same compiler
you are using for the LAMMPS build, which can avoid problems that can
arise when linking LAMMPS to the MPI library.
</P>
<P>If you just want to run LAMMPS on a single processor, you can use the
dummy MPI library provided in src/STUBS, since you don't need a true
MPI library installed on your system. See the
src/MAKE/Makefile.serial file for how to specify the 3 MPI variables
in this case. You will also need to build the STUBS library for your
platform before making LAMMPS itself. To build from the src
directory, type "make stubs", or from the STUBS dir, type "make".
This should create a libmpi_stubs.a file suitable for linking to
LAMMPS. If the build fails, you will need to edit the STUBS/Makefile
for your platform.
</P>
<P>The file STUBS/mpi.c provides a CPU timer function called
MPI_Wtime() that calls gettimeofday() . If your system doesn't
support gettimeofday() , you'll need to insert code to call another
timer. Note that the ANSI-standard function clock() rolls over after
an hour or so, and is therefore insufficient for timing long LAMMPS
simulations.
</P>
<P><B>Step 6</B>
</P>
<P>The 3 FFT variables allow you to specify an FFT library which LAMMPS
uses (for performing 1d FFTs) when running the particle-particle
particle-mesh (PPPM) option for long-range Coulombics via the
<A HREF = "kspace_style.html">kspace_style</A> command.
</P>
<P>LAMMPS supports various open-source or vendor-supplied FFT libraries
for this purpose. If you leave these 3 variables blank, LAMMPS will
use the open-source <A HREF = "http://kissfft.sf.net">KISS FFT library</A>, which is
included in the LAMMPS distribution. This library is portable to all
platforms and for typical LAMMPS simulations is almost as fast as FFTW
or vendor optimized libraries. If you are not including the KSPACE
package in your build, you can also leave the 3 variables blank.
</P>
<P>Otherwise, select which kinds of FFTs to use as part of the FFT_INC
setting by a switch of the form -DFFT_XXX. Recommended values for XXX
are: MKL, SCSL, FFTW2, and FFTW3. Legacy options are: INTEL, SGI,
ACML, and T3E. For backward compatability, using -DFFT_FFTW will use
the FFTW2 library. Using -DFFT_NONE will use the KISS library
described above.
</P>
<P>You may also need to set the FFT_INC, FFT_PATH, and FFT_LIB variables,
so the compiler and linker can find the needed FFT header and library
files. Note that on some large parallel machines which use "modules"
for their compile/link environements, you may simply need to include
the correct module in your build environment. Or the parallel machine
may have a vendor-provided FFT library which the compiler has no
trouble finding.
</P>
<P>FFTW is a fast, portable library that should also work on any
platform. You can download it from
<A HREF = "http://www.fftw.org">www.fftw.org</A>. Both the legacy version 2.1.X and
the newer 3.X versions are supported as -DFFT_FFTW2 or -DFFT_FFTW3.
Building FFTW for your box should be as simple as ./configure; make.
Note that on some platforms FFTW2 has been pre-installed, and uses
renamed files indicating the precision it was compiled with,
e.g. sfftw.h, or dfftw.h instead of fftw.h. In this case, you can
specify an additional define variable for FFT_INC called -DFFTW_SIZE,
which will select the correct include file. In this case, for FFT_LIB
you must also manually specify the correct library, namely -lsfftw or
-ldfftw.
</P>
<P>The FFT_INC variable also allows for a -DFFT_SINGLE setting that will
use single-precision FFTs with PPPM, which can speed-up long-range
calulations, particularly in parallel or on GPUs. Fourier transform
and related PPPM operations are somewhat insensitive to floating point
truncation errors and thus do not always need to be performed in
double precision. Using the -DFFT_SINGLE setting trades off a little
accuracy for reduced memory use and parallel communication costs for
transposing 3d FFT data. Note that single precision FFTs have only
been tested with the FFTW3, FFTW2, MKL, and KISS FFT options.
</P>
<P><B>Step 7</B>
</P>
<P>The 3 JPG variables allow you to specify a JPEG library which LAMMPS
uses when writing out JPEG files via the <A HREF = "dump_image.html">dump image</A>
command. These can be left blank if you do not use the -DLAMMPS_JPEG
switch discussed above in Step 4, since in that case JPEG output will
be disabled.
</P>
<P>A standard JPEG library usually goes by the name libjpeg.a and has an
associated header file jpeglib.h. Whichever JPEG library you have on
your platform, you'll need to set the appropriate JPG_INC, JPG_PATH,
and JPG_LIB variables, so that the compiler and linker can find it.
</P>
<P>As before, if these header and library files are in the usual place on
your machine, you may not need to set these variables.
</P>
<P><B>Step 8</B>
</P>
<P>Note that by default only a few of LAMMPS optional packages are
installed. To build LAMMPS with optional packages, see <A HREF = "#start_3">this
section</A> below, before proceeding to Step 9.
</P>
<P><B>Step 9</B>
</P>
<P>That's it. Once you have a correct Makefile.foo, you have installed
the optional LAMMPS packages you want to include in your build, and
you have pre-built any other needed libraries (e.g. MPI, FFT, package
libraries), all you need to do from the src directory is type
something like this:
</P>
<PRE>make foo
or
gmake foo
</PRE>
<P>You should get the executable lmp_foo when the build is complete.
</P>
<HR>
<A NAME = "start_2_3"></A><B><I>Errors that can occur when making LAMMPS:</I></B>
<P>IMPORTANT NOTE: If an error occurs when building LAMMPS, the compiler
or linker will state very explicitly what the problem is. The error
message should give you a hint as to which of the steps above has
failed, and what you need to do in order to fix it. Building a code
with a Makefile is a very logical process. The compiler and linker
need to find the appropriate files and those files need to be
compatible with LAMMPS source files. When a make fails, there is
usually a very simple reason, which you or a local expert will need to
fix.
</P>
<P>Here are two non-obvious errors that can occur:
</P>
<P>(1) If the make command breaks immediately with errors that indicate
it can't find files with a "*" in their names, this can be because
your machine's native make doesn't support wildcard expansion in a
makefile. Try gmake instead of make. If that doesn't work, try using
a -f switch with your make command to use a pre-generated
Makefile.list which explicitly lists all the needed files, e.g.
</P>
<PRE>make makelist
make -f Makefile.list linux
gmake -f Makefile.list mac
</PRE>
<P>The first "make" command will create a current Makefile.list with all
the file names in your src dir. The 2nd "make" command (make or
gmake) will use it to build LAMMPS. Note that you should
include/exclude any desired optional packages before using the "make
makelist" command.
</P>
<P>(2) If you get an error that says something like 'identifier "atoll"
is undefined', then your machine does not support "long long"
integers. Try using the -DLAMMPS_LONGLONG_TO_LONG setting described
above in Step 4.
</P>
<HR>
<A NAME = "start_2_4"></A><B><I>Additional build tips:</I></B>
<P>(1) Building LAMMPS for multiple platforms.
</P>
<P>You can make LAMMPS for multiple platforms from the same src
directory. Each target creates its own object sub-directory called
Obj_target where it stores the system-specific *.o files.
</P>
<P>(2) Cleaning up.
</P>
<P>Typing "make clean-all" or "make clean-machine" will delete *.o object
files created when LAMMPS is built, for either all builds or for a
particular machine.
</P>
<P>(3) Changing the LAMMPS size limits via -DLAMMPS_SMALLBIG or
-DLAMMPS_BIBIG or -DLAMMPS_SMALLSMALL
</P>
<P>As explained above, any of these 3 settings can be specified on the
LMP_INC line in your low-level src/MAKE/Makefile.foo.
</P>
<P>The default is -DLAMMPS_SMALLBIG which allows for systems with up to
2^63 atoms and timesteps (about 9 billion billion). The atom limit is
for atomic systems that do not require atom IDs. For molecular
models, which require atom IDs, the limit is 2^31 atoms (about 2
billion). With this setting, image flags are stored in 32-bit
integers, which means for 3 dimensions that atoms can only wrap around
a periodic box at most 512 times. If atoms move through the periodic
box more than this limit, the image flags will "roll over", e.g. from
511 to -512, which can cause diagnostics like the mean-squared
displacement, as calculated by the <A HREF = "compute_msd.html">compute msd</A>
command, to be faulty.
</P>
<P>To allow for larger molecular systems or larger image flags, compile
with -DLAMMPS_BIGBIG. This enables molecular systems with up to 2^63
atoms (about 9 billion billion). And image flags will not "roll over"
until they reach 2^20 = 1048576.
</P>
<P>IMPORTANT NOTE: As of 6/2012, the BIGBIG setting does not yet enable
molecular systems to grow as large as 2^63. Only the image flag roll
over is currently affected by this compile option.
</P>
<P>If your system does not support 8-byte integers, you will need to
compile with the -DLAMMPS_SMALLSMALL setting. This will restrict your
total number of atoms (for atomic or molecular models) and timesteps
to 2^31 (about 2 billion). Image flags will roll over at 2^9 = 512.
</P>
<P>Note that in src/lmptype.h there are also settings for the MPI data
types associated with the integers that store atom IDs and total
system sizes. These need to be consistent with the associated C data
types, or else LAMMPS will generate a run-time error.
</P>
<P>In all cases, the size of problem that can be run on a per-processor
basis is limited by 4-byte integer storage to 2^31 atoms per processor
(about 2 billion). This should not normally be a restriction since
such a problem would have a huge per-processor memory footprint due to
neighbor lists and would run very slowly in terms of CPU
secs/timestep.
</P>
<HR>
<A NAME = "start_2_5"></A><B><I>Building for a Mac:</I></B>
<P>OS X is BSD Unix, so it should just work. See the
src/MAKE/Makefile.mac file.
</P>
<HR>
<A NAME = "start_2_6"></A><B><I>Building for Windows:</I></B>
<P>The LAMMPS download page has an option to download both a serial and
parallel pre-built Windows exeutable. See the <A HREF = "#start_6">Running
LAMMPS</A> section for instructions for running these
executables on a Windows box.
</P>
<P>The pre-built executables are built with a subset of the available
pacakges; see the download page for the list. If you want
a Windows version with specific packages included and excluded,
you can build it yourself.
</P>
<P>One way to do this is install and use cygwin to build LAMMPS with a
standard Linus make, just as you would on any Linux box; see
src/MAKE/Makefile.cygwin.
</P>
<P>The other way to do this is using Visual Studio and project files.
See the src/WINDOWS directory and its README.txt file for instructions
on both a basic build and a customized build with pacakges you select.
</P>
<HR>
<H4><A NAME = "start_3"></A>2.3 Making LAMMPS with optional packages
</H4>
<P>This section has the following sub-sections:
</P>
<UL><LI><A HREF = "#start_3_1">Package basics</A>
<LI><A HREF = "#start_3_2">Including/excluding packages</A>
<LI><A HREF = "#start_3_3">Packages that require extra libraries</A>
<LI><A HREF = "#start_3_4">Additional Makefile settings for extra libraries</A>
</UL>
<HR>
<A NAME = "start_3_1"></A><B><I>Package basics:</I></B>
<P>The source code for LAMMPS is structured as a set of core files which
are always included, plus optional packages. Packages are groups of
files that enable a specific set of features. For example, force
fields for molecular systems or granular systems are in packages. You
can see the list of all packages by typing "make package" from within
the src directory of the LAMMPS distribution.
</P>
<P>If you use a command in a LAMMPS input script that is specific to a
particular package, you must have built LAMMPS with that package, else
you will get an error that the style is invalid or the command is
unknown. Every command's doc page specfies if it is part of a
package. You can also type
</P>
<PRE>lmp_machine -h
</PRE>
<P>to run your executable with the optional <A HREF = "#start_7">-h command-line
switch</A> for "help", which will list the styles and commands
known to your executable.
</P>
<P>There are two kinds of packages in LAMMPS, standard and user packages.
More information about the contents of standard and user packages is
given in <A HREF = "Section_packages.html">Section_packages</A> of the manual. The
difference between standard and user packages is as follows:
</P>
<P>Standard packages are supported by the LAMMPS developers and are
written in a syntax and style consistent with the rest of LAMMPS.
This means we will answer questions about them, debug and fix them if
necessary, and keep them compatible with future changes to LAMMPS.
</P>
<P>User packages have been contributed by users, and always begin with
the user prefix. If they are a single command (single file), they are
typically in the user-misc package. Otherwise, they are a a set of
files grouped together which add a specific functionality to the code.
</P>
<P>User packages don't necessarily meet the requirements of the standard
packages. If you have problems using a feature provided in a user
package, you will likely need to contact the contributor directly to
get help. Information on how to submit additions you make to LAMMPS
as a user-contributed package is given in <A HREF = "Section_modify.html#mod_15">this
section</A> of the documentation.
</P>
<P>Some packages (both standard and user) require additional libraries.
See more details below.
</P>
<HR>
<A NAME = "start_3_2"></A><B><I>Including/excluding packages:</I></B>
<P>To use or not use a package you must include or exclude it before
building LAMMPS. From the src directory, this is typically as simple
as:
</P>
<PRE>make yes-colloid
make g++
</PRE>
<P>or
</P>
<PRE>make no-manybody
make g++
</PRE>
<P>Some packages have individual files that depend on other packages
being included. LAMMPS checks for this and does the right thing.
I.e. individual files are only included if their dependencies are
already included. Likewise, if a package is excluded, other files
dependent on that package are also excluded.
</P>
<P>The reason to exclude packages is if you will never run certain kinds
of simulations. For some packages, this will keep you from having to
build auxiliary libraries (see below), and will also produce a smaller
executable which may run a bit faster.
</P>
<P>When you download a LAMMPS tarball, these packages are pre-installed
in the src directory: KSPACE, MANYBODY,MOLECULE. When you download
LAMMPS source files from the SVN or Git repositories, no packages are
pre-installed.
</P>
<P>Packages are included or excluded by typing "make yes-name" or "make
no-name", where "name" is the name of the package in lower-case, e.g.
name = kspace for the KSPACE package or name = user-atc for the
USER-ATC package. You can also type "make yes-standard", "make
no-standard", "make yes-user", "make no-user", "make yes-all" or "make
no-all" to include/exclude various sets of packages. Type "make
package" to see the all of the package-related make options.
</P>
<P>IMPORTANT NOTE: Inclusion/exclusion of a package works by simply
moving files back and forth between the main src directory and
sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC),
so that the files are seen or not seen when LAMMPS is built. After
you have included or excluded a package, you must re-build LAMMPS.
</P>
<P>Additional package-related make options exist to help manage LAMMPS
files that exist in both the src directory and in package
sub-directories. You do not normally need to use these commands
unless you are editing LAMMPS files or have downloaded a patch from
the LAMMPS WWW site.
</P>
<P>Typing "make package-update" will overwrite src files with files from
the package sub-directories if the package has been included. It
should be used after a patch is installed, since patches only update
the files in the package sub-directory, but not the src files. Typing
"make package-overwrite" will overwrite files in the package
sub-directories with src files.
</P>
<P>Typing "make package-status" will show which packages are currently
included. Of those that are included, it will list files that are
different in the src directory and package sub-directory. Typing
"make package-diff" lists all differences between these files. Again,
type "make package" to see all of the package-related make options.
</P>
<HR>
<A NAME = "start_3_3"></A><B><I>Packages that require extra libraries:</I></B>
<P>A few of the standard and user packages require additional auxiliary
libraries. They must be compiled first, before LAMMPS is built. If
you get a LAMMPS build error about a missing library, this is likely
the reason. See the <A HREF = "Section_packages.html">Section_packages</A> doc page
for a list of packages that have auxiliary libraries.
</P>
<P>Code for some of these auxiliary libraries is included in the LAMMPS
distribution under the lib directory. Examples are the USER-ATC and
MEAM packages. Some auxiliary libraries are not included with LAMMPS;
to use the associated package you must download and install the
auxiliary library yourself. Examples are the KIM and VORONOI and
USER-MOLFILE packages.
</P>
<P>For libraries with provided source code, each lib directory has a
README file (e.g. lib/reax/README) with instructions on how to build
that library. Typically this is done by typing something like:
</P>
<PRE>make -f Makefile.g++
</PRE>
<P>If one of the provided Makefiles is not
appropriate for your system you will need to edit or add one.
Note that all the Makefiles have a setting for EXTRAMAKE at
the top that names a Makefile.lammps.* file.
</P>
<P>If successful, this will produce 2 files in the lib directory:
</P>
<PRE>libpackage.a
Makefile.lammps
</PRE>
<P>The Makefile.lammps file is a copy of the EXTRAMAKE file specified
in the Makefile you used.
</P>
<P>You MUST insure that the settings in Makefile.lammps are appropriate
for your system. If they are not, the LAMMPS build will fail.
</P>
<P>As explained in the lib/package/README files, they are used to specify
additional system libraries and their locations so that LAMMPS can
build with the auxiliary library. For example, if the MEAM or REAX
packages are used, the auxiliary libraries consist of F90 code, build
with a F90 complier. To link that library with LAMMPS (a C++ code)
via whatever C++ compiler LAMMPS is built with, typically requires
additional Fortran-to-C libraries be included in the link. Another
example are the BLAS and LAPACK libraries needed to use the USER-ATC
or USER-AWPMD packages.
</P>
<P>For libraries without provided source code, see the
src/package/Makefile.lammps file for information on where to find the
library and how to build it. E.g. the file src/KIM/Makefile.lammps.
This file serves the same purpose as the lib/package/Makefile.lammps
file described above. It has settings needed when LAMMPS is built to
link with the auxiliary library. Again, you MUST insure that the
settings in src/package/Makefile.lammps are appropriate for your
system and where you installed the auxiliary library. If they are
not, the LAMMPS build will fail.
</P>
<HR>
<H4><A NAME = "start_4"></A>2.4 Building LAMMPS via the Make.py script
</H4>
<P>The src directory includes a Make.py script, written
in Python, which can be used to automate various steps
of the build process.
</P>
<P>You can run the script from the src directory by typing either:
</P>
<PRE>Make.py
python Make.py
</PRE>
<P>which will give you info about the tool. For the former to work, you
may need to edit the 1st line of the script to point to your local
Python. And you may need to insure the script is executable:
</P>
<PRE>chmod +x Make.py
</PRE>
<P>The following options are supported as switches:
</P>
<UL><LI>-i file1 file2 ...
<LI>-p package1 package2 ...
<LI>-u package1 package2 ...
<LI>-e package1 arg1 arg2 package2 ...
<LI>-o dir
<LI>-b machine
<LI>-s suffix1 suffix2 ...
<LI>-l dir
<LI>-j N
<LI>-h switch1 switch2 ...
</UL>
<P>Help on any switch can be listed by using -h, e.g.
</P>
<PRE>Make.py -h -i -p
</PRE>
<P>At a hi-level, these are the kinds of package management
and build tasks that can be performed easily, using
the Make.py tool:
</P>
<UL><LI>install/uninstall packages and build the associated external libs (use -p and -u and -e)
<LI>install packages needed for one or more input scripts (use -i and -p)
<LI>build LAMMPS, either in the src dir or new dir (use -b)
<LI>create a new dir with only the source code needed for one or more input scripts (use -i and -o)
</UL>
<P>The last bullet can be useful when you wish to build a stripped-down
version of LAMMPS to run a specific script(s). Or when you wish to
move the minimal amount of files to another platform for a remote
LAMMPS build.
</P>
<P>Note that using Make.py is not a substitute for insuring you have a
valid src/MAKE/Makefile.foo for your system, or that external library
Makefiles in any lib/* directories you use are also valid for your
system. But once you have done that, you can use Make.py to quickly
include/exclude the packages and external libraries needed by your
input scripts.
</P>
<HR>
<H4><A NAME = "start_5"></A>2.5 Building LAMMPS as a library
</H4>
<P>LAMMPS can be built as either a static or shared library, which can
then be called from another application or a scripting language. See
<A HREF = "Section_howto.html#howto_10">this section</A> for more info on coupling
LAMMPS to other codes. See <A HREF = "Section_python.html">this section</A> for
more info on wrapping and running LAMMPS from Python.
</P>
<H5><B>Static library:</B>
</H5>
<P>To build LAMMPS as a static library (*.a file on Linux), type
</P>
<PRE>make makelib
make -f Makefile.lib foo
</PRE>
<P>where foo is the machine name. This kind of library is typically used
to statically link a driver application to LAMMPS, so that you can
insure all dependencies are satisfied at compile time. Note that
inclusion or exclusion of any desired optional packages should be done
before typing "make makelib". The first "make" command will create a
current Makefile.lib with all the file names in your src dir. The
second "make" command will use it to build LAMMPS as a static library,
using the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The
build will create the file liblammps_foo.a which another application can
link to.
</P>
<H5><B>Shared library:</B>
</H5>
<P>To build LAMMPS as a shared library (*.so file on Linux), which can be
dynamically loaded, e.g. from Python, type
</P>
<PRE>make makeshlib
make -f Makefile.shlib foo
</PRE>
<P>where foo is the machine name. This kind of library is required when
wrapping LAMMPS with Python; see <A HREF = "Section_python.html">Section_python</A>
for details. Again, note that inclusion or exclusion of any desired
optional packages should be done before typing "make makelib". The
first "make" command will create a current Makefile.shlib with all the
file names in your src dir. The second "make" command will use it to
build LAMMPS as a shared library, using the SHFLAGS and SHLIBFLAGS
settings in src/MAKE/Makefile.foo. The build will create the file
liblammps_foo.so which another application can link to dyamically. It
will also create a soft link liblammps.so, which the Python wrapper uses
by default.
</P>
<P>Note that for a shared library to be usable by a calling program, all
the auxiliary libraries it depends on must also exist as shared
libraries. This will be the case for libraries included with LAMMPS,
such as the dummy MPI library in src/STUBS or any package libraries in
lib/packges, since they are always built as shared libraries with the
-fPIC switch. However, if a library like MPI or FFTW does not exist
as a shared library, the second make command will generate an error.
This means you will need to install a shared library version of the
package. The build instructions for the library should tell you how
to do this.
</P>
<P>As an example, here is how to build and install the <A HREF = "http://www-unix.mcs.anl.gov/mpi">MPICH
library</A>, a popular open-source version of MPI, distributed by
Argonne National Labs, as a shared library in the default
/usr/local/lib location:
</P>
<PRE>./configure --enable-shared
make
make install
</PRE>
<P>You may need to use "sudo make install" in place of the last line if
you do not have write privileges for /usr/local/lib. The end result
should be the file /usr/local/lib/libmpich.so.
</P>
<H5><B>Additional requirement for using a shared library:</B>
</H5>
<P>The operating system finds shared libraries to load at run-time using
the environment variable LD_LIBRARY_PATH. So you may wish to copy the
file src/liblammps.so or src/liblammps_g++.so (for example) to a place
the system can find it by default, such as /usr/local/lib, or you may
wish to add the LAMMPS src directory to LD_LIBRARY_PATH, so that the
current version of the shared library is always available to programs
that use it.
</P>
<P>For the csh or tcsh shells, you would add something like this to your
~/.cshrc file:
</P>
<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src
</PRE>
<H5><B>Calling the LAMMPS library:</B>
</H5>
<P>Either flavor of library (static or shared0 allows one or more LAMMPS
objects to be instantiated from the calling program.
</P>
<P>When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from
within the calling code, as needed.
</P>
<P>When used from a C or Fortran program or a scripting language like
Python, the library has a simple function-style interface, provided in
src/library.cpp and src/library.h.
</P>
<P>See the sample codes in examples/COUPLE/simple for examples of C++ and
C and Fortran codes that invoke LAMMPS thru its library interface.
There are other examples as well in the COUPLE directory which are
discussed in <A HREF = "Section_howto.html#howto_10">Section_howto 10</A> of the
manual. See <A HREF = "Section_python.html">Section_python</A> of the manual for a
description of the Python wrapper provided with LAMMPS that operates
through the LAMMPS library interface.
</P>
<P>The files src/library.cpp and library.h define the C-style API for
using LAMMPS as a library. See <A HREF = "Section_howto.html#howto_19">Section_howto
19</A> of the manual for a description of the
interface and how to extend it for your needs.
</P>
<HR>
<H4><A NAME = "start_6"></A>2.6 Running LAMMPS
</H4>
<P>By default, LAMMPS runs by reading commands from stdin; e.g. lmp_linux
< in.file. This means you first create an input script (e.g. in.file)
containing the desired commands. <A HREF = "Section_commands.html">This section</A>
describes how input scripts are structured and what commands they
contain.
</P>
<P>You can test LAMMPS on any of the sample inputs provided in the
examples or bench directory. Input scripts are named in.* and sample
outputs are named log.*.name.P where name is a machine and P is the
number of processors it was run on.
</P>
<P>Here is how you might run a standard Lennard-Jones benchmark on a
Linux box, using mpirun to launch a parallel job:
</P>
<PRE>cd src
make linux
cp lmp_linux ../bench
cd ../bench
mpirun -np 4 lmp_linux < in.lj
</PRE>
<P>See <A HREF = "http://lammps.sandia.gov/bench.html">this page</A> for timings for this and the other benchmarks
on various platforms.
</P>
<HR>
<P>On a Windows box, you can skip making LAMMPS and simply download an
executable, as described above, though the pre-packaged executables
include only certain packages.
</P>
<P>To run a LAMMPS executable on a Windows machine, first decide whether
you want to download the non-MPI (serial) or the MPI (parallel)
version of the executable. Download and save the version you have
chosen.
</P>
<P>For the non-MPI version, follow these steps:
</P>
<UL><LI>Get a command prompt by going to Start->Run... ,
then typing "cmd".
<LI>Move to the directory where you have saved lmp_win_no-mpi.exe
(e.g. by typing: cd "Documents").
<LI>At the command prompt, type "lmp_win_no-mpi -in in.lj", replacing in.lj
with the name of your LAMMPS input script.
</UL>
<P>For the MPI version, which allows you to run LAMMPS under Windows on
multiple processors, follow these steps:
</P>
<UL><LI>Download and install
<A HREF = "http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads">MPICH2</A>
for Windows.
<LI>You'll need to use the mpiexec.exe and smpd.exe files from the MPICH2 package. Put them in
same directory (or path) as the LAMMPS Windows executable.
<LI>Get a command prompt by going to Start->Run... ,
then typing "cmd".
<LI>Move to the directory where you have saved lmp_win_mpi.exe
(e.g. by typing: cd "Documents").
<LI>Then type something like this: "mpiexec -np 4 -localonly lmp_win_mpi -in in.lj",
replacing in.lj with the name of your LAMMPS input script.
<LI>Note that you may need to provide smpd with a passphrase --- it doesn't matter what you
type.
<LI>In this mode, output may not immediately show up on the screen, so
if your input script takes a long time to execute, you may need to be
patient before the output shows up.
<LI>Alternatively, you can still use this executable to run on a single processor by
typing something like: "lmp_win_mpi -in in.lj".
</UL>
<HR>
<P>The screen output from LAMMPS is described in the next section. As it
runs, LAMMPS also writes a log.lammps file with the same information.
</P>
<P>Note that this sequence of commands copies the LAMMPS executable
(lmp_linux) to the directory with the input files. This may not be
necessary, but some versions of MPI reset the working directory to
where the executable is, rather than leave it as the directory where
you launch mpirun from (if you launch lmp_linux on its own and not
under mpirun). If that happens, LAMMPS will look for additional input
files and write its output files to the executable directory, rather
than your working directory, which is probably not what you want.
</P>
<P>If LAMMPS encounters errors in the input script or while running a
simulation it will print an ERROR message and stop or a WARNING
message and continue. See <A HREF = "Section_errors.html">Section_errors</A> for a
discussion of the various kinds of errors LAMMPS can or can't detect,
a list of all ERROR and WARNING messages, and what to do about them.
</P>
<P>LAMMPS can run a problem on any number of processors, including a
single processor. In theory you should get identical answers on any
number of processors and on any machine. In practice, numerical
round-off can cause slight differences and eventual divergence of
molecular dynamics phase space trajectories.
</P>
<P>LAMMPS can run as large a problem as will fit in the physical memory
of one or more processors. If you run out of memory, you must run on
more processors or setup a smaller problem.
</P>
<HR>
<H4><A NAME = "start_7"></A>2.7 Command-line options
</H4>
<P>At run time, LAMMPS recognizes several optional command-line switches
which may be used in any order. Either the full word or a one-or-two
letter abbreviation can be used:
</P>
<UL><LI>-c or -cuda
<LI>-e or -echo
<LI>-i or -in
<LI>-h or -help
<LI>-l or -log
<LI>-p or -partition
<LI>-pl or -plog
<LI>-ps or -pscreen
<LI>-r or -reorder
<LI>-sc or -screen
<LI>-sf or -suffix
<LI>-v or -var
</UL>
<P>For example, lmp_ibm might be launched as follows:
</P>