lammps/doc

LAMMPS Documentation

Depending on how you obtained LAMMPS, this 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)
utils           utilities 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

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" or by "make pdf", respectively.  This requires various tools
including the Python documentation processing tool Sphinx, which the
build process will attempt to download and install on your system into
a python virtual environment, if not already available.  The PDF file
will require a working LaTeX installation with several add-on packages
in addition to the Python/Sphinx setup.  See more details below.

----------------

The generation of all documentation is managed by the Makefile in this
dir.

Options:

make html         # generate HTML in html dir using Sphinx
make pdf          # generate 2 PDF files (Manual.pdf,Developer.pdf)
                  #   in this dir via Sphinx and PDFLaTeX
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

----------------

Installing prerequisites for HTML build

To run the HTML documention build toolchain, Python 3 and virtualenv
have to be installed.  Here are instructions for common setups:

# Ubuntu

sudo apt-get install python-virtualenv

# Fedora (up to version 21)
# Red Hat Enterprise Linux or CentOS (up to version 7.x)

sudo yum install python3-virtualenv

# Fedora (since version 22)

sudo dnf install python3-virtualenv

# MacOS X

## Python 3

Download the latest Python 3 MacOS X package from
https://www.python.org and install it.  This will install both Python
3 and pip3.

## virtualenv

Once Python 3 is installed, open a Terminal and type

pip3 install virtualenv

This will install virtualenv from the Python Package Index.

----------------

Installing prerequisites for PDF build

Same as for HTML plus a compatible LaTeX installation with
support for PDFLaTeX. Also the following LaTeX packages need
to be installed (e.g. from texlive):
- amsmath
- babel
- capt-of
- cmap
- fncychap
- framed
- geometry
- hyperref
- hypcap
- needspace
- times
- tabulary
- upquote
- wrapfig
----------------

Installing prerequisites for epub build

## ePUB

Same as for HTML. This uses the same tools and configuration
files as the HTML tree. The ePUB format conversion currently
does not support processing mathematical expressions via MathJAX,
so there will be limitations on some pages. For the time being
until this is resolved, building and using the PDF format file
is recommended instead.

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/
You first create the ePUB file with 'make epub' and then do:

ebook-convert LAMMPS.epub LAMMPS.mobi