Merge pull request #1074 from akohlmey/more-doc-fixes

SOURCES=$(filter-out $(wildcard src/lammps_commands*.txt) src/lammps_support.txt src/lammps_tutorials.txt,$(wildcard src/*.txt))

OBJECTS=$(SOURCES:src/%.txt=$(RSTDIR)/%.rst)

.PHONY: help clean-all clean epub html pdf old venv spelling anchor_check

.PHONY: help clean-all clean epub mobi html pdf old venv spelling anchor_check

# ------------------------------------------

	@echo "  old        create old-style HTML doc pages in old dir"

	@echo "  fetch      fetch HTML and PDF files from LAMMPS web site"

	@echo "  epub       create ePUB format manual for e-book readers"

	@echo "  mobi       convert ePUB to MOBI format manual for e-book readers (e.g. Kindle)"

	@echo "                      (requires ebook-convert tool from calibre)"

	@echo "  clean      remove all intermediate RST files"

	@echo "  clean-all  reset the entire build environment"

	@echo "  txt2html   build txt2html tool"

	@rm -rf epub

	@echo "Build finished. The ePUB manual file is created."

mobi: epub

	@rm -f LAMMPS.mobi

	@ebook-convert LAMMPS.epub LAMMPS.mobi

	@echo "Conversion finished. The MOBI manual file is created."

pdf: utils/txt2html/txt2html.exe

	@(\

		set -e; \

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

For a serial build, you need to specify the 3 variables, as shown

above.

For a serial LAMMPS build, use the dummy MPI library provided in

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

You can tell CMake to look for a specific compiler with these variable

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

library.  The LAMMPS 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 via its library interface.

"Python"_Python_head.html doc page for more info on wrapping and

running LAMMPS from Python via its library interface.

[CMake variables]:

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

the lib/packages directroy, since they are always built as shared

the lib/packages directory, 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

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 directory

that you may need super-user privileges (e.g. sudo) if the directory

you want to copy files to is protected.

[CMake variable]:

If your machine has multiple CPU cores (most do these days), using a

command like "make -jN" (with N being the number of available local

CPU cores) can be much faster.  If you plan to do development on

LAMMPS or need to recompile LAMMPS repeatedly, installation of the

LAMMPS or need to re-compile LAMMPS repeatedly, installation of the

ccache (= Compiler Cache) software may speed up compilation even more.

After compilation, you can optionally copy the LAMMPS executable and

:line

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

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

environment.  On Linux all the versions produce a Makefile as their

module avail           # is a cmake module available?

module load cmake3     # load cmake module with appropriate name :pre

Most Linux distributions offer precompiled cmake packages through

Most Linux distributions offer pre-compiled cmake packages through

their package management system. 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/.

superseded by the USER-MEAMC package, which is a direct translation of

the Fortran code in the MEAM library to C++. The code in USER-MEAMC

should be functionally equivalent to the MEAM package, fully supports

use of "pair_style hybrid"_pair_hybrid.html (the MEAM packaged doesn

use of "pair_style hybrid"_pair_hybrid.html (the MEAM package does

not), and has optimizations that make it significantly faster than the

MEAM package.

-D PYTHON_EXECUTABLE=path   # path to Python executable to use :pre

Without this setting, CMake will ues the default Python on your

Without this setting, CMake will guess the default Python on your

system.  To use a different Python version, you can either create a

virtualenv, activate it and then run cmake.  Or you can set the

PYTHON_EXECUTABLE variable to specify which Python interpreter should

No additional settings are needed besides "-D PKG_USER-H5MD=yes".

This should autodetect the H5MD library on your system.  Several

This should auto-detect the H5MD library on your system.  Several

advanced CMake H5MD options exist if you need to specify where it is

installed.  Use the ccmake (terminal window) or cmake-gui (graphical)

tools to see these options and set them interactively from their user

No additional settings are needed besides "-D PKG_USER-NETCDF=yes".

This should autodetect the NETCDF library if it is installed on your

This should auto-detect the NETCDF library if it is installed on your

system at standard locations.  Several advanced CMake NETCDF options

exist if you need to specify where it was installed.  Use the ccmake

(terminal window) or cmake-gui (graphical) tools to see these options

-D EIGEN3_INCLUDE_DIR=path    # path to Eigen library (only needed if a custom location) :pre

If DOWNLOAD_EIGEN3 is set, the Eigen3 library will be downloaded and

inside the CMake build directory.  If the Eig3n3 library is already on

inside the CMake build directory.  If the Eigen3 library is already on

your system (in a location CMake cannot find it), EIGEN3_INCLUDE_DIR

is the directory the Eigen3++ include file is in.

No additional settings are needed besides "-D PKG_USER-VTK=yes".

This should autodetect the VTK library if it is installed on your

This should auto-detect 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.  Use the ccmake (terminal

window) or cmake-gui (graphical) tools to see these options and set

project with many features. If your machine has multiple CPU cores

(most do these days), using a command like "make -jN mpi" (with N =

the number of available CPU cores) can be much faster.  If you plan to

do development on LAMMPS or need to recompile LAMMPS repeatedly, the

do development on LAMMPS or need to re-compile LAMMPS repeatedly, the

installation of the ccache (= Compiler Cache) software may speed up

compilation even more.

After the initial build, whenever you edit LAMMPS source files, or add

or remove new files to the source directory (e.g. by installing or

uninstalling packages), you must recompile and relink the LAMMPS

uninstalling packages), you must re-compile and relink the LAMMPS

executable with the same "make" command.  This makefiles dependencies

should insure that only the subset of files that need to be are

recompiled.

re-compiled.

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

first be installed).  Many of these include specific compiler flags

for optimized performance.  Please note, however, that some of these

customized machine Makefile are contributed by users.  Since both

compilers, OS configs, and LAMMPS itself keep changing, their settings

may become outdated:

compilers, OS configurations, and LAMMPS itself keep changing, their

settings may become outdated:

make mac             # build serial LAMMPS on a Mac

make mac_mpi         # build parallel LAMMPS on a Mac