From a97ad15d22699e22adb269df95aa9fc33ee85081 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 9 Aug 2018 05:09:46 -0400 Subject: [PATCH 01/51] update .gitignore --- src/.gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/.gitignore b/src/.gitignore index 058833ffb3..df3a22a5cd 100644 --- a/src/.gitignore +++ b/src/.gitignore @@ -729,6 +729,8 @@ /pair_eam.h /pair_eam_alloy.cpp /pair_eam_alloy.h +/pair_eam_cd.cpp +/pair_eam_cd.h /pair_eam_fs.cpp /pair_eam_fs.h /pair_edip.cpp From df20fbbca499b9a86f65b16d7719929940f8c296 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 9 Aug 2018 16:50:09 +0200 Subject: [PATCH 02/51] fix a bunch of broken linke or make links unique across files --- doc/src/Commands_bond.txt | 2 +- doc/src/Howto_tip4p.txt | 4 ++-- doc/src/Intro_features.txt | 4 ++-- doc/src/Manual.txt | 6 ++++-- doc/src/Packages_details.txt | 8 ++++---- doc/src/Packages_standard.txt | 4 ++-- doc/src/Python_install.txt | 2 +- doc/src/Python_shlib.txt | 3 ++- doc/src/fix_manifoldforce.txt | 2 +- doc/src/fix_property_atom.txt | 3 ++- doc/src/fix_wall_reflect.txt | 4 ++-- 11 files changed, 23 insertions(+), 19 deletions(-) diff --git a/doc/src/Commands_bond.txt b/doc/src/Commands_bond.txt index 314260cb14..48069d3120 100644 --- a/doc/src/Commands_bond.txt +++ b/doc/src/Commands_bond.txt @@ -9,7 +9,7 @@ Documentation"_ld - "LAMMPS Commands"_lc :c "Fix styles"_Commands_fix.html, "Compute styles"_Commands_compute.html, "Pair styles"_Commands_pair.html, -"Bond styles"_Commands_bond.html, +"Bond styles"_Commands_bond.html#bond, "Angle styles"_Commands_bond.html#angle, "Dihedral styles"_Commands_bond.html#dihedral, "Improper styles"_Commands_bond.html#improper, diff --git a/doc/src/Howto_tip4p.txt b/doc/src/Howto_tip4p.txt index f9e548e268..9f7f141314 100644 --- a/doc/src/Howto_tip4p.txt +++ b/doc/src/Howto_tip4p.txt @@ -31,7 +31,7 @@ using the "fix shake"_fix_shake.html command. These are the additional parameters (in real units) to set for O and H atoms and the water molecule to run a rigid TIP4P model with a cutoff -"(Jorgensen)"_#Jorgensen1. Note that the OM distance is specified in +"(Jorgensen)"_#Jorgensen5. Note that the OM distance is specified in the "pair_style"_pair_style.html command, not as part of the pair coefficients. @@ -107,6 +107,6 @@ models"_http://en.wikipedia.org/wiki/Water_model. :line -:link(Jorgensen1) +:link(Jorgensen5) [(Jorgensen)] Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem Phys, 79, 926 (1983). diff --git a/doc/src/Intro_features.txt b/doc/src/Intro_features.txt index 2bb7e25683..07c549c156 100644 --- a/doc/src/Intro_features.txt +++ b/doc/src/Intro_features.txt @@ -20,7 +20,7 @@ classes of functionality: "Integrators"_#integrate "Diagnostics"_#diag "Output"_#output -"Multi-replica models"_#replica +"Multi-replica models"_#replica1 "Pre- and post-processing"_#prepost "Specialized features (beyond MD itself)"_#special :ul @@ -154,7 +154,7 @@ Output :h4,link(output) time averaging of system-wide quantities atom snapshots in native, XYZ, XTC, DCD, CFG formats :ul -Multi-replica models :h4,link(replica) +Multi-replica models :h4,link(replica1) "nudged elastic band"_neb.html "parallel replica dynamics"_prd.html diff --git a/doc/src/Manual.txt b/doc/src/Manual.txt index a5e8b63640..5a70be5c50 100644 --- a/doc/src/Manual.txt +++ b/doc/src/Manual.txt @@ -8,6 +8,8 @@ +

+ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c @@ -18,8 +20,6 @@ :line -

