Section_start.txt
c92047aeb5eclammm-master

Section_start.txt
View Options

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

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

			:line

			2. Getting Started :h3

			This section describes how to build and run LAMMPS, for both new and
			experienced users.

			2.1 "What's in the LAMMPS distribution"_#start_1
			2.2 "Making LAMMPS"_#start_2
			2.3 "Making LAMMPS with optional packages"_#start_3
			2.4 "Building LAMMPS as a library"_#start_4
			2.5 "Running LAMMPS"_#start_5
			2.6 "Command-line options"_#start_6
			2.7 "Screen output"_#start_7
			2.8 "Tips for users of previous versions"_#start_8 :all(b)

			:line
			:line

			2.1 What's in the LAMMPS distribution :h4,link(start_1)

			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.

			gunzip lammps*.tar.gz
			tar xvf lammps*.tar :pre

			This will create a LAMMPS directory containing two files and several
			sub-directories:

			README: text file
			LICENSE: the GNU General Public License (GPL)
			bench: benchmark problems
			couple: code coupling examples, using LAMMPS as a library
			doc: documentation
			examples: simple test problems
			potentials: embedded atom method (EAM) potential files
			src: source files
			tools: pre- and post-processing tools :tb(s=:)

			If you download one of the Windows executables from the download page,
			then you just get a single file:

			lmp_windows.exe :pre

			Skip to the "Running LAMMPS"_#start_5 sections for info on how to
			launch these executables on a Windows box.

			The Windows executables for serial or parallel only include certain
			packages and bug-fixes/upgrades listed on "this
			page"_http://lammps.sandia.gov/bug.html 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.

			:line

			2.2 Making LAMMPS :h4,link(start_2)

			This section has the following sub-sections:

			"Read this first"_#start_2_1
			"Steps to build a LAMMPS executable"_#start_2_2
			"Common errors that can occur when making LAMMPS"_#start_2_3
			"Additional build tips"_#start_2_4
			"Building for a Mac"_#start_2_5
			"Building for Windows"_#start_2_6 :ul

			:line

			[{Read this first:}] :link(start_2_1)

			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
			please send an email to the
			"developers"_http://lammps.sandia.gov/authors.html.

			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'll include it in future LAMMPS releases.

			:line

			[{Steps to build a LAMMPS executable:}] :link(start_2_2)

			[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 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 :pre

			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.

			If you get no errors and an executable like lmp_linux or lmp_mac is
			produced, you're done; it's your lucky day.

			Note that by default only a few of LAMMPS optional pacakges are
			installed. To build LAMMPS with optional packages, see "this
			section"_#start_3 below.

			[Step 1]

			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.

			[Step 2]

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

			[Step 3]

			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 "Intel's compiler site"_intel.

			:link(intel,http://www.intel.com/software/products/noncom)

			If building a C++ code on your machine requires additional libraries,
			then you should list them as part of the LIB variable.

			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.

			[Step 4]

			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:

			-DLAMMPS_GZIP
			-DLAMMPS_JPEG
			-DLAMMPS_MEMALIGN
			-DLAMMPS_XDR
			-DLAMMPS_SMALLBIG
			-DLAMMPS_BIGBIG
			-DLAMMPS_SMALLSMALL
			-DLAMMPS_LONGLONG_TO_LONG
			-DPACK_ARRAY
			-DPACK_POINTER
			-DPACK_MEMCPY :ul

			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.

			If you use -DLAMMPS_JPEG, the "dump image"_dump.html 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.

			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.

			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 "dump"_dump.html command for details.

			Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG,
			-D-DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG.
			These refer to use of 4-byte (small) vs 8-byte (big) integers within
			LAMMPS, as described 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. The only reason to use the SMALLSMALL
			setting is if your machine does not support 64-bit integers.

			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.

			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
			"kspace_style"_kspace_style.html command for info about PPPM. See
			Step 6 below for info about building LAMMPS with an FFT library.

			[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 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 MPICH2
			or OpenMPI. MPICH can be downloaded from the "Argonne MPI
			site"_http://www.mcs.anl.gov/research/projects/mpich2/. OpenMPI can
			be downloaded from the "OpenMPI site"_http://www.open-mpi.org.
			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.

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

			[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"_kspace_style.html command.

			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"_http://kissfft.sf.net, 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.

			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.

			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"_http://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.

			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.

			[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"_dump_image.html
			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, so that the compiler and linker can find it.

			As before, if these header and library files are in the usual place on
			your machine, you may not need to set these variables.

			[Step 8]

			Note that by default only a few of LAMMPS optional pacakges are
			installed. To build LAMMPS with optional packages, see "this
			section"_#start_3 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 :pre

			You should get the executable lmp_foo when the build is complete.

			:line

			[{Errors that can occur when making LAMMPS:}] :link(start_2_3)

			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 :pre

			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. Try using the -DLAMMPS_LONGLONG_TO_LONG setting described
			above in Step 4.

			:line

			[{Additional build tips:}] :link(start_2_4)

			(1) Building LAMMPS for multiple platforms.

			You can make LAMMPS for multiple platforms from the same src
			directory. Each target creates its own object sub-directory called
			Obj_name where it stores the system-specific *.o files.

			(2) Cleaning up.

			Typing "make clean-all" or "make clean-foo" will delete *.o object
			files created when LAMMPS is built, for either all builds or for a
			particular machine.

			(3) Changing the size limits in src/lmptype.h

			If you are running a very large problem (billions of atoms or more)
			and get a run-time error about the system being too big, either on a
			per-processor basis or in total size, then you may need to change one
			or more settings in src/lmptype.h and re-compile LAMMPS.

			As the documentation in that file explains, you have basically
			two choices to make:

			set the data type size of integer atom IDs to 4 or 8 bytes
			set the data type size of integers that store the total system size to 4 or 8 bytes :ul

			The default for atom IDs is 4-byte integers since there is a memory
			and communication cost for 8-byte integers. Non-molecular problems do
			not need atom IDs so this does not restrict their size. Molecular
			problems (which use IDs to define molecular topology), are limited to
			about 2 billion atoms (2^31) with 4-byte IDs. With 8-byte IDs they
			are effectively unlimited in size (2^63).

			The default for total system size quantities (like the number of atoms
			or timesteps) is 8-byte integers by default which is effectively
			unlimited in size (2^63). If your system or MPI implementation does
			not support 8-byte integers, an error will be generated, and you will
			need to set "bigint" to 4-byte integers. This restricts your total
			system size to about 2 billion atoms or timesteps (2^31).

			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, which need to be set consistent with the associated C
			data types.

			In all cases, the size of problem that can be run on a per-processor
			basis is limited by 4-byte integer storage to about 2 billion atoms
			per processor (2^31), which 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.

			:line

			[{Building for a Mac:}] :link(start_2_5)

			OS X is BSD Unix, so it should just work. See the Makefile.mac file.

			:line

			[{Building for Windows:}] :link(start_2_6)

			The LAMMPS download page has an option to download both a serial and
			parallel pre-built Windows exeutable. See the "Running
			LAMMPS"_#start_5 section for instructions for running these
			executables on a Windows box.

			If the pre-built executable doesn't have the options you want, then
			you can build LAMMPS from its source files on a Windows box. 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.

			There is a also a src/WINDOWS directory that contains project files
			for Microsoft Visual Studio 2005, which should also work with later
			versions of VS. That directory contains a README.txt file which
			provides instructions for building LAMMPS from source code using
			Visual Studio that are hopefully easy to follow for Windows and VS
			users.

			Four VS project options are provided. The first includes the default
			packages (MANYBODY, MOLECULE, and KSPACE). The second includes all
			standard packages (except GPU, MEAM, and REAX which are not yet
			included because they require NVIDIA or Fortran compilation). The
			third includes all standard packages (with the exceptions) and some
			user packages. The included user packages are USER-EFF, USER-CG-CMM,
			and USER-REAXC. The fourth project includes the USER-AWPMD package.

			:line

			2.3 Making LAMMPS with optional packages :h4,link(start_3)

			This section has the following sub-sections:

			"Package basics"_#start_3_1
			"Including/excluding packages"_#start_3_2
			"Packages that require extra libraries"_#start_3_3
			"Additional Makefile settings for extra libraries"_#start_3_4 :ul

			:line

			[{Package basics:}] :link(start_3_1)

			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.

			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

			lmp_machine -h :pre

			to run your executable with the optional "-h command-line
			switch"_#start_6 for "help", which will list the styles and commands
			known to your executable.

			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 "this section"_Section_packages.html of the manual. The
			difference between standard and user packages is as follows:

			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.

			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.

			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 "this
			section"_Section_modify.html#mod_14 of the documentation.

			:line

			[{Including/excluding packages:}] :link(start_3_2)

			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++ :pre

			or

			make no-manybody
			make g++ :pre

			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.

			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.

			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.

			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.

			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.

			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.

			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.

			:line

			[{Packages that require extra libraries:}] :link(start_3_3)

			A few of the standard and user packages require additional auxiliary
			libraries to 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 or see
			"this section"_Section_packages.html of the doc pages.

			Each lib directory has a README file (e.g. lib/reax/README) with
			instructions on how to build that library. Typically this is done
			in this manner:

			make -f Makefile.g++ :pre

			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.

			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.

			When you have built one of these libraries, there are 2 things to
			check:

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

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

			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.

			Note that if these settings are not correct for your box, the LAMMPS
			build will likely fail.

			:line

			2.4 Building LAMMPS as a library :h4,link(start_4)

			LAMMPS itself can be built as a library, which can then be called from
			another application or a scripting language. See "this
			section"_Section_howto.html#howto_10 for more info on coupling LAMMPS
			to other codes. Building LAMMPS as a library is done by typing

			make makelib
			make -f Makefile.lib foo :pre

			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
			namespace; you can safely use any of its classes and methods from
			within your application code, as needed.

			When used from a C or Fortran program or a scripting language, the
			library has a simple function-style interface, provided in
			src/library.cpp and src/library.h.

			See the sample codes couple/simple/simple.cpp and simple.c as examples
			of C++ and C codes that invoke LAMMPS thru its library interface.
			There are other examples as well in the couple directory which are
			discussed in "this section"_Section_howto.html#howto_10 of the manual.
			See "this section"_Section_python.html of the manual for a description
			of the Python wrapper provided with LAMMPS that operates through the
			LAMMPS library interface.

			The files src/library.cpp and library.h contain the C-style interface
			to LAMMPS. See "this section"_Section_howto.html#howto_19 of the
			manual for a description of the interface and how to extend it for
			your needs.

			:line

			2.5 Running LAMMPS :h4,link(start_5)

			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. "This section"_Section_commands.html
			describes how input scripts are structured and what commands they
			contain.

			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.

			Here is how you might run a standard Lennard-Jones benchmark on a
			Linux box, using mpirun to launch a parallel job:

			cd src
			make linux
			cp lmp_linux ../bench
			cd ../bench
			mpirun -np 4 lmp_linux < in.lj :pre

			See "this page"_bench for timings for this and the other benchmarks
			on various platforms.

			:link(bench,http://lammps.sandia.gov/bench.html)

			:line

			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.

			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.

			For the non-MPI version, follow these steps:

			Get a command prompt by going to Start->Run... ,
			then typing "cmd". :ulb,l

			Move to the directory where you have saved lmp_win_no-mpi.exe
			(e.g. by typing: cd "Documents"). :l

			At the command prompt, type "lmp_win_no-mpi -in in.lj", replacing in.lj
			with the name of your LAMMPS input script. :l,ule

			For the MPI version, which allows you to run LAMMPS under Windows on
			multiple processors, follow these steps:

			Download and install
			"MPICH2"_http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads
			for Windows. :ulb,l

			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. :l

			Get a command prompt by going to Start->Run... ,
			then typing "cmd". :l

			Move to the directory where you have saved lmp_win_mpi.exe
			(e.g. by typing: cd "Documents"). :l

			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. :l
			Note that you may need to provide smpd with a passphrase --- it doesn't matter what you
			type. :l
			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. :l
			Alternatively, you can still use this executable to run on a single processor by
			typing something like: "lmp_win_mpi -in in.lj". :l,ule

			:line

			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.

			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.

			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 "this section"_Section_errors.html 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.

			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.

			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.

			:line

			2.6 Command-line options :h4,link(start_6)

			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:

			-c or -cuda
			-e or -echo
			-i or -in
			-h or -help
			-l or -log
			-p or -partition
			-pl or -plog
			-ps or -pscreen
			-sc or -screen
			-sf or -suffix
			-v or -var :ul

			For example, lmp_ibm might be launched as follows:

			mpirun -np 16 lmp_ibm -v f tmp.out -l my.log -sc none < in.alloy
			mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none < in.alloy :pre

			Here are the details on the options:

			-cuda on/off :pre

			Explicitly enable or disable CUDA support, as provided by the
			USER-CUDA package. If LAMMPS is built with this package, as described
			above in "Section 2.3"_#start_3, then by default LAMMPS will run in
			CUDA mode. If this switch is set to "off", then it will not, even if
			it was built with the USER-CUDA package, which means you can run
			standard LAMMPS or with the GPU package for testing or benchmarking
			purposes. The only reason to set the switch to "on", is to check if
			LAMMPS was built with the USER-CUDA package, since an error will be
			generated if it was not.

			-echo style :pre

			Set the style of command echoing. The style can be {none} or {screen}
			or {log} or {both}. Depending on the style, each command read from
			the input script will be echoed to the screen and/or logfile. This
			can be useful to figure out which line of your script is causing an
			input error. The default value is {log}. The echo style can also be
			set by using the "echo"_echo.html command in the input script itself.

			-in file :pre

			Specify a file to use as an input script. This is an optional switch
			when running LAMMPS in one-partition mode. If it is not specified,
			LAMMPS reads its input script from stdin - e.g. lmp_linux < in.run.
			This is a required switch when running LAMMPS in multi-partition mode,
			since multiple processors cannot all read from stdin.

			-help :pre

			Print a list of options compiled into this executable for each LAMMPS
			style (atom_style, fix, compute, pair_style, bond_style, etc). This
			can help you know if the command you want to use was included via the
			appropriate package. LAMMPS will print the info and immediately exit
			if this switch is used.

			-log file :pre

			Specify a log file for LAMMPS to write status information to. In
			one-partition mode, if the switch is not used, LAMMPS writes to the
			file log.lammps. If this switch is used, LAMMPS writes to the
			specified file. In multi-partition mode, if the switch is not used, a
			log.lammps file is created with hi-level status information. Each
			partition also writes to a log.lammps.N file where N is the partition
			ID. If the switch is specified in multi-partition mode, the hi-level
			logfile is named "file" and each partition also logs information to a
			file.N. For both one-partition and multi-partition mode, if the
			specified file is "none", then no log files are created. Using a
			"log"_log.html command in the input script will override this setting.
			Option -plog will override the name of the partition log files file.N.

			-partition 8x2 4 5 ... :pre

			Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P
			processors and this switch is not used, LAMMPS runs in one partition,
			i.e. all P processors run a single simulation. If this switch is
			used, the P processors are split into separate partitions and each
			partition runs its own simulation. The arguments to the switch
			specify the number of processors in each partition. Arguments of the
			form MxN mean M partitions, each with N processors. Arguments of the
			form N mean a single partition with N processors. The sum of
			processors in all partitions must equal P. Thus the command
			"-partition 8x2 4 5" has 10 partitions and runs on a total of 25
			processors.

			Running with multiple partitions can e useful for running
			"multi-replica simulations"_Section_howto.html#howto_5, where each
			replica runs on on one or a few processors. Note that with MPI
			installed on a machine (e.g. your desktop), you can run on more
			(virtual) processors than you have physical processors.

			To run multiple independent simulatoins from one input script, using
			multiple partitions, see "this section"_Section_howto.html#howto_4 of
			the manual. World- and universe-style "variables"_variable.html are
			useful in this context.

			-plog file :pre

			Specify the base name for the partition log files, so partition N
			writes log information to file.N. If file is none, then no partition
			log files are created. This overrides the filename specified in the
			-log command-line option. This option is useful when working with
			large numbers of partitions, allowing the partition log files to be
			suppressed (-plog none) or placed in a sub-directory (-plog
			replica_files/log.lammps) If this option is not used the log file for
			partition N is log.lammps.N or whatever is specified by the -log
			command-line option.

			-pscreen file :pre

			Specify the base name for the partition screen file, so partition N
			writes screen information to file.N. If file is none, then no
			partition screen files are created. This overrides the filename
			specified in the -screen command-line option. This option is useful
			when working with large numbers of partitions, allowing the partition
			screen files to be suppressed (-pscreen none) or placed in a
			sub-directory (-pscreen replica_files/screen) If this option is not
			used the screen file for partition N is screen.N or whatever is
			specified by the -screen command-line option.

			-screen file :pre

			Specify a file for LAMMPS to write its screen information to. In
			one-partition mode, if the switch is not used, LAMMPS writes to the
			screen. If this switch is used, LAMMPS writes to the specified file
			instead and you will see no screen output. In multi-partition mode,
			if the switch is not used, hi-level status information is written to
			the screen. Each partition also writes to a screen.N file where N is
			the partition ID. If the switch is specified in multi-partition mode,
			the hi-level screen dump is named "file" and each partition also
			writes screen information to a file.N. For both one-partition and
			multi-partition mode, if the specified file is "none", then no screen
			output is performed. Option -pscreen will override the name of the
			partition screen files file.N.

			-suffix style :pre

			Use variants of various styles if they exist. The specified style can
			be {opt}, {omp}, {gpu}, or {cuda}. These refer to optional packages that
			LAMMPS can be built with, as described above in "Section
			2.3"_#start_3. The "opt" style corrsponds to the OPT package, the
			"omp" style to the USER-OMP package, the "gpu" style to the GPU
			package, and the "cuda" style to the USER-CUDA package.

			As an example, all of the packages provide a "pair_style
			lj/cut"_pair_lj.html variant, with style names lj/cut/opt, lj/cut/omp,
			lj/cut/gpu, or lj/cut/cuda. A variant styles can be specified
			explicitly in your input script, e.g. pair_style lj/cut/gpu. If the
			-suffix switch is used, you do not need to modify your input script.
			The specified suffix (opt,omp,gpu,cuda) is automatically appended
			whenever your input script command creates a new
			"atom"_atom_style.html, "pair"_pair_style.html, "fix"_fix.html,
			"compute"_compute.html, or "run"_run_style.html style. If the variant
			version does not exist, the standard version is created.

			For the GPU package, using this command-line switch also invokes the
			default GPU settings, as if the command "package gpu force/neigh 0 0
			1" were used at the top of your input script. These settings can be
			changed by using the "package gpu"_pacakge.html command in your script
			if desired.

			For the OMP package, using this command-line switch also invokes the
			default OMP settings, as if the command "package omp *" were used at
			the top of your input script. These settings can be changed by using
			the "package omp"_pacakge.html command in your script if desired.

			The "suffix"_suffix.html command can also set a suffix and it can also
			turn off/on any suffix setting made via the command line.

			-var name value1 value2 ... :pre

			Specify a variable that will be defined for substitution purposes when
			the input script is read. "Name" is the variable name which can be a
			single character (referenced as $x in the input script) or a full
			string (referenced as $\{abc\}). An "index-style
			variable"_variable.html will be created and populated with the
			subsequent values, e.g. a set of filenames. Using this command-line
			option is equivalent to putting the line "variable name index value1
			value2 ..." at the beginning of the input script. Defining an index
			variable as a command-line argument overrides any setting for the same
			index variable in the input script, since index variables cannot be
			re-defined. See the "variable"_variable.html command for more info on
			defining index and other kinds of variables and "this
			section"_Section_commands.html#cmd_2 for more info on using variables
			in input scripts.

			NOTE: Currently, the command-line parser looks for arguments that
			start with "-" to indicate new switches. Thus you cannot specify
			multiple variable values if any of they start with a "-", e.g. a
			negative numeric value. It is OK if the first value1 starts with a
			"-", since it is automatically skipped.

			:line

			2.7 LAMMPS screen output :h4,link(start_7)

			As LAMMPS reads an input script, it prints information to both the
			screen and a log file about significant actions it takes to setup a
			simulation. When the simulation is ready to begin, LAMMPS performs
			various initializations and prints the amount of memory (in MBytes per
			processor) that the simulation requires. It also prints details of
			the initial thermodynamic state of the system. During the run itself,
			thermodynamic information is printed periodically, every few
			timesteps. When the run concludes, LAMMPS prints the final
			thermodynamic state and a total run time for the simulation. It then
			appends statistics about the CPU time and storage requirements for the
			simulation. An example set of statistics is shown here:

			Loop time of 49.002 on 2 procs for 2004 atoms :pre

			Pair time (%) = 35.0495 (71.5267)
			Bond time (%) = 0.092046 (0.187841)
			Kspce time (%) = 6.42073 (13.103)
			Neigh time (%) = 2.73485 (5.5811)
			Comm time (%) = 1.50291 (3.06703)
			Outpt time (%) = 0.013799 (0.0281601)
			Other time (%) = 2.13669 (4.36041) :pre

			Nlocal: 1002 ave, 1015 max, 989 min
			Histogram: 1 0 0 0 0 0 0 0 0 1
			Nghost: 8720 ave, 8724 max, 8716 min
			Histogram: 1 0 0 0 0 0 0 0 0 1
			Neighs: 354141 ave, 361422 max, 346860 min
			Histogram: 1 0 0 0 0 0 0 0 0 1 :pre

			Total # of neighbors = 708282
			Ave neighs/atom = 353.434
			Ave special neighs/atom = 2.34032
			Number of reneighborings = 42
			Dangerous reneighborings = 2 :pre

			The first section gives the breakdown of the CPU run time (in seconds)
			into major categories. The second section lists the number of owned
			atoms (Nlocal), ghost atoms (Nghost), and pair-wise neighbors stored
			per processor. The max and min values give the spread of these values
			across processors with a 10-bin histogram showing the distribution.
			The total number of histogram counts is equal to the number of
			processors.

			The last section gives aggregate statistics for pair-wise neighbors
			and special neighbors that LAMMPS keeps track of (see the
			"special_bonds"_special_bonds.html command). The number of times
			neighbor lists were rebuilt during the run is given as well as the
			number of potentially "dangerous" rebuilds. If atom movement
			triggered neighbor list rebuilding (see the
			"neigh_modify"_neigh_modify.html command), then dangerous
			reneighborings are those that were triggered on the first timestep
			atom movement was checked for. If this count is non-zero you may wish
			to reduce the delay factor to insure no force interactions are missed
			by atoms moving beyond the neighbor skin distance before a rebuild
			takes place.

			If an energy minimization was performed via the
			"minimize"_minimize.html command, additional information is printed,
			e.g.

			Minimization stats:
			E initial, next-to-last, final = -0.895962 -2.94193 -2.94342
			Gradient 2-norm init/final= 1920.78 20.9992
			Gradient inf-norm init/final= 304.283 9.61216
			Iterations = 36
			Force evaluations = 177 :pre

			The first line lists the initial and final energy, as well as the
			energy on the next-to-last iteration. The next 2 lines give a measure
			of the gradient of the energy (force on all atoms). The 2-norm is the
			"length" of this force vector; the inf-norm is the largest component.
			The last 2 lines are statistics on how many iterations and
			force-evaluations the minimizer required. Multiple force evaluations
			are typically done at each iteration to perform a 1d line minimization
			in the search direction.

			If a "kspace_style"_kspace_style.html long-range Coulombics solve was
			performed during the run (PPPM, Ewald), then additional information is
			printed, e.g.

			FFT time (% of Kspce) = 0.200313 (8.34477)
			FFT Gflps 3d 1d-only = 2.31074 9.19989 :pre

			The first line gives the time spent doing 3d FFTs (4 per timestep) and
			the fraction it represents of the total KSpace time (listed above).
			Each 3d FFT requires computation (3 sets of 1d FFTs) and communication
			(transposes). The total flops performed is 5Nlog_2(N), where N is the
			number of points in the 3d grid. The FFTs are timed with and without
			the communication and a Gflop rate is computed. The 3d rate is with
			communication; the 1d rate is without (just the 1d FFTs). Thus you
			can estimate what fraction of your FFT time was spent in
			communication, roughly 75% in the example above.

			:line

			2.8 Tips for users of previous LAMMPS versions :h4,link(start_8)

			The current C++ began with a complete rewrite of LAMMPS 2001, which
			was written in F90. Features of earlier versions of LAMMPS are listed
			in "this section"_Section_history.html. The F90 and F77 versions
			(2001 and 99) are also freely distributed as open-source codes; check
			the "LAMMPS WWW Site"_lws for distribution information if you prefer
			those versions. The 99 and 2001 versions are no longer under active
			development; they do not have all the features of C++ LAMMPS.

			If you are a previous user of LAMMPS 2001, these are the most
			significant changes you will notice in C++ LAMMPS:

			(1) The names and arguments of many input script commands have
			changed. All commands are now a single word (e.g. read_data instead
			of read data).

			(2) All the functionality of LAMMPS 2001 is included in C++ LAMMPS,
			but you may need to specify the relevant commands in different ways.

			(3) The format of the data file can be streamlined for some problems.
			See the "read_data"_read_data.html command for details. The data file
			section "Nonbond Coeff" has been renamed to "Pair Coeff" in C++ LAMMPS.

			(4) Binary restart files written by LAMMPS 2001 cannot be read by C++
			LAMMPS with a "read_restart"_read_restart.html command. This is
			because they were output by F90 which writes in a different binary
			format than C or C++ writes or reads. Use the {restart2data} tool
			provided with LAMMPS 2001 to convert the 2001 restart file to a text
			data file. Then edit the data file as necessary before using the C++
			LAMMPS "read_data"_read_data.html command to read it in.

			(5) There are numerous small numerical changes in C++ LAMMPS that mean
			you will not get identical answers when comparing to a 2001 run.
			However, your initial thermodynamic energy and MD trajectory should be
			close if you have setup the problem for both codes the same.

lammps/doc/Section_start.txtc92047aeb5eclammm-master

Section_start.txtView Options

lammps/doc/Section_start.txt
c92047aeb5eclammm-master

Section_start.txt
View Options