This section has the following sub-sections:
Building LAMMPS can be non-trivial. You will likely need to edit a -makefile, there are compiler options, additional libraries can be used -(MPI, FFT, JPEG), etc. 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 are not really LAMMPS issues - they are peculiar to the user's -system, compilers, libraries, etc. Such questions are better answered -by a local expert. +
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. +
+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 not really +LAMMPS issues - they are peculiar to the user's system, compilers, +libraries, etc. Such questions are better answered by a local expert.
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 @@ -104,16 +106,19 @@ to the developers and we'll include it in future LAMMPS releases.
Step 0 +
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 several machines. From within the src +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:
make linux +or gmake mac
Note that on a multi-processor or multi-core platform you can launch a @@ -123,62 +128,27 @@ will build LAMMPS more quickly.
If you get no errors and an executable like lmp_linux or lmp_mac is produced, you're done; it's your lucky day.
-(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 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 Makefile.list which explicitly -lists all the needed files, e.g. +
Note that by default only a few of LAMMPS optional pacakges are +installed. To build LAMMPS with optional packages, see this +section below.
-make makelist -make -f Makefile.list linux -gmake -f Makefile.list mac --
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. +
Step 1
-(2) If you get an error that says something like 'identifier "atoll" -is undefined', then your machine does not support "long long" -integers, and you need to edit the src/lmptype.h file. There is a -comment in the file about what to do. Basically you replace -MPI_LONG_LONG with MPI_LONG and atoll with atol. +
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.
-(3) Other errors typically occur because the low-level Makefile isn't -setup correctly for your machine. If your platform is named "foo", -you will need to create a Makefile.foo in the MAKE sub-directory. Use -whatever existing file is closest to your platform as a starting -point. See the next section for more instructions. +
Step 2
-(4) If you get a link-time error about missing libraries or missing -dependencies, then it can be because: +
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".
-The first issue is discussed below. The other two issue mean you need -to edit your low-level Makefile.foo, as discussed in the next -sub-section. +
Step 3
-These are the issues you need to address when editing a low-level -Makefile for your machine. The portions of the file you typically -need to edit are the first line, the "compiler/linker settings" -section, and the "system-specific settings" section. -
-(1) Change the first line of Makefile.foo to list the word "foo" after -the "#", and whatever other options you set. This is the line you -will see if you just type "make". -
-(2) The "compiler/linker settings" section lists compiler and linker +
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 @@ -204,11 +174,15 @@ 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.
-(3) The "system-specific settings" section has 6 parts. +
Step 4
-(3.a) The LMP_INC variable is used to include options that turn on -system-dependent ifdefs within the LAMMPS code. The settings -that are currently recogized are: +
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). +
+The LMP_INC variable is used to include options that turn on ifdefs +within the LAMMPS code. The options that are currently recogized are:
If you use -DLAMMPS_JPEG, the dump image 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. See section (3.d) below for more -details on this. +link LAMMPS with a JPEG library, as described below.
-(3.b) The 3 MPI variables are used to specify an MPI library to build -LAMMPS with. +
Step 5 +
+The 3 MPI variables are used to specify an MPI library to build LAMMPS +with.
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 can probably leave these 3 variables -blank. If you do not use "mpicc" as your compiler/linker, then you -need to specify where the mpi.h file (MPI_INC) and the MPI library -(MPI_PATH) is found and its name (MPI_LIB). +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. +
+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).
If you are installing MPI yourself, we recommend Argonne's MPICH 1.2 or 2.0 or OpenMPI. MPICH can be downloaded from the Argonne MPI @@ -262,100 +245,154 @@ 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.
-If you just want LAMMPS to run on a single processor, you can use the -STUBS library in place of MPI, since you don't need a true MPI library -installed on your system. See the Makefile.serial file for how to -specify the 3 MPI variables. You will also need to build the STUBS -library for your platform before making LAMMPS itself. From the STUBS -dir, type "make" and it will hopefully create a libmpi.a suitable for -linking to LAMMPS. If this build fails, you will need to edit the -STUBS/Makefile for your platform. +
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. From the src directory, type +"make stubs", or from the STUBS dir, type "make" and it should create +a libmpi.a suitable for linking to LAMMPS. If this build fails, you +will need to edit the STUBS/Makefile for your platform.
-The file STUBS/mpi.cpp has a CPU timer function 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. +
The file STUBS/mpi.cpp 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.
-(3.c) The 3 FFT variables are used to specify an FFT library which -LAMMPS uses when using the particle-particle particle-mesh (PPPM) -option in LAMMPS for long-range Coulombics via the +
Step 6 +
+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 kspace_style command.
-LAMMPS supports various open-source or vendor-supplied libraries for -this purpose. You need to set the appropriate FFT_INC, FFT_PATH, and -FFT_LIB variables, so the compiler and linker can find the needed -files. +
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 KISS FFT library, 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.
-If nothing is specified for these 3 variables, LAMMPS uses an internal -FFT library which is derived from KISSFFT. -This library is portable to all platforms and for typical LAMMPS -simulations it is almost as fast as vendor optimized libraries. +
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.
-Other open-source or vendor-supplied FFT libaries can be specified as -part of the FFT_INC setting by a switch of the form -DFFT_XXX where -recommended values for XXX are: MKL, SCSL, FFTW2, FFTW3 or NONE. -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. +
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.
FFTW is a fast, portable library that should also work on any platform. You can download it from -www.fftw.org. 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 in -your lo-level LAMMPS Makefile, called -DFFTW2_SIZE, which will select -the correct include file. In this case, For FFT_LIB you still must -manually specify the correct -lsfftw or -ldfftw. +www.fftw.org. 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 -DFFTW2_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.
-(3.d) 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 -the internal KISS FFTs options. +
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 packages.
-(3.e) The 3 JPG variables are used to specify a JPEG library which -LAMMPS uses when writing a JPEG file via the dump -image command. These can be left blank if you are -not using the -DLAMMPS_JPEG switch discussed above in section (3.a). +
Step 7 +
+The 3 JPG variables allow you to specify a JPEG library which LAMMPS +uses when writing out JPEG files via the dump image +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.
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 in Makefile.foo so that the compiler and linker -can find it. +and JPG_LIB variables, so that the compiler and linker can find it.
-(3.e) The several SYSLIB and SYSPATH variables can be ignored unless -you are building LAMMPS with one or more of the LAMMPS packages that -require these extra system libraries. The names of these packages are -the prefixes on the SYSLIB and SYSPATH variables. See the section -below for more details. The SYSLIB variables list the system -libraries. The SYSPATH variables are where they are located on your -machine, which is typically only needed if they are in some -non-standard place, that is not in your library search path. +
As before, if these header and library files are in the usual place on +your machine, you may not need to set these variables.
-That's it. Once you have a correct Makefile.foo and you have -pre-built any other libraries it will use (e.g. MPI, FFT, package -libraries), all you need to do from the src directory is type one of -these 2 commands: +
Step 8 +
+Note that by default only a few of LAMMPS optional pacakges are +installed. To build LAMMPS with optional packages, see this +section below, before proceeding to Step 9. +
+Step 9 +
+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:
make foo +or gmake foo
You should get the executable lmp_foo when the build is complete.
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. +
+Here are two non-obvious errors that can occur: +
+(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. +
+make makelist +make -f Makefile.list linux +gmake -f Makefile.list mac ++
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. +
+(2) If you get an error that says something like 'identifier "atoll" +is undefined', then your machine does not support "long long" +integers, and you need to edit the src/lmptype.h file. There is a +comment in the file about what to do. Basically you replace +MPI_LONG_LONG with MPI_LONG and atoll with atol. +
+(1) Building LAMMPS for multiple platforms.
@@ -410,13 +447,13 @@ secs/timestep.OS X is BSD Unix, so it should just work. See the Makefile.mac file.
The LAMMPS download page has an option to download both a serial and parallel pre-built Windows exeutable. See the Running LAMMPS @@ -459,12 +496,11 @@ and USER-REAXC. The fourth project includes the USER-AWPMD package. Package basics: -
The source code for LAMMPS is structured as a large 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". +
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".
The current list of standard packages is as follows:
@@ -490,12 +526,13 @@ package".There are also user-contributed packages which may be as simple as a -single additional file (see the src/USER-MISC directory) or many files -grouped together which add a specific functionality to the code. +
There are also several user-contributed packages which may be as +simple as a single additional file (see the src/USER-MISC directory) +or many files grouped together which add a specific functionality to +the code.
The difference between a standard package versus a user package is -as follows. +as follows:
Standard packages are supported by the LAMMPS developers and are written in a syntax and style consistent with the rest of LAMMPS. @@ -513,19 +550,28 @@ documentation. Including/excluding packages: -
To use or not use a package you must be include or exclude it before -LAMMPS is built. +
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:
+make yes-colloid +make g++ ++
or +
+make no-manybody +make g++ +
Some packages have individual files that depend on other packages -being included, but LAMMPS checks for this and does the right thing. +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.
The reason to exclude packages is if you will never run certain kinds -of simulations. This will keep you from having to build auxiliary -libraries (see below) and will produce a smaller executable which may -run a bit faster. +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.
By default, LAMMPS includes only the "kspace", "manybody", and "molecule" packages. @@ -537,168 +583,90 @@ 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.
-IMPORTANT NOTE: These make commands work by simply moving files back -and forth between the main src directory and sub-directories with the -package name, 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. +
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.
-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. +
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.
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. +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.
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. +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.
A few standard or user packages require that additional libraries be -compiled first, which LAMMPS will link to when it builds. The source -code for these libraries is included in the LAMMPS distribution under -the "lib" directory. Look at the README files in the lib directories -(e.g. lib/reax/README) for instructions on how to build each library. +
A few of the standard and user packages require additional auxiliary +libraries be compiled first. If you get a LAMMPS build error about a +missing library, this is likely the reason. The source code for these +libraries is included in the LAMMPS distribution under the "lib" +directory. Look at the lib/README file for a list of these.
-IMPORTANT NOTE: If you are including a package in your LAMMPS build -that uses one of these libraries, then you must build the library -BEFORE building LAMMPS itself, since the LAMMPS build will attempt to -link with the library file. -
-Here is a bit of information about each library: -
-The "atc" library in lib/atc is used by the user-atc package. It -provides continuum field estimation and molecular dynamics-finite -element coupling methods. It was written by Reese Jones, Jeremy -Templeton and Jonathan Zimmerman at Sandia. -
-The "cuda" library in lib/cuda is used by the user-cuda package. It -was written by Christian Trott at U of Technology Ilmenau in Germany. -It contains code to enable portions of LAMMPS to run on NVIDIA GPUs -associated with your CPUs. Currently, only NVIDIA GPUs are supported. -Building this library requires NVIDIA Cuda tools to be installed on -your system. See this section of the -manual for more information about using this package effectively and -how it differs from the gpu package. -
-The "gpu" library in lib/gpu is used by the gpu package. It was -written by Mike Brown at ORNL. It contains code to enable portions of -LAMMPS to run on GPUs associated with your CPUs. Currently, only -NVIDIA GPUs are supported, but eventually this may be extended to -OpenCL. Building this library requires NVIDIA Cuda tools to be -installed on your system. See this -section of the manual for more -information about using this package effectively and how it differs -from the user-cuda package. -
-The "meam" library in lib/meam is used by the meam package. It was -written by Greg Wagner at Sandia. It computes the modified embedded -atom method potential, which is a generalization of EAM potentials -that can be used to model a wider variety of materials. This MEAM -implementation was written by Greg Wagner at Sandia. It requires a -F90 compiler to build. The C++ to FORTRAN function calls in -pair_meam.cpp assumes that FORTRAN object names are converted to C -object names by appending an underscore character. This is generally -the case, but on machines that do not conform to this convention, you -will need to modify either the C++ code or your compiler settings. -
-The "poems" library in lib/poems is used by the poems package. It was -written by Rudra Mukherjee at JPL. It computes the constrained -rigid-body motion of articulated (jointed) multibody systems. POEMS -is distributed by Prof Kurt Anderson's group at Rensselaer Polytechnic -Institute (RPI). -
-The "reax" library in lib/reax is used by the reax package. It was -written by Aidan Thompson at Sandia. It computes the Reactive Force -Field (ReaxFF) potential, developed by Adri van Duin in Bill Goddard's -group at CalTech. This implementation in LAMMPS uses many of Adri's -files and was developed by Aidan Thompson at Sandia and Hansohl Cho at -MIT. It requires a F77 or F90 compiler to build. The C++ to FORTRAN -function calls in pair_reax.cpp assume that FORTRAN object names are -converted to C object names by appending an underscore character. This -is generally the case, but on machines that do not conform to this -convention, you will need to modify either the C++ code or your -compiler settings. The name conversion is handled by the preprocessor -macro called FORTRAN in pair_reax_fortran.h. Different definitions of -this macro can be obtained by adding a machine-specific macro -definition to the CCFLAGS variable in your Makefile e.g. -D_IBM. See -pair_reax_fortran.h for more info. -
-As described in the README file in each lib directory, each library is -typically built by typing something like +
Each lib directly 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:
make -f Makefile.g++-
in the appropriate directory, e.g. in lib/reax. +
in the appropriate directory, e.g. in lib/reax. Some of the libraries +do not build this way. Again, see the libary README file for details.
-You must use a Makefile that is a match for your system. If one of -the provided Makefiles is not appropriate for your system you will -need to edit or add one. For example, in the case of Fotran-based -libraries, your system must have a Fortran compiler, the settings for -which will be in the Makefile. +
In any event, you will need to use a Makefile that is a match for your +system. If one of the provided Makefiles is not appropriate for your +system you will need to edit or add one. For example, in the case of +Fortran-based libraries, your system must have a Fortran compiler, the +settings for which will need to be listed in the Makefile.
-Note that the cuda library, used by the user-cuda package is an -exception. See its README file and this -section of the manual for instructions -on how to build it. +
When you have built one of these libraries, there are 2 things to +check:
-After the desired library or libraries are built, and the package has -been included, you can build LAMMPS itself. For example, from the -lammps/src directory you would type this, to build LAMMPS with ReaxFF. -Note that as discussed in the preceding section, the package library -itself, namely lib/reax/libreax.a, must already have been built, for -the LAMMPS build to be successful. +
(1) The file libname.a should now exist in lib/name. +E.g. lib/reax/libreax.a. This is the library file LAMMPS will link +against. One exception is the lib/cuda library which produces the +file liblammpscuda.a, because there is already a system library +libcuda.a.
-make yes-reax -make g++ --
Also note that simply building the library is not sufficient to use it -from LAMMPS. As in this example, you must also include the package -that uses and wraps the library before you build LAMMPS itself. +
(2) The file Makefile.lammps should exist in lib/name. E.g. +lib/cuda/Makefile.lammps. This file may be auto-generated by the +build of the library, or you may need to make a copy of the +appropriate provided file (e.g. lib/meam/Makefile.lammps.gfortran). +Either way you should insure that the settings in this file are +appropriate for your system.
-As discussed in point (3.e) of this section above, there are -settings in the low-level Makefile that specify additional system -libraries needed by some of the LAMMPS add-on libraries. These are -the settings you must specify correctly in your low-level Makefile in -lammps/src/MAKE, such as Makefile.foo: +
There are typically 3 settings in the Makefile.lammps file (unless +some are blank or not needed): a SYSINC, SYSPATH, and SYSLIB setting, +specific to this package. These are settings the LAMMPS build will +import when compiling the LAMMPS package files (not the library +files), and linking to the auxiliary library. They typically list any +other system libraries needed to support the package and where to find +them. An example is the BLAS and LAPACK libraries needed by the +USER-ATC package. Or the system libraries that support calling +Fortran from C++, as the MEAM and REAX packages do.
-To use the gpu package and library, the settings for gpu_SYSLIB and -gpu_SYSPATH must be correct. These are specific to the NVIDIA CUDA -software which must be installed on your system. -
-To use the meam or reax packages and their libraries which are Fortran -based, the settings for meam_SYSLIB, reax_SYSLIB, meam_SYSPATH, and -reax_SYSPATH must be correct. This is so that the C++ compiler can -perform a cross-language link using the appropriate system Fortran -libraries. -
-To use the user-atc package and atc library, the settings for -user-atc_SYSLIB and user-atc_SYSPATH must be correct. This is so that -the appropriate BLAS and LAPACK libs, used by the user-atc library, -can be found. +
Note that if these settings are not correct for your box, the LAMMPS +build will likely fail.
LAMMPS can be built as a library, which can then be called from +
LAMMPS itself can be built as a library, which can then be called from another application or a scripting language. See this section for more info on coupling LAMMPS to other codes. Building LAMMPS as a library is done by typing @@ -706,13 +674,14 @@ other codes. Building LAMMPS as a library is done by typing
make makelib make -f Makefile.lib foo-
where foo is the machine name. The first "make" command will create a -current Makefile.lib with all the file names in your src dir. The 2nd -"make" command will use it to build LAMMPS as a library. This -requires that Makefile.foo have a library target (lib) and -system-specific settings for ARCHIVE and ARFLAGS. See Makefile.linux -for an example. The build will create the file liblmp_foo.a which -another application can link to. +
where foo is the machine name. 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 2nd "make" command will +use it to build LAMMPS as a library. This requires that Makefile.foo +have a library target (lib) and system-specific settings for ARCHIVE +and ARFLAGS. See Makefile.linux for an example. The build will +create the file liblmp_foo.a which another application can link to.
When used from a C++ program, the library allows one or more LAMMPS objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS @@ -768,8 +737,8 @@ on various platforms.
On a Windows box, you can skip making LAMMPS and simply download an -executable, as described above. though the pre-packaged executables -make only certain packages available. +executable, as described above, though the pre-packaged executables +include only certain packages.
To run a LAMMPS executable on a Windows machine, first decide whether you want to download the non-MPI (serial) or the MPI (parallel) @@ -851,8 +820,8 @@ more processors or setup a smaller problem.
At run time, LAMMPS recognizes several optional command-line switches -which may be used in any order. Either the full word or a one-letter -abbreviation can be used: +which may be used in any order. Either the full word or a one-or-two +letter abbreviation can be used: