Merge pull request #1926 from akohlmey/doc-cleanup

  Some potentials that are also implemented in the Yet Another Force Field (YAFF) code.

  The expressions and their use are discussed in the following papers:

  <ul>

    <li><a href="http://dx.doi.org/10.1002/jcc.23877" target="_blank">Vanduyfhuys et al., J. Comput. Chem., 36 (13), 1015-1027 (2015)</a></li>

    <li><a href="http://dx.doi.org/10.1002/jcc.25173" target="_blank">Vanduyfhuys et al., J. Comput. Chem., 39 (16), 999-1011 (2018)</a></li>

    <li><a href="https://doi.org/10.1002/jcc.23877" target="_blank">Vanduyfhuys et al., J. Comput. Chem., 36 (13), 1015-1027 (2015)</a></li>

    <li><a href="https://doi.org/10.1002/jcc.25173" target="_blank">Vanduyfhuys et al., J. Comput. Chem., 39 (16), 999-1011 (2018)</a></li>

  </ul>

  </td>

  <td>

	@cp -r src/PDF html/PDF

	@cp -r src/USER html/USER

	@mkdir -p html/JPG

	@cp `grep -A2 '\.\. image::' src/*.rst | grep ':target:' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html/JPG/

	@cp `grep -A2 '\.\. .*image::' src/*.rst | grep ':target:' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html/JPG/

	@rm -rf html/PDF/.[sg]*

	@rm -rf html/USER/.[sg]*

	@rm -rf html/USER/*/.[sg]*

alternative you can download a package with pre-built executables

as described on the :doc:`Install <Install>` doc page.

.. toctree::

   :maxdepth: 1

* :ref:`Build the LAMMPS documentation <doc>`

* :ref:`Install LAMMPS after a build <install>`

----------

.. _serial:

Serial vs parallel build

   make serial             # serial build, produces lmp_serial using Makefile/serial

   make mybox              # uses Makefile.mybox to produce lmp_mybox

Any "make machine" command will look up the make settings from a file

Makefile.machine, create a folder Obj\_machine with all objects and

generated files and an executable called *lmp\_machine*\ .  The standard

'src/USER-OMP/hack\_openmp\_for\_pgi\_gcc9.sh' can be used to automate

this conversion.

----------

.. _compile:

Choice of compiler and compile/link options

   -D CMAKE_C_FLAGS=string               # flags to use with C compiler

   -D CMAKE_Fortran_FLAGS=string         # flags to use with Fortran compiler

A few example command lines are:

.. code-block:: bash

.. code-block:: bash

   make machine               # build LAMMPS executable lmp_machine

   mkae mode=exe machine      # same as "make machine"

   make mode=exe machine      # same as "make machine"

   make mode=lib machine      # build LAMMPS static lib liblammps_machine.a

   make mode=shlib machine    # build LAMMPS shared lib liblammps_machine.so

   make mode=shexe machine    # same as "mode=exe" but uses objects from "mode=shlib"

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, as a shared library

in the default /usr/local/lib location:

----------

.. _doc:

Build the LAMMPS documentation

  make package_check # check for complete and consistent package lists

  make spelling      # spell-check the manual

Thus "make html" will create a "doc/html" directory with the HTML format

manual pages so that you can browse them with a web browser locally on

your system.

   You can also download a tarball of the documentation for the

   current LAMMPS version (HTML and PDF files), from the website

   `download page <http://lammps.sandia.gov/download.html>`_.

   `download page <https://lammps.sandia.gov/download.html>`_.

**CMake build option**\ :

   -D BUILD_DOC=value       # yes or no (default)

----------

.. _tools:

Build LAMMPS tools

**CMake build3**\ :

.. code-block:: bash

   -D BUILD_TOOLS=value       # yes or no (default)

**Traditional make**\ :

.. code-block:: bash

   cd lammps/tools

   make micelle2d        # build only micelle2d tool

   make thermo_extract   # build only thermo_extract tool

----------

.. _install:

Install LAMMPS after a build

**CMake build**\ :

.. code-block:: bash

   cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake

for how to use CMake to build LAMMPS.  If you are new to CMake it is a

good place to start.

----------

Building LAMMPS with CMake is a two-step process.  First you use CMake

to create a build environment in a new directory.  On Linux systems,

this will be based on makefiles for use with make.  Then you use the

make command to build LAMMPS, which uses the created

Makefile(s). Example:

.. code-block:: bash

   cd lammps                        # change to the LAMMPS distribution directory

After compilation, you may optionally install the LAMMPS executable into

your system with:

.. code-block:: bash

   make install    # optional, copy LAMMPS executable & library elsewhere

tree is set by the CMake variable "CMAKE\_INSTALL\_PREFIX" which defaults

to ${HOME}/.local

----------

There are 3 variants of CMake: a command-line version (cmake), a text mode

UI version (ccmake), and a graphical GUI version (cmake-GUI).  You can use

any of them interchangeably to configure and create the LAMMPS build

various options; see details below.  Or you can remove the entire build

folder, recreate the directory and start over.

----------

**Command-line version of CMake**\ :

.. code-block:: bash

   cmake [options ...] /path/to/lammps/cmake  # build from any dir

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

The argument can be prefixed or followed by various CMake

command-line options.  Several useful ones are:

.. code-block:: bash

   -D CMAKE_INSTALL_PREFIX=path  # where to install LAMMPS executable/lib if desired

files/directories in the build directory, or start with a fresh build

directory.

----------

**Curses version (terminal-style menu) of CMake**\ :

.. code-block:: bash

   ccmake ../cmake

in between.  Please see the `ccmake manual <https://cmake.org/cmake/help/latest/manual/ccmake.1.html>`_ for

more information.

----------

**GUI version of CMake**\ :

.. code-block:: bash

   cmake-gui ../cmake

Please see the `cmake-gui manual <https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html>`_

for more information.

----------

**Installing CMake**

Check if your machine already has CMake installed:

.. code-block:: bash

   which cmake             # do you have it?

On clusters or supercomputers which use environment modules to manage

software packages, do this:

.. code-block:: bash

   module list            # is a module for cmake already loaded?