Merge branch 'collected-small-changes' into doc-reorg-start

"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

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

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

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

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.

:line

:link(Jorgensen1)

:link(Jorgensen5)

[(Jorgensen)] Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem

Phys, 79, 926 (1983).