- LAMMPS Documentation :c,h1 2 Aug 2018 version :c,h2 @@ -71,6 +71,7 @@ every LAMMPS command. :name: userdoc :includehidden: + Manual_version Intro Section_start Commands @@ -82,6 +83,7 @@ every LAMMPS command. Modify Python Errors + Build_manual .. toctree:: :caption: Index diff --git a/doc/src/Packages_details.txt b/doc/src/Packages_details.txt index eb92fe4dc4..8b28002c2e 100644 --- a/doc/src/Packages_details.txt +++ b/doc/src/Packages_details.txt @@ -49,7 +49,7 @@ as contained in the file name. "PYTHON"_#PYTHON, "QEQ"_#QEQ, "REAX"_#REAX, -"REPLICA"_#REPLICA, +"REPLICA"_#REPLICA2, "RIGID"_#RIGID, "SHOCK"_#SHOCK, "SNAP"_#SNAP, @@ -392,7 +392,7 @@ src/GPU: filenames -> commands src/GPU/README lib/gpu/README "Speed packages"_Speed_packages.html -"Speed gpu"_Speed_gpu.html.html +"Speed gpu"_Speed_gpu.html "Section 2.6 -sf gpu"_Section_start.html#start_6 "Section 2.6 -pk gpu"_Section_start.html#start_6 "package gpu"_package.html @@ -1225,7 +1225,7 @@ examples/reax :ul :line -REPLICA package :link(REPLICA),h4 +REPLICA package :link(REPLICA2),h4 [Contents:] @@ -1373,7 +1373,7 @@ make machine :pre [Supporting info:] src/SPIN: filenames -> commands -"Howto spin"_Howto_spin.html +"Howto spins"_Howto_spins.html "pair_style spin/dmi"_pair_spin_dmi.html "pair_style spin/exchange"_pair_spin_exchange.html "pair_style spin/magelec"_pair_spin_magelec.html diff --git a/doc/src/Packages_standard.txt b/doc/src/Packages_standard.txt index 7e64345602..56ec693185 100644 --- a/doc/src/Packages_standard.txt +++ b/doc/src/Packages_standard.txt @@ -57,9 +57,9 @@ Package, Description, Doc page, Example, Library "PYTHON"_Packages_details.html#PYTHON, embed Python code in an input script, "python"_python.html, python, sys "QEQ"_Packages_details.html#QEQ, QEq charge equilibration, "fix qeq"_fix_qeq.html, qeq, - "REAX"_Packages_details.html#REAX, ReaxFF potential (Fortran), "pair_style reax"_pair_reax.html, reax, int -"REPLICA"_Packages_details.html#REPLICA, multi-replica methods, "Howto replica"_Howto_replica.html, tad, - +"REPLICA"_Packages_details.html#REPLICA2, multi-replica methods, "Howto replica"_Howto_replica.html, tad, - "RIGID"_Packages_details.html#RIGID, rigid bodies and constraints, "fix rigid"_fix_rigid.html, rigid, - "SHOCK"_Packages_details.html#SHOCK, shock loading methods, "fix msst"_fix_msst.html, -, - "SNAP"_Packages_details.html#SNAP, quantum-fitted potential, "pair_style snap"_pair_snap.html, snap, - -"SPIN"_#SPIN, magnetic atomic spin dynamics, "Howto spin"_Howto_spin.html, SPIN, -"SRD"_Packages_details.html#SRD, stochastic rotation dynamics, "fix srd"_fix_srd.html, srd, - +"SPIN"_#SPIN, magnetic atomic spin dynamics, "Howto spins"_Howto_spins.html, SPIN, -"SRD"_Packages_details.html#SRD, stochastic rotation dynamics, "fix srd"_fix_srd.html, srd, - "VORONOI"_Packages_details.html#VORONOI, Voronoi tesselation, "compute voronoi/atom"_compute_voronoi_atom.html, -, ext :tb(ea=c,ca1=l) diff --git a/doc/src/Python_install.txt b/doc/src/Python_install.txt index 6591360ae2..85cf267de0 100644 --- a/doc/src/Python_install.txt +++ b/doc/src/Python_install.txt @@ -68,7 +68,7 @@ need to prefix this with "sudo". In this mode you cannot control which Python is invoked by root. Note that if you want Python to be able to load different versions of -the LAMMPS shared library (see "this section"_#py_5 below), you will +the LAMMPS shared library (see "this section"_Python_shlib.html), you will need to manually copy files like liblammps_g++.so into the appropriate system directory. This is not needed if you set the LD_LIBRARY_PATH environment variable as described above. diff --git a/doc/src/Python_shlib.txt b/doc/src/Python_shlib.txt index 1a921e4025..c3b81fa342 100644 --- a/doc/src/Python_shlib.txt +++ b/doc/src/Python_shlib.txt @@ -31,4 +31,5 @@ extra libraries must also be shared libraries. If the LAMMPS shared-library build fails with an error complaining about this, see "Section 2.4"_Section_start.html#start_4 for more details. -Also include CMake info on this +TODO: Also include CMake info on this + diff --git a/doc/src/fix_manifoldforce.txt b/doc/src/fix_manifoldforce.txt index aa32a875bf..2159d6211a 100644 --- a/doc/src/fix_manifoldforce.txt +++ b/doc/src/fix_manifoldforce.txt @@ -24,7 +24,7 @@ fix constrain all manifoldforce sphere 5.0 [Description:] -This fix subtracts each time step from the force the component along the normal of the specified "manifold"_manifolds.html. +This fix subtracts each time step from the force the component along the normal of the specified "manifold"_Howto_manifold.html. This can be used in combination with "minimize"_minimize.html to remove overlap between particles while keeping them (roughly) constrained to the given manifold, e.g. to set up a run with "fix nve/manifold/rattle"_fix_nve_manifold_rattle.html. I have found that only {hftn} and {quickmin} with a very small time step perform adequately though. diff --git a/doc/src/fix_property_atom.txt b/doc/src/fix_property_atom.txt index 136ed6c15e..8a70cd8213 100644 --- a/doc/src/fix_property_atom.txt +++ b/doc/src/fix_property_atom.txt @@ -200,7 +200,8 @@ added classes. :line -:link(isotopes) Example for using per-atom masses with TIP4P water to +:link(isotopes) +Example for using per-atom masses with TIP4P water to study isotope effects. When setting up simulations with the "TIP4P pair styles"_Howto_tip4p.html for water, you have to provide exactly one atom type each to identify the water oxygen and hydrogen diff --git a/doc/src/fix_wall_reflect.txt b/doc/src/fix_wall_reflect.txt index 78be84eb63..e35fac6eeb 100644 --- a/doc/src/fix_wall_reflect.txt +++ b/doc/src/fix_wall_reflect.txt @@ -51,7 +51,7 @@ corresponding component of its velocity is flipped. When used in conjunction with "fix nve"_fix_nve.html and "run_style verlet"_run_style.html, the resultant time-integration algorithm is equivalent to the primitive splitting algorithm (PSA) described by -"Bond"_#Bond. Because each reflection event divides +"Bond"_#Bond1. Because each reflection event divides the corresponding timestep asymmetrically, energy conservation is only satisfied to O(dt), rather than to O(dt^2) as it would be for velocity-Verlet integration without reflective walls. @@ -179,5 +179,5 @@ error. :line -:link(Bond) +:link(Bond1) [(Bond)] Bond and Leimkuhler, SIAM J Sci Comput, 30, p 134 (2007). From a06514372388ad7e7d003259aa51990cda621518 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 9 Aug 2018 16:50:36 +0200 Subject: [PATCH 03/51] create missing "Build_manual.txt" file from 'doc/README' --- doc/src/Build_manual.txt | 125 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 doc/src/Build_manual.txt diff --git a/doc/src/Build_manual.txt b/doc/src/Build_manual.txt new file mode 100644 index 0000000000..3dfc3d08b3 --- /dev/null +++ b/doc/src/Build_manual.txt @@ -0,0 +1,125 @@ +"Previous Section"_Errors.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next +Section"_Manual.html :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Building the LAMMPS Manual :h2 + +Depending on how you obtained LAMMPS, the doc directory has +2 or 3 sub-directories and optionally 2 PDF files and an ePUB file: + +src content files for LAMMPS documentation +html HTML version of the LAMMPS manual (see html/Manual.html) +tools tools and settings for building the documentation +Manual.pdf large PDF version of entire manual +Developer.pdf small PDF with info about how LAMMPS is structured +LAMMPS.epub Manual in ePUB format :pre + +If you downloaded LAMMPS as a tarball from the web site, all these +directories and files should be included. + +If you downloaded LAMMPS from the public SVN or Git repositories, then +the HTML and PDF files are not included. Instead you need to create +them, in one of three ways: + +(a) You can "fetch" the current HTML and PDF files from the LAMMPS web +site. Just type "make fetch". This should create a html_www dir and +Manual_www.pdf/Developer_www.pdf files. Note that if new LAMMPS +features have been added more recently than the date of your version, +the fetched documentation will include those changes (but your source +code will not, unless you update your local repository). + +(b) You can build the HTML and PDF files yourself, by typing "make +html" followed by "make pdf". Note that the PDF make requires the +HTML files already exist. This requires various tools including +Sphinx, which the build process will attempt to download and install +on your system, if not already available. See more details below. + +(c) You can genererate an older, simpler, less-fancy style of HTML +documentation by typing "make old". This will create an "old" +directory. This can be useful if (b) does not work on your box for +some reason, or you want to quickly view the HTML version of a doc +page you have created or edited yourself within the src directory. +E.g. if you are planning to submit a new feature to LAMMPS. + +:line + +The generation of all documentation is managed by the Makefile in +the doc dir. + +Documentation Build Options: :pre + +make html # generate HTML in html dir using Sphinx +make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf) + # in doc dir via htmldoc and pdflatex +make old # generate old-style HTML pages in old dir via txt2html +make fetch # fetch HTML doc pages and 2 PDF files from web site + # as a tarball and unpack into html dir and 2 PDFs +make epub # generate LAMMPS.epub in ePUB format using Sphinx +make clean # remove intermediate RST files created by HTML build +make clean-all # remove entire build folder and any cached data :pre + +:line + +Installing prerequisites for HTML build :h3 + +To run the HTML documention build toolchain, Python 3 and virtualenv +have to be installed. Here are instructions for common setups: + +Ubuntu :h4 + +sudo apt-get install python-virtualenv :pre + +Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x) :h4 + +sudo yum install python3-virtualenv :pre + +Fedora (since version 22) :h4 + +sudo dnf install python3-virtualenv pre + +MacOS X :h4 + +Python 3 :h5 + +Download the latest Python 3 MacOS X package from +"https://www.python.org"_https://www.python.org +and install it. This will install both Python 3 +and pip3. + +virtualenv :h5 + +Once Python 3 is installed, open a Terminal and type + +pip3 install virtualenv :pre + +This will install virtualenv from the Python Package Index. + +:line + +Installing prerequisites for PDF build + +[TBA] + +:line + +Installing prerequisites for epub build :h3 + +ePUB :h4 + +Same as for HTML. This uses the same tools and configuration +files as the HTML tree. + +For converting the generated ePUB file to a mobi format file +(for e-book readers like Kindle, that cannot read ePUB), you +also need to have the 'ebook-convert' tool from the "calibre" +software installed. "http://calibre-ebook.com/"_http://calibre-ebook.com/ +You first create the ePUB file with 'make epub' and then do: + +ebook-convert LAMMPS.epub LAMMPS.mobi :pre + From 1604f011d223b686ea493392568d629fa282d4dc Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 9 Aug 2018 16:58:05 +0200 Subject: [PATCH 04/51] fix a couple more broken links --- doc/src/Errors_common.txt | 2 +- doc/src/Howto_bioFF.txt | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/src/Errors_common.txt b/doc/src/Errors_common.txt index 43d1a85a7b..8d04d8b0b4 100644 --- a/doc/src/Errors_common.txt +++ b/doc/src/Errors_common.txt @@ -93,7 +93,7 @@ decide if the WARNING is important or not. A WARNING message that is generated in the middle of a run is only printed to the screen, not to the logfile, to avoid cluttering up thermodynamic output. If LAMMPS crashes or hangs without spitting out an error message first then it -could be a bug (see "this section"_#err_2) or one of the following +could be a bug (see "this section"_Errors_bugs.html) or one of the following cases: LAMMPS runs in the available memory a processor allows to be diff --git a/doc/src/Howto_bioFF.txt b/doc/src/Howto_bioFF.txt index afb8a84f2e..deb5b31441 100644 --- a/doc/src/Howto_bioFF.txt +++ b/doc/src/Howto_bioFF.txt @@ -96,6 +96,10 @@ documentation for the formula it computes. [(MacKerell)] MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, Fischer, Gao, Guo, Ha, et al, J Phys Chem, 102, 3586 (1998). +:link(howto-Cornell) +[(Cornell)] Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, +Spellmeyer, Fox, Caldwell, Kollman, JACS 117, 5179-5197 (1995). + :link(howto-Mayo) [(Mayo)] Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909 (1990). From f4ea28cd322399cced20b9bb30cbbf5de1e3da36 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 9 Aug 2018 16:58:19 +0200 Subject: [PATCH 05/51] update src/lammps.book file with missing entries --- doc/src/lammps.book | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/src/lammps.book b/doc/src/lammps.book index c0ca357f21..75a44141df 100644 --- a/doc/src/lammps.book +++ b/doc/src/lammps.book @@ -1,6 +1,7 @@ #HTMLDOC 1.8.28 -t pdf14 -f "../Manual.pdf" --book --toclevels 4 --no-numbered --toctitle "Table of Contents" --title --textcolor #000000 --linkcolor #0000ff --linkstyle plain --bodycolor #ffffff --size Universal --left 1.00in --right 0.50in --top 0.50in --bottom 0.50in --header .t. --header1 ... --footer ..1 --nup 1 --tocheader .t. --tocfooter ..i --portrait --color --no-pscommands --no-xrxcomments --compression=9 --jpeg=0 --fontsize 11.0 --fontspacing 1.2 --headingfont Sans --bodyfont Serif --headfootsize 11.0 --headfootfont Sans-Bold --charset iso-8859-15 --links --embedfonts --pagemode document --pagelayout single --firstpage c1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password "" --user-password "" --browserwidth 680 --no-strict --no-overflow Manual.html +Manual_version.html Intro.html Intro_overview.html Intro_features.html @@ -106,6 +107,7 @@ Errors_common.html Errors_bugs.html Errors_messages.html Errors_warnings.html +Build_manual.html lammps_commands.html atom_modify.html From 8e9ea1e4fadeb57268fcc378e3622a378b16cb35 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 9 Aug 2018 17:07:45 +0200 Subject: [PATCH 06/51] formatting tweak for Build the manual page --- doc/src/Build_manual.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/src/Build_manual.txt b/doc/src/Build_manual.txt index 3dfc3d08b3..695ac21a13 100644 --- a/doc/src/Build_manual.txt +++ b/doc/src/Build_manual.txt @@ -13,12 +13,12 @@ Building the LAMMPS Manual :h2 Depending on how you obtained LAMMPS, the doc directory has 2 or 3 sub-directories and optionally 2 PDF files and an ePUB file: -src content files for LAMMPS documentation -html HTML version of the LAMMPS manual (see html/Manual.html) -tools tools and settings for building the documentation -Manual.pdf large PDF version of entire manual -Developer.pdf small PDF with info about how LAMMPS is structured -LAMMPS.epub Manual in ePUB format :pre +src # content files for LAMMPS documentation +html # HTML version of the LAMMPS manual (see html/Manual.html) +tools # tools and settings for building the documentation +Manual.pdf # large PDF version of entire manual +Developer.pdf # small PDF with info about how LAMMPS is structured +LAMMPS.epub # Manual in ePUB format :pre If you downloaded LAMMPS as a tarball from the web site, all these directories and files should be included. From bb25e5d98a8933ecbfb8b762e45759a2bdc4b0b4 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 9 Aug 2018 17:07:57 +0200 Subject: [PATCH 07/51] adjust header levels for Tools section --- doc/src/Tools.txt | 60 +++++++++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/doc/src/Tools.txt b/doc/src/Tools.txt index 85ee531cfd..aa4adb7dc1 100644 --- a/doc/src/Tools.txt +++ b/doc/src/Tools.txt @@ -77,7 +77,7 @@ own sub-directories with their own Makefiles and/or README files. :line :line -amber2lmp tool :h4,link(amber) +amber2lmp tool :h3,link(amber) The amber2lmp sub-directory contains two Python scripts for converting files back-and-forth between the AMBER MD code and LAMMPS. See the @@ -92,7 +92,7 @@ necessary modifications yourself. :line -binary2txt tool :h4,link(binary) +binary2txt tool :h3,link(binary) The file binary2txt.cpp converts one or more binary LAMMPS dump file into ASCII text files. The syntax for running the tool is @@ -105,7 +105,7 @@ since binary files are not compatible across all platforms. :line -ch2lmp tool :h4,link(charmm) +ch2lmp tool :h3,link(charmm) The ch2lmp sub-directory contains tools for converting files back-and-forth between the CHARMM MD code and LAMMPS. @@ -130,7 +130,7 @@ Chris Lorenz (chris.lorenz at kcl.ac.uk), King's College London. :line -chain tool :h4,link(chain) +chain tool :h3,link(chain) The file chain.f creates a LAMMPS data file containing bead-spring polymer chains and/or monomer solvent atoms. It uses a text file @@ -147,7 +147,7 @@ for the "chain benchmark"_Speed_bench.html. :line -colvars tools :h4,link(colvars) +colvars tools :h3,link(colvars) The colvars directory contains a collection of tools for postprocessing data produced by the colvars collective variable library. @@ -169,7 +169,7 @@ gmail.com) at ICTP, Italy. :line -createatoms tool :h4,link(createatoms) +createatoms tool :h3,link(createatoms) The tools/createatoms directory contains a Fortran program called createAtoms.f which can generate a variety of interesting crystal @@ -182,7 +182,7 @@ The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov. :line -doxygen tool :h4,link(doxygen) +doxygen tool :h3,link(doxygen) The tools/doxygen directory contains a shell script called doxygen.sh which can generate a call graph and API lists using @@ -194,7 +194,7 @@ The tool is authored by Nandor Tamaskovics, numericalfreedom at googlemail.com. :line -drude tool :h4,link(drude) +drude tool :h3,link(drude) The tools/drude directory contains a Python script called polarizer.py which can add Drude oscillators to a LAMMPS @@ -207,7 +207,7 @@ at univ-bpclermont.fr, alain.dequidt at univ-bpclermont.fr :line -eam database tool :h4,link(eamdb) +eam database tool :h3,link(eamdb) The tools/eam_database directory contains a Fortran program that will generate EAM alloy setfl potential files for any combination of 16 @@ -223,7 +223,7 @@ X. W. Zhou, R. A. Johnson, and H. N. G. Wadley, Phys. Rev. B, 69, :line -eam generate tool :h4,link(eamgn) +eam generate tool :h3,link(eamgn) The tools/eam_generate directory contains several one-file C programs that convert an analytic formula into a tabulated "embedded atom @@ -236,7 +236,7 @@ The source files and potentials were provided by Gerolf Ziegenhain :line -eff tool :h4,link(eff) +eff tool :h3,link(eff) The tools/eff directory contains various scripts for generating structures and post-processing output for simulations using the @@ -247,7 +247,7 @@ These tools were provided by Andres Jaramillo-Botero at CalTech :line -emacs tool :h4,link(emacs) +emacs tool :h3,link(emacs) The tools/emacs directory contains an Emacs Lisp add-on file for GNU Emacs that enables a lammps-mode for editing input scripts when using GNU Emacs, @@ -258,7 +258,7 @@ These tools were provided by Aidan Thompson at Sandia :line -fep tool :h4,link(fep) +fep tool :h3,link(fep) The tools/fep directory contains Python scripts useful for post-processing results from performing free-energy perturbation @@ -271,7 +271,7 @@ See README file in the tools/fep directory. :line -i-pi tool :h4,link(ipi) +i-pi tool :h3,link(ipi) The tools/i-pi directory contains a version of the i-PI package, with all the LAMMPS-unrelated files removed. It is provided so that it can @@ -288,7 +288,7 @@ calculations with LAMMPS. :line -ipp tool :h4,link(ipp) +ipp tool :h3,link(ipp) The tools/ipp directory contains a Perl script ipp which can be used to facilitate the creation of a complicated file (say, a lammps input @@ -302,7 +302,7 @@ tools/createatoms tool's input file. :line -kate tool :h4,link(kate) +kate tool :h3,link(kate) The file in the tools/kate directory is an add-on to the Kate editor in the KDE suite that allow syntax highlighting of LAMMPS input @@ -313,7 +313,7 @@ The file was provided by Alessandro Luigi Sellerio :line -lmp2arc tool :h4,link(arc) +lmp2arc tool :h3,link(arc) The lmp2arc sub-directory contains a tool for converting LAMMPS output files to the format for Accelrys' Insight MD code (formerly @@ -329,7 +329,7 @@ Greathouse at Sandia (jagreat at sandia.gov). :line -lmp2cfg tool :h4,link(cfg) +lmp2cfg tool :h3,link(cfg) The lmp2cfg sub-directory contains a tool for converting LAMMPS output files into a series of *.cfg files which can be read into the @@ -340,7 +340,7 @@ This tool was written by Ara Kooser at Sandia (askoose at sandia.gov). :line -matlab tool :h4,link(matlab) +matlab tool :h3,link(matlab) The matlab sub-directory contains several "MATLAB"_matlabhome scripts for post-processing LAMMPS output. The scripts include readers for log @@ -358,7 +358,7 @@ These scripts were written by Arun Subramaniyan at Purdue Univ :line -micelle2d tool :h4,link(micelle) +micelle2d tool :h3,link(micelle) The file micelle2d.f creates a LAMMPS data file containing short lipid chains in a monomer solution. It uses a text file containing lipid @@ -375,7 +375,7 @@ definition file. This tool was used to create the system for the :line -moltemplate tool :h4,link(moltemplate) +moltemplate tool :h3,link(moltemplate) The moltemplate sub-directory contains a Python-based tool for building molecular systems based on a text-file description, and @@ -389,7 +389,7 @@ supports it. It has its own WWW page at :line -msi2lmp tool :h4,link(msi) +msi2lmp tool :h3,link(msi) The msi2lmp sub-directory contains a tool for creating LAMMPS template input and data files from BIOVIA's Materias Studio files (formerly Accelrys' @@ -406,7 +406,7 @@ See the README file in the tools/msi2lmp folder for more information. :line -phonon tool :h4,link(phonon) +phonon tool :h3,link(phonon) The phonon sub-directory contains a post-processing tool useful for analyzing the output of the "fix phonon"_fix_phonon.html command in @@ -421,7 +421,7 @@ University. :line -polybond tool :h4,link(polybond) +polybond tool :h3,link(polybond) The polybond sub-directory contains a Python-based tool useful for performing "programmable polymer bonding". The Python file @@ -435,7 +435,7 @@ This tool was written by Zachary Kraus at Georgia Tech. :line -pymol_asphere tool :h4,link(pymol) +pymol_asphere tool :h3,link(pymol) The pymol_asphere sub-directory contains a tool for converting a LAMMPS dump file that contains orientation info for ellipsoidal @@ -453,7 +453,7 @@ This tool was written by Mike Brown at Sandia. :line -python tool :h4,link(pythontools) +python tool :h3,link(pythontools) The python sub-directory contains several Python scripts that perform common LAMMPS post-processing tasks, such as: @@ -469,7 +469,7 @@ README for more info on Pizza.py and how to use these scripts. :line -reax tool :h4,link(reax_tool) +reax tool :h3,link(reax_tool) The reax sub-directory contains stand-alond codes that can post-process the output of the "fix reax/bonds"_fix_reax_bonds.html @@ -480,7 +480,7 @@ These tools were written by Aidan Thompson at Sandia. :line -smd tool :h4,link(smd) +smd tool :h3,link(smd) The smd sub-directory contains a C++ file dump2vtk_tris.cpp and Makefile which can be compiled and used to convert triangle output @@ -496,7 +496,7 @@ Ernst Mach Institute in Germany (georg.ganzenmueller at emi.fhg.de). :line -vim tool :h4,link(vim) +vim tool :h3,link(vim) The files in the tools/vim directory are add-ons to the VIM editor that allow easier editing of LAMMPS input scripts. See the README.txt @@ -507,7 +507,7 @@ ziegenhain.com) :line -xmgrace tool :h4,link(xmgrace) +xmgrace tool :h3,link(xmgrace) The files in the tools/xmgrace directory can be used to plot the thermodynamic data in LAMMPS log files via the xmgrace plotting From c97e6537c805abcae1a6e8fd466b07f070b8d2c7 Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Thu, 9 Aug 2018 10:19:10 -0600 Subject: [PATCH 08/51] changes to replace Section_start.txt --- doc/src/Build.txt | 50 + doc/src/Build_basics.txt | 318 ++++++ doc/src/Build_cmake.txt | 159 +++ doc/src/Build_extras.txt | 803 +++++++++++++++ doc/src/Build_link.txt | 85 ++ doc/src/Build_make.txt | 66 ++ doc/src/Build_package.txt | 182 ++++ doc/src/Build_settings.txt | 327 +++++++ doc/src/Install.txt | 64 ++ doc/src/Install_git.txt | 120 +++ doc/src/Install_linux.txt | 120 +++ doc/src/Install_mac.txt | 55 ++ doc/src/Install_patch.txt | 67 ++ doc/src/Install_svn.txt | 95 ++ doc/src/Install_tarball.txt | 64 ++ doc/src/Install_windows.txt | 52 + doc/src/Run.txt | 37 + doc/src/Run_basics.txt | 87 ++ doc/src/Run_options.txt | 470 +++++++++ doc/src/Run_output.txt | 176 ++++ doc/src/Run_windows.txt | 73 ++ doc/src/Section_start.txt | 1823 ----------------------------------- 22 files changed, 3470 insertions(+), 1823 deletions(-) create mode 100644 doc/src/Build.txt create mode 100644 doc/src/Build_basics.txt create mode 100644 doc/src/Build_cmake.txt create mode 100644 doc/src/Build_extras.txt create mode 100644 doc/src/Build_link.txt create mode 100644 doc/src/Build_make.txt create mode 100644 doc/src/Build_package.txt create mode 100644 doc/src/Build_settings.txt create mode 100644 doc/src/Install.txt create mode 100644 doc/src/Install_git.txt create mode 100644 doc/src/Install_linux.txt create mode 100644 doc/src/Install_mac.txt create mode 100644 doc/src/Install_patch.txt create mode 100644 doc/src/Install_svn.txt create mode 100644 doc/src/Install_tarball.txt create mode 100644 doc/src/Install_windows.txt create mode 100644 doc/src/Run.txt create mode 100644 doc/src/Run_basics.txt create mode 100644 doc/src/Run_options.txt create mode 100644 doc/src/Run_output.txt create mode 100644 doc/src/Run_windows.txt delete mode 100644 doc/src/Section_start.txt diff --git a/doc/src/Build.txt b/doc/src/Build.txt new file mode 100644 index 0000000000..653c217d4c --- /dev/null +++ b/doc/src/Build.txt @@ -0,0 +1,50 @@ +"Previous Section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Run.html :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Build LAMMPS :h2 + +LAMMPS can be built as an executable or library from source code via +either CMake or traditional make. As an alternative you can download +a pre-built executable file as described on the "Install"_Install.html +doc page. + + + + + +"Build LAMMPS with CMake"_Build_cmake.html +"Build LAMMPS with make"_Build_make.html +"Link LAMMPS as a library to another code"_Build_link.html :all(b) + +Build options: + +"Basic build options: serial/parallel, compilers, executable/library"_Build_basics.html +"Optional build settings"_Build_settings.html :all(b) +"Include packages in build"_Build_package.html +"Packages with extra build options"_Build_extras.html :all(b) + +If you have problems building LAMMPS, it is often due to software +issues on your local machine. If you can, find a local expert to +help. If you're still stuck, send an email to the "LAMMPS mail +list"_http://lammps.sandia.gov/mail.html. diff --git a/doc/src/Build_basics.txt b/doc/src/Build_basics.txt new file mode 100644 index 0000000000..b2816b7acb --- /dev/null +++ b/doc/src/Build_basics.txt @@ -0,0 +1,318 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Basic build options :h3 + +The following topics are covered on this page, for building both with +CMake and make: + +"Serial vs parallel build"_#serial +"Choice of compiler and compile/link options"_#compile +"Build LAMMPS as an executable or a library"_#exe +"Build the LAMMPS documentation"_#doc +"Install LAMMPS after a build"_#install :ul + +:line +:line + +Serial vs parallel build :h3,link(serial) + +LAMMPS can be built to run in parallel using the ubiquitous "MPI +(message-passing +interface)"_https://en.wikipedia.org/wiki/Message_Passing_Interface +library. Or it can built to run on a single processor (serial) +without MPI. It can also be built with support for OpenMP threading +(see more discussion below). + +[CMake variables]: + +-D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else no +-D BUILD_OMP=value # yes or no (default) +-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc + # no default value :pre + +The executable CMake creates (after running make) is lmp_name. If the +LAMMPS_MACHINE variable is not specified, the executable is just lmp. +Using BUILD_MPI=no will produce a serial executable. + +[Traditional make]: + +cd lammps/src +make mpi # parallel build, produces lmp_mpi using Makefile.mpi +make serial # serial build, produces lmp_serial using Makefile/serial +make mybox :pre # uses Makefile.mybox, produces lmp_mybox :pre + +Serial build (see src/MAKE/Makefile.serial): + +MPI_INC = -I../STUBS +MPI_PATH = -L../STUBS +MPI_LIB = -lmpi_stubs :pre + +For a parallel build, if MPI is installed on your system in the usual +place (e.g. under /usr/local), you do not need to specify the 3 +variables MPI_INC, MPI_PATH, MPI_LIB. The MPI wrapper on the compiler +(e.g. mpicxx, mpiCC) knows where to find the needed include and +library files. Failing this, these 3 variables can be used to specify +where the mpi.h file (MPI_INC), and the MPI library files (MPI_PATH) +are found, and the name of the library files (MPI_LIB). + +For a serial build, you need to specify the 3 varaibles, as shown +above. + +For a serial LAMMPS build, use the dummy MPI library provided in +src/STUBS. You also need to build the STUBS library for your platform +before making LAMMPS itself. A "make serial" build does this for. +Otherwise, type "make mpi-stubs" from the src directory, or "make" +from the src/STUBS dir. If the build fails, you will need to edit the +STUBS/Makefile for your platform. + +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. + +[CMake and make info]: + +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 large parallel +machine, your system admins 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. + +The majority of OpenMP (threading) support in LAMMPS is provided by +the USER-OMP package; see the "Speed omp"_Speed_omp.html doc page for +details. + +However, there are a few commands in LAMMPS that have native OpenMP +support. These are commands in the MPIIO, SNAP, USER-COLVARS, and +USER-DPD packages. See the "Packages details"_Packages_details.html +doc page for more info on these packages and the doc pages for their +respective commands for OpenMP threading info. + +TODO: is this the complete list of native OpenMP commands in LAMMPS? + +For CMake, if you use BUILD_OMP=yes, then you can use these packages +and turn on their native OpenMP support at run time, by first setting +the OMP_NUM_THREADS environment variable. + +For make, ... + +TODO: how do we build LAMMPS with make, to include OpenMP support +(separate from USER-OMP package). Akin to CMake with BUILD_OMP=yes. + +:line + +Choice of compiler and compile/link options :h3,link(compile) + +The choice of compiler and compiler flags can be important for +performance. Vendor compilers can produce faster code than +open-source compilers like GNU. On boxes with Intel CPUs, we suggest +trying the "Intel C++ compiler"_intel. + +:link(intel,https://software.intel.com/en-us/intel-compilers) + +On parallel clusters or supercomputers which use "modules" for their +compile/link environments, you can often access different compilers by +simply loading the appropriate module before building LAMMPS. + +[CMake variables]: + +-D CMAKE_CXX_COMPILER=name # name of C++ compiler +-D CMAKE_C_COMPILER=name # name of C compiler +-D CMAKE_Fortran_COMPILER=name # name of Fortran compiler :pre + +-D CMAKE_CXX_FlAGS=string # flags to use with C++ compiler +-D CMAKE_C_FlAGS=string # flags to use with C compiler +-D CMAKE_Fortran_FlAGS=string # flags to use with Fortran compiler :pre + +By default CMake will use a compiler it finds and it will use +optimization flags appropriate to that compiler and any "accelerator +packages"_Speed_packages.html you have included in the build. + +You can tell CMake to look for a specific compiler with these varaible +settings. Likewise you can specify the FLAGS variables if you want to +experiment with alternate optimization flags. You should specify all +3 compilers, so that the small number of LAMMPS source files written +in C or Fortran are built with a compiler consistent with the one used +for all the C++ files: + +Building with GNU Compilers: +cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran +Building with Intel Compilers: +cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort +Building with LLVM/Clang Compilers: +cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang :pre + +NOTE: When the cmake command completes, it prints info to the screen +as to what compilers it is using, and what flags will be used in the +compilation. Note that if the top-level compiler is mpicxx, it is +simply a wrapper on a real compiler. The low-level compiler info is +also in the output. You should check to insure you are using the +compiler and optimization flags that are the ones you want. + +[Makefile.machine settings]: + +Parallel build (see src/MAKE/Makefile.mpi): + +CC = mpicxx +CCFLAGS = -g -O3 +LINK = mpicxx +LINKFLAGS = -g -O :pre + +Serial build (see src/MAKE/Makefile.serial): + +CC = g++ +CCFLAGS = -g -O3 +LINK = g++ +LINKFLAGS = -g -O :pre + +The "compiler/linker settings" section of a Makefile.machine lists +compiler and linker settings for your C++ compiler, including +optimization flags. You should always use mpicxx or mpiCC for +a parallel build, since these compiler wrappers will include +a variety of settings appropriate for your MPI installation. + +NOTE: If you build LAMMPS with any "accelerator +packages"_Speed_packages.html included, they have specific +optimization flags that are either required or recommended for optimal +performance. You need to include these in the CCFLAGS and LINKFLAGS +settings above. For details, see the individual package doc pages +listed on the "Speed packages"_Speed_packages.html doc page. Or +examine these files in the src/MAKE/OPTIONS directory. They +correspond to each of the 5 accelerator packages and their hardware +variants: + +Makefile.opt # OPT package +Makefile.omp # USER-OMP package +Makefile.intel_cpu # USER-INTEL package for CPUs +Makefile.intel_coprocessor # USER-INTEL package for KNLs +Makefile.gpu # GPU package +Makefile.kokkos_cuda_mpi # KOKKOS package for GPUs +Makefile.kokkos_omp # KOKKOS package for CPUs (OpenMP) +Makefile.kokkos_phi # KOKKOS package for KNLs (OpenMP) :pre + +NOTE: When you build LAMMPS for the first time, 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. + +:line + +Build LAMMPS as an executable or a library :h3,link(exe) + +LAMMPS can be built as either an executable or as a static or shared +library. The library can be called from another application or a +scripting language. See the "Howto couple"_Howto_couple.html doc page +for more info on coupling LAMMPS to other codes. See the +"Python"_Python doc page for more info on wrapping and running LAMMPS +from Python. + +[CMake variables]: + +-D BUILD_EXE=value # yes (default) or no +-D BUILD_LIB=value # yes or no (default) +-D BUILD_SHARED_LIBS=value # yes or no (default) :pre + +Setting BUILD_EXE=no will not produce an executable. Setting +BUILD_LIB=yes will produce a static library named liblammps.a. +Setting both BUILD_LIB=yes and BUILD_SHARED_LIBS=yes will produce a +static library named liblammps.so. + +[Traditional make]: + +cd lammps/src +make machine # build LAMMPS executable lmp_machine +make mode=lib machine # build LAMMPS static lib liblammps_machine.a +make mode=shlib machine # build LAMMPS shared lib liblammps_machine.so :pre + +The two library builds also create generic links liblammps.a and +liblammps.so which point to the liblammps_machine files. + +[CMake and make info]: + +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/packages, since they are always built as shared libraries using +the -fPIC switch. However, if a library like MPI or FFTW does not +exist as a shared library, the shared library build will generate an +error. This means you will need to install a shared library version +of the auxiliary library. The build instructions for the library +should tell you how to do this. + +As an example, here is how to build and install the "MPICH +library"_mpich, a popular open-source version of MPI, distributed by +Argonne National Labs, as a shared library in the default +/usr/local/lib location: + +:link(mpich,http://www-unix.mcs.anl.gov/mpi) + +./configure --enable-shared +make +make install :pre + +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. + +:line + +Build the LAMMPS documentation :h3,link(doc) + +[CMake variable]: + +-D BUILD_DOC=value # yes or no (default) :pre + +This will create the HTML doc pages within the CMake build dir. The +reason to do this is if you want to "install" LAMMPS on a system after +the CMake build, and include the doc pages in the install. + +[Traditional make]: + +cd lammps/doc +make html # html doc pages +make pdf # single Manual.pdf file :pre + +This will create a lammps/doc/html dir with the HTML doc pages so that +you can browse them locally on your system. Type "make" from the the +lammps/doc dir to see other options. + +:line + +Install LAMMPS after a build :h3,link(install) + +After building LAMMPS, you may wish to copy the LAMMPS executable of +library, along with other LAMMPS files (library header, doc files) to +a globally visible place on your system, for others to access. Note +that you may need super-user priveleges (e.g. sudo) if the place you +want to copy files to is protected. + +[CMake variable]: + +cmake CMAKE_INSTALL_PREFIX=path \[options ...\] ~/lammps/cmake +make # perform make after CMake command +make install # perform the installation :pre + +Note that The CMAKE_INSTALL_PREFIX=path is not a -D variable like +other LAMMPS settings, but rather an option to the cmake command. The +path is where to install the LAMMPS files. + +TODO: is this sub-section correct? + +[Traditional make]: + +There is no "install" option in the src/Makefile for LAMMPS. If you +wish to do this you will need to build, then manually copy the +desired LAMMPS files to the appopriate system directories. diff --git a/doc/src/Build_cmake.txt b/doc/src/Build_cmake.txt new file mode 100644 index 0000000000..2bc10d1463 --- /dev/null +++ b/doc/src/Build_cmake.txt @@ -0,0 +1,159 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Build LAMMPS with CMake :h3 + +This page is a short summary of how to use CMake to build LAMMPS. +Specific details on CMake variables that enable LAMMPS build options +are given on the pages linked to from the "Build"_Build.html doc page. + +Richard Berger (Temple U) has also written a more comprehensive guide +for how to use CMake to build LAMMPS. If you are new to CMake it is a +good place to start: + +"Bulding LAMMPS using +CMake"_https://github.com/rbberger/lammps/tree/cmake_documentation/cmake + +:line + +Building LAMMPS with CMake is a two-step process. First use CMake to +create a Makefile. Then use the standard make command to build +LAMMPS, which uses the created Makefile. + +mkdir mydir; cd mydir # create a new dir for build +cmake ~/lammps/cmake \[options ...\] # command-line version +ccmake ~/lammps/cmake # curses version (terminal-style menu) +cmake-gui ~/lammps/cmake # GUI version +make # traditional make command +make install # optional, copy LAMMPS executable & library elsewhere :pre + +The make command will compile and link LAMMPS, producing the +executable lmp and the library liblammps.a in mydir. + +If your machine has multiple cores (most do), using a command like +"make -j" will be much faster. + +:line + +There are 3 variants of CMake: a command-line verison, a curses +version (teminal-style menu), and a GUI version. You can use any of +them to build LAMMPS. All the versions produce a Makefile as their +output. See more details on each below. + +You can specify a variety of options with any of the 3 versions, which +affect how the build is performed and what is included in the LAMMPS +executable. Links to pages explaining all the options are listed on +the "Build"_Build.html doc page. + +Perform the build in a new directory you create. It can be a sub-dir +within lammps/cmake or anywhere you wish. You can perform separate +builds, with different options, in as many directories as you like. +All the auxiliary files created by the build (executable, object +files, log files, etc) are stored in that directory or sub-directories +within it that CMake creates. + +NOTE: To perform a CMake build, no packages can be installed in the +LAMMPS src dir. Likewise no style*.h or a lmpinstalledpkgs.h file can +exist, which are auto-generated by "building LAMMPS via traditional +make"_Build_make.html. CMake detects if this is not the case and +generates an error, telling you to type "make no-all purge" in the src +directory to un-install all packages. The purge removes all the +auto-generated *.h files. + +You must have CMake version 2.8 or later on your system to build +LAMMPS. If you include the GPU package, version 3.2 or later is +required. Installation instructions for CMake are below. + +After the initial build, if you edit LAMMPS source files, or add your +own new files to the source directory, you can just re-type make from +your build directory and it will re-compile only the files that have +changed. If you want to change CMake options, you can remove the +cache file CMakeCache.txt in the build directory and start over. Or +you can run cmake again from the same build directory and alter +various options; see details below. + +:line + +[Command-line version of CMake]: + +cmake \[options ...\] ~/lammps/cmake # build from any dir +cmake \[options ...\] .. # build from lammps/cmake/newdir :pre + +The cmake command takes one required argument, which is the LAMMPS +cmake directory which contains the CMakeLists.txt file. + +The argument can be preceeded or followed by various CMake +command-line options. Several useful ones are: + +CAKE_INSTALL_PREFIX=path # where to install LAMMPS executable/lib if desired +CMAKE_BUILD_TYPE=type # type = Release or Debug +-G output # style of output CMake generates +-DVARIABLE=value # setting for a LAMMPS feature to enable +-D VARIABLE=value # ditto, but cannot come after CMakeLists.txt dir + +All the LAMMPS-specific -D variables that a LAMMPS build supports are +described on the pages linked to from the "Build"_Build.html doc page. +All of these variable names are upper-case and their values are +lower-case, e.g. -D LAMMPS_SIZES=smallbig. For boolean values, any of +these forms can be used: yes/no, on/off, 1/0. + +By default CMake generates a Makefile to perform the LAMMPS build. +Alternate forms of build info can be generated via the -G switch, +e.g. Visual Studio on a Windows machine. Type "cmake --help" to see +the "Generator" styles of output your system supports. + +NOTE: When CMake runs, it prints configuration info to the screen. +You should scan this to verify all the features you requested were +enabled, including packages. You can also see what compiler and +compile options will be used for the build. Any errors will also be +flagged, e.g. mis-typed variable names or variable values. + +CMake creates a CMakeCache.txt file when it runs. This stores all the +settings, so that running CMake again from the same directory will +inherit those settings. + +TODO: explain how to change settings on a subsequent cmake in the same +build dir. In that case is "." the final arg of cmake? + +[Curses version (terminal-style menu) of CMake]: + +ccmake ~/lammps/cmake :pre + +TODO: give brief explanation of how to find and toggle options, how to +perform the generate, how to use it multiple times. + +[GUI version of CMake]: + +cmake-gui ~/lammps/cmake :pre + +TODO: give brief explanation of how to find and toggle options, how to +perform the generate, how to use it multiple times. + +:line + +[Installing CMake] + +Check if your machine already has CMake installed: + +which cmake # do you have it? +which cmake3 # version 3 may have this name +cmake --version # what specific version you have :pre + +On clusters or supercomputers which use modules to manage software +packages, do this: + +module list # is a cmake module is already loaded +module avail # is a cmake module available? +module load cmake3 # load cmake module with appropriate name :pre + +If you do not have CMake or a new enough version, you can install it +as follows: + +TODO: give install instructions for Linux, Mac, Windows + diff --git a/doc/src/Build_extras.txt b/doc/src/Build_extras.txt new file mode 100644 index 0000000000..82f720791d --- /dev/null +++ b/doc/src/Build_extras.txt @@ -0,0 +1,803 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Packages with extra build options :h3 + +When building with some packages, additional steps may be required, +beyond just "-D PKG_NAME=yes" for CMake or "make yes-name" for make, +as described on the "Build_package"_Build_package.html doc page. + +For a CMake build there may be additional variables that can be set. +For a build with make, a provided library under the lammps/lib +directory may need to be built first. Or an external library may need +to be downloaded and built, and you may need to tell LAMMPS where it +is found on your system. + +This is the list of packages that may require additional steps. + +"GPU"_#gpu, +"KIM"_#kim, +"KOKKOS"_#kokkos, +"LATTE"_#latte, +"MEAM"_#meam, +"MSCG"_#mscg, +"OPT"_#opt, +"POEMS"_#poems, +"PYTHON"_#python, +"REAX"_#reax, +"VORONOI"_#voronoi, +"USER-ATC"_#user-atc, +"USER-AWPMD"_#user-awpmd, +"USER-COLVARS"_#user-colvars, +"USER-H5MD"_#user-h5md, +"USER-INTEL"_#user-intel, +"USER-MOLFILE"_#user-molfile, +"USER-NETCDF"_#user-netcdf, +"USER-OMP"_#user-omp, +"USER-QMMM"_#user-qmmm, +"USER-QUIP"_#user-quip, +"USER-SMD"_#user-smd, +"USER-VTK"_#user-vtk :tb(c=6,ea=c) + +:line +:line + +COMPRESS package + +To build with this package you must have the zlib compression library +available on your system. + +[CMake build]: + +If CMake cannot find the library, you can set these variables: + +-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file +-D ZLIB_LIBRARIES=path # path to libzlib.a (.so) file + +[Traditional make]: + +If make cannot find the library, you can edit the +lib/compress/Makefile.lammps file to specify the paths and library +name. + +:line + +GPU package :h3,link(gpu) + +To build with this package, you need to choose options for precision +and which GPU hardware to build for. To build with make you also need +to build the library in lib/gpu first. + +[CMake build]: + +-D GPU_API=value # value = opencl (default) or cuda +-D GPU_PREC=value # precision setting + # value = single or mixed (default) or double +-D OCL_TUNE=value # hardware choice for GPU_API=opencl + # generic (default) or intel (Intel CPU) or phi (Intel Xeon Phi) or fermi (NVIDIA) or kepler (NVIDIA) or cypress (NVIDIA) +-D GPU_ARCH=value # hardware choice for GPU_API=cuda + # value = sm20 (Fermi) or sm30 (Kepler) or sm50 (Maxwell) or sm60 (Pascal) or sm70 (Volta) + # default is Cuda-compiler dependent, but typically Fermi +-D CUDPP_OPT=value # optimization setting for GPU_API=cudea + # enables CUDA Performance Primitives Optimizations + # on (default) or off + +[Traditional make]: + +You must first build the GPU library in lib/gpu. You can do this +manually if you prefer; follow the instructions in lib/gpu/README. +Note that the GPU library uses MPI calls, so you must use the same MPI +library (or the STUBS library) settings as the main LAMMPS code. This +also applies to the -DLAMMPS_BIGBIG, -DLAMMPS_SMALLBIG, or +-DLAMMPS_SMALLSMALL settings in whichever Makefile you use. + +You can also build the library in one step from the lammps/src dir, +using a command like these, which simply invoke the lib/gpu/Install.py +script with the specified args: + +make lib-gpu # print help message +make lib-gpu args="-b" # build GPU library with default Makefile.linux +make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision +make lib-gpu args="-m mpi -p mixed -b" # build GPU library with mixed precision using settings in Makefile.mpi :pre + +Note that this procedure starts with a Makefile.machine in lib/gpu, as +specified by the "-m" switch. For your convenience, machine makefiles +for "mpi" and "serial" are provided, which have the same settings as +the corresponding machine makefiles in the main LAMMPS source +folder. In addition you can alter 4 important settings in the +Makefile.machine you start from, via the -h, -a, -p, -e switches, and +also save a copy of the new Makefile, if desired: + +CUDA_HOME = where NVIDIA CUDA software is installed on your system +CUDA_ARCH = what GPU hardware you have (see help message for details) +CUDA_PRECISION = precision (double, mixed, single) +EXTRAMAKE = which Makefile.lammps.* file to copy to Makefile.lammps :ul + +If the library build is successful, 3 files should be created: +lib/gpu/libgpu.a, lib/gpu/nvc_get_devices, and +lib/gpu/Makefile.lammps. The latter has settings that enable LAMMPS +to link with CUDA libraries. If the settings in Makefile.lammps for +your machine are not correct, the LAMMPS build will fail, and +lib/gpu/Makefile.lammps may need to be edited. + +NOTE: If you re-build the GPU library in lib/gpu, you should always +un-install the GPU package, then re-install it and re-build LAMMPS. +This is because the compilation of files in the GPU package use the +library settings from the lib/gpu/Makefile.machine used to build the +GPU library. + +:line + +KIM package :h3,link(kim) + +To build with this package, the KIM library must be downloaded and +built on your system. It must include the KIM models that you want to +use with LAMMPS. + +Note that in LAMMPS lingo, a KIM model driver is a pair style +(e.g. EAM or Tersoff). A KIM model is a pair style for a particular +element or alloy and set of parameters, e.g. EAM for Cu with a +specific EAM potential file. Also note that installing the KIM API +library with all its models, may take around 30 min to build. Of +course you only need to do that once. + +See the list of KIM model drivers here: +https://openkim.org/kim-items/model-drivers/alphabetical + +See the list of all KIM models here: +https://openkim.org/kim-items/models/by-model-drivers + +See the list of example KIM models included by default here: +https://openkim.org/kim-api on the "What is in the KIM API source +package?" page. + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +You can do download and build the KIM library manually if you prefer; +follow the instructions in lib/kim/README. You can also do it in one +step from the lammps/src dir, using a command like these, which simply +invoke the lib/kim/Install.py script with the specified args. + +make lib-kim # print help message +make lib-kim args="-b " # (re-)install KIM API lib with only example models +make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model +make lib-kim args="-b -a everything" # install KIM API lib with all models +make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # add one model or model driver +make lib-kim args="-p /usr/local/kim-api" # use an existing KIM API installation at the provided location +make lib-kim args="-p /usr/local/kim-api -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver :pre + +:line + +KOKKOS package :h3,link(kokkos) + +To build with this package, you have to choose a Kokkos setting for +either CPU (multi-threading via OpenMP) or KNL (OpenMP) or GPU (Cuda) +support. + +[CMake build]: + +TODO: how to do this, how to select CPU vs KNL vs GPU, and other +traditional make settings + +[Traditional make]: + + how to choose these 3 things: mode archgpu=N archcpu=SNB + mode = omp or cuda or phi (def = KOKKOS_DEVICES setting in Makefile ) + archgpu = number like 35 (Kepler) or 21 (Fermi) (def = none) + sets KOKKOS_ARCH for GPU to appropriate value + archcpu = SNB or HSW or BGQ or Power7 or Power8 (def = none) + for CPU = SandyBridge, Haswell, BGQ, Power7, Power8 + sets KOKKOS_ARCH for GPU to appropriate value + +For the KOKKOS package, you have 3 choices when building. You can +build with either CPU or KNL or GPU support. Each choice requires +additional settings in your Makefile.machine for the KOKKOS_DEVICES +and KOKKOS_ARCH settings. See the src/MAKE/OPTIONS/Makefile.kokkos* +files for examples. + +For multicore CPUs using OpenMP: + +KOKKOS_DEVICES = OpenMP +KOKKOS_ARCH = HSW # HSW = Haswell, SNB = SandyBridge, BDW = Broadwell, etc :pre + +For Intel KNLs using OpenMP: + +KOKKOS_DEVICES = OpenMP +KOKKOS_ARCH = KNL :pre + +For NVIDIA GPUs using CUDA: + +KOKKOS_DEVICES = Cuda +KOKKOS_ARCH = Pascal60,Power8 # P100 hosted by an IBM Power8, etc +KOKKOS_ARCH = Kepler37,Power8 # K80 hosted by an IBM Power8, etc :pre + +For GPUs, you also need these 2 lines in your Makefile.machine before +the CC line is defined, in this case for use with OpenMPI mpicxx. The +2 lines define a nvcc wrapper compiler, which will use nvcc for +compiling CUDA files or use a C++ compiler for non-Kokkos, non-CUDA +files. + +KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd) +export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper +CC = mpicxx :pre + +Once you have an appropriate Makefile.machine, you can +install/un-install the package and build LAMMPS in the usual manner. +Note that you cannot build one executable to run on multiple hardware +targets (CPU or KNL or GPU). You need to build LAMMPS once for each +hardware target, to produce a separate executable. Also note that we +do not recommend building with other acceleration packages installed +(GPU, OPT, USER-INTEL, USER-OMP) when also building with KOKKOS. + +:line + +LATTE package :h3,link(latte) + +To build with this package, you must download and build the LATTE +library. + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +You can do this manually if you prefer; follow the instructions in +lib/latte/README. You can also do it in one step from the lammps/src +dir, using a command like these, which simply invokes the +lib/latte/Install.py script with the specified args: + +make lib-latte # print help message +make lib-latte args="-b" # download and build in lib/latte/LATTE-master +make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte +make lib-latte args="-b -m gfortran" # download and build in lib/latte and + # copy Makefile.lammps.gfortran to Makefile.lammps +:pre + +Note that 3 symbolic (soft) links, "includelink" and "liblink" and +"filelink.o", are created in lib/latte to point into the LATTE home +dir. When LAMMPS builds in src it will use these links. You should +also check that the Makefile.lammps file you create is appropriate for +the compiler you use on your system to build LATTE. + +:line + +MEAM package :h3,link(meam) + +NOTE: You should test building the MEAM library with both the Intel +and GNU compilers to see if a simulation runs faster with one versus +the other on your system. + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +MEAM library in lib/meam. You can do this manually if you prefer; +follow the instructions in lib/meam/README. You can also do it in one +step from the lammps/src dir, using a command like these, which simply +invoke the lib/meam/Install.py script with the specified args: + +make lib-meam # print help message +make lib-meam args="-m mpi" # build with default Fortran compiler compatible with your MPI library +make lib-meam args="-m serial" # build with compiler compatible with "make serial" (GNU Fortran) +make lib-meam args="-m ifort" # build with Intel Fortran compiler using Makefile.ifort :pre + +The build should produce two files: lib/meam/libmeam.a and +lib/meam/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to link C++ (LAMMPS) with +Fortran (MEAM library). Typically the two compilers used for LAMMPS +and the MEAM library need to be consistent (e.g. both Intel or both +GNU compilers). If necessary, you can edit/create a new +lib/meam/Makefile.machine file for your system, which should define an +EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine +file. + +:line + +MSCG package :h3,link(mscg) + +Before building LAMMPS with this package, you must first download and +build the MS-CG library. + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +Building the MS-CG library and using it from +LAMMPS requires a C++11 compatible compiler and that the GSL +(GNU Scientific Library) headers and libraries are installed on your +machine. See the lib/mscg/README and MSCG/Install files for more details. + +Assuming these libraries are in place, you can do the download and +build of MS-CG manually if you prefer; follow the instructions in +lib/mscg/README. You can also do it in one step from the lammps/src +dir, using a command like these, which simply invoke the +lib/mscg/Install.py script with the specified args: + +make lib-mscg # print help message +make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master + # with the settings compatible with "make serial" +make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master + # with the settings compatible with "make mpi" +make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release :pre + +Note that 2 symbolic (soft) links, "includelink" and "liblink", will be created in lib/mscg +to point to the MS-CG src/installation dir. When LAMMPS is built in src it will use these links. +You should not need to edit the lib/mscg/Makefile.lammps file. + +:line + +OPT package :h3,link(opt) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +NOTE: The compile flag "-restrict" must be used to build LAMMPS with +the OPT package when using Intel compilers. It should be added to +the CCFLAGS line of your Makefile.machine. See Makefile.opt in +src/MAKE/OPTIONS for an example. + +CCFLAGS: add -restrict for Intel compilers :ul + +:line + +POEMS package :h3,link(poems) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +POEMS library in lib/poems. You can do this manually if you prefer; +follow the instructions in lib/poems/README. You can also do it in +one step from the lammps/src dir, using a command like these, which +simply invoke the lib/poems/Install.py script with the specified args: + +make lib-poems # print help message +make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial") +make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi") +make lib-poems args="-m icc" # build with Intel icc compiler :pre + +The build should produce two files: lib/poems/libpoems.a and +lib/poems/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to build LAMMPS with the +POEMS library (though typically the settings are just blank). If +necessary, you can edit/create a new lib/poems/Makefile.machine file +for your system, which should define an EXTRAMAKE variable to specify +a corresponding Makefile.lammps.machine file. + +:line + +PYTHON package :h3,link(python) + +Building with the PYTHON package assumes you have a Python shared +library available on your system, which needs to be a Python 2 +version, 2.6 or later. Python 3 is not yet supported. See the +lib/python/README for more details. + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +The build uses the lib/python/Makefile.lammps file in the compile/link +process. You should only need to create a new Makefile.lammps.* file +(and copy it to Makefile.lammps) if the LAMMPS build fails. + +:line + +REAX package :h3,link(reax) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +REAX library in lib/reax. You can do this manually if you prefer; +follow the instructions in lib/reax/README. You can also do it in one +step from the lammps/src dir, using a command like these, which simply +invoke the lib/reax/Install.py script with the specified args: + +make lib-reax # print help message +make lib-reax args="-m serial" # build with GNU Fortran compiler (settings as with "make serial") +make lib-reax args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi") +make lib-reax args="-m ifort" # build with Intel ifort compiler :pre + +The build should produce two files: lib/reax/libreax.a and +lib/reax/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to link C++ (LAMMPS) with +Fortran (REAX library). Typically the two compilers used for LAMMPS +and the REAX library need to be consistent (e.g. both Intel or both +GNU compilers). If necessary, you can edit/create a new +lib/reax/Makefile.machine file for your system, which should define an +EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine +file. + +:line + +VORONOI package :h3,link(voronoi) + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +Before building LAMMPS with this package, you must first download and +build the Voro++ library. You can do this manually if you prefer; +follow the instructions in lib/voronoi/README. You can also do it in +one step from the lammps/src dir, using a command like these, which +simply invoke the lib/voronoi/Install.py script with the specified +args: + +make lib-voronoi # print help message +make lib-voronoi args="-b" # download and build the default version in lib/voronoi/voro++- +make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++ +make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6 :pre + +Note that 2 symbolic (soft) links, "includelink" and "liblink", are +created in lib/voronoi to point to the Voro++ src dir. When LAMMPS +builds in src it will use these links. You should not need to edit +the lib/voronoi/Makefile.lammps file. + +:line +:line + +USER-ATC package :h3,link(user-atc) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the ATC +library in lib/atc. You can do this manually if you prefer; follow +the instructions in lib/atc/README. You can also do it in one step +from the lammps/src dir, using a command like these, which simply +invoke the lib/atc/Install.py script with the specified args: + +make lib-atc # print help message +make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial") +make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi") +make lib-atc args="-m icc" # build with Intel icc compiler :pre + +The build should produce two files: lib/atc/libatc.a and +lib/atc/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to build LAMMPS with the ATC +library. If necessary, you can edit/create a new +lib/atc/Makefile.machine file for your system, which should define an +EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine +file. + +Note that the Makefile.lammps file has settings for the BLAS and +LAPACK linear algebra libraries. As explained in lib/atc/README these +can either exist on your system, or you can use the files provided in +lib/linalg. In the latter case you also need to build the library +in lib/linalg with a command like these: + +make lib-linalg # print help message +make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial") +make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi") +make lib-linalg args="-m gfortran" # build with GNU Fortran compiler :pre + + +:line + +USER-AWPMD package :h3,link(user-awpmd) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +AWPMD library in lib/awpmd. You can do this manually if you prefer; +follow the instructions in lib/awpmd/README. You can also do it in +one step from the lammps/src dir, using a command like these, which +simply invoke the lib/awpmd/Install.py script with the specified args: + +make lib-awpmd # print help message +make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial") +make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi") +make lib-awpmd args="-m icc" # build with Intel icc compiler :pre + +The build should produce two files: lib/awpmd/libawpmd.a and +lib/awpmd/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to build LAMMPS with the +AWPMD library. If necessary, you can edit/create a new +lib/awpmd/Makefile.machine file for your system, which should define +an EXTRAMAKE variable to specify a corresponding +Makefile.lammps.machine file. + +Note that the Makefile.lammps file has settings for the BLAS and +LAPACK linear algebra libraries. As explained in lib/awpmd/README +these can either exist on your system, or you can use the files +provided in lib/linalg. In the latter case you also need to build the +library in lib/linalg with a command like these: + +make lib-linalg # print help message +make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial") +make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi") +make lib-linalg args="-m gfortran" # build with GNU Fortran compiler :pre + +:line + +USER-COLVARS package :h3,link(user-colvars) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +COLVARS library in lib/colvars. You can do this manually if you +prefer; follow the instructions in lib/colvars/README. You can also +do it in one step from the lammps/src dir, using a command like these, +which simply invoke the lib/colvars/Install.py script with the +specified args: + +make lib-colvars # print help message +make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial") +make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi") +make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled :pre + +The build should produce two files: lib/colvars/libcolvars.a and +lib/colvars/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to build LAMMPS with the +COLVARS library (though typically the settings are just blank). If +necessary, you can edit/create a new lib/colvars/Makefile.machine file +for your system, which should define an EXTRAMAKE variable to specify +a corresponding Makefile.lammps.machine file. + +:line + +USER-H5MD package :h3,link(user-h5md) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Note that to follow these steps to compile and link to the CH5MD +library, you need the standard HDF5 software package installed on your +system, which should include the h5cc compiler and the HDF5 library. + +Before building LAMMPS with this package, you must first build the +CH5MD library in lib/h5md. You can do this manually if you prefer; +follow the instructions in lib/h5md/README. You can also do it in one +step from the lammps/src dir, using a command like these, which simply +invoke the lib/h5md/Install.py script with the specified args: + +make lib-h5md # print help message +make lib-hm5d args="-m h5cc" # build with h5cc compiler :pre + +The build should produce two files: lib/h5md/libch5md.a and +lib/h5md/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to build LAMMPS with the +system HDF5 library. If necessary, you can edit/create a new +lib/h5md/Makefile.machine file for your system, which should define an +EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine +file. + +:line + +USER-INTEL package :h3,link(user-intel) + +[CMake build]: + +TODO: how to choose CPU vs KNL ?? + +[Traditional make]: + +For the USER-INTEL package, you have 2 choices when building. You can +build with either CPU or KNL support. Each choice requires additional +settings in your Makefile.machine for CCFLAGS and LINKFLAGS and +optimized malloc libraries. See the +src/MAKE/OPTIONS/Makefile.intel_cpu and src/MAKE/OPTIONS/Makefile.knl +files for examples. + +For CPUs: + +OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits +CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload \ +-fno-alias -ansi-alias -restrict $(OPTFLAGS) +LINKFLAGS = -g -qopenmp $(OPTFLAGS) +LIB = -ltbbmalloc -ltbbmalloc_proxy :pre + +For KNLs: + +OPTFLAGS = -xMIC-AVX512 -O2 -fp-model fast=2 -no-prec-div -qoverride-limits +CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload \ +-fno-alias -ansi-alias -restrict $(OPTFLAGS) +LINKFLAGS = -g -qopenmp $(OPTFLAGS) +LIB = -ltbbmalloc :pre + +Once you have an appropriate Makefile.machine, you can +install/un-install the package and build LAMMPS in the usual manner. +Note that you cannot build one executable to run on multiple hardware +targets (Intel CPUs or KNL). You need to build LAMMPS once for each +hardware target, to produce a separate executable. + +You should also typically install the USER-OMP package, as it can be +used in tandem with the USER-INTEL package to good effect, as +explained on the "Speed intel"_Speed_intel.html doc page. + +:line + +USER-MOLFILE package :h3,link(user-molfile) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Note that the lib/molfile/Makefile.lammps file has a setting for a +dynamic loading library libdl.a that should is typically present on +all systems, which is required for LAMMPS to link with this package. +If the setting is not valid for your system, you will need to edit the +Makefile.lammps file. See lib/molfile/README and +lib/molfile/Makefile.lammps for details. + +:line + +USER-NETCDF package :h3,link(user-netcdf) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Note that to follow these steps, you need the standard NetCDF software +package installed on your system. The lib/netcdf/Makefile.lammps file +has settings for NetCDF include and library files that LAMMPS needs to +compile and linkk with this package. If the settings are not valid +for your system, you will need to edit the Makefile.lammps file. See +lib/netcdf/README for details. + +:line + +USER-OMP package :h3,link(user-omp) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +CCFLAGS: add -fopenmp (and -restrict when using Intel compilers) +LINKFLAGS: add -fopenmp :ul + +:line + +USER-QMMM package :h3,link(user-qmmm) + +The LAMMPS executable these steps produce is not yet functional for a +QM/MM simulation. You must also build Quantum ESPRESSO and create a +new executable which links LAMMPS and Quantum ESPRESSO together. +These are steps 3 and 4 described in the lib/qmmm/README file. + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +QMMM library in lib/qmmm. You can do this manually if you prefer; +follow the first two steps explained in lib/qmmm/README. You can +also do it in one step from the lammps/src dir, using a command like +these, which simply invoke the lib/qmmm/Install.py script with the +specified args: + +make lib-qmmm # print help message +make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial") +make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi") +make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler :pre + +The build should produce two files: lib/qmmm/libqmmm.a and +lib/qmmm/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to build LAMMPS with the +QMMM library (though typically the settings are just blank). If +necessary, you can edit/create a new lib/qmmm/Makefile.machine file +for your system, which should define an EXTRAMAKE variable to specify +a corresponding Makefile.lammps.machine file. + +You can then install/un-install the package and build LAMMPS in the +usual manner: + +:line + +USER-QUIP package :h3,link(user-quip) + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +Note that to follow these steps to compile and link to the QUIP +library, you must first download and build QUIP on your systems. It +can be obtained from GitHub. See step 1 and step 1.1 in the +lib/quip/README file for details on how to do this. Note that it +requires setting two environment variables, QUIP_ROOT and QUIP_ARCH, +which will be accessed by the lib/quip/Makefile.lammps file which is +used when you compile and link LAMMPS with this package. You should +only need to edit this file if the LAMMPS build can not use its +settings to successfully build on your system. + +:line + +USER-SMD package :h3,link(user-smd) + +[CMake build]: + +-D EIGEN3_INCLUDE_DIR + +[Traditional make]: + +Before building LAMMPS with this package, you must first download the +Eigen library. Eigen is a template library, so you do not need to +build it, just download it. You can do this manually if you prefer; +follow the instructions in lib/smd/README. You can also do it in one +step from the lammps/src dir, using a command like these, which simply +invoke the lib/smd/Install.py script with the specified args: + +make lib-smd # print help message +make lib-smd args="-b" # download and build in default lib/smd/eigen-eigen-... +make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3 :pre + +Note that a symbolic (soft) link named "includelink" is created in +lib/smd to point to the Eigen dir. When LAMMPS builds it will use +this link. You should not need to edit the lib/smd/Makefile.lammps file. + +You can then install/un-install the package and build LAMMPS in the +usual manner: + +:line + +USER-VTK package :h3,link(user-vtk) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +The lib/vtk/Makefile.lammps file has settings for accessing VTK files +and its library, which are required for LAMMPS to build and link with +this package. If the settings are not valid for your system, check if +one of the other lib/vtk/Makefile.lammps.* files is compatible and +copy it to Makefile.lammps. If none of the provided files work, you +will need to edit the Makefile.lammps file. + +You can then install/un-install the package and build LAMMPS in the +usual manner: diff --git a/doc/src/Build_link.txt b/doc/src/Build_link.txt new file mode 100644 index 0000000000..1a1b387f3f --- /dev/null +++ b/doc/src/Build_link.txt @@ -0,0 +1,85 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Link LAMMPS as a library to another code :h3 + +LAMMPS can be used as a library by another application, including +Python scripts. The files src/library.cpp and library.h define the +C-style API for using LAMMPS as a library. See the "Howto +library"_Howto_library.html doc page for a description of the +interface and how to extend it for your needs. + +The "Build basics"_Build_basics.html doc page explains how to build +LAMMPS as either a shared or static library. This results in one of +these 2 files: + +liblammps.so # shared library +liblammps.a # static library + +:line + +[Link with LAMMPS as a static library]: + +The calling application can link to LAMMPS as a static library with a +link command like this: + +g++ caller.o -L/home/sjplimp/lammps/src -llammps -o caller + +The -L argument is the path to where the liblammps.a file is. The +-llammps argument is shorthand for the file liblammps.a. + +:line + +[Link with LAMMPS as a shared library]: + +If you wish to link to liblammps.so, the operating system finds shared +libraries to load at run-time using the environment variable +LD_LIBRARY_PATH. To enable this you can do one of two things: + +(1) Copy the liblammps.so file to a location the system can find it, +such as /usr/local/lib. I.e. a directory already listed in your +LD_LIBRARY_PATH variable. You can type + +printenv LD_LIBRARY_PATH :pre + +to see what directories are in that list. + +(2) Add the LAMMPS src directory (or the directory you perform CMake +build in) to your LD_LIBRARY_PATH, so that the current version of the +shared library is always available to programs that use it. + +For the csh or tcsh shells, you would add something like this to your +~/.cshrc file: + +setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre + +:line + +[Calling the LAMMPS library]: + +Either flavor of library (static or shared) allows one or more LAMMPS +objects to be instantiated from the calling program. + +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. + +When used from a C or Fortran program, the library has a simple +C-style interface, provided in src/library.cpp and src/library.h. + +See the "Python library"_Python_library.html doc page for a +description of the Python interface to LAMMPS, which wraps the C-style +interface. + +See the sample codes in examples/COUPLE/simple for examples of C++ and +C and Fortran codes that invoke LAMMPS thru its library interface. +Other examples in the COUPLE directory use coupling ideas discussed on +the "Howto couple"_Howto_couple.html doc page. + + diff --git a/doc/src/Build_make.txt b/doc/src/Build_make.txt new file mode 100644 index 0000000000..4603a986a3 --- /dev/null +++ b/doc/src/Build_make.txt @@ -0,0 +1,66 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Build LAMMPS with make :h3 + +Building LAMMPS with traditional make requires you have a +Makefile.machine file in the src/MAKE directory appropriate for your +system (see below). It can list various options for what to +include/exclude in a LAMMPS build. To include LAMMPS packages you +must install them first, as discussed on the "Build +package"_Build_package.html doc page. If the packages use provided or +external libraries, you must build those libraries before building +LAMMPS. Building "LAMMPS with CMake"_Build_cmake.html can automate +all of this, so we suggest you try it first. + +These commands perform a default LAMMPS build, producing the LAMMPS +executable lmp_serial or lmp_mpi in lammps/src: + +cd lammps/src +make serial # build a serial LAMMPS executable +make mpi # build a parallel LAMMPS executable with MPI +make # see a variety of make options :pre + +If your machine has multiple cores (most do), using a command like +"make -j mpi" will be much faster. + +After the initial build, if you edit LAMMPS source files, or add new +files to the source directory, you can re-type make and it will only +re-compile the files that have changed. + +:line + +The lammps/src/MAKE directory contains all the Makefile.machine files +included in the LAMMPS distribution. Typing "make machine" uses +Makefile.machine. Thus the "make serial" or "make mpi" lines above +use Makefile.serial and Makefile.mpi. Others are in these dirs: + +OPTIONS # Makefiles which enable specific options +MACHINES # Makefiles for specific machines +MINE # customized Makefiles you create :pre + +Typing "make" lists all the available Makefile.machine files. A file +with the same name can appear in multiple dirs (not a good idea). The +order the dirs are searched is as follows: src/MAKE/MINE, src/MAKE, +src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference to a +customized file you put in src/MAKE/MINE. + +Makefiles you may wish to try include these (some require a package +first be installed). Many of these include specific compiler flags +for optimized performance: + +make mac # build serial LAMMPS on a Mac +make mac_mpi # build parallel LAMMPS on a Mac +make intel_cpu # build with the USER-INTEL package optimized for CPUs +make knl # build with the USER-INTEL package optimized for KNLs +make opt # build with the OPT package optimized for CPUs +make omp # build with the USER-OMP package optimized for OpenMP +make kokkos_omp # build with the KOKKOS package for OpenMP +make kokkos_cuda_mpi # build with the KOKKOS package for GPUs +make kokkos_phi # build with the KOKKOS package for KNLs :pre diff --git a/doc/src/Build_package.txt b/doc/src/Build_package.txt new file mode 100644 index 0000000000..e59bf2b9d6 --- /dev/null +++ b/doc/src/Build_package.txt @@ -0,0 +1,182 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Include packages in build :h3 + +In LAMMPS, a package is a group of files that enable a specific set of +features. For example, force fields for molecular systems or +rigid-body constraints are in packages. In the src directory, each +package is a sub-directory with the package name in capital letters. + +A complete list of packages with brief overviews of each are on the +"Packages details"_Packages_details.html doc page. + +When building LAMMPS, you can choose to include or exclude each +package. In general there is no need to include a package if you +never plan to use its features. + +If you get a run-time error that a LAMMPS command or style is +"Unknown", it is often because the command is contained in a package, +and your build did not include the package. Running LAMMPS with the +"-h command-line switch"_Run_options.html will print all the included +packages and commands for that executable. + +The mechanism for including packages is different for CMake versus a +traditional make. + +For the majority of packages, if you follow the single step below to +include it, you can then build LAMMPS exactly the same as you would +without any packages installed. A few packages may require additional +steps, as explained on the "Build extras"_Build_extras.html doc page. + +These links take you to the extra instructions for those select +packages: + +"GPU"_Build_extras.html#gpu, +"KIM"_Build_extras.html#kim, +"KOKKOS"_Build_extras.html#kokkos, +"LATTE"_Build_extras.html#latte, +"MEAM"_Build_extras.html#meam, +"MSCG"_Build_extras.html#mscg, +"OPT"_Build_extras.html#opt, +"POEMS"_Build_extras.html#poems, +"PYTHON"_Build_extras.html#python, +"REAX"_Build_extras.html#reax, +"VORONOI"_Build_extras.html#voronoi, +"USER-ATC"_Build_extras.html#user-atc, +"USER-AWPMD"_Build_extras.html#user-awpmd, +"USER-COLVARS"_Build_extras.html#user-colvars, +"USER-H5MD"_Build_extras.html#user-h5md, +"USER-INTEL"_Build_extras.html#user-intel, +"USER-MOLFILE"_Build_extras.html#user-molfile, +"USER-NETCDF"_Build_extras.html#user-netcdf, +"USER-OMP"_Build_extras.html#user-omp, +"USER-QMMM"_Build_extras.html#user-qmmm, +"USER-QUIP"_Build_extras.html#user-quip, +"USER-SMD"_Build_extras.html#user-smd, +"USER-VTK"_Build_extras.html#user-vtk :tb(c=6,ea=c) + +[CMake variables]: + +-D PKG_NAME=value # yes or no (default) :pre + +Examples: + +-D PKG_MANYBODY=yes +-D PKG_USER-INTEL=yes :pre + +All standard and user packages are included the same way. Note that +USER packages have a hyphen between USER and the rest of the package +name, not an underscore. + +NOTE: If you toggle back and forth between building with CMake vs +make, no packages in the src directory can be installed when you +invoke cmake. CMake will give an error if that is not the case, +indicating how you can un-install all packages in the src dir. + +[Traditional make]: + +cd lammps/src +make ps # check which packages are currently installed +make yes-name # install a package with name +make no-name # un-install a package with name +make mpi # build LAMMPS with whatever packages are now installed :pre + +Examples: + +make no-rigid +make yes-user-intel :pre + +All standard and user packages are included the same way. + +NOTE: You must always re-build LAMMPS (via make) after installing or +un-installing a package, for the action to take effect. + +NOTE: You cannot install or un-install packages and build LAMMPS in a +single make command with multiple targets, e.g. make yes-colloid mpi. +This is because the make procedure creates a list of source files that +will be out-of-date for the build if the package configuration changes +within the same command. You can include or exclude multiple packages +in a single make command, e.g. make yes-colloid no-manybody. + +[CMake and make info]: + +Any package can be included or excluded in a LAMMPS build, independent +of all other packages. However, some packages include files derived +from files in other packages. LAMMPS checks for this and does the +right thing. 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. + +NOTE: The one exception is that for a build via make (ok via CMake), +we do not recommend building with the KOKKOS package installed along +with any of the other acceleration packages (GPU, OPT, USER-INTEL, +USER-OMP) also installed. This is because of how Kokkos sometimes +builds using a wrapper compiler which can make it difficult to invoke +all the compile/link flags correctly for both Kokkos and non-Kokkos +files. + +When you download a LAMMPS tarball, three packages are pre-installed +in the src directory: KSPACE, MANYBODY, MOLECULE. This is because +they are so commonly used. When you download LAMMPS source files from +the Git or SVN repositories, no packages are pre-installed. + +:line + +The following make commands are useful for managing package source +files and their installation when building LAMMPS via traditional +make. Just type "make" in lammps/src to see a one-line summary. + +These commands install/un-install sets of packages: + +make yes-all | install all packages +make no-all | un-install all packages +make yes-standard or make yes-std | install standard packages +make no-standard or make no-std| un-install standard packages +make yes-user | install user packages +make no-user | un-install user packages +make yes-lib | install packages that require extra libraries +make no-lib | un-install packages that require extra libraries +make yes-ext | install packages that require external libraries +make no-ext | un-install packages that require external libraries :tb(s=|,a=l) + +which install/un-install various sets of packages. Typing "make +package" will list all the these commands. + +NOTE: Installing or un-installing a package works by simply copying +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 included or excluded when LAMMPS is built. + +The following make commands help manage 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 are +"installing a patch"_Install_patch.html downloaded from the LAMMPS web +site. + +Type "make package-status" or "make ps" to show which packages are +currently installed. For those that are installed, it will list any +files that are different in the src directory and package +sub-directory. + +Type "make package-installed" or "make pi" to show which packages are +currently installed, without listing the status of packages that are +not installed. + +Type "make package-update" or "make pu" to overwrite src files with +files from the package sub-directories if the package is installed. +It should be used after a "patch has been applied"_Install_patch.html, +since patches only update the files in the package sub-directory, but +not the src files. + +Type "make package-overwrite" to overwrite files in the package +sub-directories with src files. + +Type "make package-diff" to list all differences between pairs of +files in both the src dir and a package dir. diff --git a/doc/src/Build_settings.txt b/doc/src/Build_settings.txt new file mode 100644 index 0000000000..1969e9588b --- /dev/null +++ b/doc/src/Build_settings.txt @@ -0,0 +1,327 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Optional build settings :h3 + +LAMMPS can be built with several optional settings. Each sub-section +explain how to do this for either a CMake build or traditional make. + +"FFT library"_#fft for use with "kspace_style pppm"_kspace_style.html command +"Size of LAMMPS data types"_#size +"Read or write compressed files"_#compress +"Output of JPG and PNG files"_#graphics via "dump image"_dump_image.html command +"Output of movie files"_#graphics via "dump_movie"_dump_image.html command +"Memory allocation alignment"_#align +"Workaround for long long integers"_#longlong +"Error handling exceptions"_#exceptions when using LAMMPS as a library :all(b) + +:line +:line + +FFT library :h3,link(fft) + +When the KSPACE package is included in a LAMMPS build, the +"kspace_style pppm"_kspace_style.html command performs 3d FFTs which +require use of an FFT library to compute 1d FFTs. The KISS FFT +library is included with LAMMPS but other libraries are typically +faster if they are available on your system. See details on other FFT +libraries below. + +[CMake variables]: + +-D FFT=value # kiss or fftw3 or fftw2 or mkl, default is fftw3 if found, else kiss +-D FFT_SINGLE=value # yes or no (default), no = double precision +-D FFT_PACK=value # array (default) or pointer or memcpy :pre + +Usually these settings are all that is needed. If CMake cannot find +the FFT library, you can set these variables: + +-D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files +-D FFTW2_LIBRARIES=path # path to FFTW3 libraries +-D FFTW2_INCLUDE_DIRS=path # ditto for FFTW2 +-D FFTW3_LIBRARIES=path +-D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library +-D MKL_LIBRARIES=path :pre + +[Makefile.machine settings]: + +FFT_INC = -DFFT_FFTW3 # FFTW3, FFTW2, FFTW (same as FFTW3), MKL, or KISS + # default is KISS if not specified +FFT_INC = -DFFT_SINGLE # do not specify for double precision +FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY :pre + +TODO: change code to use FFT_PACK_OPTION + +FFT_INC = -I/usr/local/include +FFT_PATH = -L/usr/local/lib +FFT_LIB = -lfftw3 # FFTW3 double precision +FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision +FFT_LIB = -lfftw # FFTW2 double precision, or -ldfftw +FFT_LIB = -lsfftw # FFTW2 single precision +FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler +FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compier :pre + +As with CMake, you do not need to set paths in FFT_INC or FFT_PATH, if +make can find the FFT header and library files. You must specify +FFT_LIB with the appropriate FFT libraries to include in the link. + +[CMake and make info]: + +The "KISS FFT library"_http://kissfft.sf.net is included in the LAMMPS +distribution, so not FFT_LIB setting is required. It is portable +across all platforms. + +FFTW is fast, portable library that should also work on any platform +and typically be faster than KISS FFT. 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. Building FFTW for your box +should be as simple as ./configure; make; make install. The install +command typically requires root privileges (e.g. invoke it via sudo), +unless you specify a local directory with the "--prefix" option of +configure. Type "./configure --help" to see various options. + +The Intel MKL math library is part of the Intel compiler suite. It +can be used with the Intel or GNU compiler (see FFT_LIB setting above). + +3d FFTs can be computationally expensive. Their cost can be reduced +by performing single-precision FFTs instead of double precision. +Single precision means the real and imaginary parts of a complex datum +are 4-byte floats. Double precesion means they are 8-byte doubles. +Note that 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 this setting trades +off a little accuracy for reduced memory use and parallel +communication costs for transposing 3d FFT data. + +When using -DFFT_SINGLE with FFTW3 or FFTW2, you may need to build the +FFTW library a second time with support for single-precision. + +For FFTW3, do the following, which should produce the additional +library libfftw3f.a + +make clean +./configure --enable-single; make; make install :pre + +For FFTW2, do the following, which should produce the additional +library libsfftw.a + +make clean +./configure --enable-float --enable-type-prefix; make; make install :pre + +Performing 3d FFTs requires communication to transpose the 3d FFT +grid. The data packing/unpacking for this can be done in one of 3 +modes (ARRAY, POINTER, MEMCPY) as set by the FFT_PACK syntax above. +Depending on the machine, the size of the FFT grid, the number of +processors used, one option may be slightly faster. The default is +ARRAY mode. + +:line + +Size of LAMMPS data types :h3,link(size) + +LAMMPS has a few integer data types which can be defined as 4-byte or +8-byte integers. The default setting of "smallbig" is almost always +adequate. + +[CMake variable]: + +-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall :pre + +[Makefile.machine setting]: + +LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL :pre + +[CMake and make info]: + +The default "smallbig" setting allows for simulations with: + +total atom count = 2^63 atoms (about 9e18) +total timesteps = 2^63 (about 9e18) +atom IDs = 2^31 (about 2 billion) +image flags = roll over at 512 :ul + +The "bigbig" setting increases the latter two limits. It allows for: + +total atom count = 2^63 atoms (about 9e18) +total timesteps = 2^63 (about 9e18) +atom IDs = 2^63 (about 9e18) +image flags = roll over at about 1 million (2^20) :ul + +The "smallsmall" setting is only needed if your machine does not +support 8-byte integers. It allows for: + +total atom count = 2^31 atoms (about 2 billion) +total timesteps = 2^31 (about 2 billion) +atom IDs = 2^31 (about 2 billion) +image flags = roll over at 512 (2^9) :ul + +Atom IDs are not required for atomic systems which do not store bond +topology information, though IDs are enabled by default. The +"atom_modify id no"_atom_modify.html command will turn them off. Atom +IDs are required for molecular systems with bond topology (bonds, +angles, dihedrals, etc). Thus if you model a molecular system with +more than 2 billion atoms, you need the "bigbig" setting. + +Image flags store 3 values per atom which count the number of times an +atom has moved through the periodic box in each dimension. See the +"dump"_dump.html doc page for a discussion. If an atom moves through +the periodic box more than this limit, the value will "roll over", +e.g. from 511 to -512, which can cause diagnostics like the +mean-squared displacement, as calculated by the "compute +msd"_compute_msd.html command, to be faulty. + +Note that the USER-ATC package is not currently compatible with the +"bigbig" setting. + +Also note that the GPU package requires its lib/gpu library to be +compiled with the same size setting, or the link will fail. A CMake +build does this automatically. When building with make, the setting +in whichever lib/gpu/Makefile is used must be the same as above. + +:line + +Output of JPG, PNG, and movie files :h3,link(graphics) + +The "dump image"_dump_image.html command has options to output JPEG or +PNG image files. Likewise the "dump movie"_dump_image.html command +ouputs movie files in MPEG format. Using these options requires the +following settings: + +[CMake variables]: + +-D LAMMPS_JPEG=value # yes or no + # default = yes if CMake finds JPEG files, else no +-D LAMMPS_PNG=value # yes or no + # default = yes if CMake finds PNG and ZLIB files, else no +-D LAMMPS_FFMPEG=value # yes or no + # default = yes if CMake can find ffmpeg, else no :pre + +Usually these settings are all that is needed. If CMake cannot find +the graphics header, library, executuable files, you can set these +variables: + +-D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file +-D JPEG_LIBRARIES=path # path to libjpeg.a (.so) file +-D PNG_INCLUDE_DIR=path # path to png.h header file +-D PNG_LIBRARIES=path # path to libpng.a (.so) file +-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file +-D ZLIB_LIBRARIES=path # path to libzlib.a (.so) file +-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable :pre + +[Makefile.machine settings]: + +LMP_INC = -DLAMMPS_JPEG +LMP_INC = -DLAMMPS_PNG +LMP_INC = -DLAMMPS_FFMPEG :pre + +JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them +JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libzlib.a (.so) files if make cannot find them +JPG_LIB = -ljpeg -lpng -lzlib # library names :pre + +As with CMake, you do not need to set JPG_INC or JPG_PATH, if make can +find the graphics header and library files. You must specify JPG_LIB +with a list of graphics libraries to include in the link. You must +insure ffmpeg is in a directory where LAMMPS can find it at runtime, +i.e. a dir in your PATH environment variable. + +[CMake and make info]: + +Using ffmpeg to output movie files requires that your machine +supports the "popen" function in the standard runtime library. + +NOTE: On some clusters with high-speed networks, using the fork() +library calls (required by popen()) can interfere with the fast +communication library and lead to simulations using ffmpeg to hang or +crash. + +:line + +Read or write compressed files :h3,link(compress) + +If this option is enabled, large files can be read or written with +gzip compression by several LAMMPS commands, including +"read_data"_read_data.html, "rerun"_rerun.html, and "dump"_dump.html. + +[CMake variables]: + +-D LAMMPS_GZIP=value # yes or no + # default is yes if CMake can find gzip, else no +-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it + +[Makefile.machine setting]: + +LMP_INC = -DLAMMPS_GZIP :pre + +[CMake and make info]: + +This option requires that your machine supports the "popen()" function +in the standard runtime library and that a gzip executable can be +found by LAMMPS during a run. + +NOTE: On some clusters with high-speed networks, using the fork() +library calls (required by popen()) can interfere with the fast +communication library and lead to simulations using compressed output +or input to hang or crash. For selected operations, compressed file +I/O is also available using a compression library instead, which is +what the "COMPRESS package"_Packages.html enables. + +:line + +Memory allocation alignment :h3,link(align) + +This setting enables the use of the posix_memalign() call instead of +malloc() when LAMMPS allocates large chunks or memory. This can make +vector instructions on CPUs more efficient, if dynamically allocated +memory is aligned on larger-than-default byte boundaries. + +[CMake variable]: + +-D LAMMPS_MEMALIGN=value # 8, 16, 32, 64 (default) :pre + +[Makefile.machine setting]: + +LMP_INC = -DLAMMPS_MEMALIGN=value # 8, 16, 32, 64 :pre + +TODO: I think the make default (no LAMMPS_MEMALIGN) is to not +use posix_memalign(), just malloc(). Does a CMake build have +an equivalent option? I.e. none. + +:line + +Workaround for long long integers :h3,link(longlong) + +If your system or MPI version does not recognize "long long" data +types, the following setting will be needed. It converts "long long" +to a "long" data type, which should be the desired 8-byte integer on +those systems: + +[CMake variable]: + +-D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default) :pre + +[Makefile.machine setting]: + +LMP_INC = -DLAMMPS_LONGLONG_TO_LONG :pre + +:line + +Exception handling when using LAMMPS as a library :h3,link(exceptions) + +This setting is useful when external codes drive LAMMPS as a library. +With this option enabled LAMMPS errors do not kill the caller. +Instead, the call stack is unwound and control returns to the caller, +e.g. to Python. + +[CMake variable]: + +-D LAMMPS_EXCEPTIONS=value # yes or no (default) :pre + +[Makefile.machine setting]: + +LMP_INC = -DLAMMPS_EXCEPTIONS :pre diff --git a/doc/src/Install.txt b/doc/src/Install.txt new file mode 100644 index 0000000000..d59c23d319 --- /dev/null +++ b/doc/src/Install.txt @@ -0,0 +1,64 @@ +"Previous Section"_Intro.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Build.html +:c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Install LAMMPS :h2 + +You can download LAMMPS as an executable or as source code. + +With source code, you also have to "build LAMMPS"_Build.html. But you +have more flexibility as to what features to include or exclude in the +build. If you plan to "modify or extend LAMMPS"_Modify.html, then you +need the source code. + + + + + +"Download an executable for Linux"_Install_linux.html +"Download an executable for Mac"_Install_mac.html +"Download an executable for Windows"_Install_windows.html :all(b) + +"Download source as a tarball"_Install_tarball.html +"Donwload source via Git"_Install_git.html +"Donwload source via SVN"_Install_svn.html +"Install patch files"_Install_patch.html :all(b) + + + +These are the files and sub-directories in the LAMMPS distribution: + +README: text file +LICENSE: GNU General Public License (GPL) +bench: benchmark problems +cmake: CMake build files +doc: documentation +examples: simple test problems +lib: additional provided or external libraries +potentials: interatomic potential files +python: Python wrapper on LAMMPS +src: source files +tools: pre- and post-processing tools :tb(s=:,a=l) + +You will have all of these if you download source. You will only have +some of them if you download executables, as explained on the pages +listed above. diff --git a/doc/src/Install_git.txt b/doc/src/Install_git.txt new file mode 100644 index 0000000000..1d043c30d2 --- /dev/null +++ b/doc/src/Install_git.txt @@ -0,0 +1,120 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download source via Git :h3 + +All LAMMPS development is coordinated through the "LAMMPS GitHub +site". If you clone the LAMMPS repository onto your local machine, it +has several advantages: + +You can stay current with changes to LAMMPS with a single git +command. :ulb,l + +You can create your own development branches to add code to LAMMPS. :l + +You can submit your new features back to GitHub for inclusion in +LAMMPS. :l,ule + +You must have "Git"_git installed on your system to communicate with +the public Git server for LAMMPS. + +IMPORTANT NOTE: As of Oct 2016, the official home of public LAMMPS +development is on GitHub. The previously advertised LAMMPS git +repositories on git.lammps.org and bitbucket.org are now deprecated, +may not be up-to-date, and may go away at any time. + +:link(git,http://git-scm.com) + +You can follow LAMMPS development on 3 different Git branches: + +[stable] : this branch is updated with every stable release +[unstable] : this branch is updated with every patch release +[master] : this branch continuously follows ongoing development :ul + +To access the Git repositories on your box, use the clone command to +create a local copy of the LAMMPS repository with a command like: + +git clone -b unstable https://github.com/lammps/lammps.git mylammps :pre + +where "mylammps" is the name of the directory you wish to create on +your machine and "unstable" is one of the 3 branches listed above. +(Note that you actually download all 3 branches; you can switch +between them at any time using "git checkout ".) + +Once the command completes, your directory will contain the same files +as if you unpacked a current LAMMPS tarball, with two exceptions: + +1) No LAMMPS packages are initially installed in the src dir (a few +packages are installed by default in the tarball src dir). You can +install whichever packages you wish before building LAMMPS; type "make +package" from the src dir to see the options, and the +"Packages"_Packages.html doc page for a discussion of packages. + +2) The HTML documentation files are not included. They can be fetched +from the LAMMPS website by typing "make fetch" in the doc directory. +Or they can be generated from the content provided in doc/src by +typing "make html" from the the doc directory. + +After initial cloning, as bug fixes and new features are added to +LAMMPS, as listed on "this page"_bug.html, you can stay up-to-date by +typing the following Git commands from within the "mylammps" +directory: + +git checkout unstable # not needed if you always stay in this branch +git checkout stable # use one of the 3 checkout commands +git checkout master +git pull :pre + +Doing a "pull" will not change any files you have added to the LAMMPS +directory structure. It will also not change any existing LAMMPS +files you have edited, unless those files have changed in the +repository. In that case, Git will attempt to merge the new +repository file with your version of the file and tell you if there +are any conflicts. See the Git documentation for details. + +If you want to access a particular previous release version of LAMMPS, +you can instead "checkout" any version with a published tag. See the +output of "git tag -l" for the list of tags. The Git command to do +this is as follows. + +git checkout tagID :pre + +Stable versions and what tagID to use for a particular stable version +are discussed on "this page"_bug.html. Note that this command will +print some warnings, because in order to get back to the latest +revision and to be able to update with "git pull" again, you first +will need to first type "git checkout unstable" (or check out any +other desired branch). + +Once you have updated your local files with a "git pull" (or "git +checkout"), you still need to re-build LAMMPS if any source files have +changed. To do this, you should cd to the src directory and type: + +make purge # remove any deprecated src files +make package-update # sync package files with src files +make foo # re-build for your machine (mpi, serial, etc) :pre + +just as described on the "Install patch"_Install_patch.html doc page, +after a patch has been installed. + +IMPORTANT NOTE: If you wish to edit/change a src file that is from a +package, you should edit the version of the file inside the package +sub-directory with src, then re-install the package. The version in +the src dir is merely a copy and will be wiped out if you type "make +package-update". + +IMPORTANT NOTE: The GitHub servers support both the "git://" and +"https://" access protocols for anonymous read-only access. If you +have a correspondingly configured GitHub account, you may also use SSH +with "git@github.com:/lammps/lammps.git". + +The LAMMPS GitHub project is managed by Christoph Junghans (LANL, +junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at +gmail.com) and Richard Berger (Temple U, richard.berger at +temple.edu). diff --git a/doc/src/Install_linux.txt b/doc/src/Install_linux.txt new file mode 100644 index 0000000000..10da3d933f --- /dev/null +++ b/doc/src/Install_linux.txt @@ -0,0 +1,120 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download an executable for Linux :h3 + +Binaries are available for many different versions of Linux: + +"Pre-built binary RPMs for Fedora/RedHat/CentOS/openSUSE"_#rpm +"Pre-built Ubuntu Linux executables"_#unbuntu +"Pre-built Gentoo Linux executable"_#gentoo :all(b) + +:line +:line + +Pre-built binary RPMs for Fedora/RedHat/CentOS/openSUSE :h4,link(rpm) + +Pre-built LAMMPS executables for various Linux distributions +can be downloaded as binary RPM files from this site: + +"http://rpm.lammps.org"_http://rpm.lammps.org + +There are multiple package variants supporting serial, parallel and +Python wrapper versions. The LAMMPS binaries contain all optional +packages included in the source distribution except: GPU, KIM, REAX, +and USER-INTEL. + +Installation instructions for the various versions are here: + +"http://rpm.lammps.org/install.html"_http://rpm.lammps.org/install.html + +The instructions show how to enable the repository in the respective +system's package management system. Installing and updating are then +straightforward and automatic. + +Thanks to Axel Kohlmeyer (Temple U, akohlmey at gmail.com) for setting +up this RPM capability. + +:line + +Pre-built Ubuntu Linux executables :h4,link(ubuntu) + +A pre-built LAMMPS executable suitable for running on the latest +Ubuntu Linux versions, can be downloaded as a Debian package. This +allows you to install LAMMPS with a single command, and stay +up-to-date with the current version of LAMMPS by simply updating your +operating system. + +To install the appropriate personal-package archive (PPA), do the +following once: + +sudo add-apt-repository ppa:gladky-anton/lammps +sudo apt-get update :pre + +To install LAMMPS do the following once: + +sudo apt-get install lammps-daily :pre + +This downloads an executable named "lammps-daily" to your box, which +can then be used in the usual way to run input scripts: + +lammps-daily < in.lj :pre + +To update LAMMPS to the most current version, do the following: + +sudo apt-get update :pre + +which will also update other packages on your system. + +To get a copy of the current documentation and examples: + +sudo apt-get install lammps-daily-doc :pre + +which will download the doc files in +/usr/share/doc/lammps-daily-doc/doc and example problems in +/usr/share/doc/lammps-doc/examples. + +Note that you may still wish to download the tarball to get potential +files and auxiliary tools. + +To un-install LAMMPS, do the following: + +sudo apt-get remove lammps-daily :pre + +Note that the lammps-daily executable is built with the following +sequence of make commands, as if you had done the same with the +unpacked tarball files in the src directory: + +make yes-all; make no-lib; make openmpi + +Thus it builds with FFTW3 and OpenMPI. + +Thanks to Anton Gladky (gladky.anton at gmail.com) for setting up this +Ubuntu package capability. + +:line + +Pre-built Gentoo Linux executable :h4,link(gentoo) + +LAMMPS is part of Gentoo's main package tree and can be installed by +typing: + +% emerge --ask lammps :pre + +Note that in Gentoo the LAMMPS source is downloaded and the package is +built on the your machine. + +Certain LAMMPS packages can be enable via USE flags, type + +% equery uses lammps :pre + +for details. + +Thanks to Nicolas Bock and Christoph Junghans (LANL) for setting up +this Gentoo capability. diff --git a/doc/src/Install_mac.txt b/doc/src/Install_mac.txt new file mode 100644 index 0000000000..3fcc55b8ab --- /dev/null +++ b/doc/src/Install_mac.txt @@ -0,0 +1,55 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download an executable for Mac :h3 + +LAMMPS can be downloaded, built, and configured for OS X on a Mac with +"Homebrew"_homebrew. Only four of the LAMMPS packages are unavailable +at this time because of additional needs not yet met: KIM, GPU, +USER-INTEL, USER-ATC. + +After installing Homebrew, you can install LAMMPS on your system with +the following commands: + +% brew tap homebrew/science +% brew install lammps # serial version +% brew install lammps --with-mpi # mpi support :pre + +This will install the executable "lammps", a python module named +"lammps", and additional resources with all the standard packages. To +get the location of the additional resources type this: + +% brew info lammps :pre + +This command also tells you additional installation options available. +The user-packages are available as options, just install them like +this example for the USER-OMP package: + +% brew install lammps --enable-user-omp :pre + +It is usually best to install LAMMPS with the most up to date source +files, which can be done with the "--HEAD" option: + +% brew install lammps --HEAD :pre + +To re-install the LAMMPS HEAD, run this command occasionally (make sure +to use the desired options). + +% brew install --force lammps --HEAD $\{options\} :pre + +Once LAMMPS is installed, you can test the installation with the +Lennard-Jones benchmark file: + +% brew test lammps -v :pre + +If you have problems with the installation you can post issues to +"this link"_https://github.com/Homebrew/homebrew-science/issues. + +Thanks to Derek Thomas (derekt at cello.t.u-tokyo.ac.jp) for setting +up the Homebrew capability. diff --git a/doc/src/Install_patch.txt b/doc/src/Install_patch.txt new file mode 100644 index 0000000000..3d0b27370e --- /dev/null +++ b/doc/src/Install_patch.txt @@ -0,0 +1,67 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Applying patches :h3 + +It is easy to stay current with the most recent LAMMPS patch releases +if you use Git or SVN to track LAMMPS development. Instructions for +how to stay current are on the "Install git"_Install_git.html and +"Install svn"_Install_svn.html doc pages. + +If you prefer to download a tarball, as described on the "Install +git"_Install_tarball.html doc page, you can stay current by +downloading "patch files" when new patch releases are made. A link to +a patch file is posted on the "bug and feature page"_bug of the +website, along with a list of changed files and details about what is +in the new patch release. This page explains how to apply the patch +file to your local LAMMPS directory. + +NOTE: You should not apply patch files to a local Git or SVN repo of +LAMMPS, only to an unpacked tarball. Use Git and SVN commands to +update repo versions of LAMMPS. + +Here are the steps to apply a patch file. Note that if your version +of LAMMPS is several patch releases behind, you need to apply all the +intervening patch files in succession to bring your version of LAMMPS +up to date. + +Download the patch file. You may have to shift-click in your browser +to download the file instead of display it. Patch files have names +like patch.12Dec16. :ulb,l + +Put the patch file in your top-level LAMMPS directory, where the +LICENSE and README files are. :l + +Apply the patch by typing the following command from your top-level +LAMMPS directory, where the redirected file is the name of the patch +file. :l + +patch -bp1 < patch.12Dec16 :pre + +A list of updated files print out to the screen. The -b switch +creates backup files of your originals (e.g. src/force.cpp.orig), so +you can manually undo the patch if something goes wrong. :l + +Type the following from the src directory, to enforce consistency +between the src and package directories. This is OK to do even if you +don't use one or more packages. If you are applying several patches +successively, you only need to type this once at the end. The purge +command removes deprecated src files if any were removed by the patch +from package sub-directories. :l + +make purge +make package-update :pre + +Re-build LAMMPS via the "make" command. :l,ule + +IMPORTANT NOTE: If you wish to edit/change a src file that is from a +package, you should edit the version of the file inside the package +sub-dir of src, then re-install the package. The version in the src +dir is merely a copy and will be wiped out if you type "make +package-update". diff --git a/doc/src/Install_svn.txt b/doc/src/Install_svn.txt new file mode 100644 index 0000000000..64fd1077cb --- /dev/null +++ b/doc/src/Install_svn.txt @@ -0,0 +1,95 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download source via SVN :h3 + +IMPORTANT NOTE: As of Oct 2016, SVN support is now implemented via a +git-to-subversion interface service on GitHub and no longer through a +mirror of the internal SVN repository at Sandia. + +You must have the "Subversion (SVN) client software"_svn installed on +your system to communicate with the Git server in this mode. + +:link(svn,http://subversion.apache.org) + +You can follow LAMMPS development on 3 different SVN branches: + +[stable] : this branch is updated with every stable release +[unstable] : this branch is updated with every patch release +[master] : this branch continuously follows ongoing development :ul + +The corresponding command lines to do an initial checkout are as +follows. (Note that unlike Git, you must perform a separate checkout +into a unique directory for each of the 3 branches.) + +svn checkout https://github.com/lammps/lammps.git/branches/unstable mylammps +svn checkout https://github.com/lammps/lammps.git/branches/stable mylammps +svn checkout https://github.com/lammps/lammps.git/trunk mylammps :pre + +where "mylammps" is the name of the directory you wish to create on +your machine. + +Once the command completes, your directory will contain the same files +as if you unpacked a current LAMMPS tarball, with two exceptions: + +1) No LAMMPS packages are initially installed in the src dir (a few +packages are installed by default in the tarball src dir). You can +install whichever packages you wish before building LAMMPS; type "make +package" from the src dir to see the options, and the +"Packages"_Packages.html doc page for a discussion of packages. + +2) The HTML documentation files are not included. They can be fetched +from the LAMMPS website by typing "make fetch" in the doc directory. +Or they can be generated from the content provided in doc/src by +typing "make html" from the the doc directory. + +After initial checkout, as bug fixes and new features are added to +LAMMPS, as listed on "this page"_bug.html, you can stay up-to-date by +typing the following SVN commands from within the "mylammps" +directory: + +svn update :pre + +You can also check if there are any updates by typing: + +svn -qu status :pre + +Doing an "update" will not change any files you have added to the +LAMMPS directory structure. It will also not change any existing +LAMMPS files you have edited, unless those files have changed in the +repository. In that case, SVN will attempt to merge the new +repository file with your version of the file and tell you if there +are any conflicts. See the SVN documentation for details. + +Please refer to the "subversion client support help pages on +GitHub"_https://help.github.com/articles/support-for-subversion-clients +if you want to use advanced features like accessing particular +previous release versions via tags. + +Once you have updated your local files with an "svn update" (or "svn +co"), you still need to re-build LAMMPS if any source files have +changed. To do this, you should cd to the src directory and type: + +make purge # remove any deprecated src files +make package-update # sync package files with src files +make foo # re-build for your machine (mpi, serial, etc) :pre + +just as described on the "Install patch"_Install_patch.html doc page, +after a patch has been installed. + +IMPORTANT NOTE: If you wish to edit/change a src file that is from a +package, you should edit the version of the file inside the package +sub-directory with src, then re-install the package. The version in +the src dir is merely a copy and will be wiped out if you type "make +package-update". + +The LAMMPS GitHub project is managed by Christoph Junghans (LANL, +junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at +gmail.com) and Richard Berger (Temple U, richard.berger at +temple.edu). diff --git a/doc/src/Install_tarball.txt b/doc/src/Install_tarball.txt new file mode 100644 index 0000000000..b672c5ff25 --- /dev/null +++ b/doc/src/Install_tarball.txt @@ -0,0 +1,64 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download source as a tarball :h3 + +You can download a current LAMMPS tarball from the "download page"_download +of the "LAMMPS website"_lws. + +:link(download,http://lammps.sandia.gov/download.html) +:link(bug,http://lammps.sandia.gov/bug.html) +:link(older,http://lammps.sandia.gov/tars) + +You have two choices of tarballs, either the most recent stable +release or the most current patch release. Stable releases occur a +few times per year, and undergo more testing before release. Patch +releases occur a couple times per month. The new contents in all +releases are listed on the "bug and feature page"_bug of the website. + +Older versions of LAMMPS can also be downloaded from "this +page"_older. + +Once you have a tarball, unzip and untar it with the following +command: + +tar -xzvf lammps*.tar.gz :pre + +This will create a LAMMPS directory with the version date +in its name, e.g. lammps-23Jun18. + +:line + +You can also download a zip file via the "Clone or download" button on +the "LAMMPS GitHub site"_git. The file name will be lammps-master.zip +which can be unzipped with the following command, to create +a lammps-master dir: + +unzip lammps*.zip :pre + +This version is the most up-to-date LAMMPS development version. It +will have the date of the most recent patch release (see the file +src/version.h). But it will also include any new bug-fixes or +features added since the last patch release. They will be included in +the next patch release tarball. + +:link(git,https://github.com/lammps/lammps) + +:line + +If you download a current LAMMPS tarball, one way to stay current as +new patch tarballs are released, is to download a patch file which you +can apply to your local directory to update it for each new patch +release. (Or of course you could just download the newest tarball +periodically.) + +The patch files are posted on the "bug and feature page"_bug of the +website, along with a list of changed files and details about what is +in the new patch release. Instructions for applying a patch file are +on the "Install patch"_Install_patch.html doc page. diff --git a/doc/src/Install_windows.txt b/doc/src/Install_windows.txt new file mode 100644 index 0000000000..df87754c5f --- /dev/null +++ b/doc/src/Install_windows.txt @@ -0,0 +1,52 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download an executable for Windows :h3 + +Pre-compiled Windows installers which install LAMMPS executables on a +Windows system can be downloaded from this site: + +"http://rpm.lammps.org/windows.html"_http://rpm.lammps.org/windows.html + +Note that each installer package has a date in its name, which +corresponds to the LAMMPS version of the same date. Installers for +current and older versions of LAMMPS are available. 32-bit and 64-bit +installers are available, and each installer contains both a serial +and parallel executable. The installer site also explains how to +install the Windows MPI package (MPICH2 from Argonne National Labs), +needed to run in parallel. + +The LAMMPS binaries contain all optional packages included in the +source distribution except: KIM, REAX, KOKKOS, USER-INTEL, +and USER-QMMM. The serial version also does not include the MPIIO and +USER-LB packages. GPU support is provided for OpenCL. + +The installer site also has instructions on how to run LAMMPS under +Windows, once it is installed, in both serial and parallel. + +When you download the installer package, you run it on your Windows +machine. It will then prompt you with a dialog, where you can choose +the installation directory, unpack and copy several executables, +potential files, documentation pdfs, selected example files, etc. It +will then update a few system settings (e.g. PATH, LAMMPS_POTENTIALS) +and add an entry into the Start Menu (with references to the +documentation, LAMMPS homepage and more). From that menu, there is +also a link to an uninstaller that removes the files and undoes the +environment manipulations. + +Note that to update to a newer version of LAMMPS, you should typically +uninstall the version you currently have, download a new installer, +and go thru the install procedure described above. I.e. the same +procedure for installing/updating most Windows programs. You can +install multiple versions of LAMMPS (in different directories), but +only the executable for the last-installed package will be found +automatically, so this should only be done for debugging purposes. + +Thanks to Axel Kohlmeyer (Temple U, akohlmey at gmail.com) for setting +up this Windows capability. diff --git a/doc/src/Run.txt b/doc/src/Run.txt new file mode 100644 index 0000000000..68c3f1e295 --- /dev/null +++ b/doc/src/Run.txt @@ -0,0 +1,37 @@ +"Previous Section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc - "Next +Section"_Commands.html :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Run LAMMPS :h2 + +These pages explain how to run LAMMPS once you have "installed an +executable"_Install.html or "downloaded the source code"_Install.html +and "built an executable"_Build.html. The "Commands"_Commands.html +doc page describes how input scripts are structured and the commands +they can contain. + + + + + +"Basics of running LAMMPS"_Run_basics.html +"Command-line options"_Run_options.html +"Screen and logfile output"_Run_output.html +"Running LAMMPS on Windows"_Run_windows.html :all(b) + + diff --git a/doc/src/Run_basics.txt b/doc/src/Run_basics.txt new file mode 100644 index 0000000000..1d4b570f21 --- /dev/null +++ b/doc/src/Run_basics.txt @@ -0,0 +1,87 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Basics of running LAMMPS :h3 + +LAMMPS is run from the command line, reading commands from standard +input, which are typically listed in an input script: + +lmp_serial < in.file +lmp_serial -in in.file +~/lammps/src/lmp_serial < in.file +mpirun -np 4 lmp_mpi -in in.file +mpirun -np 8 ~/lammps/src/lmp_mpi -in in.file +mpirun -np 6 /usr/local/bin/lmp_mpi -in in.file :pre + +You normally run from the directory your input script is in. That is +also where output files are produced, unless you specify otherwise in +your input script. As in some of the examples above, the LAMMPS +executable can be elsewhere. + +NOTE: The redirection operator "<" can often be used with mpirun, but +some systems require the -in form. + +As LAMMPS runs it prints info to the screen and a logfile named +log.lammps. More info about output is given on the "Run +output"_Run_output.html doc page. + +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 the "Errors"_Errors.html doc page 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. + +:line + +LAMMPS can run the same 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. See the "Errors +common"_Errors_common.html doc page for discussion of this. + +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 define a smaller problem. + +If you run LAMMPS in parallel via mpirun, you should be aware of the +"processors"_processors.html command which controls how MPI tasks are +mapped to the simulation box, as well as mpirun options that control +how MPI tasks are assigned to physical cores of the node(s) of the +machine you are running on. These settings can improve performance, +though the defaults are often adequate. + +For example, it is often important to bind MPI tasks (processes) to +physical cores (processor affinity), so that the operating system does +not migrate them during a simulation. If this is not the default +behavior on your machine, the mpirun option "--bind-to core" (OpenMPI) +or "-bind-to core" (MPICH) can be used. + +If the LAMMPS command(s) you are using support multi-threading, you +can set the number of threads per MPI task via the environment +variable OMP_NUM_THREADS, before you launch LAMMPS: + +export OMP_NUM_THREADS=2 # bash +setenv OMP_NUM_THREADS 2 # csh or tcsh :pre + +This can also be done via the "package"_package.html command or via +the "-pk command-line switch"_Run_options.html which invokes the +package command. See the "package"_package.html command or +"Speed"_Speed.html doc pages for more details about which accerlarator +packages and which commands support multi-threading. + +:line + +You can experiment with running LAMMPS using any of the input scripts +provided in the examples or bench directory. Input scripts are named +in.* and sample outputs are named log.*.P where P is the number of +processors it was run on. + +Some of the examples or benchmarks require LAMMPS to be built with +optional packages. diff --git a/doc/src/Run_options.txt b/doc/src/Run_options.txt new file mode 100644 index 0000000000..b1c1e376da --- /dev/null +++ b/doc/src/Run_options.txt @@ -0,0 +1,470 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Command-line options :h3 + +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: + +"-e or -echo"_#echo +"-h or -help"_#help +"-i or -in"_#in +"-k or -kokkos"_#kokkos +"-l or -log"_#log +"-nc or -nocite"_#nocite +"-pk or -package"_#package +"-p or -partition"_#partition +"-pl or -plog"_#plot +"-ps or -pscreen"_#pscreen +"-r or -restart"_#restart +"-ro or -reorder"_#reorder +"-sc or -screen"_#screen +"-sf or -suffix"_#suffix +"-v or -var"_#var :ul + +For example, the lmp_mpi executable might be launched as follows: + +mpirun -np 16 lmp_mpi -v f tmp.out -l my.log -sc none -i in.alloy +mpirun -np 16 lmp_mpi -var f tmp.out -log my.log -screen none -in in.alloy :pre + +:line +:line + +[-echo style] :link(echo) + +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. + +:line + +[-help] :link(help) + +Print a brief help summary and a list of options compiled into this +executable for each LAMMPS style (atom_style, fix, compute, +pair_style, bond_style, etc). This can tell you if the command you +want to use was included via the appropriate package at compile time. +LAMMPS will print the info and immediately exit if this switch is +used. + +:line + +[-in file] :link(file) + +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 script from standard input, typically from a script +via I/O redirection; e.g. lmp_linux < in.run. I/O redirection should +also work in parallel, but if it does not (in the unlikely case that +an MPI implementation does not support it), then use the -in flag. +Note that this is a required switch when running LAMMPS in +multi-partition mode, since multiple processors cannot all read from +stdin. + +:line + +[-kokkos on/off keyword/value ...] :link(kokkos) + +Explicitly enable or disable KOKKOS support, as provided by the KOKKOS +package. Even if LAMMPS is built with this package, as described +above in "Section 2.3"_#start_3, this switch must be set to enable +running with the KOKKOS-enabled styles the package provides. If the +switch is not set (the default), LAMMPS will operate as if the KOKKOS +package were not installed; i.e. you can run standard LAMMPS or with +the GPU or USER-OMP packages, for testing or benchmarking purposes. + +Additional optional keyword/value pairs can be specified which +determine how Kokkos will use the underlying hardware on your +platform. These settings apply to each MPI task you launch via the +"mpirun" or "mpiexec" command. You may choose to run one or more MPI +tasks per physical node. Note that if you are running on a desktop +machine, you typically have one physical node. On a cluster or +supercomputer there may be dozens or 1000s of physical nodes. + +Either the full word or an abbreviation can be used for the keywords. +Note that the keywords do not use a leading minus sign. I.e. the +keyword is "t", not "-t". Also note that each of the keywords has a +default setting. Examples of when to use these options and what +settings to use on different platforms is given on the "Speed +kokkos"_Speed_kokkos.html doc page. + +d or device +g or gpus +t or threads +n or numa :ul + +device Nd :pre + +This option is only relevant if you built LAMMPS with CUDA=yes, you +have more than one GPU per node, and if you are running with only one +MPI task per node. The Nd setting is the ID of the GPU on the node to +run on. By default Nd = 0. If you have multiple GPUs per node, they +have consecutive IDs numbered as 0,1,2,etc. This setting allows you +to launch multiple independent jobs on the node, each with a single +MPI task per node, and assign each job to run on a different GPU. + +gpus Ng Ns :pre + +This option is only relevant if you built LAMMPS with CUDA=yes, you +have more than one GPU per node, and you are running with multiple MPI +tasks per node (up to one per GPU). The Ng setting is how many GPUs +you will use. The Ns setting is optional. If set, it is the ID of a +GPU to skip when assigning MPI tasks to GPUs. This may be useful if +your desktop system reserves one GPU to drive the screen and the rest +are intended for computational work like running LAMMPS. By default +Ng = 1 and Ns is not set. + +Depending on which flavor of MPI you are running, LAMMPS will look for +one of these 3 environment variables + +SLURM_LOCALID (various MPI variants compiled with SLURM support) +MV2_COMM_WORLD_LOCAL_RANK (Mvapich) +OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) :pre + +which are initialized by the "srun", "mpirun" or "mpiexec" commands. +The environment variable setting for each MPI rank is used to assign a +unique GPU ID to the MPI task. + +threads Nt :pre + +This option assigns Nt number of threads to each MPI task for +performing work when Kokkos is executing in OpenMP or pthreads mode. +The default is Nt = 1, which essentially runs in MPI-only mode. If +there are Np MPI tasks per physical node, you generally want Np*Nt = +the number of physical cores per node, to use your available hardware +optimally. This also sets the number of threads used by the host when +LAMMPS is compiled with CUDA=yes. + +numa Nm :pre + +This option is only relevant when using pthreads with hwloc support. +In this case Nm defines the number of NUMA regions (typically sockets) +on a node which will be utilized by a single MPI rank. By default Nm += 1. If this option is used the total number of worker-threads per +MPI rank is threads*numa. Currently it is always almost better to +assign at least one MPI rank per NUMA region, and leave numa set to +its default value of 1. This is because letting a single process span +multiple NUMA regions induces a significant amount of cross NUMA data +traffic which is slow. + +:line + +[-log file] :link(log) + +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. + +:line + +[-nocite] :link(nocite) + +Disable writing the log.cite file which is normally written to list +references for specific cite-able features used during a LAMMPS run. +See the "citation page"_http://lammps.sandia.gov/cite.html for more +details. + +:line + +[-package style args ....] :link(package) + +Invoke the "package"_package.html command with style and args. The +syntax is the same as if the command appeared at the top of the input +script. For example "-package gpu 2" or "-pk gpu 2" is the same as +"package gpu 2"_package.html in the input script. The possible styles +and args are documented on the "package"_package.html doc page. This +switch can be used multiple times, e.g. to set options for the +USER-INTEL and USER-OMP packages which can be used together. + +Along with the "-suffix" command-line switch, this is a convenient +mechanism for invoking accelerator packages and their options without +having to edit an input script. + +:line + +[-partition 8x2 4 5 ...] :link(partition) + +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 be useful for running +"multi-replica simulations"_Howto_replica.html, 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 simulations from one input script, using +multiple partitions, see the "Howto multiple"_Howto_multiple.html doc +page. World- and universe-style "variables"_variable.html are useful +in this context. + +:line + +[-plog file] :link(plog) + +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. + +:line + +[-pscreen file] :link(pscreen) + +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. + +:line + +[-restart restartfile {remap} datafile keyword value ...] :link(restart) + +Convert the restart file into a data file and immediately exit. This +is the same operation as if the following 2-line input script were +run: + +read_restart restartfile {remap} +write_data datafile keyword value ... :pre + +Note that the specified restartfile and datafile can have wild-card +characters ("*",%") as described by the +"read_restart"_read_restart.html and "write_data"_write_data.html +commands. But a filename such as file.* will need to be enclosed in +quotes to avoid shell expansion of the "*" character. + +Note that following restartfile, the optional flag {remap} can be +used. This has the same effect as adding it to the +"read_restart"_read_restart.html command, as explained on its doc +page. This is only useful if the reading of the restart file triggers +an error that atoms have been lost. In that case, use of the remap +flag should allow the data file to still be produced. + +Also note that following datafile, the same optional keyword/value +pairs can be listed as used by the "write_data"_write_data.html +command. + +:line + +[-reorder] :link(reorder) + +This option has 2 forms: + +-reorder nth N +-reorder custom filename :pre + +Reorder the processors in the MPI communicator used to instantiate +LAMMPS, in one of several ways. The original MPI communicator ranks +all P processors from 0 to P-1. The mapping of these ranks to +physical processors is done by MPI before LAMMPS begins. It may be +useful in some cases to alter the rank order. E.g. to insure that +cores within each node are ranked in a desired order. Or when using +the "run_style verlet/split"_run_style.html command with 2 partitions +to insure that a specific Kspace processor (in the 2nd partition) is +matched up with a specific set of processors in the 1st partition. +See the "Speed tips"_Speed_tips.html doc page for more details. + +If the keyword {nth} is used with a setting {N}, then it means every +Nth processor will be moved to the end of the ranking. This is useful +when using the "run_style verlet/split"_run_style.html command with 2 +partitions via the -partition command-line switch. The first set of +processors will be in the first partition, the 2nd set in the 2nd +partition. The -reorder command-line switch can alter this so that +the 1st N procs in the 1st partition and one proc in the 2nd partition +will be ordered consecutively, e.g. as the cores on one physical node. +This can boost performance. For example, if you use "-reorder nth 4" +and "-partition 9 3" and you are running on 12 processors, the +processors will be reordered from + +0 1 2 3 4 5 6 7 8 9 10 11 :pre + +to + +0 1 2 4 5 6 8 9 10 3 7 11 :pre + +so that the processors in each partition will be + +0 1 2 4 5 6 8 9 10 +3 7 11 :pre + +See the "processors" command for how to insure processors from each +partition could then be grouped optimally for quad-core nodes. + +If the keyword is {custom}, then a file that specifies a permutation +of the processor ranks is also specified. The format of the reorder +file is as follows. Any number of initial blank or comment lines +(starting with a "#" character) can be present. These should be +followed by P lines of the form: + +I J :pre + +where P is the number of processors LAMMPS was launched with. Note +that if running in multi-partition mode (see the -partition switch +above) P is the total number of processors in all partitions. The I +and J values describe a permutation of the P processors. Every I and +J should be values from 0 to P-1 inclusive. In the set of P I values, +every proc ID should appear exactly once. Ditto for the set of P J +values. A single I,J pairing means that the physical processor with +rank I in the original MPI communicator will have rank J in the +reordered communicator. + +Note that rank ordering can also be specified by many MPI +implementations, either by environment variables that specify how to +order physical processors, or by config files that specify what +physical processors to assign to each MPI rank. The -reorder switch +simply gives you a portable way to do this without relying on MPI +itself. See the "processors out"_processors.html command for how +to output info on the final assignment of physical processors to +the LAMMPS simulation domain. + +:line + +[-screen file] :link(screen) + +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. + +:line + +[-suffix style args] :link(suffix) + +Use variants of various styles if they exist. The specified style can +be {cuda}, {gpu}, {intel}, {kk}, {omp}, {opt}, or {hybrid}. These +refer to optional packages that LAMMPS can be built with, as described +above in "Section 2.3"_#start_3. The "gpu" style corresponds to the +GPU package, the "intel" style to the USER-INTEL package, the "kk" +style to the KOKKOS package, the "opt" style to the OPT package, and +the "omp" style to the USER-OMP package. The hybrid style is the only +style that accepts arguments. It allows for two packages to be +specified. The first package specified is the default and will be used +if it is available. If no style is available for the first package, +the style for the second package will be used if available. For +example, "-suffix hybrid intel omp" will use styles from the +USER-INTEL package if they are installed and available, but styles for +the USER-OMP package otherwise. + +Along with the "-package" command-line switch, this is a convenient +mechanism for invoking accelerator packages and their options without +having to edit an input script. + +As an example, all of the packages provide a "pair_style +lj/cut"_pair_lj.html variant, with style names lj/cut/gpu, +lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style +can be specified explicitly in your input script, e.g. pair_style +lj/cut/gpu. If the -suffix switch is used the specified suffix +(gpu,intel,kk,omp,opt) 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 1" were used at +the top of your input script. These settings can be changed by using +the "-package gpu" command-line switch or the "package +gpu"_package.html command in your script. + +For the USER-INTEL package, using this command-line switch also +invokes the default USER-INTEL settings, as if the command "package +intel 1" were used at the top of your input script. These settings +can be changed by using the "-package intel" command-line switch or +the "package intel"_package.html command in your script. If the +USER-OMP package is also installed, the hybrid style with "intel omp" +arguments can be used to make the omp suffix a second choice, if a +requested style is not available in the USER-INTEL package. It will +also invoke the default USER-OMP settings, as if the command "package +omp 0" were used at the top of your input script. These settings can +be changed by using the "-package omp" command-line switch or the +"package omp"_package.html command in your script. + +For the KOKKOS package, using this command-line switch also invokes +the default KOKKOS settings, as if the command "package kokkos" were +used at the top of your input script. These settings can be changed +by using the "-package kokkos" command-line switch or the "package +kokkos"_package.html command in your script. + +For the OMP package, using this command-line switch also invokes the +default OMP settings, as if the command "package omp 0" were used at +the top of your input script. These settings can be changed by using +the "-package omp" command-line switch or the "package +omp"_package.html command in your script. + +The "suffix"_suffix.html command can also be used within an input +script to set a suffix, or to turn off or back on any suffix setting +made via the command line. + +:line + +[-var name value1 value2 ...] :link(var) + +Specify a variable that will be defined for substitution purposes when +the input script is read. This switch can be used multiple times to +define multiple variables. "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 the "Commands +parse"_Commands_parse.html page 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 them start with a "-", e.g. a +negative numeric value. It is OK if the first value1 starts with a +"-", since it is automatically skipped. diff --git a/doc/src/Run_output.txt b/doc/src/Run_output.txt new file mode 100644 index 0000000000..a534ae7c7b --- /dev/null +++ b/doc/src/Run_output.txt @@ -0,0 +1,176 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Screen and logfile output :h3 + +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 info about the run it is about to +perform, including 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 also +appends statistics about the CPU time and storage requirements for the +simulation. An example set of statistics is shown here: + +Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms :pre + +Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s +97.0% CPU use with 4 MPI tasks x no OpenMP threads :pre + +MPI task timings breakdown: +Section | min time | avg time | max time |%varavg| %total +--------------------------------------------------------------- +Pair | 1.9808 | 2.0134 | 2.0318 | 1.4 | 71.60 +Bond | 0.0021894 | 0.0060319 | 0.010058 | 4.7 | 0.21 +Kspace | 0.3207 | 0.3366 | 0.36616 | 3.1 | 11.97 +Neigh | 0.28411 | 0.28464 | 0.28516 | 0.1 | 10.12 +Comm | 0.075732 | 0.077018 | 0.07883 | 0.4 | 2.74 +Output | 0.00030518 | 0.00042665 | 0.00078821 | 1.0 | 0.02 +Modify | 0.086606 | 0.086631 | 0.086668 | 0.0 | 3.08 +Other | | 0.007178 | | | 0.26 :pre + +Nlocal: 501 ave 508 max 490 min +Histogram: 1 0 0 0 0 0 1 1 0 1 +Nghost: 6586.25 ave 6628 max 6548 min +Histogram: 1 0 1 0 0 0 1 0 0 1 +Neighs: 177007 ave 180562 max 170212 min +Histogram: 1 0 0 0 0 0 0 1 1 1 :pre + +Total # of neighbors = 708028 +Ave neighs/atom = 353.307 +Ave special neighs/atom = 2.34032 +Neighbor list builds = 26 +Dangerous builds = 0 :pre + +:line + +The first section provides a global loop timing summary. The {loop +time} is the total wall-clock time for the simulation to run. The +{Performance} line is provided for convenience to help predict how +long it will take to run a desired physical simulation. The {CPU use} +line provides the CPU utilization per MPI task; it should be close to +100% times the number of OpenMP threads (or 1 of not using OpenMP). +Lower numbers correspond to delays due to file I/O or insufficient +thread utilization. + +:line + +The {MPI task} section gives the breakdown of the CPU run time (in +seconds) into major categories: + +{Pair} = non-bonded force computations +{Bond} = bonded interactions: bonds, angles, dihedrals, impropers +{Kspace} = long-range interactions: Ewald, PPPM, MSM +{Neigh} = neighbor list construction +{Comm} = inter-processor communication of atoms and their properties +{Output} = output of thermodynamic info and dump files +{Modify} = fixes and computes invoked by fixes +{Other} = all the remaining time :ul + +For each category, there is a breakdown of the least, average and most +amount of wall time any processor spent on this category of +computation. The "%varavg" is the percentage by which the max or min +varies from the average. This is an indication of load imbalance. A +percentage close to 0 is perfect load balance. A large percentage is +imbalance. The final "%total" column is the percentage of the total +loop time is spent in this category. + +When using the "timer full"_timer.html setting, an additional column +is added that also prints the CPU utilization in percent. In addition, +when using {timer full} and the "package omp"_package.html command are +active, a similar timing summary of time spent in threaded regions to +monitor thread utilization and load balance is provided. A new {Thread +timings} section is also added, which lists the time spent in reducing +the per-thread data elements to the storage for non-threaded +computation. These thread timings are measured for the first MPI rank +only and and thus, because the breakdown for MPI tasks can change from +MPI rank to MPI rank, this breakdown can be very different for +individual ranks. Here is an example output for this section: + +Thread timings breakdown (MPI rank 0): +Total threaded time 0.6846 / 90.6% +Section | min time | avg time | max time |%varavg| %total +--------------------------------------------------------------- +Pair | 0.5127 | 0.5147 | 0.5167 | 0.3 | 75.18 +Bond | 0.0043139 | 0.0046779 | 0.0050418 | 0.5 | 0.68 +Kspace | 0.070572 | 0.074541 | 0.07851 | 1.5 | 10.89 +Neigh | 0.084778 | 0.086969 | 0.089161 | 0.7 | 12.70 +Reduce | 0.0036485 | 0.003737 | 0.0038254 | 0.1 | 0.55 :pre + +:line + +The third section above 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. + +:line + +The last section gives aggregate statistics (across all processors) +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 is tallied, as is 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. + +:line + +If an energy minimization was performed via the +"minimize"_minimize.html command, additional information is printed, +e.g. + +Minimization stats: + Stopping criterion = linesearch alpha is zero + Energy initial, next-to-last, final = + -6372.3765206 -8328.46998942 -8328.46998942 + Force two-norm initial, final = 1059.36 5.36874 + Force max component initial, final = 58.6026 1.46872 + Final line search alpha, max atom move = 2.7842e-10 4.0892e-10 + Iterations, force evaluations = 701 1516 :pre + +The first line prints the criterion that determined minimization was +converged. The next 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 3N-component force vector; the largest +component (x, y, or z) of force (infinity-norm) is also given. Then +information is provided about the line search and 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. See the +"minimize"_minimize.html doc page for more details. + +:line + +If a "kspace_style"_kspace_style.html long-range Coulombics solver +that performs FFTs was used 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 is the time spent doing 3d FFTs (several 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. diff --git a/doc/src/Run_windows.txt b/doc/src/Run_windows.txt new file mode 100644 index 0000000000..1151a4a2bb --- /dev/null +++ b/doc/src/Run_windows.txt @@ -0,0 +1,73 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Running LAMMPS on Windows :h3 + +To run a serial (non-MPI) executable, follow these steps: + +Get a command prompt by going to Start->Run... , +then typing "cmd". :ulb,l + +Move to the directory where you have your input script, +(e.g. by typing: cd "Documents"). :l + +At the command prompt, type "lmp_serial -in in.file", where +in.file is the name of your LAMMPS input script. :l,ule + +Note that the serial executable includes support for multi-threading +parallelization from the styles in the USER-OMP packages. To run with +4 threads, you can type this: + +lmp_serial -in in.lj -pk omp 4 -sf omp :pre + +:line + +For the MPI executable, which allows you to run LAMMPS under Windows +in parallel, follow these steps. + +Download and install a compatible MPI library binary package: + +for 32-bit Windows: "mpich2-1.4.1p1-win-ia32.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-ia32.msi +for 64-bit Windows: "mpich2-1.4.1p1-win-x86-64.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-x86-64.msi :ul + +The LAMMPS Windows installer packages will automatically adjust your +path for the default location of this MPI package. After the +installation of the MPICH2 software, it needs to be integrated into +the system. For this you need to start a Command Prompt in +{Administrator Mode} (right click on the icon and select it). Change +into the MPICH2 installation directory, then into the subdirectory +[bin] and execute [smpd.exe -install]. Exit the command window. + +Get a new, regular command prompt by going to Start->Run... , +then typing "cmd". :ulb,l + +Move to the directory where you have your input file +(e.g. by typing: cd "Documents"). :l,ule + +Then type something like this: + +mpiexec -localonly 4 lmp_mpi -in in.file +mpiexec -np 4 lmp_mpi -in in.file :pre + +where in.file is the name of your LAMMPS input script. For the latter +case, you may be prompted to enter your password. + +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. + +The parallel executable can also run on a single processor by typing +something like this: + +lmp_mpi -in in.lj :pre + +Note that the parallel executable also includes OpenMP +multi-threading, which can be combined with MPI using something like: + +mpiexec -localonly 2 lmp_mpi -in in.lj -pk omp 2 -sf omp :pre diff --git a/doc/src/Section_start.txt b/doc/src/Section_start.txt deleted file mode 100644 index 19a798d5df..0000000000 --- a/doc/src/Section_start.txt +++ /dev/null @@ -1,1823 +0,0 @@ -"Previous Section"_Intro.html - "LAMMPS WWW Site"_lws - -"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next -Section"_Commands.html :c - -:link(lws,http://lammps.sandia.gov) -:link(ld,Manual.html) -:link(lc,Commands_all.html) - -:line - -2. Getting Started :h2 - -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 - -2.1 What's in the LAMMPS distribution :h3,link(start_1) - -When you download a LAMMPS tarball you will need to unzip and untar -the downloaded file with the following commands, after placing the -tarball in an appropriate directory. - -tar -xzvf lammps*.tar.gz :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 -doc: documentation -examples: simple test problems -potentials: embedded atom method (EAM) potential files -src: source files -tools: pre- and post-processing tools :tb(s=:) - -Note that the "download page"_download also has links to download -pre-build Windows installers, as well as pre-built packages for -several widely used Linux distributions. It also has instructions -for how to download/install LAMMPS for Macs (via Homebrew), and to -download and update LAMMPS from SVN and Git repositories, which gives -you access to the up-to-date sources that are used by the LAMMPS -core developers. - -:link(download,http://lammps.sandia.gov/download.html) - -The Windows and Linux packages for serial or parallel include -only selected 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 an executable with -non-included packages or that is more current, then you'll need to -build LAMMPS yourself, as discussed in the next section. - -Skip to the "Running LAMMPS"_#start_6 sections for info on how to -launch a LAMMPS Windows executable on a Windows box. - -:line - -2.2 Making LAMMPS :h3,link(start_2) - -This section has the following sub-sections: - -2.2.1 "Read this first"_#start_2_1 -2.2.1 "Steps to build a LAMMPS executable"_#start_2_2 -2.2.3 "Common errors that can occur when making LAMMPS"_#start_2_3 -2.2.4 "Additional build tips"_#start_2_4 -2.2.5 "Building for a Mac"_#start_2_5 -2.2.6 "Building for Windows"_#start_2_6 :all(b) - -:line - -Read this first :h4,link(start_2_1) - -If you want to avoid building LAMMPS yourself, read the preceding -section about options available for downloading and installing -executables. Details are discussed on the "download"_download page. - -Building LAMMPS can be simple or not-so-simple. If all you need are -the default packages installed in LAMMPS, and MPI is already installed -on your machine, or you just want to run LAMMPS in serial, then you -can typically use the Makefile.mpi or Makefile.serial files in -src/MAKE by typing one of these lines (from the src dir): - -make mpi -make serial :pre - -Note that on a facility supercomputer, there are often "modules" -loaded in your environment that provide the compilers and MPI you -should use. In this case, the "mpicxx" compile/link command in -Makefile.mpi should simply work by accessing those modules. - -It may be the case that one of the other Makefile.machine files in the -src/MAKE sub-directories is a better match to your system (type "make" -to see a list), you can use it as-is by typing (for example): - -make stampede :pre - -If any of these builds (with an existing Makefile.machine) works on -your system, then you're done! - -If you need to install an optional package with a LAMMPS command you -want to use, and the package does not depend on an extra library, you -can simply type - -make name :pre - -before invoking (or re-invoking) the above steps. "Name" is the -lower-case name of the package, e.g. replica or user-misc. - -If you want to do one of the following: - -use a LAMMPS command that requires an extra library (e.g. "dump -image"_dump_image.html) build with a package that requires an extra -library build with an accelerator package that requires special -compiler/linker settings run on a machine that has its own compilers, -settings, or libraries :ul - -then building LAMMPS is more complicated. You may need to find where -extra libraries exist on your machine or install them if they don't. -You may need to build extra libraries that are included in the LAMMPS -distribution, before building LAMMPS itself. You may need to edit a -Makefile.machine file to make it compatible with your system. - -Please read the following sections 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 compilation, linking, and run problems users experience 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. - -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 the issue to the "LAMMPS mail -list"_http://lammps.sandia.gov/mail.html. - -If you succeed in building LAMMPS on a new kind of machine, for which -there isn't a similar machine Makefile included in the -src/MAKE/MACHINES directory, then send it to the developers and we can -include it in the LAMMPS distribution. - -:line - -Steps to build a LAMMPS executable :h4,link(start_2_2) - -Step 0 :h5 - -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 systems and machines. See the -src/MAKE/README file for a quick overview of what files are available -and what sub-directories they are in. - -The src/MAKE dir has a few files that should work as-is on many -platforms. The src/MAKE/OPTIONS dir has more that invoke additional -compiler, MPI, and other setting options commonly used by LAMMPS, to -illustrate their syntax. The src/MAKE/MACHINES dir has many more that -have been tweaked or optimized for specific machines. These files are -all good starting points if you find you need to change them for your -machine. Put any file you edit into the src/MAKE/MINE directory and -it will be never be touched by any LAMMPS updates. - ->From within the src directory, type "make" or "gmake". You should see -a list of available choices from src/MAKE and all of its -sub-directories. If one of those has the options you want or is the -machine you want, you can type a command like: - -make mpi :pre -or - -make serial :pre -or - -gmake mac :pre - -Note that the corresponding Makefile.machine can exist in src/MAKE or -any of its sub-directories. If a file with the same name appears in -multiple places (not a good idea), the order they are used is as -follows: src/MAKE/MINE, src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. -This gives preference to a file you have created/edited and put in -src/MAKE/MINE. - -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_mpi] or [lmp_serial] -or [lmp_mac] is produced, then you're done; it's your lucky day. - -Note that by default only a few of LAMMPS optional packages are -installed. To build LAMMPS with optional packages, see "this -section"_#start_3 below. - -Step 1 :h5 - -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 Makefile.* in src/MAKE or one of its sub-directories 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. When it works, put the edited -file in src/MAKE/MINE and it will not be altered by any future LAMMPS -updates. - -Step 2 :h5 - -Change the first line of 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 :h5 - -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 mpicxx 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 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. You should -not need to do this if you use mpicxx. - -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++ and Intel icc 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 :h5 - -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 recognized are: - --DLAMMPS_GZIP --DLAMMPS_JPEG --DLAMMPS_PNG --DLAMMPS_FFMPEG --DLAMMPS_MEMALIGN --DLAMMPS_SMALLBIG --DLAMMPS_BIGBIG --DLAMMPS_SMALLSMALL --DLAMMPS_LONGLONG_TO_LONG --DLAMMPS_EXCEPTIONS --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 machine supports -the "popen()" function in the standard runtime library and that a gzip -executable can be found by LAMMPS during a run. - -NOTE: on some clusters with high-speed networks, using the fork() -library calls (required by popen()) can interfere with the fast -communication library and lead to simulations using compressed output -or input to hang or crash. For selected operations, compressed file -I/O is also available using a compression library instead, which are -provided in the COMPRESS package. From more details about compiling -LAMMPS with packages, please see below. - -If you use -DLAMMPS_JPEG, the "dump image"_dump_image.html command -will be able to write out JPEG image files. For JPEG files, you must -also link LAMMPS with a JPEG library, as described below. If you use --DLAMMPS_PNG, the "dump image"_dump.html command will be able to write -out PNG image files. For PNG files, you must also link LAMMPS with a -PNG library, as described below. If neither of those two defines are -used, LAMMPS will only be able to write out uncompressed PPM image -files. - -If you use -DLAMMPS_FFMPEG, the "dump movie"_dump_image.html command -will be available to support on-the-fly generation of rendered movies -the need to store intermediate image files. It requires that your -machines supports the "popen" function in the standard runtime library -and that an FFmpeg executable can be found by LAMMPS during the run. - -NOTE: Similar to the note above, this option can conflict with -high-speed networks, because it uses popen(). - -Using -DLAMMPS_MEMALIGN= 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. - -Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG, --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 -(which store bond topology info) with more than 2 billion atoms, or to -track the image flags of moving atoms that wrap around a periodic box -more than 512 times. Normally, the only reason to use SMALLSMALL is -if your machine does not support 64-bit integers, though you can use -SMALLSMALL setting if you are running in serial or on a desktop -machine or small cluster where you will never run large systems or for -long time (more than 2 billion atoms, more than 2 billion timesteps). -See the "Additional build tips"_#start_2_4 section below for more -details on these settings. - -Note that the USER-ATC package is not currently compatible with --DLAMMPS_BIGBIG. Also the GPU package requires the lib/gpu library to -be compiled with the same setting, or the link will fail. - -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. - -The -DLAMMPS_EXCEPTIONS setting can be used to activate alternative -versions of error handling inside of LAMMPS. This is useful when -external codes drive LAMMPS as a library. Using this option, LAMMPS -errors do not kill the caller. Instead, the call stack is unwound and -control returns to the caller. The library interface provides the -lammps_has_error() and lammps_get_last_error_message() functions to -detect and find out more about a LAMMPS error. - -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 :h5 - -The 3 MPI variables are used to specify an MPI library to build LAMMPS -with. Note that you do not need to set these if you use the MPI -compiler mpicxx for your CC and LINK setting in the section above. -The MPI wrapper knows where to find the needed files. - -If you want LAMMPS to run in parallel, you must have an MPI library -installed on your platform. If MPI is installed on your system in the -usual place (under /usr/local), you also may not need to specify these -3 variables, assuming /usr/local is in your path. On some large -parallel machines which use "modules" for their compile/link -environments, you may simply need to include the correct module in -your build environment, before building LAMMPS. Or the parallel -machine may have a vendor-provided MPI which the compiler has no -trouble finding. - -Failing this, these 3 variables can be used to 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 src/MAKE/Makefile.serial -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. Note that if you are building with src/MAKE/Makefile.serial, -e.g. by typing "make serial", then the STUBS library is built for you. - -To build the STUBS library from the src directory, type "make -mpi-stubs", or from the src/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. - -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. - -Step 6 :h5 - -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 common 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 or FFTW3. FFTW2 and NONE are supported as legacy options. -Selecting -DFFT_FFTW will use the FFTW3 library and -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 environments, 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. See the src/MAKE/OPTIONS/Makefile.fftw file for an -example of how to specify these variables to use the FFTW3 library. - -FFTW is fast, portable library that should also work on any platform -and typically be faster than KISS FFT. 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; -make install. The install command typically requires root privileges -(e.g. invoke it via sudo), unless you specify a local directory with -the "--prefix" option of configure. Type "./configure --help" to see -various options. - -If you wish to have FFTW support for single-precision FFTs (see below -about -DFFT_SINGLE) in addition to the default double-precision FFTs, -you will need to build FFTW a second time for single-precision. For -FFTW3, do this via: - -make clean -./configure --enable-single; make; make install :pre - -which should produce the additional library libfftw3f.a. - -For FFTW2, do this: - -make clean -./configure --enable-float --enable-type-prefix; make; make install :pre - -which should produce the additional library libsfftw.a and additional -include file sfttw.a. Note that on some platforms FFTW2 has been -pre-installed for both single- and double-precision, and may already -have these files as well as libdfftw.a and dfftw.h for double -precision. - -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 -calculations, 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. - -When using -DFFT_SINGLE with FFTW3 or FFTW2, you need to build FFTW -with support for single-precision, as explained above. For FFTW3 you -also need to include -lfftw3f with the FFT_LIB setting, in addition to --lfftw3. For FFTW2, you also need to specify -DFFT_SIZE with the -FFT_INC setting and -lsfftw with the FFT_LIB setting (in place of --lfftw). Similarly, if FFTW2 has been pre-installed with an explicit -double-precision library (libdfftw.a and not the default libfftw.a), -then you can specify -DFFT_SIZE (and not -DFFT_SINGLE), and specify --ldfftw to use double-precision FFTs. - -Step 7 :h5 - -The 3 JPG variables allow you to specify a JPEG and/or PNG library -which LAMMPS uses when writing out JPEG or PNG files via the "dump -image"_dump_image.html command. These can be left blank if you do not -use the -DLAMMPS_JPEG or -DLAMMPS_PNG switches discussed above in Step -4, since in that case JPEG/PNG output will be disabled. - -A standard JPEG library usually goes by the name libjpeg.a or -libjpeg.so 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. - -A standard PNG library usually goes by the name libpng.a or libpng.so -and has an associated header file png.h. Whichever PNG 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 :h5 - -Note that by default only a few of LAMMPS optional packages are -installed. To build LAMMPS with optional packages, see "this -section"_#start_3 below, before proceeding to Step 9. - -Step 9 :h5 - -That's it. Once you have a correct Makefile.foo, and you have -pre-built any other needed libraries (e.g. MPI, FFT, etc) all you need -to do from the src directory is type something like this: - -make foo -make -j N foo -gmake foo -gmake -j N foo :pre - -The -j or -j N switches perform a parallel build which can be much -faster, depending on how many cores your compilation machine has. N -is the number of cores the build runs on. - -You should get the executable lmp_foo when the build is complete. - -:line - -Errors that can occur when making LAMMPS :h4 :link(start_2_3) - -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 -settings and 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 :h4,link(start_2_4) - -Building LAMMPS for multiple platforms. :h5 - -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. - -Cleaning up. :h5 - -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. - -Changing the LAMMPS size limits via -DLAMMPS_SMALLBIG or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL :h5 - -As explained above, any of these 3 settings can be specified on the -LMP_INC line in your low-level src/MAKE/Makefile.foo. - -The default is -DLAMMPS_SMALLBIG which allows for systems with up to -2^63 atoms and 2^63 timesteps (about 9e18). The atom limit is for -atomic systems which do not store bond topology info and thus do not -require atom IDs. If you use atom IDs for atomic systems (which is -the default) or if you use a molecular model, which stores bond -topology info and thus requires atom IDs, the limit is 2^31 atoms -(about 2 billion). This is because the IDs are stored in 32-bit -integers. - -Likewise, with this setting, the 3 image flags for each atom (see the -"dump"_dump.html doc page for a discussion) are stored in a 32-bit -integer, which means the atoms can only wrap around a periodic box (in -each dimension) at most 512 times. If atoms move through the periodic -box more than this many times, 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 "compute -msd"_compute_msd.html command, to be faulty. - -To allow for larger atomic systems with atom IDs or larger molecular -systems or larger image flags, compile with -DLAMMPS_BIGBIG. This -stores atom IDs and image flags in 64-bit integers. This enables -atomic or molecular systems with atom IDS of up to 2^63 atoms (about -9e18). And image flags will not "roll over" until they reach 2^20 = -1048576. - -If your system does not support 8-byte integers, you will need to -compile with the -DLAMMPS_SMALLSMALL setting. This will restrict the -total number of atoms (for atomic or molecular systems) and timesteps -to 2^31 (about 2 billion). Image flags will roll over at 2^9 = 512. - -Note that in src/lmptype.h there are definitions of all these data -types as well as the MPI data types associated with them. The MPI -types need to be consistent with the associated C data types, or else -LAMMPS will generate a run-time error. As far as we know, the -settings defined in src/lmptype.h are portable and work on every -current system. - -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 limitation 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 :h4,link(start_2_5) - -OS X is a derivative of BSD Unix, so it should just work. See the -src/MAKE/MACHINES/Makefile.mac and Makefile.mac_mpi files. - -:line - -Building for Windows :h4,link(start_2_6) - -If you want to build a Windows version of LAMMPS, you can build it -yourself, but it may require some effort. LAMMPS expects a Unix-like -build environment for the default build procedure. This can be done -using either Cygwin or MinGW; the latter also exists as a ready-to-use -Linux-to-Windows cross-compiler in several Linux distributions. In -these cases, you can do the installation after installing several -unix-style commands like make, grep, sed and bash with some shell -utilities. - -For Cygwin and the MinGW cross-compilers, suitable makefiles are -provided in src/MAKE/MACHINES. When using other compilers, like -Visual C++ or Intel compilers for Windows, you may have to implement -your own build system. Due to differences between the Windows OS -and Windows system libraries to Unix-like environments like Linux -or MacOS, when compiling for Windows a few adjustments may be needed: - -Do [not] set the -DLAMMPS_MEMALIGN define (see LMP_INC makefile variable) -Add -lwsock32 -lpsapi to the linker flags (see LIB makefile variable) -Try adding -static-libgcc or -static or both to the linker flags when your LAMMPS executable complains about missing .dll files :ul - -Since none of the current LAMMPS core developers has significant -experience building executables on Windows, we are happy to distribute -contributed instructions and modifications to improve the situation, -but we cannot provide support for those. - -With the so-called "Anniversary Update" to Windows 10, there is a -Ubuntu Linux subsystem available for Windows, that can be installed -and then used to compile/install LAMMPS as if you are running on a -Ubuntu Linux system instead of Windows. - -As an alternative, you can download pre-compiled installer packages from -"packages.lammps.org/windows.html"_http://packages.lammps.org/windows.html. -These executables are built with most optional packages included and the -download includes documentation, potential files, some tools and many -examples, but no source code. - -:line - -2.3 Making LAMMPS with optional packages :h3,link(start_3) - -This section has the following sub-sections: - -2.3.1 "Package basics"_#start_3_1 -2.3.2 "Including/excluding packages"_#start_3_2 -2.3.3 "Packages that require extra libraries"_#start_3_3 :all(b) - -:line - -Package basics: :h4,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. - -The "Packages"_Packages.html doc pages has details about all the -packages, which come in two flavors: [standard] and [user] -packages. It also has specific instructions for building LAMMPS with -any package which requires an extra library. General instructions are -below. - -You can see the list of all packages by typing "make package" from -within the src directory of the LAMMPS distribution. It will also -list various make commands that can be used to manage packages. - -If you use a command in a LAMMPS input script that is part of a -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 specifies if it is part of a package. You can -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, and immediately exit. - -:line - -Including/excluding packages :h4,link(start_3_2) - -To use (or not use) a package you must install it (or un-install it) -before building LAMMPS. From the src directory, this is as simple as: - -make yes-colloid -make mpi :pre - -or - -make no-user-omp -make mpi :pre - -NOTE: You should NOT install/un-install packages and build LAMMPS in a -single make command using multiple targets, e.g. make yes-colloid mpi. -This is because the make procedure creates a list of source files that -will be out-of-date for the build if the package configuration changes -within the same command. - -Any package can be installed or not in a LAMMPS build, independent of -all other packages. However, some packages include files derived from -files in other packages. 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. - -NOTE: The one exception is that we do not recommend building with both -the KOKKOS package installed and any of the other acceleration -packages (GPU, OPT, USER-INTEL, USER-OMP) also installed. This is -because of how Kokkos sometimes builds using a wrapper compiler which -can make it difficult to invoke all the compile/link flags correctly -for both Kokkos and non-Kokkos files. - -If you will never run simulations that use the features in a -particular packages, there is no reason to include it in your build. -For some packages, this will keep you from having to build extra -libraries, and will also produce a smaller executable which may run a -bit faster. - -When you download a LAMMPS tarball, three packages are pre-installed -in the src directory -- KSPACE, MANYBODY, MOLECULE -- because they are -so commonly used. When you download LAMMPS source files from the SVN -or Git repositories, no packages are pre-installed. - -Packages are installed or un-installed by typing - -make yes-name -make no-name :pre - -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 any of these commands: - -make yes-all | install all packages -make no-all | un-install all packages -make yes-standard or make yes-std | install standard packages -make no-standard or make no-std| un-install standard packages -make yes-user | install user packages -make no-user | un-install user packages -make yes-lib | install packages that require extra libraries -make no-lib | un-install packages that require extra libraries -make yes-ext | install packages that require external libraries -make no-ext | un-install packages that require external libraries :tb(s=|) - -which install/un-install various sets of packages. Typing "make -package" will list all the these commands. - -NOTE: Installing or un-installing 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 included or excluded when LAMMPS is built. -After you have installed or un-installed a package, you must re-build -LAMMPS for the action to take effect. - -The following make commands help manage 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 web site. - -Typing "make package-status" or "make ps" will show which packages are -currently installed. For those that are installed, it will list any -files that are different in the src directory and package -sub-directory. - -Typing "make package-installed" or "make pi" will list which packages are -currently installed, without listing the status of packages that are not -installed. - -Typing "make package-update" or "make pu" will overwrite src files -with files from the package sub-directories if the package is -installed. It should be used after a patch has been applied, 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-diff" lists all differences between these files. - -Again, just type "make package" to see all of the package-related make -options. - -:line - -Packages that require extra libraries :h4,link(start_3_3) - -A few of the standard and user packages require extra libraries. See -the "Packages"_Packages.html doc pages for two tables of packages -which indicate which ones require libraries. For each such package, -the Section 4 doc page gives details on how to build the extra -library, including how to download it if necessary. The basic ideas -are summarized here. - -[System libraries:] - -Packages in the standard and user tables of the -"Packages"_Packages.html doc pages with a "sys" in the last column -link to system libraries that typically already exist on your machine. -E.g. the python package links to a system Python library. If your -machine does not have the required library, you will have to download -and install it on your machine, in either the system or user space. - -[Internal libraries:] - -Packages in the standard and user tables of the -"Packages"_Packages.html doc pages with an "int" in the last column -link to internal libraries whose source code is included with LAMMPS, -in the lib/name directory where name is the package name. You must -first build the library in that directory before building LAMMPS with -that package installed. E.g. the gpu package links to a library you -build in the lib/gpu dir. You can often do the build in one step by -typing "make lib-name args=..." from the src dir, with appropriate -arguments. You can leave off the args to see a help message. See the -"Packages details"_Packages_details.html doc page for details for each -package. - -[External libraries:] - -Packages in the standard and user tables of the -"Packages"_Packages.html doc pages with an "ext" in the last column -link to external libraries whose source code is not included with -LAMMPS. You must first download and install the library before -building LAMMPS with that package installed. E.g. the voronoi package -links to the freely available "Voro++ library"_voro_home2. You can -often do the download/build in one step by typing "make lib-name -args=..." from the src dir, with appropriate arguments. You can leave -off the args to see a help message. See the "Packages -details"_Packages_details.html doc page for details for each package. - -:link(voro_home2,http://math.lbl.gov/voro++) - -[Possible errors:] - -There are various common errors which can occur when building extra -libraries or when building LAMMPS with packages that require the extra -libraries. - -If you cannot build the extra library itself successfully, you may -need to edit or create an appropriate Makefile for your machine, e.g. -with appropriate compiler or system settings. Provided makefiles are -typically in the lib/name directory. E.g. see the Makefile.* files in -lib/gpu. - -The LAMMPS build often uses settings in a lib/name/Makefile.lammps -file which either exists in the LAMMPS distribution or is created or -copied from a lib/name/Makefile.lammps.* file when the library is -built. If those settings are not correct for your machine you will -need to edit or create an appropriate Makefile.lammps file. - -Package-specific details for these steps are given on the "Packages -details"_Packages_details.html doc page and in README files in the -lib/name directories. - -[Compiler options needed for accelerator packages:] - -Several packages contain code that is optimized for specific hardware, -e.g. CPU, KNL, or GPU. These are the OPT, GPU, KOKKOS, USER-INTEL, -and USER-OMP packages. Compiling and linking the source files in -these accelerator packages for optimal performance requires specific -settings in the Makefile.machine file you use. - -A summary of the Makefile.machine settings needed for each of these -packages is given on the "Packages"_Packages.html doc pages. More -info is given on the doc pages that describe each package in detail: - -"USER-INTEL package"_Speed_intel.html -"GPU package"_Speed_gpu.html -"KOKKOS package"_Speed_kokkos.html -"USER-OMP package"_Speed_omp.html -"OPT package"_Speed_opt.html :all(b) - -You can also use or examine the following machine Makefiles in -src/MAKE/OPTIONS, which include the settings. Note that the -USER-INTEL and KOKKOS packages can use settings that build LAMMPS for -different hardware. The USER-INTEL package can be compiled for Intel -CPUs and KNLs; the KOKKOS package builds for CPUs (OpenMP), GPUs -(CUDA), and Intel KNLs. - -Makefile.intel_cpu -Makefile.intel_phi -Makefile.kokkos_omp -Makefile.kokkos_cuda_mpi -Makefile.kokkos_phi -Makefile.omp -Makefile.opt :ul - -:line - -2.4 Building LAMMPS as a library :h3,link(start_4) - -LAMMPS can be built as either a static or shared library, which can -then be called from another application or a scripting language. See -the "Howto couple"_Howto_couple.html doc page for more info on -coupling LAMMPS to other codes. See the "Python"_Python.html doc page -for more info on wrapping and running LAMMPS from Python. - -Static library :h4 - -To build LAMMPS as a static library (*.a file on Linux), type - -make foo mode=lib :pre - -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. This will use -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. It will also create a soft link liblammps.a, which will -point to the most recently built static library. - -Shared library :h4 - -To build LAMMPS as a shared library (*.so file on Linux), which can be -dynamically loaded, e.g. from Python, type - -make foo mode=shlib :pre - -where foo is the machine name. This kind of library is required when -wrapping LAMMPS with Python; see the "Python"_Python.html doc page for -details. This will use the SHFLAGS and SHLIBFLAGS settings in -src/MAKE/Makefile.foo and perform the build in the directory -Obj_shared_foo. This is so that each file can be compiled with the --fPIC flag which is required for inclusion in a shared library. The -build will create the file liblammps_foo.so which another application -can link to dynamically. It will also create a soft link -liblammps.so, which will point to the most recently built shared -library. This is the file the Python wrapper loads by default. - -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/packages, since they are always built as shared libraries using -the -fPIC switch. However, if a library like MPI or FFTW does not -exist as a shared library, the shared library build will generate an -error. This means you will need to install a shared library version -of the auxiliary library. The build instructions for the library -should tell you how to do this. - -Here is an example of such errors when the system FFTW or provided -lib/colvars library have not been built as shared libraries: - -/usr/bin/ld: /usr/local/lib/libfftw3.a(mapflags.o): relocation -R_X86_64_32 against '.rodata' can not be used when making a shared -object; recompile with -fPIC -/usr/local/lib/libfftw3.a: could not read symbols: Bad value :pre - -/usr/bin/ld: ../../lib/colvars/libcolvars.a(colvarmodule.o): -relocation R_X86_64_32 against '__pthread_key_create' can not be used -when making a shared object; recompile with -fPIC -../../lib/colvars/libcolvars.a: error adding symbols: Bad value :pre - -As an example, here is how to build and install the "MPICH -library"_mpich, a popular open-source version of MPI, distributed by -Argonne National Labs, as a shared library in the default -/usr/local/lib location: - -:link(mpich,http://www-unix.mcs.anl.gov/mpi) - -./configure --enable-shared -make -make install :pre - -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. - -[Additional requirement for using a shared library:] :h4 - -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. - -For the csh or tcsh shells, you would add something like this to your -~/.cshrc file: - -setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre - -Calling the LAMMPS library :h4 - -Either flavor of library (static or shared) allows one or more LAMMPS -objects to be instantiated from the calling program. - -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. - -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. - -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 use -coupling ideas discussed on the "Howto couple"_Howto_couple.html doc -page. See the "Python"_Python.html doc page 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 define the C-style API for -using LAMMPS as a library. See the "Howto library"_Howto_library.html -doc page for a description of the interface and how to extend it for -your needs. - -:line - -2.5 Running LAMMPS :h3,link(start_5) - -By default, LAMMPS runs by reading commands from standard input. Thus -if you run the LAMMPS executable by itself, e.g. - -lmp_linux :pre - -it will simply wait, expecting commands from the keyboard. Typically -you should put commands in an input script and use I/O redirection, -e.g. - -lmp_linux < in.file :pre - -For parallel environments this should also work. If it does not, use -the '-in' command-line switch, e.g. - -lmp_linux -in in.file :pre - -The "Commands"_Commands.html doc page 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 in.lj :pre - -See "this page"_bench for timings for this and the other benchmarks on -various platforms. Note that some of the example scripts require -LAMMPS to be built with one or more of its optional packages. - -:link(bench,http://lammps.sandia.gov/bench.html) - -:line - -On a Windows box, you can skip making LAMMPS and simply download an -installer package from "here"_http://packages.lammps.org/windows.html - -For running the non-MPI executable, follow these steps: - -Get a command prompt by going to Start->Run... , -then typing "cmd". :ulb,l - -Move to the directory where you have your input, e.g. a copy of -the [in.lj] input from the bench folder. (e.g. by typing: cd "Documents"). :l - -At the command prompt, type "lmp_serial -in in.lj", replacing [in.lj] -with the name of your LAMMPS input script. :l - -The serial executable includes support for multi-threading -parallelization from the styles in the USER-OMP packages. - -To run with, e.g. 4 threads, type "lmp_serial -in in.lj -pk omp 4 -sf omp" -:ule - -For the MPI version, which allows you to run LAMMPS under Windows with -the more general message passing parallel library (LAMMPS has been -designed from ground up to use MPI efficiently), follow these steps: - -Download and install a compatible MPI library binary package: -for 32-bit Windows -"mpich2-1.4.1p1-win-ia32.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-ia32.msi -and for 64-bit Windows -"mpich2-1.4.1p1-win-x86-64.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-x86-64.msi -:ulb,l - -The LAMMPS Windows installer packages will automatically adjust your -path for the default location of this MPI package. After the installation -of the MPICH2 software, it needs to be integrated into the system. -For this you need to start a Command Prompt in {Administrator Mode} -(right click on the icon and select it). Change into the MPICH2 -installation directory, then into the subdirectory [bin] and execute -[smpd.exe -install]. Exit the command window. - -Get a new, regular command prompt by going to Start->Run... , -then typing "cmd". :l - -Move to the directory where you have your input file -(e.g. by typing: cd "Documents"). :l - -Then type something like this: - -mpiexec -localonly 4 lmp_mpi -in in.lj :pre -or - -mpiexec -np 4 lmp_mpi -in in.lj :pre - -replacing [in.lj] with the name of your LAMMPS input script. For the latter -case, you may be prompted to enter your password. :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 - -The parallel executable can also run on a single processor by typing -something like: - -lmp_mpi -in in.lj :pre - -And the parallel executable also includes OpenMP multi-threading, which -can be combined with MPI using something like: - -mpiexec -localonly 2 lmp_mpi -in in.lj -pk omp 2 -sf omp :pre - -:ule - -:line - -The screen output from LAMMPS is described in a section below. 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 the "Errors"_Errors.html doc page 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 :h3,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: - --e or -echo --h or -help --i or -in --k or -kokkos --l or -log --nc or -nocite --pk or -package --p or -partition --pl or -plog --ps or -pscreen --r or -restart --ro or -reorder --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 in.alloy -mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none -in in.alloy :pre - -Here are the details on the options: - --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. - --help :pre - -Print a brief help summary and a list of options compiled into this -executable for each LAMMPS style (atom_style, fix, compute, -pair_style, bond_style, etc). This can tell you if the command you -want to use was included via the appropriate package at compile time. -LAMMPS will print the info and immediately exit if this switch is -used. - --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 script from standard input, typically from a script -via I/O redirection; e.g. lmp_linux < in.run. I/O redirection should -also work in parallel, but if it does not (in the unlikely case that -an MPI implementation does not support it), then use the -in flag. -Note that this is a required switch when running LAMMPS in -multi-partition mode, since multiple processors cannot all read from -stdin. - --kokkos on/off keyword/value ... :pre - -Explicitly enable or disable KOKKOS support, as provided by the KOKKOS -package. Even if LAMMPS is built with this package, as described -above in "Section 2.3"_#start_3, this switch must be set to enable -running with the KOKKOS-enabled styles the package provides. If the -switch is not set (the default), LAMMPS will operate as if the KOKKOS -package were not installed; i.e. you can run standard LAMMPS or with -the GPU or USER-OMP packages, for testing or benchmarking purposes. - -Additional optional keyword/value pairs can be specified which -determine how Kokkos will use the underlying hardware on your -platform. These settings apply to each MPI task you launch via the -"mpirun" or "mpiexec" command. You may choose to run one or more MPI -tasks per physical node. Note that if you are running on a desktop -machine, you typically have one physical node. On a cluster or -supercomputer there may be dozens or 1000s of physical nodes. - -Either the full word or an abbreviation can be used for the keywords. -Note that the keywords do not use a leading minus sign. I.e. the -keyword is "t", not "-t". Also note that each of the keywords has a -default setting. Example of when to use these options and what -settings to use on different platforms is given on the "Speed -kokkos"_Speed_kokkos.html doc page. - -d or device -g or gpus -t or threads -n or numa :ul - -device Nd :pre - -This option is only relevant if you built LAMMPS with CUDA=yes, you -have more than one GPU per node, and if you are running with only one -MPI task per node. The Nd setting is the ID of the GPU on the node to -run on. By default Nd = 0. If you have multiple GPUs per node, they -have consecutive IDs numbered as 0,1,2,etc. This setting allows you -to launch multiple independent jobs on the node, each with a single -MPI task per node, and assign each job to run on a different GPU. - -gpus Ng Ns :pre - -This option is only relevant if you built LAMMPS with CUDA=yes, you -have more than one GPU per node, and you are running with multiple MPI -tasks per node (up to one per GPU). The Ng setting is how many GPUs -you will use. The Ns setting is optional. If set, it is the ID of a -GPU to skip when assigning MPI tasks to GPUs. This may be useful if -your desktop system reserves one GPU to drive the screen and the rest -are intended for computational work like running LAMMPS. By default -Ng = 1 and Ns is not set. - -Depending on which flavor of MPI you are running, LAMMPS will look for -one of these 3 environment variables - -SLURM_LOCALID (various MPI variants compiled with SLURM support) -MV2_COMM_WORLD_LOCAL_RANK (Mvapich) -OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) :pre - -which are initialized by the "srun", "mpirun" or "mpiexec" commands. -The environment variable setting for each MPI rank is used to assign a -unique GPU ID to the MPI task. - -threads Nt :pre - -This option assigns Nt number of threads to each MPI task for -performing work when Kokkos is executing in OpenMP or pthreads mode. -The default is Nt = 1, which essentially runs in MPI-only mode. If -there are Np MPI tasks per physical node, you generally want Np*Nt = -the number of physical cores per node, to use your available hardware -optimally. This also sets the number of threads used by the host when -LAMMPS is compiled with CUDA=yes. - -numa Nm :pre - -This option is only relevant when using pthreads with hwloc support. -In this case Nm defines the number of NUMA regions (typically sockets) -on a node which will be utilized by a single MPI rank. By default Nm -= 1. If this option is used the total number of worker-threads per -MPI rank is threads*numa. Currently it is always almost better to -assign at least one MPI rank per NUMA region, and leave numa set to -its default value of 1. This is because letting a single process span -multiple NUMA regions induces a significant amount of cross NUMA data -traffic which is slow. - --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. - --nocite :pre - -Disable writing the log.cite file which is normally written to list -references for specific cite-able features used during a LAMMPS run. -See the "citation page"_http://lammps.sandia.gov/cite.html for more -details. - --package style args .... :pre - -Invoke the "package"_package.html command with style and args. The -syntax is the same as if the command appeared at the top of the input -script. For example "-package gpu 2" or "-pk gpu 2" is the same as -"package gpu 2"_package.html in the input script. The possible styles -and args are documented on the "package"_package.html doc page. This -switch can be used multiple times, e.g. to set options for the -USER-INTEL and USER-OMP packages which can be used together. - -Along with the "-suffix" command-line switch, this is a convenient -mechanism for invoking accelerator packages and their options without -having to edit an input script. - --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 be useful for running -"multi-replica simulations"_Howto_replica.html, 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 simulations from one input script, using -multiple partitions, see the "Howto multiple"_Howto_multiple.html doc -page. 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. - --restart restartfile {remap} datafile keyword value ... :pre - -Convert the restart file into a data file and immediately exit. This -is the same operation as if the following 2-line input script were -run: - -read_restart restartfile {remap} -write_data datafile keyword value ... :pre - -Note that the specified restartfile and datafile can have wild-card -characters ("*",%") as described by the -"read_restart"_read_restart.html and "write_data"_write_data.html -commands. But a filename such as file.* will need to be enclosed in -quotes to avoid shell expansion of the "*" character. - -Note that following restartfile, the optional flag {remap} can be -used. This has the same effect as adding it to the -"read_restart"_read_restart.html command, as explained on its doc -page. This is only useful if the reading of the restart file triggers -an error that atoms have been lost. In that case, use of the remap -flag should allow the data file to still be produced. - -Also note that following datafile, the same optional keyword/value -pairs can be listed as used by the "write_data"_write_data.html -command. - --reorder nth N --reorder custom filename :pre - -Reorder the processors in the MPI communicator used to instantiate -LAMMPS, in one of several ways. The original MPI communicator ranks -all P processors from 0 to P-1. The mapping of these ranks to -physical processors is done by MPI before LAMMPS begins. It may be -useful in some cases to alter the rank order. E.g. to insure that -cores within each node are ranked in a desired order. Or when using -the "run_style verlet/split"_run_style.html command with 2 partitions -to insure that a specific Kspace processor (in the 2nd partition) is -matched up with a specific set of processors in the 1st partition. -See the "Speed tips"_Speed_tips.html doc page for more details. - -If the keyword {nth} is used with a setting {N}, then it means every -Nth processor will be moved to the end of the ranking. This is useful -when using the "run_style verlet/split"_run_style.html command with 2 -partitions via the -partition command-line switch. The first set of -processors will be in the first partition, the 2nd set in the 2nd -partition. The -reorder command-line switch can alter this so that -the 1st N procs in the 1st partition and one proc in the 2nd partition -will be ordered consecutively, e.g. as the cores on one physical node. -This can boost performance. For example, if you use "-reorder nth 4" -and "-partition 9 3" and you are running on 12 processors, the -processors will be reordered from - -0 1 2 3 4 5 6 7 8 9 10 11 :pre - -to - -0 1 2 4 5 6 8 9 10 3 7 11 :pre - -so that the processors in each partition will be - -0 1 2 4 5 6 8 9 10 -3 7 11 :pre - -See the "processors" command for how to insure processors from each -partition could then be grouped optimally for quad-core nodes. - -If the keyword is {custom}, then a file that specifies a permutation -of the processor ranks is also specified. The format of the reorder -file is as follows. Any number of initial blank or comment lines -(starting with a "#" character) can be present. These should be -followed by P lines of the form: - -I J :pre - -where P is the number of processors LAMMPS was launched with. Note -that if running in multi-partition mode (see the -partition switch -above) P is the total number of processors in all partitions. The I -and J values describe a permutation of the P processors. Every I and -J should be values from 0 to P-1 inclusive. In the set of P I values, -every proc ID should appear exactly once. Ditto for the set of P J -values. A single I,J pairing means that the physical processor with -rank I in the original MPI communicator will have rank J in the -reordered communicator. - -Note that rank ordering can also be specified by many MPI -implementations, either by environment variables that specify how to -order physical processors, or by config files that specify what -physical processors to assign to each MPI rank. The -reorder switch -simply gives you a portable way to do this without relying on MPI -itself. See the "processors out"_processors.html command for how -to output info on the final assignment of physical processors to -the LAMMPS simulation domain. - --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 args :pre - -Use variants of various styles if they exist. The specified style can -be {cuda}, {gpu}, {intel}, {kk}, {omp}, {opt}, or {hybrid}. These -refer to optional packages that LAMMPS can be built with, as described -above in "Section 2.3"_#start_3. The "gpu" style corresponds to the -GPU package, the "intel" style to the USER-INTEL package, the "kk" -style to the KOKKOS package, the "opt" style to the OPT package, and -the "omp" style to the USER-OMP package. The hybrid style is the only -style that accepts arguments. It allows for two packages to be -specified. The first package specified is the default and will be used -if it is available. If no style is available for the first package, -the style for the second package will be used if available. For -example, "-suffix hybrid intel omp" will use styles from the -USER-INTEL package if they are installed and available, but styles for -the USER-OMP package otherwise. - -Along with the "-package" command-line switch, this is a convenient -mechanism for invoking accelerator packages and their options without -having to edit an input script. - -As an example, all of the packages provide a "pair_style -lj/cut"_pair_lj.html variant, with style names lj/cut/gpu, -lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style -can be specified explicitly in your input script, e.g. pair_style -lj/cut/gpu. If the -suffix switch is used the specified suffix -(gpu,intel,kk,omp,opt) 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 1" were used at -the top of your input script. These settings can be changed by using -the "-package gpu" command-line switch or the "package -gpu"_package.html command in your script. - -For the USER-INTEL package, using this command-line switch also -invokes the default USER-INTEL settings, as if the command "package -intel 1" were used at the top of your input script. These settings -can be changed by using the "-package intel" command-line switch or -the "package intel"_package.html command in your script. If the -USER-OMP package is also installed, the hybrid style with "intel omp" -arguments can be used to make the omp suffix a second choice, if a -requested style is not available in the USER-INTEL package. It will -also invoke the default USER-OMP settings, as if the command "package -omp 0" were used at the top of your input script. These settings can -be changed by using the "-package omp" command-line switch or the -"package omp"_package.html command in your script. - -For the KOKKOS package, using this command-line switch also invokes -the default KOKKOS settings, as if the command "package kokkos" were -used at the top of your input script. These settings can be changed -by using the "-package kokkos" command-line switch or the "package -kokkos"_package.html command in your script. - -For the OMP package, using this command-line switch also invokes the -default OMP settings, as if the command "package omp 0" were used at -the top of your input script. These settings can be changed by using -the "-package omp" command-line switch or the "package -omp"_package.html command in your script. - -The "suffix"_suffix.html command can also be used within an input -script to set a suffix, or to turn off or back 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. This switch can be used multiple times to -define multiple variables. "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 the "Commands -parse"_Commands_parse.html page 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 :h3,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 2.81192 on 4 procs for 300 steps with 2004 atoms :pre - -Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s -97.0% CPU use with 4 MPI tasks x no OpenMP threads :pre - -MPI task timings breakdown: -Section | min time | avg time | max time |%varavg| %total ---------------------------------------------------------------- -Pair | 1.9808 | 2.0134 | 2.0318 | 1.4 | 71.60 -Bond | 0.0021894 | 0.0060319 | 0.010058 | 4.7 | 0.21 -Kspace | 0.3207 | 0.3366 | 0.36616 | 3.1 | 11.97 -Neigh | 0.28411 | 0.28464 | 0.28516 | 0.1 | 10.12 -Comm | 0.075732 | 0.077018 | 0.07883 | 0.4 | 2.74 -Output | 0.00030518 | 0.00042665 | 0.00078821 | 1.0 | 0.02 -Modify | 0.086606 | 0.086631 | 0.086668 | 0.0 | 3.08 -Other | | 0.007178 | | | 0.26 :pre - -Nlocal: 501 ave 508 max 490 min -Histogram: 1 0 0 0 0 0 1 1 0 1 -Nghost: 6586.25 ave 6628 max 6548 min -Histogram: 1 0 1 0 0 0 1 0 0 1 -Neighs: 177007 ave 180562 max 170212 min -Histogram: 1 0 0 0 0 0 0 1 1 1 :pre - -Total # of neighbors = 708028 -Ave neighs/atom = 353.307 -Ave special neighs/atom = 2.34032 -Neighbor list builds = 26 -Dangerous builds = 0 :pre - -The first section provides a global loop timing summary. The {loop time} -is the total wall time for the section. The {Performance} line is -provided for convenience to help predicting the number of loop -continuations required and for comparing performance with other, -similar MD codes. The {CPU use} line provides the CPU utilization per -MPI task; it should be close to 100% times the number of OpenMP -threads (or 1 of no OpenMP). Lower numbers correspond to delays due -to file I/O or insufficient thread utilization. - -The MPI task section gives the breakdown of the CPU run time (in -seconds) into major categories: - -{Pair} stands for all non-bonded force computation -{Bond} stands for bonded interactions: bonds, angles, dihedrals, impropers -{Kspace} stands for reciprocal space interactions: Ewald, PPPM, MSM -{Neigh} stands for neighbor list construction -{Comm} stands for communicating atoms and their properties -{Output} stands for writing dumps and thermo output -{Modify} stands for fixes and computes called by them -{Other} is the remaining time :ul - -For each category, there is a breakdown of the least, average and most -amount of wall time a processor spent on this section. Also you have the -variation from the average time. Together these numbers allow to gauge -the amount of load imbalance in this segment of the calculation. Ideally -the difference between minimum, maximum and average is small and thus -the variation from the average close to zero. The final column shows -the percentage of the total loop time is spent in this section. - -When using the "timer full"_timer.html setting, an additional column -is present that also prints the CPU utilization in percent. In -addition, when using {timer full} and the "package omp"_package.html -command are active, a similar timing summary of time spent in threaded -regions to monitor thread utilization and load balance is provided. A -new entry is the {Reduce} section, which lists the time spent in -reducing the per-thread data elements to the storage for non-threaded -computation. These thread timings are taking from the first MPI rank -only and and thus, as the breakdown for MPI tasks can change from MPI -rank to MPI rank, this breakdown can be very different for individual -ranks. Here is an example output for this section: - -Thread timings breakdown (MPI rank 0): -Total threaded time 0.6846 / 90.6% -Section | min time | avg time | max time |%varavg| %total ---------------------------------------------------------------- -Pair | 0.5127 | 0.5147 | 0.5167 | 0.3 | 75.18 -Bond | 0.0043139 | 0.0046779 | 0.0050418 | 0.5 | 0.68 -Kspace | 0.070572 | 0.074541 | 0.07851 | 1.5 | 10.89 -Neigh | 0.084778 | 0.086969 | 0.089161 | 0.7 | 12.70 -Reduce | 0.0036485 | 0.003737 | 0.0038254 | 0.1 | 0.55 :pre - -The third 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: - Stopping criterion = linesearch alpha is zero - Energy initial, next-to-last, final = - -6372.3765206 -8328.46998942 -8328.46998942 - Force two-norm initial, final = 1059.36 5.36874 - Force max component initial, final = 58.6026 1.46872 - Final line search alpha, max atom move = 2.7842e-10 4.0892e-10 - Iterations, force evaluations = 701 1516 :pre - -The first line prints the criterion that determined the minimization -to be completed. The third 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. Then some information about the line search and -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 :h3,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 -on the "History page"_http://lammps.sandia.gov/history.html of the -LAMMPS website. The F90 and F77 versions (2001 and 99) are also -freely distributed as open-source codes; check the "History -page"_http://lammps.sandia.gov/history.html of the LAMMPS website for -info about 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. From cfc1b3a82399f636197d3271deeaaf522519f681 Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Thu, 9 Aug 2018 10:20:02 -0600 Subject: [PATCH 09/51] more changes induced by removing Section_start.txt --- doc/src/Errors_common.txt | 6 +- doc/src/Errors_messages.txt | 4 +- doc/src/Examples.txt | 8 +- doc/src/Howto.txt | 6 +- doc/src/Howto_couple.txt | 21 +- doc/src/Howto_library.txt | 19 +- doc/src/Howto_multiple.txt | 3 +- doc/src/Howto_replica.txt | 17 +- doc/src/Howto_restart.txt | 4 +- doc/src/Howto_temperature.txt | 11 +- doc/src/Manual.txt | 25 +- doc/src/Modify_contribute.txt | 15 +- doc/src/Packages.txt | 8 +- doc/src/Packages_details.txt | 1175 ++--------------- doc/src/Python_shlib.txt | 13 +- doc/src/Python_test.txt | 8 +- doc/src/Speed_gpu.txt | 18 +- doc/src/Speed_intel.txt | 71 +- doc/src/Speed_kokkos.txt | 73 +- doc/src/Speed_measure.txt | 4 +- doc/src/Speed_omp.txt | 21 +- doc/src/Speed_opt.txt | 4 +- doc/src/Speed_packages.txt | 6 +- doc/src/angle_charmm.txt | 12 +- doc/src/angle_class2.txt | 12 +- doc/src/angle_cosine.txt | 12 +- doc/src/angle_cosine_buck6d.txt | 4 +- doc/src/angle_cosine_delta.txt | 12 +- doc/src/angle_cosine_periodic.txt | 12 +- doc/src/angle_cosine_shift.txt | 19 +- doc/src/angle_cosine_shift_exp.txt | 12 +- doc/src/angle_cosine_squared.txt | 12 +- doc/src/angle_dipole.txt | 12 +- doc/src/angle_fourier.txt | 12 +- doc/src/angle_fourier_simple.txt | 12 +- doc/src/angle_harmonic.txt | 12 +- doc/src/angle_hybrid.txt | 4 +- doc/src/angle_quartic.txt | 12 +- doc/src/angle_sdk.txt | 4 +- doc/src/angle_style.txt | 7 +- doc/src/angle_table.txt | 12 +- doc/src/atom_modify.txt | 6 +- doc/src/atom_style.txt | 12 +- doc/src/balance.txt | 10 +- doc/src/bond_class2.txt | 12 +- doc/src/bond_fene.txt | 14 +- doc/src/bond_fene_expand.txt | 14 +- doc/src/bond_gromos.txt | 14 +- doc/src/bond_harmonic.txt | 14 +- doc/src/bond_harmonic_shift.txt | 12 +- doc/src/bond_harmonic_shift_cut.txt | 12 +- doc/src/bond_hybrid.txt | 6 +- doc/src/bond_morse.txt | 14 +- doc/src/bond_nonlinear.txt | 14 +- doc/src/bond_oxdna.txt | 4 +- doc/src/bond_quartic.txt | 14 +- doc/src/bond_style.txt | 7 +- doc/src/bond_table.txt | 14 +- doc/src/compute_ackland_atom.txt | 4 +- doc/src/compute_basal_atom.txt | 4 +- doc/src/compute_cnp_atom.txt | 4 +- doc/src/compute_damage_atom.txt | 4 +- doc/src/compute_dilatation_atom.txt | 4 +- doc/src/compute_dpd.txt | 4 +- doc/src/compute_dpd_atom.txt | 4 +- doc/src/compute_edpd_temp_atom.txt | 4 +- doc/src/compute_entropy_atom.txt | 4 +- doc/src/compute_erotate_rigid.txt | 4 +- doc/src/compute_event_displace.txt | 4 +- doc/src/compute_fep.txt | 4 +- doc/src/compute_ke_atom_eff.txt | 4 +- doc/src/compute_ke_eff.txt | 4 +- doc/src/compute_ke_rigid.txt | 4 +- doc/src/compute_meso_e_atom.txt | 4 +- doc/src/compute_meso_rho_atom.txt | 4 +- doc/src/compute_meso_t_atom.txt | 4 +- doc/src/compute_msd_nongauss.txt | 6 +- doc/src/compute_plasticity_atom.txt | 4 +- doc/src/compute_pressure.txt | 8 +- doc/src/compute_pressure_uef.txt | 6 +- doc/src/compute_rigid_local.txt | 4 +- doc/src/compute_saed.txt | 4 +- doc/src/compute_smd_contact_radius.txt | 4 +- doc/src/compute_smd_damage.txt | 4 +- doc/src/compute_smd_hourglass_error.txt | 4 +- doc/src/compute_smd_internal_energy.txt | 8 +- doc/src/compute_smd_plastic_strain.txt | 8 +- doc/src/compute_smd_plastic_strain_rate.txt | 8 +- doc/src/compute_smd_rho.txt | 4 +- doc/src/compute_smd_tlsph_defgrad.txt | 8 +- doc/src/compute_smd_tlsph_dt.txt | 4 +- doc/src/compute_smd_tlsph_num_neighs.txt | 4 +- doc/src/compute_smd_tlsph_shape.txt | 4 +- doc/src/compute_smd_tlsph_strain.txt | 4 +- doc/src/compute_smd_tlsph_strain_rate.txt | 4 +- doc/src/compute_smd_tlsph_stress.txt | 4 +- .../compute_smd_triangle_mesh_vertices.txt | 4 +- doc/src/compute_smd_ulsph_num_neighs.txt | 8 +- doc/src/compute_smd_ulsph_strain.txt | 8 +- doc/src/compute_smd_ulsph_strain_rate.txt | 9 +- doc/src/compute_smd_ulsph_stress.txt | 8 +- doc/src/compute_smd_vol.txt | 4 +- doc/src/compute_sna_atom.txt | 4 +- doc/src/compute_spin.txt | 8 +- doc/src/compute_tally.txt | 6 +- doc/src/compute_tdpd_cc_atom.txt | 4 +- doc/src/compute_temp.txt | 8 +- doc/src/compute_temp_asphere.txt | 4 +- doc/src/compute_temp_body.txt | 4 +- doc/src/compute_temp_deform_eff.txt | 4 +- doc/src/compute_temp_eff.txt | 4 +- doc/src/compute_temp_partial.txt | 8 +- doc/src/compute_temp_region_eff.txt | 4 +- doc/src/compute_temp_rotate.txt | 4 +- doc/src/compute_temp_uef.txt | 6 +- doc/src/compute_ti.txt | 4 +- doc/src/compute_voronoi_atom.txt | 4 +- doc/src/compute_xrd.txt | 4 +- doc/src/dihedral_charmm.txt | 12 +- doc/src/dihedral_class2.txt | 12 +- doc/src/dihedral_cosine_shift_exp.txt | 12 +- doc/src/dihedral_fourier.txt | 12 +- doc/src/dihedral_harmonic.txt | 12 +- doc/src/dihedral_helix.txt | 12 +- doc/src/dihedral_hybrid.txt | 4 +- doc/src/dihedral_multi_harmonic.txt | 12 +- doc/src/dihedral_nharmonic.txt | 12 +- doc/src/dihedral_opls.txt | 12 +- doc/src/dihedral_quadratic.txt | 12 +- doc/src/dihedral_spherical.txt | 4 +- doc/src/dihedral_style.txt | 7 +- doc/src/dihedral_table.txt | 12 +- doc/src/dihedral_table_cut.txt | 4 +- doc/src/dump.txt | 21 +- doc/src/dump_cfg_uef.txt | 6 +- doc/src/dump_h5md.txt | 14 +- doc/src/dump_image.txt | 7 +- doc/src/dump_molfile.txt | 4 +- doc/src/dump_netcdf.txt | 4 +- doc/src/dump_vtk.txt | 6 +- doc/src/echo.txt | 4 +- doc/src/fix.txt | 6 +- doc/src/fix_addforce.txt | 8 +- doc/src/fix_addtorque.txt | 4 +- doc/src/fix_append_atoms.txt | 4 +- doc/src/fix_atom_swap.txt | 4 +- doc/src/fix_ave_correlate_long.txt | 4 +- doc/src/fix_aveforce.txt | 8 +- doc/src/fix_bocs.txt | 4 +- doc/src/fix_bond_break.txt | 4 +- doc/src/fix_bond_create.txt | 4 +- doc/src/fix_bond_react.txt | 4 +- doc/src/fix_bond_swap.txt | 4 +- doc/src/fix_cmap.txt | 4 +- doc/src/fix_colvars.txt | 4 +- doc/src/fix_deform.txt | 8 +- doc/src/fix_deposit.txt | 4 +- doc/src/fix_dpd_energy.txt | 12 +- doc/src/fix_dpd_source.txt | 4 +- doc/src/fix_efield.txt | 4 +- doc/src/fix_ehex.txt | 4 +- doc/src/fix_enforce2d.txt | 8 +- doc/src/fix_eos_cv.txt | 4 +- doc/src/fix_eos_table.txt | 4 +- doc/src/fix_eos_table_rx.txt | 12 +- doc/src/fix_evaporate.txt | 4 +- doc/src/fix_filter_corotate.txt | 4 +- doc/src/fix_flow_gauss.txt | 4 +- doc/src/fix_freeze.txt | 12 +- doc/src/fix_gcmc.txt | 4 +- doc/src/fix_gld.txt | 4 +- doc/src/fix_gle.txt | 6 +- doc/src/fix_gravity.txt | 8 +- doc/src/fix_grem.txt | 4 +- doc/src/fix_imd.txt | 4 +- doc/src/fix_ipi.txt | 6 +- doc/src/fix_langevin.txt | 8 +- doc/src/fix_langevin_eff.txt | 4 +- doc/src/fix_langevin_spin.txt | 6 +- doc/src/fix_latte.txt | 8 +- doc/src/fix_lb_fluid.txt | 4 +- doc/src/fix_lb_momentum.txt | 4 +- doc/src/fix_lb_pc.txt | 4 +- doc/src/fix_lb_rigid_pc_sphere.txt | 4 +- doc/src/fix_lb_viscous.txt | 4 +- doc/src/fix_manifoldforce.txt | 27 +- doc/src/fix_meso.txt | 4 +- doc/src/fix_meso_stationary.txt | 4 +- doc/src/fix_momentum.txt | 8 +- doc/src/fix_mscg.txt | 4 +- doc/src/fix_msst.txt | 4 +- doc/src/fix_mvv_dpd.txt | 4 +- doc/src/fix_neb.txt | 4 +- doc/src/fix_nh.txt | 8 +- doc/src/fix_nh_eff.txt | 4 +- doc/src/fix_nh_uef.txt | 4 +- doc/src/fix_nph_asphere.txt | 12 +- doc/src/fix_nph_body.txt | 12 +- doc/src/fix_nph_sphere.txt | 8 +- doc/src/fix_nphug.txt | 12 +- doc/src/fix_npt_asphere.txt | 12 +- doc/src/fix_npt_body.txt | 12 +- doc/src/fix_npt_sphere.txt | 8 +- doc/src/fix_nve.txt | 8 +- doc/src/fix_nve_asphere.txt | 12 +- doc/src/fix_nve_asphere_noforce.txt | 4 +- doc/src/fix_nve_body.txt | 4 +- doc/src/fix_nve_dot.txt | 4 +- doc/src/fix_nve_dotc_langevin.txt | 4 +- doc/src/fix_nve_eff.txt | 4 +- doc/src/fix_nve_line.txt | 4 +- doc/src/fix_nve_manifold_rattle.txt | 4 +- doc/src/fix_nve_sphere.txt | 8 +- doc/src/fix_nve_spin.txt | 6 +- doc/src/fix_nve_tri.txt | 4 +- doc/src/fix_nvk.txt | 6 +- doc/src/fix_nvt_asphere.txt | 12 +- doc/src/fix_nvt_body.txt | 12 +- doc/src/fix_nvt_manifold_rattle.txt | 14 +- doc/src/fix_nvt_sllod.txt | 8 +- doc/src/fix_nvt_sllod_eff.txt | 4 +- doc/src/fix_nvt_sphere.txt | 8 +- doc/src/fix_orient.txt | 4 +- doc/src/fix_phonon.txt | 8 +- doc/src/fix_pimd.txt | 4 +- doc/src/fix_poems.txt | 4 +- doc/src/fix_pour.txt | 4 +- doc/src/fix_precession_spin.txt | 8 +- doc/src/fix_python_invoke.txt | 6 +- doc/src/fix_python_move.txt | 4 +- doc/src/fix_qbmsst.txt | 4 +- doc/src/fix_qeq.txt | 4 +- doc/src/fix_qeq_comb.txt | 8 +- doc/src/fix_qeq_reax.txt | 12 +- doc/src/fix_qmmm.txt | 4 +- doc/src/fix_qtb.txt | 4 +- doc/src/fix_reax_bonds.txt | 12 +- doc/src/fix_reaxc_species.txt | 16 +- doc/src/fix_rhok.txt | 4 +- doc/src/fix_rigid.txt | 12 +- doc/src/fix_rx.txt | 12 +- doc/src/fix_setforce.txt | 8 +- doc/src/fix_shake.txt | 12 +- doc/src/fix_shardlow.txt | 12 +- doc/src/fix_smd.txt | 4 +- doc/src/fix_smd_adjust_dt.txt | 27 +- doc/src/fix_smd_integrate_tlsph.txt | 18 +- doc/src/fix_smd_integrate_ulsph.txt | 28 +- doc/src/fix_smd_move_triangulated_surface.txt | 34 +- doc/src/fix_smd_setvel.txt | 4 +- doc/src/fix_smd_wall_surface.txt | 45 +- doc/src/fix_srd.txt | 4 +- doc/src/fix_temp_rescale_eff.txt | 4 +- doc/src/fix_tfmc.txt | 4 +- doc/src/fix_thermal_conductivity.txt | 4 +- doc/src/fix_ti_spring.txt | 4 +- doc/src/fix_tmd.txt | 4 +- doc/src/fix_ttm.txt | 3 +- doc/src/fix_tune_kspace.txt | 6 +- doc/src/fix_viscosity.txt | 4 +- doc/src/fix_wall.txt | 8 +- doc/src/fix_wall_body_polygon.txt | 4 +- doc/src/fix_wall_body_polyhedron.txt | 6 +- doc/src/fix_wall_ees.txt | 4 +- doc/src/fix_wall_gran.txt | 4 +- doc/src/fix_wall_gran_region.txt | 4 +- doc/src/fix_wall_piston.txt | 4 +- doc/src/fix_wall_reflect.txt | 8 +- doc/src/group2ndx.txt | 4 +- doc/src/improper_class2.txt | 12 +- doc/src/improper_cossq.txt | 12 +- doc/src/improper_cvff.txt | 12 +- doc/src/improper_distance.txt | 4 +- doc/src/improper_fourier.txt | 12 +- doc/src/improper_harmonic.txt | 12 +- doc/src/improper_hybrid.txt | 4 +- doc/src/improper_inversion_harmonic.txt | 4 +- doc/src/improper_ring.txt | 12 +- doc/src/improper_style.txt | 7 +- doc/src/improper_umbrella.txt | 12 +- doc/src/jump.txt | 11 +- doc/src/kspace_style.txt | 20 +- doc/src/lammps.book | 22 +- doc/src/log.txt | 5 +- doc/src/neb.txt | 20 +- doc/src/neighbor.txt | 4 +- doc/src/next.txt | 10 +- doc/src/package.txt | 93 +- doc/src/pair_adp.txt | 8 +- doc/src/pair_agni.txt | 25 +- doc/src/pair_airebo.txt | 12 +- doc/src/pair_beck.txt | 8 +- doc/src/pair_body_nparticle.txt | 4 +- doc/src/pair_body_rounded_polygon.txt | 4 +- doc/src/pair_body_rounded_polyhedron.txt | 4 +- doc/src/pair_bop.txt | 5 +- doc/src/pair_born.txt | 12 +- doc/src/pair_brownian.txt | 12 +- doc/src/pair_buck.txt | 12 +- doc/src/pair_buck6d_coul_gauss.txt | 6 +- doc/src/pair_buck_long.txt | 14 +- doc/src/pair_charmm.txt | 14 +- doc/src/pair_class2.txt | 12 +- doc/src/pair_colloid.txt | 12 +- doc/src/pair_comb.txt | 14 +- doc/src/pair_coul.txt | 10 +- doc/src/pair_coul_diel.txt | 9 +- doc/src/pair_coul_shield.txt | 6 +- doc/src/pair_cs.txt | 4 +- doc/src/pair_dipole.txt | 16 +- doc/src/pair_dpd.txt | 8 +- doc/src/pair_dpd_fdt.txt | 12 +- doc/src/pair_dsmc.txt | 4 +- doc/src/pair_eam.txt | 12 +- doc/src/pair_edip.txt | 12 +- doc/src/pair_eff.txt | 4 +- doc/src/pair_eim.txt | 8 +- doc/src/pair_exp6_rx.txt | 12 +- doc/src/pair_gauss.txt | 12 +- doc/src/pair_gayberne.txt | 12 +- doc/src/pair_gran.txt | 12 +- doc/src/pair_gromacs.txt | 8 +- doc/src/pair_gw.txt | 4 +- doc/src/pair_hbond_dreiding.txt | 8 +- doc/src/pair_hybrid.txt | 12 +- doc/src/pair_ilp_graphene_hbn.txt | 4 +- doc/src/pair_kim.txt | 4 +- doc/src/pair_kolmogorov_crespi_full.txt | 4 +- doc/src/pair_kolmogorov_crespi_z.txt | 4 +- doc/src/pair_lcbop.txt | 4 +- doc/src/pair_line_lj.txt | 4 +- doc/src/pair_list.txt | 4 +- doc/src/pair_lj.txt | 14 +- doc/src/pair_lj96.txt | 8 +- doc/src/pair_lj_cubic.txt | 8 +- doc/src/pair_lj_expand.txt | 8 +- doc/src/pair_lj_long.txt | 14 +- doc/src/pair_lj_smooth.txt | 8 +- doc/src/pair_lj_smooth_linear.txt | 8 +- doc/src/pair_lj_soft.txt | 10 +- doc/src/pair_lubricate.txt | 12 +- doc/src/pair_lubricateU.txt | 4 +- doc/src/pair_mdf.txt | 4 +- doc/src/pair_meam.txt | 14 +- doc/src/pair_meam_spline.txt | 12 +- doc/src/pair_meam_sw_spline.txt | 5 +- doc/src/pair_meso.txt | 4 +- doc/src/pair_mgpt.txt | 4 +- doc/src/pair_momb.txt | 4 +- doc/src/pair_morse.txt | 16 +- doc/src/pair_multi_lucy.txt | 4 +- doc/src/pair_multi_lucy_rx.txt | 12 +- doc/src/pair_nb3b_harmonic.txt | 12 +- doc/src/pair_nm.txt | 12 +- doc/src/pair_oxdna.txt | 4 +- doc/src/pair_oxdna2.txt | 4 +- doc/src/pair_peri.txt | 12 +- doc/src/pair_polymorphic.txt | 4 +- doc/src/pair_python.txt | 4 +- doc/src/pair_quip.txt | 4 +- doc/src/pair_reaxc.txt | 12 +- doc/src/pair_resquared.txt | 12 +- doc/src/pair_sdk.txt | 18 +- doc/src/pair_smd_hertz.txt | 30 +- doc/src/pair_smd_tlsph.txt | 44 +- doc/src/pair_smd_triangulated_surface.txt | 24 +- doc/src/pair_smd_ulsph.txt | 50 +- doc/src/pair_smtbq.txt | 4 +- doc/src/pair_snap.txt | 14 +- doc/src/pair_soft.txt | 8 +- doc/src/pair_sph_heatconduction.txt | 4 +- doc/src/pair_sph_idealgas.txt | 4 +- doc/src/pair_sph_lj.txt | 4 +- doc/src/pair_sph_rhosum.txt | 4 +- doc/src/pair_sph_taitwater.txt | 4 +- doc/src/pair_sph_taitwater_morris.txt | 4 +- doc/src/pair_spin_dmi.txt | 8 +- doc/src/pair_spin_exchange.txt | 8 +- doc/src/pair_spin_magelec.txt | 8 +- doc/src/pair_spin_neel.txt | 8 +- doc/src/pair_style.txt | 7 +- doc/src/pair_sw.txt | 12 +- doc/src/pair_table.txt | 8 +- doc/src/pair_table_rx.txt | 12 +- doc/src/pair_tersoff.txt | 12 +- doc/src/pair_tersoff_mod.txt | 12 +- doc/src/pair_tersoff_zbl.txt | 12 +- doc/src/pair_thole.txt | 12 +- doc/src/pair_tri_lj.txt | 4 +- doc/src/pair_ufm.txt | 8 +- doc/src/pair_vashishta.txt | 12 +- doc/src/pair_yukawa.txt | 8 +- doc/src/pair_yukawa_colloid.txt | 12 +- doc/src/pair_zbl.txt | 8 +- doc/src/partition.txt | 7 +- doc/src/prd.txt | 22 +- doc/src/processors.txt | 29 +- doc/src/python.txt | 4 +- doc/src/read_data.txt | 8 +- doc/src/read_dump.txt | 6 +- doc/src/read_restart.txt | 3 +- doc/src/region.txt | 8 +- doc/src/rerun.txt | 4 +- doc/src/restart.txt | 3 +- doc/src/run_style.txt | 22 +- doc/src/suffix.txt | 16 +- doc/src/tad.txt | 4 +- doc/src/temper.txt | 25 +- doc/src/temper_grem.txt | 4 +- doc/src/temper_npt.txt | 4 +- doc/src/thermo_style.txt | 6 +- doc/src/timer.txt | 4 +- doc/src/variable.txt | 49 +- doc/src/write_data.txt | 2 +- doc/src/write_restart.txt | 3 +- 415 files changed, 2029 insertions(+), 2890 deletions(-) diff --git a/doc/src/Errors_common.txt b/doc/src/Errors_common.txt index 43d1a85a7b..8f26b22b3a 100644 --- a/doc/src/Errors_common.txt +++ b/doc/src/Errors_common.txt @@ -58,9 +58,9 @@ style", with ... being fix, compute, pair, etc, it means that you mistyped the style name or that the command is part of an optional package which was not compiled into your executable. The list of available styles in your executable can be listed by using "the -h -command-line argument"_Section_start.html#start_6. The installation -and compilation of optional packages is explained in the "installation -instructions"_Section_start.html#start_3. +command-line swith"_Run_options.html. The installation and +compilation of optional packages is explained on the "Build +packages"_Build_packages.html doc page. For a given command, LAMMPS expects certain arguments in a specified order. If you mess this up, LAMMPS will often flag the error, but it diff --git a/doc/src/Errors_messages.txt b/doc/src/Errors_messages.txt index 03fc25b561..d279b5e975 100644 --- a/doc/src/Errors_messages.txt +++ b/doc/src/Errors_messages.txt @@ -7911,8 +7911,8 @@ Atom IDs must be positive integers. :dd {One or more atom IDs is too big} :dt The limit on atom IDs is set by the SMALLBIG, BIGBIG, SMALLSMALL -setting in your Makefile. See Section_start 2.2 of the manual for -more details. :dd +setting in your LAMMPS build. See the "Build +settings"_Build_settings.html doc page for more info. :dd {One or more atom IDs is zero} :dt diff --git a/doc/src/Examples.txt b/doc/src/Examples.txt index 5bd8da2409..4b6db8a047 100644 --- a/doc/src/Examples.txt +++ b/doc/src/Examples.txt @@ -112,10 +112,10 @@ web site. If you uncomment the "dump image"_dump_image.html line(s) in the input script a series of JPG images will be produced by the run (assuming -you built LAMMPS with JPG support; see "Section -2.2"_Section_start.html#start_2 for details). These can be viewed -individually or turned into a movie or animated by tools like -ImageMagick or QuickTime or various Windows-based tools. See the +you built LAMMPS with JPG support; see the +"Build_settings"_Build_settings.html doc page for details). These can +be viewed individually or turned into a movie or animated by tools +like ImageMagick or QuickTime or various Windows-based tools. See the "dump image"_dump_image.html doc page for more details. E.g. this Imagemagick command would create a GIF file suitable for viewing in a browser. diff --git a/doc/src/Howto.txt b/doc/src/Howto.txt index d9a60d1ef4..6e434552e7 100644 --- a/doc/src/Howto.txt +++ b/doc/src/Howto.txt @@ -84,7 +84,7 @@ END_RST --> "Using GitHub with LAMMPS"_Howto_github.html "PyLAMMPS interface to LAMMPS"_Howto_pylammps.html -"Using LAMMPS with bash on Windows"_Howto_bash.html +"Using LAMMPS with bash on Windows"_Howto_bash.html :all(b) "Restart a simulation"_Howto_restart.html "Visualize LAMMPS snapshots"_Howto_viz.html @@ -121,8 +121,8 @@ END_RST --> "Polarizable models"_Howto_polarizable.html "Adiabatic core/shell model"_Howto_coreshell.html "Drude induced dipoles"_Howto_drude.html -"Drude induced dipoles (extended)"_Howto_drude2.html :all(b) +"Drude induced dipoles (extended)"_Howto_drude2.html "Manifolds (surfaces)"_Howto_manifold.html -"Magnetic spins"_Howto_spins.html +"Magnetic spins"_Howto_spins.html :all(b) diff --git a/doc/src/Howto_couple.txt b/doc/src/Howto_couple.txt index 38595a9d16..4c0f72a806 100644 --- a/doc/src/Howto_couple.txt +++ b/doc/src/Howto_couple.txt @@ -77,17 +77,16 @@ strain induced across grain boundaries :l :link(quest,http://dft.sandia.gov/Quest) :link(spparks,http://www.sandia.gov/~sjplimp/spparks.html) -"This section"_Section_start.html#start_5 of the documentation -describes how to build LAMMPS as a library. Once this is done, you -can interface with LAMMPS either via C++, C, Fortran, or Python (or -any other language that supports a vanilla C-like interface). For -example, from C++ you could create one (or more) "instances" of -LAMMPS, pass it an input script to process, or execute individual -commands, all by invoking the correct class methods in LAMMPS. From C -or Fortran you can make function calls to do the same things. See the -"Python"_Python.html doc pages for a description of the Python wrapper -provided with LAMMPS that operates through the LAMMPS library -interface. +The "Build basics"_Build_basics.html doc page describes how to build +LAMMPS as a library. Once this is done, you can interface with LAMMPS +either via C++, C, Fortran, or Python (or any other language that +supports a vanilla C-like interface). For example, from C++ you could +create one (or more) "instances" of LAMMPS, pass it an input script to +process, or execute individual commands, all by invoking the correct +class methods in LAMMPS. From C or Fortran you can make function +calls to do the same things. See the "Python"_Python.html doc pages +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 the "Howto library"_Howto_library.html doc page for a diff --git a/doc/src/Howto_library.txt b/doc/src/Howto_library.txt index 0d4852fbf2..8e99182f87 100644 --- a/doc/src/Howto_library.txt +++ b/doc/src/Howto_library.txt @@ -9,10 +9,10 @@ Documentation"_ld - "LAMMPS Commands"_lc :c Library interface to LAMMPS :h3 -As described in "Section 2.5"_Section_start.html#start_5, LAMMPS can -be built as a library, so that it can be called by another code, used -in a "coupled manner"_Howto_couple.html with other codes, or driven -through a "Python interface"_Python.html. +As described on the "Build basics"_Build_basics.html doc page, LAMMPS +can be built as a library, so that it can be called by another code, +used in a "coupled manner"_Howto_couple.html with other codes, or +driven through a "Python interface"_Python.html. All of these methodologies use a C-style interface to LAMMPS that is provided in the files src/library.cpp and src/library.h. The @@ -51,12 +51,11 @@ void lammps_free(void *) :pre The lammps_open() function is used to initialize LAMMPS, passing in a list of strings as if they were "command-line -arguments"_Section_start.html#start_6 when LAMMPS is run in -stand-alone mode from the command line, and a MPI communicator for -LAMMPS to run under. It returns a ptr to the LAMMPS object that is -created, and which is used in subsequent library calls. The -lammps_open() function can be called multiple times, to create -multiple instances of LAMMPS. +arguments"_Run_options.html when LAMMPS is run in stand-alone mode +from the command line, and a MPI communicator for LAMMPS to run under. +It returns a ptr to the LAMMPS object that is created, and which is +used in subsequent library calls. The lammps_open() function can be +called multiple times, to create multiple instances of LAMMPS. LAMMPS will run on the set of processors in the communicator. This means the calling code can run LAMMPS on all or a subset of diff --git a/doc/src/Howto_multiple.txt b/doc/src/Howto_multiple.txt index edcb8196cf..9ad872fedc 100644 --- a/doc/src/Howto_multiple.txt +++ b/doc/src/Howto_multiple.txt @@ -80,8 +80,7 @@ jump in.polymer :pre All of the above examples work whether you are running on 1 or multiple processors, but assumed you are running LAMMPS on a single partition of processors. LAMMPS can be run on multiple partitions via -the "-partition" command-line switch as described in "this -section"_Section_start.html#start_6 of the manual. +the "-partition command-line switch"_Run_options.html. In the last 2 examples, if LAMMPS were run on 3 partitions, the same scripts could be used if the "index" and "loop" variables were diff --git a/doc/src/Howto_replica.txt b/doc/src/Howto_replica.txt index 1b44fe5374..2135e52e0e 100644 --- a/doc/src/Howto_replica.txt +++ b/doc/src/Howto_replica.txt @@ -29,29 +29,28 @@ runs different replicas at a series of temperature to facilitate rare-event sampling. These commands can only be used if LAMMPS was built with the REPLICA -package. See the "Making LAMMPS"_Section_start.html#start_3 section -for more info on packages. +package. See the "Build package"_Build_package.html doc page for more +info. PIMD runs different replicas whose individual particles are coupled together by springs to model a system or ring-polymers. This commands can only be used if LAMMPS was built with the USER-MISC -package. See the "Making LAMMPS"_Section_start.html#start_3 section -for more info on packages. +package. See the "Build package"_Build_package.html doc page for more +info. In all these cases, you must run with one or more processors per replica. The processors assigned to each replica are determined at run-time by using the "-partition command-line -switch"_Section_start.html#start_6 to launch LAMMPS on multiple -partitions, which in this context are the same as replicas. E.g. -these commands: +switch"_Run_options.html to launch LAMMPS on multiple partitions, +which in this context are the same as replicas. E.g. these commands: mpirun -np 16 lmp_linux -partition 8x2 -in in.temper mpirun -np 8 lmp_linux -partition 8x1 -in in.neb :pre would each run 8 replicas, on either 16 or 8 processors. Note the use -of the "-in command-line switch"_Section_start.html#start_6 to specify -the input script which is required when running in multi-replica mode. +of the "-in command-line switch"_Run_options.html to specify the input +script which is required when running in multi-replica mode. Also note that with MPI installed on a machine (e.g. your desktop), you can run on more (virtual) processors than you have physical diff --git a/doc/src/Howto_restart.txt b/doc/src/Howto_restart.txt index b211775479..bc67daa78e 100644 --- a/doc/src/Howto_restart.txt +++ b/doc/src/Howto_restart.txt @@ -16,8 +16,8 @@ restart files can be saved to disk using the "restart"_restart.html command. At a later time, these binary files can be read via a "read_restart"_read_restart.html command in a new script. Or they can be converted to text data files using the "-r command-line -switch"_Section_start.html#start_6 and read by a -"read_data"_read_data.html command in a new script. +switch"_Run_options.html and read by a "read_data"_read_data.html +command in a new script. Here we give examples of 2 scripts that read either a binary restart file or a converted data file and then issue a new run command to diff --git a/doc/src/Howto_temperature.txt b/doc/src/Howto_temperature.txt index 7a318250cf..8a9e262da1 100644 --- a/doc/src/Howto_temperature.txt +++ b/doc/src/Howto_temperature.txt @@ -17,7 +17,10 @@ aggregate motion of particles) and its thermal velocity. The sum of the two is the particle's total velocity, but the latter is often what is wanted to compute a temperature. -LAMMPS has several options for computing temperatures, any of which can be used in "thermostatting"_Howto_thermostat.html and "barostatting"_Howto_barostat.html. These "compute commands"_compute.html calculate temperature: +LAMMPS has several options for computing temperatures, any of which +can be used in "thermostatting"_Howto_thermostat.html and +"barostatting"_Howto_barostat.html. These "compute +commands"_compute.html calculate temperature: "compute temp"_compute_temp.html "compute temp/sphere"_compute_temp_sphere.html @@ -35,6 +38,6 @@ velocities) that are removed when computing the thermal temperature. temp/asphere"_compute_temp_asphere.html compute kinetic energy for finite-size particles that includes rotational degrees of freedom. They both allow for velocity biases indirectly, via an optional extra -argument which is another temperature compute that subtracts a velocity bias. -This allows the translational velocity of spherical or aspherical -particles to be adjusted in prescribed ways. +argument which is another temperature compute that subtracts a +velocity bias. This allows the translational velocity of spherical or +aspherical particles to be adjusted in prescribed ways. diff --git a/doc/src/Manual.txt b/doc/src/Manual.txt index a5e8b63640..a3747465cd 100644 --- a/doc/src/Manual.txt +++ b/doc/src/Manual.txt @@ -72,7 +72,9 @@ every LAMMPS command. :includehidden: Intro - Section_start + Install + Build + Run Commands Packages Speed @@ -107,15 +109,9 @@ END_RST --> "Introduction"_Intro.html :olb,l -"Getting started"_Section_start.html :l - 2.1 "What's in the LAMMPS distribution"_start_1 :ulb,b - 2.2 "Making LAMMPS"_start_2 :b - 2.3 "Making LAMMPS with optional packages"_start_3 :b - 2.4 "Building LAMMPS as a library"_start_4 :b - 2.5 "Running LAMMPS"_start_5 :b - 2.6 "Command-line options"_start_6 :b - 2.7 "Screen output"_start_7 :b - 2.8 "Tips for users of previous versions"_start_8 :ule,b +"Install LAMMPS"_Install.html :l +"Build LAMMPS"_Build.html :l +"Run LAMMPS"_Run.html :l "Commands"_Commands.html :l "Optional packages"_Packages.html :l "Accelerate performance"_Speed.html :l @@ -127,15 +123,6 @@ END_RST --> "Errors"_Errors.html :l :ole -:link(start_1,Section_start.html#start_1) -:link(start_2,Section_start.html#start_2) -:link(start_3,Section_start.html#start_3) -:link(start_4,Section_start.html#start_4) -:link(start_5,Section_start.html#start_5) -:link(start_6,Section_start.html#start_6) -:link(start_7,Section_start.html#start_7) -:link(start_8,Section_start.html#start_8) - diff --git a/doc/src/Modify_contribute.txt b/doc/src/Modify_contribute.txt index ef9fe6a717..8cbea8bb31 100644 --- a/doc/src/Modify_contribute.txt +++ b/doc/src/Modify_contribute.txt @@ -44,13 +44,14 @@ compression, as this works well on all platforms. If the new features/files are broadly useful we may add them as core files to LAMMPS or as part of a "standard -package"_Section_start.html#start_3. Else we will add them as a -user-contributed file or package. Examples of user packages are in -src sub-directories that start with USER. The USER-MISC package is -simply a collection of (mostly) unrelated single files, which is the -simplest way to have your contribution quickly added to the LAMMPS -distribution. You can see a list of the both standard and user -packages by typing "make package" in the LAMMPS src directory. +package"_Packages_standard.html. Else we will add them as a +user-contributed file or "user package"_Packages_user.html. Examples +of user packages are in src sub-directories that start with USER. The +USER-MISC package is simply a collection of (mostly) unrelated single +files, which is the simplest way to have your contribution quickly +added to the LAMMPS distribution. All the standard and user packages +are listed and described on the "Packages +details"_Packages_details.html doc page. Note that by providing us files to release, you are agreeing to make them open-source, i.e. we can release them under the terms of the GPL, diff --git a/doc/src/Packages.txt b/doc/src/Packages.txt index a7f45a99b7..e48c947be3 100644 --- a/doc/src/Packages.txt +++ b/doc/src/Packages.txt @@ -13,12 +13,12 @@ Optional packages :h2 This section gives an overview of the optional packages that extend LAMMPS functionality. Packages are groups of files that enable a specific set of features. For example, force fields for molecular -systems or rigid-body constraint are in packages. You can see the +systems or rigid-body constraints are in packages. You can see the list of all packages and "make" commands to manage them by typing "make package" from within the src directory of the LAMMPS -distribution. "Section 2.3"_Section_start.html#start_3 gives general -info on how to install and un-install packages as part of the LAMMPS -build process. +distribution. The "Build package"_Build_package.html doc page gives +general info on how to install and un-install packages as part of the +LAMMPS build process. diff --git a/doc/src/Build_basics.txt b/doc/src/Build_basics.txt index b2816b7acb..454e5fbe35 100644 --- a/doc/src/Build_basics.txt +++ b/doc/src/Build_basics.txt @@ -301,15 +301,9 @@ want to copy files to is protected. [CMake variable]: -cmake CMAKE_INSTALL_PREFIX=path \[options ...\] ~/lammps/cmake +cmake -D CMAKE_INSTALL_PREFIX=path \[options ...\] ~/lammps/cmake make # perform make after CMake command -make install # perform the installation :pre - -Note that The CMAKE_INSTALL_PREFIX=path is not a -D variable like -other LAMMPS settings, but rather an option to the cmake command. The -path is where to install the LAMMPS files. - -TODO: is this sub-section correct? +make install # perform the installation into prefix :pre [Traditional make]: diff --git a/doc/src/Build_cmake.txt b/doc/src/Build_cmake.txt index 2bc10d1463..b4f160f371 100644 --- a/doc/src/Build_cmake.txt +++ b/doc/src/Build_cmake.txt @@ -91,8 +91,8 @@ cmake directory which contains the CMakeLists.txt file. The argument can be preceeded or followed by various CMake command-line options. Several useful ones are: -CAKE_INSTALL_PREFIX=path # where to install LAMMPS executable/lib if desired -CMAKE_BUILD_TYPE=type # type = Release or Debug +-D CMAKE_INSTALL_PREFIX=path # where to install LAMMPS executable/lib if desired +-D CMAKE_BUILD_TYPE=type # type = Release or Debug -G output # style of output CMake generates -DVARIABLE=value # setting for a LAMMPS feature to enable -D VARIABLE=value # ditto, but cannot come after CMakeLists.txt dir @@ -103,7 +103,7 @@ All of these variable names are upper-case and their values are lower-case, e.g. -D LAMMPS_SIZES=smallbig. For boolean values, any of these forms can be used: yes/no, on/off, 1/0. -By default CMake generates a Makefile to perform the LAMMPS build. +On Unix/Linux CMake generates a Makefile by default to perform the LAMMPS build. Alternate forms of build info can be generated via the -G switch, e.g. Visual Studio on a Windows machine. Type "cmake --help" to see the "Generator" styles of output your system supports. @@ -118,22 +118,22 @@ CMake creates a CMakeCache.txt file when it runs. This stores all the settings, so that running CMake again from the same directory will inherit those settings. -TODO: explain how to change settings on a subsequent cmake in the same -build dir. In that case is "." the final arg of cmake? +If you later want to change a setting you can rerun cmake in the build +directory with different setting. Please note that some automatically +detected variables will not change their value. In these cases it is +usually better to start with a fresh build directory. [Curses version (terminal-style menu) of CMake]: ccmake ~/lammps/cmake :pre -TODO: give brief explanation of how to find and toggle options, how to -perform the generate, how to use it multiple times. +Please see the "ccmake manual"_https://cmake.org/cmake/help/latest/manual/ccmake.1.html for more information. [GUI version of CMake]: cmake-gui ~/lammps/cmake :pre -TODO: give brief explanation of how to find and toggle options, how to -perform the generate, how to use it multiple times. +Please see the "cmake-gui manual"_https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html for more information. :line @@ -152,8 +152,7 @@ module list # is a cmake module is already loaded module avail # is a cmake module available? module load cmake3 # load cmake module with appropriate name :pre -If you do not have CMake or a new enough version, you can install it -as follows: - -TODO: give install instructions for Linux, Mac, Windows - +If you do not have CMake or a new enough version, you can download the latest +version at "https://cmake.org/download/"_https://cmake.org/download/. +Instructions on how to install it on various platforms can be found +"here"_https://cmake.org/install/. diff --git a/doc/src/Build_extras.txt b/doc/src/Build_extras.txt index d940ed23cd..9a03d0092f 100644 --- a/doc/src/Build_extras.txt +++ b/doc/src/Build_extras.txt @@ -68,7 +68,7 @@ name. :line -GPU package :h3,link(gpu) +GPU package :h4,link(gpu) To build with this package, you need to choose options for precision and which GPU hardware to build for. To build with make you also need @@ -134,7 +134,7 @@ GPU library. :line -KIM package :h3,link(kim) +KIM package :h4,link(kim) To build with this package, the KIM library must be downloaded and built on your system. It must include the KIM models that you want to @@ -178,7 +178,7 @@ make lib-kim args="-p /usr/local/kim-api -a EAM_Dynamo_Ackland_W__MO_14162719659 :line -KOKKOS package :h3,link(kokkos) +KOKKOS package :h4,link(kokkos) To build with this package, you have to choose a Kokkos setting for either CPU (multi-threading via OpenMP) or KNL (OpenMP) or GPU (Cuda) @@ -241,7 +241,7 @@ do not recommend building with other acceleration packages installed :line -LATTE package :h3,link(latte) +LATTE package :h4,link(latte) To build with this package, you must download and build the LATTE library. @@ -272,7 +272,7 @@ the compiler you use on your system to build LATTE. :line -MEAM package :h3,link(meam) +MEAM package :h4,link(meam) NOTE: You should test building the MEAM library with both the Intel and GNU compilers to see if a simulation runs faster with one versus @@ -307,7 +307,7 @@ file. :line -MSCG package :h3,link(mscg) +MSCG package :h4,link(mscg) Before building LAMMPS with this package, you must first download and build the MS-CG library. @@ -342,7 +342,7 @@ You should not need to edit the lib/mscg/Makefile.lammps file. :line -OPT package :h3,link(opt) +OPT package :h4,link(opt) [CMake build]: @@ -359,7 +359,7 @@ CCFLAGS: add -restrict for Intel compilers :ul :line -POEMS package :h3,link(poems) +POEMS package :h4,link(poems) [CMake build]: @@ -388,7 +388,7 @@ a corresponding Makefile.lammps.machine file. :line -PYTHON package :h3,link(python) +PYTHON package :h4,link(python) Building with the PYTHON package assumes you have a Python shared library available on your system, which needs to be a Python 2 @@ -407,7 +407,7 @@ process. You should only need to create a new Makefile.lammps.* file :line -REAX package :h3,link(reax) +REAX package :h4,link(reax) [CMake build]: @@ -438,7 +438,7 @@ file. :line -VORONOI package :h3,link(voronoi) +VORONOI package :h4,link(voronoi) [CMake build]: @@ -466,7 +466,7 @@ the lib/voronoi/Makefile.lammps file. :line :line -USER-ATC package :h3,link(user-atc) +USER-ATC package :h4,link(user-atc) [CMake build]: @@ -507,7 +507,7 @@ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler :pre :line -USER-AWPMD package :h3,link(user-awpmd) +USER-AWPMD package :h4,link(user-awpmd) [CMake build]: @@ -547,7 +547,7 @@ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler :pre :line -USER-COLVARS package :h3,link(user-colvars) +USER-COLVARS package :h4,link(user-colvars) [CMake build]: @@ -577,7 +577,7 @@ a corresponding Makefile.lammps.machine file. :line -USER-H5MD package :h3,link(user-h5md) +USER-H5MD package :h4,link(user-h5md) [CMake build]: @@ -608,7 +608,7 @@ file. :line -USER-INTEL package :h3,link(user-intel) +USER-INTEL package :h4,link(user-intel) [CMake build]: @@ -651,7 +651,7 @@ explained on the "Speed intel"_Speed_intel.html doc page. :line -USER-MOLFILE package :h3,link(user-molfile) +USER-MOLFILE package :h4,link(user-molfile) [CMake build]: @@ -668,7 +668,7 @@ lib/molfile/Makefile.lammps for details. :line -USER-NETCDF package :h3,link(user-netcdf) +USER-NETCDF package :h4,link(user-netcdf) [CMake build]: @@ -685,7 +685,7 @@ lib/netcdf/README for details. :line -USER-OMP package :h3,link(user-omp) +USER-OMP package :h4,link(user-omp) [CMake build]: @@ -698,7 +698,7 @@ LINKFLAGS: add -fopenmp :ul :line -USER-QMMM package :h3,link(user-qmmm) +USER-QMMM package :h4,link(user-qmmm) The LAMMPS executable these steps produce is not yet functional for a QM/MM simulation. You must also build Quantum ESPRESSO and create a @@ -736,7 +736,7 @@ usual manner: :line -USER-QUIP package :h3,link(user-quip) +USER-QUIP package :h4,link(user-quip) [CMake build]: @@ -756,11 +756,11 @@ settings to successfully build on your system. :line -USER-SMD package :h3,link(user-smd) +USER-SMD package :h4,link(user-smd) [CMake build]: --D EIGEN3_INCLUDE_DIR +-D EIGEN3_INCLUDE_DIR=path [Traditional make]: @@ -784,7 +784,7 @@ usual manner: :line -USER-VTK package :h3,link(user-vtk) +USER-VTK package :h4,link(user-vtk) [CMake build]: From edb535d36fad7ca1d2dd144f6659db7f77a534cf Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Thu, 9 Aug 2018 17:08:15 -0400 Subject: [PATCH 14/51] Fix some of the missing TODOs in cmake docs --- doc/src/Build_extras.txt | 68 +++++++++++++++++++++++++++++----------- 1 file changed, 50 insertions(+), 18 deletions(-) diff --git a/doc/src/Build_extras.txt b/doc/src/Build_extras.txt index 9a03d0092f..d6b0d052b5 100644 --- a/doc/src/Build_extras.txt +++ b/doc/src/Build_extras.txt @@ -159,7 +159,10 @@ package?" page. [CMake build]: -TODO: how to do this +-D PKG_KIM=on # enable KIM package +-D DOWNLOAD_KIM=value # download OpenKIM API v1 for build, value = off (default) or on +-D KIM_LIBRARY=path # (only needed if at custom location) path to KIM shared library +-D KIM_INCLUDE_DIR=path # (only needed if at custom location) path to KIM include directory :pre [Traditional make]: @@ -248,7 +251,9 @@ library. [CMake build]: -TODO: how to do this +-D PKG_LATTE=on # enable LATTE package +-D DOWNLOAD_LATTE=value # download LATTE for build, value = off (default) or on +-D LATTE_LIBRARY=path # (only needed if at custom location) path to LATTE shared library :pre [Traditional make]: @@ -280,7 +285,7 @@ the other on your system. [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_MEAM=on # enable MEAM package :pre [Traditional make]: @@ -314,7 +319,10 @@ build the MS-CG library. [CMake build]: -TODO: how to do this +-D PKG_MSCG=on # enable MSCG package +-D DOWNLOAD_MSCG=value # download MSCG for build, value = off (default) or on +-D MSCG_LIBRARY=path # (only needed if at custom location) path to MSCG shared library +-D MSCG_INCLUDE_DIR=path # (only needed if at custom location) path to MSCG include directory :pre [Traditional make]: @@ -346,7 +354,7 @@ OPT package :h4,link(opt) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_OPT=on # enable OPT package :pre [Traditional make]: @@ -363,7 +371,7 @@ POEMS package :h4,link(poems) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_POEMS=on # enable POEMS package :pre [Traditional make]: @@ -397,7 +405,13 @@ lib/python/README for more details. [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_PYTHON=on # enable PYTHON package +-D PYTHON_EXECUTABLE=path # path to Python executable which should be used :pre + +If you want to use a different Python version other than your system default, you can +either create a virtualenv, activate it and then run cmake or use the PYTHON_EXECUTABLE +variable to specify which Python interpreter should be used. Please note that you will +also need to have the development headers installed, e.g. python2-devel. [Traditional make]: @@ -411,7 +425,7 @@ REAX package :h4,link(reax) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_REAX=on # enable REAX package :pre [Traditional make]: @@ -442,7 +456,10 @@ VORONOI package :h4,link(voronoi) [CMake build]: -TODO: how to do this +-D PKG_VORONOI=on # enable VORONOI package +-D DOWNLOAD_VORO=value # download VORO for build, value = off (default) or on +-D VORO_LIBRARY=path # (only needed if at custom location) path to VORO shared library +-D VORO_INCLUDE_DIR=path # (only needed if at custom location) path to VORO include directory :pre [Traditional make]: @@ -470,7 +487,8 @@ USER-ATC package :h4,link(user-atc) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_USER-ATC=on # enable USER-ATC package +-D PKG_MANYBODY=on # requires MANYBODY package :pre [Traditional make]: @@ -511,7 +529,7 @@ USER-AWPMD package :h4,link(user-awpmd) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_USER-AWPMD=on # enable USER-AWPMD package :pre [Traditional make]: @@ -551,7 +569,7 @@ USER-COLVARS package :h4,link(user-colvars) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_USER-COLVARS=on # enable USER-COLVARS package :pre [Traditional make]: @@ -581,7 +599,11 @@ USER-H5MD package :h4,link(user-h5md) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_USER-H5MD=on # enable USER-H5MD package :pre + +This will autodetect the H5MD library if it is installed on your system at standard locations. +Several advanced H5MD options exist if you need to specify where it was installed. Run with +ccmake to see these options. [Traditional make]: @@ -655,7 +677,7 @@ USER-MOLFILE package :h4,link(user-molfile) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_USER-MOLFILE=on # enable USER-MOLFILE package :pre [Traditional make]: @@ -672,7 +694,11 @@ USER-NETCDF package :h4,link(user-netcdf) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_USER-NETCDF=on # enable USER-NETCDF package :pre + +This will autodetect the NETCDF library if it is installed on your system at standard locations. +Several advanced NETCDF options exist if you need to specify where it was installed. Run with +ccmake to see these options. [Traditional make]: @@ -689,7 +715,8 @@ USER-OMP package :h4,link(user-omp) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_USER-OMP=on # enable USER-OMP package +-D BUILD_OMP=on # enable OpenMP support :pre [Traditional make]: @@ -760,7 +787,8 @@ USER-SMD package :h4,link(user-smd) [CMake build]: --D EIGEN3_INCLUDE_DIR=path +-D PKG_USER-SMD=on # enable USER-SMD package +-D EIGEN3_INCLUDE_DIR=path # path to include directory of Eigen library :pre [Traditional make]: @@ -788,7 +816,11 @@ USER-VTK package :h4,link(user-vtk) [CMake build]: -TODO: automatic, i.e. nothing to do? +-D PKG_USER-VTK=on # enable USER-VTK package :pre + +This will autodetect the VTK library if it is installed on your system at standard locations. +Several advanced VTK options exist if you need to specify where it was installed. Run with +ccmake to see these options. [Traditional make]: From 76289cd955d1bd6fc5397fa150a66cbdd0845b3b Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Thu, 9 Aug 2018 17:50:55 -0400 Subject: [PATCH 15/51] Add LAMMPS shared library instructions for CMake --- doc/src/Python_shlib.txt | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/doc/src/Python_shlib.txt b/doc/src/Python_shlib.txt index 18775cd2fd..206f56688c 100644 --- a/doc/src/Python_shlib.txt +++ b/doc/src/Python_shlib.txt @@ -9,6 +9,8 @@ Documentation"_ld - "LAMMPS Commands"_lc :c Build LAMMPS as a shared library :h3 +Build LAMMPS as a shared library using make :h4 + Instructions on how to build LAMMPS as a shared library are given on the "Build_basics"_Build_basics.html doc page. A shared library is one that is dynamically loadable, which is what Python requires to @@ -32,4 +34,40 @@ extra libraries must also be shared libraries. If the LAMMPS shared-library build fails with an error complaining about this, see the "Build_basics"_Build_basics.html doc page. -TODO: Also include CMake info on this +Build LAMMPS as a shared library using CMake :h4 + +When using CMake the following two options are necessary to generate the LAMMPS +shared library: + +-D BUILD_LIB=on # enable building LAMMPS as a library +-D BUILD_SHARED_LIBS=on # enable building of LAMMPS shared library (both options are needed!) :pre + +What this does is create a liblammps.so which contains the majority of LAMMPS +code. The generated lmp binary also dynamically links to this library. This +means that either this liblammps.so file has to be in the same directory, a system +library path (e.g. /usr/lib64/) or in the LD_LIBRARY_PATH. + +If you want to use the shared library with Python the recommended way is to create a virtualenv and use it as +CMAKE_INSTALL_PREFIX. + +# create virtualenv +virtualenv --python=$(which python3) myenv3 +source myenv3/bin/activate :pre + +# build library +mkdir build +cd build +cmake -D PKG_PYTHON=on -D BUILD_LIB=on -D BUILD_SHARED_LIBS=on -D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV ../cmake +make -j 4 :pre + +# install into prefix +make install :pre + +This will also install the Python module into your virtualenv. Since virtualenv +doesn't change your LD_LIBRARY_PATH, you still need to add its lib64 folder to +it, which contains the installed liblammps.so. + +export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$LD_LIBRARY_PATH :pre + +Starting Python outside (!) of your build directory, but with the virtualenv +enabled and with the LD_LIBRARY_PATH set gives you access to LAMMPS via Python. From 0b523cb48e2fcb884a273b3d76474d2c19ae5c33 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Fri, 10 Aug 2018 11:38:59 +0200 Subject: [PATCH 16/51] some rewording and updates for the traditional and cmake documentation --- doc/src/Build.txt | 8 ++- doc/src/Build_basics.txt | 2 +- doc/src/Build_cmake.txt | 146 +++++++++++++++++++++++---------------- doc/src/Build_make.txt | 48 ++++++++----- doc/src/Run_basics.txt | 24 ++++--- 5 files changed, 138 insertions(+), 90 deletions(-) diff --git a/doc/src/Build.txt b/doc/src/Build.txt index 287e151c31..76aa95de55 100644 --- a/doc/src/Build.txt +++ b/doc/src/Build.txt @@ -10,9 +10,11 @@ Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Run.html :c Build LAMMPS :h2 LAMMPS can be built as an executable or library from source code via -either CMake or traditional make. As an alternative you can download -a pre-built executable file as described on the "Install"_Install.html -doc page. +either traditional makefiles (which may require manual editing) +for use with GNU make or gmake, or a build environment generated by CMake +(Unix Makefiles, Xcode, Visual Studio, KDevelop or more). As an +alternative you can download a package with pre-built executables +as described on the "Install"_Install.html doc page. "Example scripts"_Examples.html :l "Auxiliary tools"_Tools.html :l "Modify & extend LAMMPS"_Modify.html :l -"Use Python with LAMMPS"_Python.html :l +"Use Python with LAMMPS"_Python_head.html :l "Errors"_Errors.html :l +"Building the LAMMPS manual"_Manual_build.html :l :ole diff --git a/doc/src/Manual_build.txt b/doc/src/Manual_build.txt index 2be4b98960..747a55a729 100644 --- a/doc/src/Manual_build.txt +++ b/doc/src/Manual_build.txt @@ -8,7 +8,7 @@ Section"_Manual.html :c :line -Building the LAMMPS Manual :h2 +Building the LAMMPS manual :h2 Depending on how you obtained LAMMPS, the doc directory has 2 or 3 sub-directories and optionally 2 PDF files and an ePUB file: diff --git a/doc/src/Modify.txt b/doc/src/Modify.txt index 6189b9ba3e..666aaba8a7 100644 --- a/doc/src/Modify.txt +++ b/doc/src/Modify.txt @@ -1,6 +1,6 @@ "Previous Section"_Tools.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next -Section"_Python.html :c +Section"_Python_head.html :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/src/Packages_details.txt b/doc/src/Packages_details.txt index ff0ce7844c..5ab85a80c8 100644 --- a/doc/src/Packages_details.txt +++ b/doc/src/Packages_details.txt @@ -763,8 +763,8 @@ A "python"_python.html command which allow you to execute Python code from a LAMMPS input script. The code can be in a separate file or embedded in the input script itself. See the "Python call"_Python_call.html doc page for an overview of using Python from -LAMMPS in this manner and all the "Python"_Python.html doc pages for -other ways to use LAMMPS and Python together. +LAMMPS in this manner and all the "Python"_Python_head.html doc pages +for other ways to use LAMMPS and Python together. NOTE: Building with the PYTHON package assumes you have a Python shared library available on your system, which needs to be a Python 2 @@ -780,7 +780,7 @@ extras"_Build_extras.html doc page. [Supporting info:] src/PYTHON: filenames -> commands -"Python call"_Python.html +"Python call"_Python_head.html lib/python/README examples/python :ul diff --git a/doc/src/Python_call.txt b/doc/src/Python_call.txt index 621f1fe241..029c8f831c 100644 --- a/doc/src/Python_call.txt +++ b/doc/src/Python_call.txt @@ -1,5 +1,5 @@ -"Higher level section"_Python.html - "LAMMPS WWW Site"_lws - "LAMMPS -Documentation"_ld - "LAMMPS Commands"_lc :c +"Higher level section"_Python_head.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/src/Python_examples.txt b/doc/src/Python_examples.txt index 46e5fee2b9..f4b2197464 100644 --- a/doc/src/Python_examples.txt +++ b/doc/src/Python_examples.txt @@ -1,5 +1,5 @@ -"Higher level section"_Python.html - "LAMMPS WWW Site"_lws - "LAMMPS -Documentation"_ld - "LAMMPS Commands"_lc :c +"Higher level section"_Python_head.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/src/Python.txt b/doc/src/Python_head.txt similarity index 100% rename from doc/src/Python.txt rename to doc/src/Python_head.txt diff --git a/doc/src/Python_install.txt b/doc/src/Python_install.txt index 85cf267de0..97f6bf3c3a 100644 --- a/doc/src/Python_install.txt +++ b/doc/src/Python_install.txt @@ -1,5 +1,5 @@ -"Higher level section"_Python.html - "LAMMPS WWW Site"_lws - "LAMMPS -Documentation"_ld - "LAMMPS Commands"_lc :c +"Higher level section"_Python_head.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/src/Python_library.txt b/doc/src/Python_library.txt index 8d0c724a45..9a3ea93fc3 100644 --- a/doc/src/Python_library.txt +++ b/doc/src/Python_library.txt @@ -1,5 +1,5 @@ -"Higher level section"_Python.html - "LAMMPS WWW Site"_lws - "LAMMPS -Documentation"_ld - "LAMMPS Commands"_lc :c +"Higher level section"_Python_head.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/src/Python_mpi.txt b/doc/src/Python_mpi.txt index 6e0a2ce319..96c42e0d0f 100644 --- a/doc/src/Python_mpi.txt +++ b/doc/src/Python_mpi.txt @@ -1,5 +1,5 @@ -"Higher level section"_Python.html - "LAMMPS WWW Site"_lws - "LAMMPS -Documentation"_ld - "LAMMPS Commands"_lc :c +"Higher level section"_Python_head.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/src/Python_pylammps.txt b/doc/src/Python_pylammps.txt index d7baa93e2e..303ac21a27 100644 --- a/doc/src/Python_pylammps.txt +++ b/doc/src/Python_pylammps.txt @@ -1,5 +1,5 @@ -"Higher level section"_Python.html - "LAMMPS WWW Site"_lws - "LAMMPS -Documentation"_ld - "LAMMPS Commands"_lc :c +"Higher level section"_Python_head.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/src/Python_run.txt b/doc/src/Python_run.txt index a94dc07f2d..963248efce 100644 --- a/doc/src/Python_run.txt +++ b/doc/src/Python_run.txt @@ -1,5 +1,5 @@ -"Higher level section"_Python.html - "LAMMPS WWW Site"_lws - "LAMMPS -Documentation"_ld - "LAMMPS Commands"_lc :c +"Higher level section"_Python_head.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/src/Python_shlib.txt b/doc/src/Python_shlib.txt index 206f56688c..91c90d9a8f 100644 --- a/doc/src/Python_shlib.txt +++ b/doc/src/Python_shlib.txt @@ -1,5 +1,5 @@ -"Higher level section"_Python.html - "LAMMPS WWW Site"_lws - "LAMMPS -Documentation"_ld - "LAMMPS Commands"_lc :c +"Higher level section"_Python_head.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/src/Python_test.txt b/doc/src/Python_test.txt index 3d52485aa8..2bfec91bd6 100644 --- a/doc/src/Python_test.txt +++ b/doc/src/Python_test.txt @@ -1,5 +1,5 @@ -"Higher level section"_Python.html - "LAMMPS WWW Site"_lws - "LAMMPS -Documentation"_ld - "LAMMPS Commands"_lc :c +"Higher level section"_Python_head.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) diff --git a/doc/src/fix_external.txt b/doc/src/fix_external.txt index 1dec226414..dd7f7914e9 100644 --- a/doc/src/fix_external.txt +++ b/doc/src/fix_external.txt @@ -34,7 +34,7 @@ This fix allows external programs that are running LAMMPS through its "library interface"_Howto_library.html to modify certain LAMMPS properties on specific timesteps, similar to the way other fixes do. The external driver can be a "C/C++ or Fortran -program"_Howto_library.html or a "Python script"_Python.html. +program"_Howto_library.html or a "Python script"_Python_head.html. :line diff --git a/doc/src/python.txt b/doc/src/python.txt index 0c0a203ccd..54d18d2f60 100644 --- a/doc/src/python.txt +++ b/doc/src/python.txt @@ -100,7 +100,7 @@ be passed to various commands as arguments, so that the variable is evaluated during a simulation run. A broader overview of how Python can be used with LAMMPS is given on -the "Python"_Python.html doc page. There is an examples/python +the "Python"_Python_head.html doc page. There is an examples/python directory which illustrates use of the python command. :line @@ -483,8 +483,8 @@ building LAMMPS. LAMMPS must also be built as a shared library and your Python function must be able to to load the Python module in python/lammps.py that wraps the LAMMPS library interface. These are the same steps required to use Python by itself to wrap LAMMPS. -Details on these steps are explained on the "Python"_Python.html doc -page. Note that it is important that the stand-alone LAMMPS +Details on these steps are explained on the "Python"_Python_head.html +doc page. Note that it is important that the stand-alone LAMMPS executable and the LAMMPS shared library be consistent (built from the same source code files) in order for this to work. If the two have been built at different times using different source files, problems diff --git a/lib/gpu/Install.py b/lib/gpu/Install.py index 3b12db5091..d1024c0085 100644 --- a/lib/gpu/Install.py +++ b/lib/gpu/Install.py @@ -23,16 +23,17 @@ optionally copies Makefile.auto to a new Makefile.osuffix -m = use Makefile.machine as starting point, copy to Makefile.auto default machine = linux + default for -h, -a, -p, -e settings are those in -m Makefile -h = set CUDA_HOME variable in Makefile.auto to hdir hdir = path to NVIDIA Cuda software, e.g. /usr/local/cuda -a = set CUDA_ARCH variable in Makefile.auto to arch - use arch = 20 for Fermi (C2050/C2070, deprecated as of CUDA 8.0) - or GeForce GTX 580 or similar - use arch = 30 for Kepler (K10) - use arch = 35 for Kepler (K40) or GeForce GTX Titan or similar - use arch = 37 for Kepler (dual K80) - use arch = 60 for Pascal (P100) - use arch = 70 for Volta + use arch = sm_20 for Fermi (C2050/C2070, deprecated as of CUDA 8.0) + or GeForce GTX 580 or similar + use arch = sm_30 for Kepler (K10) + use arch = sm_35 for Kepler (K40) or GeForce GTX Titan or similar + use arch = sm_37 for Kepler (dual K80) + use arch = sm_60 for Pascal (P100) + use arch = sm_70 for Volta -p = set CUDA_PRECISION variable in Makefile.auto to precision use precision = double or mixed or single -e = set EXTRAMAKE variable in Makefile.auto to Makefile.lammps.esuffix @@ -47,7 +48,7 @@ Examples: make lib-gpu args="-b" # build GPU lib with default Makefile.linux make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision -make lib-gpu args="-m mpi -a 35 -p single -o mpi.mixed -b" # create new Makefile.mpi.mixed, also build GPU lib with these settings +make lib-gpu args="-m mpi -a sm_35 -p single -o mpi.mixed -b" # create new Makefile.mpi.mixed, also build GPU lib with these settings """ # print error message or help @@ -128,7 +129,7 @@ for line in lines: if hflag and words[0] == "CUDA_HOME" and words[1] == '=': line = line.replace(words[2],hdir) if aflag and words[0] == "CUDA_ARCH" and words[1] == '=': - line = line.replace(words[2],"-arch=sm_%s" % arch) + line = line.replace(words[2],"-arch=%s" % arch) if pflag and words[0] == "CUDA_PRECISION" and words[1] == '=': line = line.replace(words[2],precstr) if eflag and words[0] == "EXTRAMAKE" and words[1] == '=': diff --git a/lib/gpu/Makefile.linux b/lib/gpu/Makefile.linux index ed5b6092d3..9580bfd4ae 100644 --- a/lib/gpu/Makefile.linux +++ b/lib/gpu/Makefile.linux @@ -13,8 +13,8 @@ endif NVCC = nvcc -# Tesla CUDA -CUDA_ARCH = -arch=sm_21 +# older CUDA +#CUDA_ARCH = -arch=sm_21 # newer CUDA #CUDA_ARCH = -arch=sm_13 # older CUDA From 1f65150e16039e149881f0f5e09586e873f5d3e0 Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Wed, 15 Aug 2018 07:34:20 -0600 Subject: [PATCH 40/51] 60 -> sm_60 for GPU_ARCH --- cmake/CMakeLists.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index 1bd9eb22b1..2ee5d9e6d6 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -834,7 +834,7 @@ if(PKG_GPU) endif() option(CUDPP_OPT "Enable CUDPP_OPT" ON) - set(GPU_ARCH "30" CACHE STRING "LAMMPS GPU CUDA SM architecture (e.g. 60)") + set(GPU_ARCH "sm_30" CACHE STRING "LAMMPS GPU CUDA SM architecture (e.g. sm_60)") file(GLOB GPU_LIB_CU ${LAMMPS_LIB_SOURCE_DIR}/gpu/*.cu ${CMAKE_CURRENT_SOURCE_DIR}/gpu/*.cu) list(REMOVE_ITEM GPU_LIB_CU ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_pppm.cu) @@ -848,10 +848,10 @@ if(PKG_GPU) endif() cuda_compile_cubin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS - -DUNIX -O3 -Xptxas -v --use_fast_math -DNV_KERNEL -DUCL_CUDADR -arch=sm_${GPU_ARCH} -D_${GPU_PREC_SETTING}) + -DUNIX -O3 -Xptxas -v --use_fast_math -DNV_KERNEL -DUCL_CUDADR -arch=${GPU_ARCH} -D_${GPU_PREC_SETTING}) cuda_compile(GPU_OBJS ${GPU_LIB_CUDPP_CU} OPTIONS $<$:-Xcompiler=-fPIC> - -DUNIX -O3 -Xptxas -v --use_fast_math -DUCL_CUDADR -arch=sm_${GPU_ARCH} -D_${GPU_PREC_SETTING}) + -DUNIX -O3 -Xptxas -v --use_fast_math -DUCL_CUDADR -arch=${GPU_ARCH} -D_${GPU_PREC_SETTING}) foreach(CU_OBJ ${GPU_GEN_OBJS}) get_filename_component(CU_NAME ${CU_OBJ} NAME_WE) @@ -1160,7 +1160,7 @@ endif() if(PKG_GPU) message(STATUS "GPU Api: ${GPU_API}") if(GPU_API_DEFINE STREQUAL "CUDA") - message(STATUS "GPU Arch: sm_${GPU_ARCH}") + message(STATUS "GPU Arch: ${GPU_ARCH}") elseif(GPU_API_DEFINE STREQUAL "OPENCL") message(STATUS "OCL Tune: ${OCL_TUNE}") endif() From 6c904102600abb5c708b7a3351b31e95741e078c Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Wed, 15 Aug 2018 07:44:36 -0600 Subject: [PATCH 41/51] one more file I forgot to commit --- doc/src/Intro_nonfeatures.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/src/Intro_nonfeatures.txt b/doc/src/Intro_nonfeatures.txt index 87ab42e2ac..f7ca6b307e 100644 --- a/doc/src/Intro_nonfeatures.txt +++ b/doc/src/Intro_nonfeatures.txt @@ -68,11 +68,11 @@ page"_http://lammps.sandia.gov/viz.html page of the LAMMPS website for visualization packages that can use LAMMPS output data. :l Plotting: See the next bullet about Pizza.py as well as the -"Python"_Python_head.html doc page for examples of plotting LAMMPS output. -Scripts provided with the {python} tool in the tools directory will -extract and massage data in log and dump files to make it easier to -analyze and plot. See the "Tools"_Tools.html doc page for more -discussion of the various tools. :l +"Python"_Python_head.html doc page for examples of plotting LAMMPS +output. Scripts provided with the {python} tool in the tools +directory will extract and massage data in log and dump files to make +it easier to analyze and plot. See the "Tools"_Tools.html doc page +for more discussion of the various tools. :l Pizza.py: Our group has also written a separate toolkit called "Pizza.py"_http://pizza.sandia.gov which can do certain kinds of From 6eededb190eda084fc24dea5e70763631e201cab Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Wed, 15 Aug 2018 07:45:52 -0600 Subject: [PATCH 42/51] one more tweak --- doc/src/Intro_nonfeatures.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/src/Intro_nonfeatures.txt b/doc/src/Intro_nonfeatures.txt index f7ca6b307e..2acf6db71f 100644 --- a/doc/src/Intro_nonfeatures.txt +++ b/doc/src/Intro_nonfeatures.txt @@ -55,9 +55,9 @@ info on how to add your own analysis code or algorithms to LAMMPS. For post-processing, LAMMPS output such as "dump file snapshots"_dump.html can be converted into formats used by other MD or post-processing codes. Some post-processing tools packaged with -LAMMPS will do these conversions. Scripts provided with the {python} -tool in the tools directory can extract and massage data in dump files -to make it easier to import into other programs. See the +LAMMPS will do these conversions. Scripts provided in the +tools/python directory can extract and massage data in dump files to +make it easier to import into other programs. See the "Tools"_Tools.html doc page for details on these various options. :l Visualization: LAMMPS can produce JPG or PNG snapshot images From 1823fc2bd183f661ec11fb394fdd38758848d204 Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Wed, 15 Aug 2018 07:50:10 -0600 Subject: [PATCH 43/51] commands.txt -> commands_list.txt to avoid conflict with Commands.txt --- doc/src/Manual.txt | 2 +- doc/src/{commands.txt => commands_list.txt} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename doc/src/{commands.txt => commands_list.txt} (100%) diff --git a/doc/src/Manual.txt b/doc/src/Manual.txt index ca30f32311..c4dbf0415e 100644 --- a/doc/src/Manual.txt +++ b/doc/src/Manual.txt @@ -91,7 +91,7 @@ every LAMMPS command. :name: index :hidden: - commands + commands_list fixes computes pairs diff --git a/doc/src/commands.txt b/doc/src/commands_list.txt similarity index 100% rename from doc/src/commands.txt rename to doc/src/commands_list.txt From 95bfc3b536aa019b8f22d44c850da0080e73ac4a Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Wed, 15 Aug 2018 07:54:17 -0600 Subject: [PATCH 44/51] one more entry to lammps.book --- doc/src/lammps.book | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/lammps.book b/doc/src/lammps.book index 66b3217561..c961004f83 100644 --- a/doc/src/lammps.book +++ b/doc/src/lammps.book @@ -111,7 +111,7 @@ Modify_region.html Modify_body.html Modify_thermo.html Modify_variable.html -Python.html +Python_head.html Python_overview.html Python_run.html Python_shlib.html From 60c9477e964c68fe012817f9db53223379871d15 Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Wed, 15 Aug 2018 10:50:51 -0400 Subject: [PATCH 45/51] Add option validation and remove extra variables in CMakeLists.txt --- cmake/CMakeLists.txt | 89 +++++++++++++++++++++++++++++++------------- 1 file changed, 64 insertions(+), 25 deletions(-) diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index 2ee5d9e6d6..b75c029a51 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -17,6 +17,32 @@ file(GLOB LIB_SOURCES ${LAMMPS_SOURCE_DIR}/*.cpp) file(GLOB LMP_SOURCES ${LAMMPS_SOURCE_DIR}/main.cpp) list(REMOVE_ITEM LIB_SOURCES ${LMP_SOURCES}) +# Utility functions +function(list_to_bulletpoints result) + list(REMOVE_AT ARGV 0) + set(temp "") + foreach(item ${ARGV}) + set(temp "${temp}* ${item}\n") + endforeach() + set(${result} "${temp}" PARENT_SCOPE) +endfunction(list_to_bulletpoints) + +function(validate_option name values) + string(TOLOWER ${${name}} needle_lower) + string(TOUPPER ${${name}} needle_upper) + list(FIND ${values} ${needle_lower} IDX_LOWER) + list(FIND ${values} ${needle_upper} IDX_UPPER) + if(${IDX_LOWER} LESS 0 AND ${IDX_UPPER} LESS 0) + list_to_bulletpoints(POSSIBLE_VALUE_LIST ${${values}}) + message(FATAL_ERROR "\n########################################################################\n" + "Invalid value '${${name}}' for option '${name}'\n" + "\n" + "Possible values are:\n" + "${POSSIBLE_VALUE_LIST}" + "########################################################################") + endif() +endfunction(validate_option) + # Cmake modules/macros are in a subdirectory to keep this file cleaner set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/Modules) @@ -131,11 +157,14 @@ else() list(APPEND LAMMPS_LINK_LIBS mpi_stubs) endif() + set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS size limit") -set_property(CACHE LAMMPS_SIZES PROPERTY STRINGS smallbig bigbig smallsmall) -string(TOUPPER ${LAMMPS_SIZES} LAMMPS_SIZES_DEFINE) -add_definitions(-DLAMMPS_${LAMMPS_SIZES_DEFINE}) -set(LAMMPS_API_DEFINES "${LAMMPS_API_DEFINES} -DLAMMPS_${LAMMPS_SIZES_DEFINE}") +set(LAMMPS_SIZES_VALUES smallbig bigbig smallsmall) +set_property(CACHE LAMMPS_SIZES PROPERTY STRINGS ${LAMMPS_SIZES_VALUES}) +validate_option(LAMMPS_SIZES LAMMPS_SIZES_VALUES) +string(TOUPPER ${LAMMPS_SIZES} LAMMPS_SIZES) +add_definitions(-DLAMMPS_${LAMMPS_SIZES}) +set(LAMMPS_API_DEFINES "${LAMMPS_API_DEFINES} -DLAMMPS_${LAMMPS_SIZES}") # posix_memalign is not available on Windows if(NOT ${CMAKE_SYSTEM_NAME} STREQUAL "Windows") @@ -219,7 +248,9 @@ if(PKG_KSPACE) else() set(FFT "KISS" CACHE STRING "FFT library for KSPACE package") endif() - set_property(CACHE FFT PROPERTY STRINGS KISS ${FFTW} MKL) + set(FFT_VALUES KISS ${FFTW} MKL) + set_property(CACHE FFT PROPERTY STRINGS ${FFT_VALUES}) + validate_option(FFT FFT_VALUES) if(NOT FFT STREQUAL "KISS") find_package(${FFT} REQUIRED) if(NOT FFT STREQUAL "FFTW3F") @@ -233,10 +264,12 @@ if(PKG_KSPACE) add_definitions(-DFFT_KISS) endif() set(FFT_PACK "array" CACHE STRING "Optimization for FFT") - set_property(CACHE FFT_PACK PROPERTY STRINGS array pointer memcpy) + set(FFT_PACK_VALUES array pointer memcpy) + set_property(CACHE FFT_PACK PROPERTY STRINGS ${FFT_PACK_VALUES}) + validate_option(FFT_PACK FFT_PACK_VALUES) if(NOT FFT_PACK STREQUAL "array") - string(TOUPPER ${FFT_PACK} FFT_PACK_DEFINE) - add_definitions(-DFFT_PACK_${FFT_PACK_DEFINE}) + string(TOUPPER ${FFT_PACK} FFT_PACK) + add_definitions(-DFFT_PACK_${FFT_PACK}) endif() endif() @@ -747,9 +780,9 @@ if(PKG_USER-INTEL) endif() set(INTEL_ARCH "cpu" CACHE STRING "Architectures used by USER-INTEL (cpu or knl)") - set_property(CACHE INTEL_ARCH PROPERTY STRINGS cpu knl) - - + set(INTEL_ARCH_VALUES cpu knl) + set_property(CACHE INTEL_ARCH PROPERTY STRINGS ${INTEL_ARCH_VALUES}) + validate_option(INTEL_ARCH INTEL_ARCH_VALUES) if(INTEL_ARCH STREQUAL "knl") set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -xHost -qopenmp -qoffload") @@ -808,25 +841,29 @@ if(PKG_GPU) ${GPU_SOURCES_DIR}/fix_gpu.cpp) set(GPU_API "opencl" CACHE STRING "API used by GPU package") - set_property(CACHE GPU_API PROPERTY STRINGS opencl cuda) - string(TOUPPER ${GPU_API} GPU_API_DEFINE) + set(GPU_API_VALUES opencl cuda) + set_property(CACHE GPU_API PROPERTY STRINGS ${GPU_API_VALUES}) + validate_option(GPU_API GPU_API_VALUES) + string(TOUPPER ${GPU_API} GPU_API) set(GPU_PREC "mixed" CACHE STRING "LAMMPS GPU precision") - set_property(CACHE GPU_PREC PROPERTY STRINGS double mixed single) - string(TOUPPER ${GPU_PREC} GPU_PREC_DEFINE) + set(GPU_PREC_VALUES double mixed single) + set_property(CACHE GPU_PREC PROPERTY STRINGS ${GPU_PREC_VALUES}) + validate_option(GPU_PREC GPU_PREC_VALUES) + string(TOUPPER ${GPU_PREC} GPU_PREC) - if(GPU_PREC_DEFINE STREQUAL "DOUBLE") + if(GPU_PREC STREQUAL "DOUBLE") set(GPU_PREC_SETTING "DOUBLE_DOUBLE") - elseif(GPU_PREC_DEFINE STREQUAL "MIXED") + elseif(GPU_PREC STREQUAL "MIXED") set(GPU_PREC_SETTING "SINGLE_DOUBLE") - elseif(GPU_PREC_DEFINE STREQUAL "SINGLE") + elseif(GPU_PREC STREQUAL "SINGLE") set(GPU_PREC_SETTING "SINGLE_SINGLE") endif() file(GLOB GPU_LIB_SOURCES ${LAMMPS_LIB_SOURCE_DIR}/gpu/*.cpp) file(MAKE_DIRECTORY ${LAMMPS_LIB_BINARY_DIR}/gpu) - if(GPU_API_DEFINE STREQUAL "CUDA") + if(GPU_API STREQUAL "CUDA") find_package(CUDA REQUIRED) find_program(BIN2C bin2c) if(NOT BIN2C) @@ -882,11 +919,13 @@ if(PKG_GPU) target_include_directories(nvc_get_devices PRIVATE ${CUDA_INCLUDE_DIRS}) - elseif(GPU_API_DEFINE STREQUAL "OPENCL") + elseif(GPU_API STREQUAL "OPENCL") find_package(OpenCL REQUIRED) set(OCL_TUNE "generic" CACHE STRING "OpenCL Device Tuning") - set_property(CACHE OCL_TUNE PROPERTY STRINGS intel fermi kepler cypress generic) - string(TOUPPER ${OCL_TUNE} OCL_TUNE_DEFINE) + set(OCL_TUNE_VALUES intel fermi kepler cypress generic) + set_property(CACHE OCL_TUNE PROPERTY STRINGS ${OCL_TUNE_VALUES}) + validate_option(OCL_TUNE OCL_TUNE_VALUES) + string(TOUPPER ${OCL_TUNE} OCL_TUNE) include(OpenCLUtils) set(OCL_COMMON_HEADERS ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_preprocessor.h ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_aux_fun1.h) @@ -908,7 +947,7 @@ if(PKG_GPU) add_library(gpu STATIC ${GPU_LIB_SOURCES}) target_link_libraries(gpu ${OpenCL_LIBRARIES}) target_include_directories(gpu PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/gpu ${OpenCL_INCLUDE_DIRS}) - target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -D${OCL_TUNE_DEFINE}_OCL -DMPI_GERYON -DUCL_NO_EXIT) + target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -D${OCL_TUNE}_OCL -DMPI_GERYON -DUCL_NO_EXIT) target_compile_definitions(gpu PRIVATE -DUSE_OPENCL) list(APPEND LAMMPS_LINK_LIBS gpu) @@ -1159,9 +1198,9 @@ if(BUILD_MPI) endif() if(PKG_GPU) message(STATUS "GPU Api: ${GPU_API}") - if(GPU_API_DEFINE STREQUAL "CUDA") + if(GPU_API STREQUAL "CUDA") message(STATUS "GPU Arch: ${GPU_ARCH}") - elseif(GPU_API_DEFINE STREQUAL "OPENCL") + elseif(GPU_API STREQUAL "OPENCL") message(STATUS "OCL Tune: ${OCL_TUNE}") endif() message(STATUS "GPU Precision: ${GPU_PREC}") From 3bb8fefb121c8e8abbb3cd41e80218722cfde880 Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Wed, 15 Aug 2018 10:57:45 -0400 Subject: [PATCH 46/51] Little tweak to error message --- cmake/CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index b75c029a51..8d2038aea8 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -35,7 +35,7 @@ function(validate_option name values) if(${IDX_LOWER} LESS 0 AND ${IDX_UPPER} LESS 0) list_to_bulletpoints(POSSIBLE_VALUE_LIST ${${values}}) message(FATAL_ERROR "\n########################################################################\n" - "Invalid value '${${name}}' for option '${name}'\n" + "Invalid value '${${name}}' for option ${name}\n" "\n" "Possible values are:\n" "${POSSIBLE_VALUE_LIST}" From 1776ade72e216389915536295a296aab6f95530e Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Wed, 15 Aug 2018 11:23:02 -0400 Subject: [PATCH 47/51] Update CMake README.md --- cmake/README.md | 120 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 99 insertions(+), 21 deletions(-) diff --git a/cmake/README.md b/cmake/README.md index b6644ffda9..a401d5296e 100644 --- a/cmake/README.md +++ b/cmake/README.md @@ -62,7 +62,7 @@ should get you started. git clone https://github.com/lammps/lammps.git mkdir lammps/build cd lammps/build -cmake ../cmake [-DOPTION_A=VALUE_A -DOPTION_B=VALUE_B ...] +cmake [-D OPTION_A=VALUE_A -D OPTION_B=VALUE_B ...] ../cmake make ``` @@ -174,7 +174,7 @@ presets can be found in the `cmake/presets` folder. # build LAMMPS with all "standard" packages which don't use libraries and enable GPU package mkdir build cd build -cmake -C ../cmake/presets/std_nolib.cmake ../cmake -DPKG_GPU=on +cmake -C ../cmake/presets/std_nolib.cmake -D PKG_GPU=on ../cmake ``` # Reference @@ -265,6 +265,16 @@ cmake -C ../cmake/presets/std_nolib.cmake ../cmake -DPKG_GPU=on + + BUILD_LIB + control whether to build LAMMPS as a library + +
+
off (default)
+
on
+
+ + BUILD_SHARED_LIBS control whether to build LAMMPS as a shared-library @@ -315,8 +325,8 @@ cmake -C ../cmake/presets/std_nolib.cmake ../cmake -DPKG_GPU=on `mpicxx` in your path and use this MPI implementation.
-
off (default)
-
on
+
on (default, if found)
+
off
@@ -325,8 +335,8 @@ cmake -C ../cmake/presets/std_nolib.cmake ../cmake -DPKG_GPU=on control whether to build LAMMPS with OpenMP support.
-
off (default)
-
on
+
on (default, if found)
+
off
@@ -1271,7 +1281,7 @@ providing the identical features and USER interface.

-
KISSFFT
+
KISS
FFTW3
FFTW2
MKL
@@ -1279,13 +1289,13 @@ providing the identical features and USER interface.

- PACK_ARRAY + FFT_PACK Optimization for FFT
-
PACK_ARRAY
-
PACK_POINTER
-
PACK_MEMCPY
+
array (default)
+
pointer
+
memcpy
@@ -1377,6 +1387,29 @@ TODO ### PYTHON Package +### USER-INTEL Package + + + + + + + + + + + + + + + + +
OptionDescriptionValues
INTEL_ARCHTarget architecture for USER-INTEL package +
+
cpu (default)
+
knl
+
+
### GPU Package The GPU package builds a support library which can either use OpenCL or CUDA as @@ -1396,8 +1429,8 @@ target API. API used by GPU package
-
OpenCL (default)
-
CUDA
+
opencl (default)
+
cuda
@@ -1406,9 +1439,9 @@ target API. Precision size used by GPU package kernels
-
SINGLE_DOUBLE
-
SINGLE_SINGLE
-
DOUBLE_DOUBLE
+
mixed (default)
+
single
+
double
@@ -1517,6 +1550,16 @@ Requires a Eigen3 installation + + WITH_JPEG + Enables/Disable JPEG support in LAMMPS + +
+
yes (default, if found)
+
no
+
+ + JPEG_INCLUDE_DIR @@ -1544,6 +1587,16 @@ Requires a Eigen3 installation + + WITH_PNG + Enables/Disable PNG support in LAMMPS + +
+
yes (default, if found)
+
no
+
+ + PNG_INCLUDE_DIR @@ -1572,6 +1625,16 @@ requires `gzip` to be in your `PATH` + + WITH_GZIP + Enables/Disable GZIP support in LAMMPS + +
+
yes (default, if found)
+
no
+
+ + GZIP_EXECUTABLE @@ -1594,6 +1657,16 @@ requires `ffmpeg` to be in your `PATH` + + WITH_FFMPEG + Enables/Disable FFMPEG support in LAMMPS + +
+
yes (default, if found)
+
no
+
+ + FFMPEG_EXECUTABLE @@ -1606,8 +1679,13 @@ requires `ffmpeg` to be in your `PATH` ## Compilers -By default, `cmake` will use your environment C/C++/Fortran compilers for a build. It uses the `CC`, `CXX` and `FC` environment variables to detect which compilers should be used. However, these values -will be cached after the first run of `cmake`. Subsequent runs of `cmake` will ignore changes in these environment variables. To ensure the correct values are used you avoid the cache by setting the `CMAKE_C_COMPILER`, `CMAKE_CXX_COMPILER`, `CMAKE_Fortran_COMPILER` options directly. +By default, `cmake` will use your environment C/C++/Fortran compilers for a +build. It uses the `CC`, `CXX` and `FC` environment variables to detect which +compilers should be used. However, these values will be cached after the first +run of `cmake`. Subsequent runs of `cmake` will ignore changes in these +environment variables. To ensure the correct values are used you avoid the +cache by setting the `CMAKE_C_COMPILER`, `CMAKE_CXX_COMPILER`, +`CMAKE_Fortran_COMPILER` options directly. @@ -1643,20 +1721,20 @@ will be cached after the first run of `cmake`. Subsequent runs of `cmake` will i ### Building with GNU Compilers ```bash -cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran +cmake -D CMAKE_C_COMPILER=gcc -D CMAKE_CXX_COMPILER=g++ -D CMAKE_Fortran_COMPILER=gfortran ../cmake ``` ### Building with Intel Compilers ```bash -cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort +cmake -D CMAKE_C_COMPILER=icc -D CMAKE_CXX_COMPILER=icpc -D CMAKE_Fortran_COMPILER=ifort ../cmake ``` ### Building with LLVM/Clang Compilers ```bash -cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang +cmake -D CMAKE_C_COMPILER=clang -D CMAKE_CXX_COMPILER=clang++ -D CMAKE_Fortran_COMPILER=flang ../cmake ``` From 023c8e5d6ee02a93f0d37e0bae7b5d5cfac68557 Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Wed, 15 Aug 2018 11:31:22 -0400 Subject: [PATCH 48/51] Correct option values to lower case in README.md --- cmake/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/cmake/README.md b/cmake/README.md index a401d5296e..85375cd2aa 100644 --- a/cmake/README.md +++ b/cmake/README.md @@ -1450,12 +1450,12 @@ target API. From c9131cf1de48a52fc2ad86dd67ffcbd91eaeaf9a Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Wed, 15 Aug 2018 13:54:37 -0600 Subject: [PATCH 49/51] drop FFTW2 support, and change doc pages --- doc/src/Build_settings.txt | 32 ++++++++------------------- src/KSPACE/fft3d.cpp | 14 +++++++++++- src/KSPACE/fft3d.h | 44 +++++++++++++++++++------------------- 3 files changed, 44 insertions(+), 46 deletions(-) diff --git a/doc/src/Build_settings.txt b/doc/src/Build_settings.txt index 6c36420f77..db281c0857 100644 --- a/doc/src/Build_settings.txt +++ b/doc/src/Build_settings.txt @@ -33,27 +33,25 @@ LAMMPS can use them if they are available on your system. [CMake variables]: --D FFT=value # KISS or FFTW3 or FFTW2 or MKL, default is FFTW3 if found, else KISS +-D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS -D FFT_SINGLE=value # yes or no (default), no = double precision -D FFT_PACK=value # array (default) or pointer or memcpy :pre -NOTE: The values for the FFT variable must be in upper-case. -This is an exception to the rule that all CMake variables can -be specified with lower-case values. +NOTE: The values for the FFT variable must be in upper-case. This is +an exception to the rule that all CMake variables can be specified +with lower-case values. Usually these settings are all that is needed. If CMake cannot find the FFT library, you can set these variables: -D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files -D FFTW3_LIBRARIES=path # path to FFTW3 libraries --D FFTW2_INCLUDE_DIRS=path # ditto for FFTW2 --D FFTW2_LIBRARIES=path -D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library -D MKL_LIBRARIES=path :pre [Makefile.machine settings]: -FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW2, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS +FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS # default is KISS if not specified FFT_INC = -DFFT_SINGLE # do not specify for double precision FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY :pre @@ -63,8 +61,6 @@ FFT_INC = -I/usr/local/include FFT_PATH = -L/usr/local/lib FFT_LIB = -lfftw3 # FFTW3 double precision FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision -FFT_LIB = -lfftw # FFTW2 double precision, or -ldfftw -FFT_LIB = -lsfftw # FFTW2 single precision FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compier :pre @@ -89,13 +85,9 @@ details. FFTW is a fast, portable FFT library that should also work on any platform and can be faster than the KISS FFT library. You can -download it from "www.fftw.org"_http://www.fftw.org. Both the -(obsolete) legacy version 2.1.X and the newer 3.X versions are -supported. +download it from "www.fftw.org"_http://www.fftw.org. LAMMPS requires +version 3.X; the legacy version 2.1.X is no longer supported. -NOTE: FFTW2 has not been updated since 1999 and has been declared -obsolete by its developers. - Building FFTW for your box should be as simple as ./configure; make; make install. The install command typically requires root privileges (e.g. invoke it via sudo), unless you specify a local directory with @@ -116,8 +108,8 @@ error is less than the difference in precision. Using the -DFFT_SINGLE setting trades off a little accuracy for reduced memory use and parallel communication costs for transposing 3d FFT data. -When using -DFFT_SINGLE with FFTW3 or FFTW2, you may need to build the -FFTW library a second time with support for single-precision. +When using -DFFT_SINGLE with FFTW3 you may need to build the FFTW +library a second time with support for single-precision. For FFTW3, do the following, which should produce the additional library libfftw3f.a @@ -125,12 +117,6 @@ library libfftw3f.a make clean ./configure --enable-single; make; make install :pre -For FFTW2, do the following, which should produce the additional -library libsfftw.a - -make clean -./configure --enable-float --enable-type-prefix; make; make install :pre - Performing 3d FFTs requires communication to transpose the 3d FFT grid. The data packing/unpacking for this can be done in one of 3 modes (ARRAY, POINTER, MEMCPY) as set by the FFT_PACK syntax above. diff --git a/src/KSPACE/fft3d.cpp b/src/KSPACE/fft3d.cpp index db44feabcc..7d3c8c83f2 100644 --- a/src/KSPACE/fft3d.cpp +++ b/src/KSPACE/fft3d.cpp @@ -104,11 +104,13 @@ void fft_3d(FFT_DATA *in, FFT_DATA *out, int flag, struct fft_plan_3d *plan) DftiComputeForward(plan->handle_fast,data); else DftiComputeBackward(plan->handle_fast,data); + /* #elif defined(FFT_FFTW2) if (flag == -1) fftw(plan->plan_fast_forward,total/length,data,1,length,NULL,0,0); else - fftw(plan->plan_fast_backward,total/length,data,1,length,NULL,0,0); + fftw(plan->plan_fast_backward,total/length,data,1,length,NULL,0,0); + */ #elif defined(FFT_FFTW3) if (flag == -1) theplan=plan->plan_fast_forward; @@ -143,11 +145,13 @@ void fft_3d(FFT_DATA *in, FFT_DATA *out, int flag, struct fft_plan_3d *plan) DftiComputeForward(plan->handle_mid,data); else DftiComputeBackward(plan->handle_mid,data); + /* #elif defined(FFT_FFTW2) if (flag == -1) fftw(plan->plan_mid_forward,total/length,data,1,length,NULL,0,0); else fftw(plan->plan_mid_backward,total/length,data,1,length,NULL,0,0); + */ #elif defined(FFT_FFTW3) if (flag == -1) theplan=plan->plan_mid_forward; @@ -182,11 +186,13 @@ void fft_3d(FFT_DATA *in, FFT_DATA *out, int flag, struct fft_plan_3d *plan) DftiComputeForward(plan->handle_slow,data); else DftiComputeBackward(plan->handle_slow,data); + /* #elif defined(FFT_FFTW2) if (flag == -1) fftw(plan->plan_slow_forward,total/length,data,1,length,NULL,0,0); else fftw(plan->plan_slow_backward,total/length,data,1,length,NULL,0,0); + */ #elif defined(FFT_FFTW3) if (flag == -1) theplan=plan->plan_slow_forward; @@ -520,6 +526,7 @@ struct fft_plan_3d *fft_3d_create_plan( (out_khi-out_klo+1); } + /* #elif defined(FFT_FFTW2) plan->plan_fast_forward = @@ -561,6 +568,7 @@ struct fft_plan_3d *fft_3d_create_plan( plan->normnum = (out_ihi-out_ilo+1) * (out_jhi-out_jlo+1) * (out_khi-out_klo+1); } + */ #elif defined(FFT_FFTW3) plan->plan_fast_forward = @@ -660,6 +668,7 @@ void fft_3d_destroy_plan(struct fft_plan_3d *plan) DftiFreeDescriptor(&(plan->handle_fast)); DftiFreeDescriptor(&(plan->handle_mid)); DftiFreeDescriptor(&(plan->handle_slow)); + /* #elif defined(FFT_FFTW2) if (plan->plan_slow_forward != plan->plan_fast_forward && plan->plan_slow_forward != plan->plan_mid_forward) { @@ -672,6 +681,7 @@ void fft_3d_destroy_plan(struct fft_plan_3d *plan) } fftw_destroy_plan(plan->plan_fast_forward); fftw_destroy_plan(plan->plan_fast_backward); + */ #elif defined(FFT_FFTW3) FFTW_API(destroy_plan)(plan->plan_slow_forward); FFTW_API(destroy_plan)(plan->plan_slow_backward); @@ -809,6 +819,7 @@ void fft_1d_only(FFT_DATA *data, int nsize, int flag, struct fft_plan_3d *plan) DftiComputeBackward(plan->handle_mid,data); DftiComputeBackward(plan->handle_slow,data); } + /* #elif defined(FFT_FFTW2) if (flag == -1) { fftw(plan->plan_fast_forward,total1/length1,data,1,0,NULL,0,0); @@ -819,6 +830,7 @@ void fft_1d_only(FFT_DATA *data, int nsize, int flag, struct fft_plan_3d *plan) fftw(plan->plan_mid_backward,total2/length2,data,1,0,NULL,0,0); fftw(plan->plan_slow_backward,total3/length3,data,1,0,NULL,0,0); } + */ #elif defined(FFT_FFTW3) FFTW_API(plan) theplan; if (flag == -1) diff --git a/src/KSPACE/fft3d.h b/src/KSPACE/fft3d.h index ab3bca8358..a51818d986 100644 --- a/src/KSPACE/fft3d.h +++ b/src/KSPACE/fft3d.h @@ -24,7 +24,7 @@ typedef float FFT_SCALAR; typedef double FFT_SCALAR; #endif -// set default fftw library. switch to FFT_FFTW3 when convenient. +// if user set FFTW, it means FFTW3 #ifdef FFT_FFTW #define FFT_FFTW3 @@ -41,13 +41,13 @@ typedef double FFT_SCALAR; typedef float _Complex FFT_DATA; #define FFT_MKL_PREC DFTI_SINGLE -#elif defined(FFT_FFTW2) -#if defined(FFTW_SIZE) -#include "sfftw.h" -#else -#include "fftw.h" -#endif -typedef FFTW_COMPLEX FFT_DATA; +//#elif defined(FFT_FFTW2) +//#if defined(FFTW_SIZE) +//#include "sfftw.h" +//#else +//#include "fftw.h" +//#endif +//typedef FFTW_COMPLEX FFT_DATA; #elif defined(FFT_FFTW3) #include "fftw3.h" @@ -82,13 +82,13 @@ typedef struct kiss_fft_state* kiss_fft_cfg; typedef double _Complex FFT_DATA; #define FFT_MKL_PREC DFTI_DOUBLE -#elif defined(FFT_FFTW2) -#if defined(FFTW_SIZE) -#include "dfftw.h" -#else -#include "fftw.h" -#endif -typedef FFTW_COMPLEX FFT_DATA; +//#elif defined(FFT_FFTW2) +//#if defined(FFTW_SIZE) +//#include "dfftw.h" +//#else +//#include "fftw.h" +//#endif +//typedef FFTW_COMPLEX FFT_DATA; #elif defined(FFT_FFTW3) #include "fftw3.h" @@ -139,13 +139,13 @@ struct fft_plan_3d { DFTI_DESCRIPTOR *handle_fast; DFTI_DESCRIPTOR *handle_mid; DFTI_DESCRIPTOR *handle_slow; -#elif defined(FFT_FFTW2) - fftw_plan plan_fast_forward; - fftw_plan plan_fast_backward; - fftw_plan plan_mid_forward; - fftw_plan plan_mid_backward; - fftw_plan plan_slow_forward; - fftw_plan plan_slow_backward; +//#elif defined(FFT_FFTW2) +// fftw_plan plan_fast_forward; +// fftw_plan plan_fast_backward; +// fftw_plan plan_mid_forward; +// fftw_plan plan_mid_backward; +//fftw_plan plan_slow_forward; +//fftw_plan plan_slow_backward; #elif defined(FFT_FFTW3) FFTW_API(plan) plan_fast_forward; FFTW_API(plan) plan_fast_backward; From 9e154abba01c34a03c9679cc3f16c50453b67d39 Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Wed, 15 Aug 2018 14:55:48 -0600 Subject: [PATCH 50/51] remove pre-install of 3 default packages from docs --- doc/src/Build_package.txt | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/src/Build_package.txt b/doc/src/Build_package.txt index 45626dbbae..dc8918c884 100644 --- a/doc/src/Build_package.txt +++ b/doc/src/Build_package.txt @@ -121,10 +121,14 @@ right thing. 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. -When you download a LAMMPS tarball, three packages are pre-installed -in the src directory: KSPACE, MANYBODY, MOLECULE. This is because -they are so commonly used. When you download LAMMPS source files from -the Git or SVN repositories, no packages are pre-installed. +When you download a LAMMPS tarball or download LAMMPS source files +from the Git or SVN repositories, no packages are pre-installed in the +src directory. + +NOTE: Prior to Aug 2018, if you downloaded a tarball, 3 packages +(KSPACE, MANYBODY, MOLECULE) were pre-installed in the src directory. +That is no longer the case, so that CMake will build as-is without the +need to un-install those packages. :line From 46f1e63a196dace70150bb50297ef279447706b2 Mon Sep 17 00:00:00 2001 From: "Steven J. Plimpton" Date: Wed, 15 Aug 2018 15:14:01 -0600 Subject: [PATCH 51/51] update to Authors for CMake addition --- doc/src/Intro_authors.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/src/Intro_authors.txt b/doc/src/Intro_authors.txt index 8bb0fa9c22..06c86f6e3c 100644 --- a/doc/src/Intro_authors.txt +++ b/doc/src/Intro_authors.txt @@ -63,6 +63,7 @@ Jim Belak and Roy Pollock (LLNL) :ul Here is a timeline for when various individuals contributed to a new feature or command or tool added to LAMMPS: +Aug18 : CMake build option for LAMMPS : Christoph Junghans (LANL), Richard Berger, and Axel Kohlmeyer (Temple U) Jul18 : DEM polygonal and polyhedron particles : Trung Nguyen (Northwestern U) Jun18 : SPIN package : Julien Tranchida (Sandia and CEA) Jun18 : compute entropy/atom : Pablo Piaggi (EPLF, Switzerland)
Tuning target for OpenCL driver code
-
GENERIC (default)
-
INTEL (Intel CPU)
-
PHI (Intel Xeon Phi)
-
FERMI (NVIDIA)
-
KEPLER (NVIDIA)
-
CYPRESS (AMD)
+
generic (default)
+
intel (Intel CPU)
+
phi (Intel Xeon Phi)
+
fermi (NVIDIA)
+
kepler (NVIDIA)
+
cypress (AMD)