jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #2309 from lammps/doxygen-integration 

Add doxygen and graphviz processing into the documentation build
This commit is contained in:
Axel Kohlmeyer 2020-08-26 13:05:00 -04:00 committed by GitHub
parent 4ad68c98a0 94db627ba5
commit 629ead6348
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
31 changed files with 1218 additions and 286 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
cmake/Modules/Documentation.cmake
View File

@ -15,75 +15,93 @@ if(BUILD_DOC)
endif()
set(VIRTUALENV ${Python3_EXECUTABLE} -m virtualenv -p ${Python3_EXECUTABLE})
endif()
find_package(Doxygen 1.8.10 REQUIRED)
file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.rst)
add_custom_command(
OUTPUT docenv
COMMAND ${VIRTUALENV} docenv
)
set(DOCENV_BINARY_DIR ${CMAKE_BINARY_DIR}/docenv/bin)
set(DOCENV_REQUIREMENTS_FILE ${LAMMPS_DOC_DIR}/utils/requirements.txt)
set(SPHINX_CONFIG_DIR ${LAMMPS_DOC_DIR}/utils/sphinx-config)
set(SPHINX_CONFIG_FILE_TEMPLATE ${SPHINX_CONFIG_DIR}/conf.py.in)
set(SPHINX_STATIC_DIR ${SPHINX_CONFIG_DIR}/_static)
# configuration and static files are copied to binary dir to avoid collisions with parallel builds
set(DOC_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc)
set(DOC_BUILD_CONFIG_FILE ${DOC_BUILD_DIR}/conf.py)
set(DOC_BUILD_STATIC_DIR ${DOC_BUILD_DIR}/_static)
set(DOXYGEN_BUILD_DIR ${DOC_BUILD_DIR}/doxygen)
set(DOXYGEN_XML_DIR ${DOXYGEN_BUILD_DIR}/xml)
# copy entire configuration folder to doc build directory
# files in _static are automatically copied during sphinx-build, so no need to copy them individually
file(COPY ${SPHINX_CONFIG_DIR}/ DESTINATION ${DOC_BUILD_DIR})
# configure paths in conf.py, since relative paths change when file is copied
configure_file(${SPHINX_CONFIG_FILE_TEMPLATE} ${DOC_BUILD_CONFIG_FILE})
add_custom_command(
OUTPUT requirements.txt
DEPENDS docenv
COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/utils/requirements.txt requirements.txt
OUTPUT ${DOC_BUILD_DIR}/requirements.txt
DEPENDS docenv ${DOCENV_REQUIREMENTS_FILE}
COMMAND ${CMAKE_COMMAND} -E copy ${DOCENV_REQUIREMENTS_FILE} ${DOC_BUILD_DIR}/requirements.txt
COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade pip
COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters
COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r requirements.txt --upgrade
COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r ${DOC_BUILD_DIR}/requirements.txt --upgrade
)
# download mathjax distribution and unpack to folder "mathjax"
if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5)
if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/mathjax/es5)
file(DOWNLOAD "https://github.com/mathjax/MathJax/archive/3.0.5.tar.gz"
"${CMAKE_CURRENT_BINARY_DIR}/mathjax.tar.gz"
EXPECTED_MD5 5d9d3799cce77a1a95eee6be04eb68e7)
execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf mathjax.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
file(GLOB MATHJAX_VERSION_DIR ${CMAKE_CURRENT_BINARY_DIR}/MathJax-*)
execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${CMAKE_CURRENT_BINARY_DIR}/mathjax)
execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${DOC_BUILD_STATIC_DIR}/mathjax)
endif()
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax)
file(COPY ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5 DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/)
# for increased browser compatibility
if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js)
if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/polyfill.js)
file(DOWNLOAD "https://polyfill.io/v3/polyfill.min.js?features=es6"
"${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js")
"${DOC_BUILD_STATIC_DIR}/polyfill.js")
endif()
# note, this may run in parallel with other tasks, so we must not use multiple processes here
# set up doxygen and add targets to run it
file(MAKE_DIRECTORY ${DOXYGEN_BUILD_DIR})
file(COPY ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png DESTINATION ${DOXYGEN_BUILD_DIR}/lammps-logo.png)
configure_file(${LAMMPS_DOC_DIR}/doxygen/Doxyfile.in ${DOXYGEN_BUILD_DIR}/Doxyfile)
get_target_property(LAMMPS_SOURCES lammps SOURCES)
add_custom_command(
OUTPUT html
DEPENDS ${DOC_SOURCES} docenv requirements.txt
COMMAND ${DOCENV_BINARY_DIR}/sphinx-build -b html -c ${LAMMPS_DOC_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${LAMMPS_DOC_DIR}/src html
COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${CMAKE_CURRENT_BINARY_DIR}/html/index.html
OUTPUT ${DOXYGEN_XML_DIR}/index.xml
DEPENDS ${DOC_SOURCES} ${LAMMPS_SOURCES}
COMMAND Doxygen::doxygen ${DOXYGEN_BUILD_DIR}/Doxyfile WORKING_DIRECTORY ${DOXYGEN_BUILD_DIR}
COMMAND ${CMAKE_COMMAND} -E touch ${DOXYGEN_XML_DIR}/run.stamp
)
# copy selected image files to html output tree
file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/html/JPG)
set(HTML_EXTRA_IMAGES balance_nonuniform.jpg balance_rcb.jpg
balance_uniform.jpg bow_tutorial_01.png bow_tutorial_02.png
bow_tutorial_03.png bow_tutorial_04.png bow_tutorial_05.png
dump1.jpg dump2.jpg examples_mdpd.gif gran_funnel.png gran_mixer.png
hop1.jpg hop2.jpg saed_ewald_intersect.jpg saed_mesh.jpg
screenshot_atomeye.jpg screenshot_gl.jpg screenshot_pymol.jpg
screenshot_vmd.jpg sinusoid.jpg xrd_mesh.jpg)
set(HTML_IMAGE_TARGETS "")
foreach(_IMG ${HTML_EXTRA_IMAGES})
string(PREPEND _IMG JPG/)
list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}")
if(EXISTS ${DOXYGEN_XML_DIR}/run.stamp)
set(SPHINX_EXTRA_OPTS "-E")
else()
set(SPHINX_EXTRA_OPTS "")
endif()
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}
DEPENDS ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_CURRENT_BINARY_DIR}/html/JPG
COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_BINARY_DIR}/html/${_IMG}
OUTPUT html
DEPENDS ${DOC_SOURCES} docenv ${DOC_BUILD_DIR}/requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${BUILD_DOC_CONFIG_FILE}
COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${DOC_BUILD_DIR} -d ${DOC_BUILD_DIR}/doctrees ${LAMMPS_DOC_DIR}/src ${DOC_BUILD_DIR}/html
COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${DOC_BUILD_DIR}/html/index.html
COMMAND ${CMAKE_COMMAND} -E copy_directory ${LAMMPS_DOC_DIR}/src/PDF ${DOC_BUILD_DIR}/html/PDF
COMMAND ${CMAKE_COMMAND} -E remove -f ${DOXYGEN_XML_DIR}/run.stamp
)
endforeach()
add_custom_target(
doc ALL
DEPENDS html ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/es5 ${HTML_IMAGE_TARGETS}
DEPENDS html ${DOC_BUILD_STATIC_DIR}/mathjax/es5
SOURCES ${LAMMPS_DOC_DIR}/utils/requirements.txt ${DOC_SOURCES}
)
install(DIRECTORY ${CMAKE_BINARY_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR})
install(DIRECTORY ${DOC_BUILD_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR})
endif()

7
doc/.gitignore vendored
View File

@ -1,6 +1,7 @@
/old
/html
/html-offline
/epub
/latex
/mathjax
/spelling
@ -10,3 +11,9 @@
/Developer.pdf
/doctrees
/docenv
/doxygen-warn.log
/utils/sphinx-config/conf.py
/doxygen/Doxyfile
*.el
/utils/sphinx-config/_static/mathjax
/utils/sphinx-config/_static/polyfill.js

90
doc/Makefile
View File

@ -4,20 +4,28 @@ SHELL = /bin/bash
BUILDDIR = ${CURDIR}
RSTDIR = $(BUILDDIR)/src
VENV = $(BUILDDIR)/docenv
MATHJAX = $(BUILDDIR)/mathjax
TXT2RST = $(VENV)/bin/txt2rst
ANCHORCHECK = $(VENV)/bin/rst_anchor_check
SPHINXCONFIG = $(BUILDDIR)/utils/sphinx-config
MATHJAX = $(SPHINXCONFIG)/_static/mathjax
POLYFILL = $(SPHINXCONFIG)/_static/polyfill.js
PYTHON = $(shell which python3)
DOXYGEN = $(shell which doxygen)
VIRTUALENV = virtualenv
HAS_PYTHON3 = NO
HAS_VIRTUALENV = NO
HAS_DOXYGEN = NO
HAS_PDFLATEX = NO
ifeq ($(shell which python3 >/dev/null 2>&1; echo $$?), 0)
HAS_PYTHON3 = YES
endif
ifeq ($(shell which doxygen >/dev/null 2>&1; echo $$?), 0)
HAS_DOXYGEN = YES
endif
ifeq ($(shell which virtualenv-3 >/dev/null 2>&1; echo $$?), 0)
VIRTUALENV = virtualenv-3
HAS_VIRTUALENV = YES
@ -33,9 +41,13 @@ HAS_PDFLATEX = YES
endif
SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') $(shell test -f $(BUILDDIR)/doxygen/xml/run.stamp && printf -- "-E")
.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check
# grab list of sources from doxygen config file.
# we only want to use explicitly listed files.
DOXYFILES = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+=/p' doxygen/Doxyfile.in | sed -e 's/@LAMMPS_SOURCE_DIR@/..\/src/g' -e 's/\\//g' -e 's/ \+/ /' -e 's/[A-Z_]\+ \+= *\(YES\|NO\|\)//')
.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check xmlgen
# ------------------------------------------
@ -57,23 +69,32 @@ help:
# ------------------------------------------
clean-all: clean
rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees $(BUILDDIR)/mathjax Manual.pdf Developer.pdf
rm -rf $(BUILDDIR)/docenv $(MATHJAX) $(BUILDDIR)/LAMMPS.mobi $(BUILDDIR)/LAMMPS.epub $(BUILDDIR)/Manual.pdf $(BUILDDIR)/Developer.pdf
clean: clean-spelling
rm -rf html epub latex
rm -rf $(BUILDDIR)/html $(BUILDDIR)/epub $(BUILDDIR)/latex $(BUILDDIR)/doctrees $(BUILDDIR)/doxygen/xml $(BUILDDIR)/doxygen-warn.log $(BUILDDIR)/doxygen/Doxyfile $(SPHINXCONFIG)/conf.py
clean-spelling:
rm -rf spelling
rm -rf $(BUILDDIR)/spelling
html: $(ANCHORCHECK) $(MATHJAX)
$(SPHINXCONFIG)/conf.py: $(SPHINXCONFIG)/conf.py.in
sed -e 's,@DOXYGEN_XML_DIR@,$(BUILDDIR)/doxygen/xml,g' \
-e 's,@LAMMPS_SOURCE_DIR@,$(BUILDDIR)/../src,g' \
-e 's,@LAMMPS_PYTHON_DIR@,$(BUILDDIR)/../python,g' \
-e 's,@LAMMPS_DOC_DIR@,$(BUILDDIR),g' $< > $@
html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) $(POLYFILL)
@$(MAKE) $(MFLAGS) -C graphviz all
@(\
. $(VENV)/bin/activate ;\
sphinx-build $(SPHINXEXTRA) -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
ln -sf Manual.html html/index.html;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
echo "############################################" ;\
rst_anchor_check src/*.rst ;\
python utils/check-packages.py -s ../src -d src ;\
python $(BUILDDIR)/utils/check-packages.py -s ../src -d src ;\
env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
python utils/check-styles.py -s ../src -d src ;\
python $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\
echo "############################################" ;\
deactivate ;\
)
@ -82,30 +103,28 @@ html: $(ANCHORCHECK) $(MATHJAX)
@rm -rf html/USER
@rm -rf html/JPG
@cp -r src/PDF html/PDF
@mkdir -p html/JPG
@cp `grep -A2 '\.\. .*\(image\|figure\)::' src/*.rst | grep ':target: JPG' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html/JPG/
@rm -rf html/PDF/.[sg]*
@mkdir -p html/_static/mathjax
@cp -r $(MATHJAX)/es5 html/_static/mathjax/
@echo "Build finished. The HTML pages are in doc/html."
spelling: $(VENV) utils/sphinx-config/false_positives.txt
spelling: xmlgen $(VENV) $(SPHINXCONFIG)/false_positives.txt
@(\
. $(VENV)/bin/activate ;\
cp utils/sphinx-config/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \
sphinx-build -b spelling -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
cp $(SPHINXCONFIG)/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \
sphinx-build -b spelling -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
deactivate ;\
)
@echo "Spell check finished."
epub: $(VENV)
epub: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
@$(MAKE) $(MFLAGS) -C graphviz all
@mkdir -p epub/JPG
@rm -f LAMMPS.epub
@cp src/JPG/lammps-logo.png epub/
@cp src/JPG/*.* epub/JPG
@(\
. $(VENV)/bin/activate ;\
sphinx-build $(SPHINXEXTRA) -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
sphinx-build $(SPHINXEXTRA) -b epub -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
deactivate ;\
)
@mv epub/LAMMPS.epub .
@ -117,7 +136,8 @@ mobi: epub
@ebook-convert LAMMPS.epub LAMMPS.mobi
@echo "Conversion finished. The MOBI manual file is created."
pdf: $(ANCHORCHECK)
pdf: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
@$(MAKE) $(MFLAGS) -C graphviz all
@if [ "$(HAS_PDFLATEX)" == "NO" ] ; then echo "PDFLaTeX was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
@(\
cd src/Developer; \
@ -127,8 +147,9 @@ pdf: $(ANCHORCHECK)
cd ../../; \
)
@(\
. $(VENV)/bin/activate ;\
sphinx-build $(SPHINXEXTRA) -b latex -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
sphinx-build $(SPHINXEXTRA) -b latex -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
echo "############################################" ;\
rst_anchor_check src/*.rst ;\
python utils/check-packages.py -s ../src -d src ;\
@ -185,21 +206,32 @@ package_check : $(VENV)
deactivate ;\
)
xmlgen : doxygen/xml/index.xml
doxygen/Doxyfile: doxygen/Doxyfile.in
sed -e 's/@LAMMPS_SOURCE_DIR@/..\/..\/src/g' $< > $@
doxygen/xml/index.xml : $(VENV) doxygen/Doxyfile $(DOXYFILES)
@(cd doxygen; $(DOXYGEN) Doxyfile && touch xml/run.stamp)
# ------------------------------------------
$(VENV):
@if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "Python3 was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "python3 was not found! Please see README for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_DOXYGEN)" == "NO" ] ; then echo "doxygen was not found! Please see README for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please see README for further instructions" 1>&2; exit 1; fi
@( \
$(VIRTUALENV) -p $(PYTHON) $(VENV); \
. $(VENV)/bin/activate; \
pip install --upgrade pip; \
pip install --use-feature=2020-resolver -r requirements.txt; \
pip install --use-feature=2020-resolver -r $(BUILDDIR)/utils/requirements.txt; \
deactivate;\
)
$(MATHJAX):
@git clone --depth 1 https://github.com/mathjax/MathJax.git mathjax
@git clone --depth 1 https://github.com/mathjax/MathJax.git $@
$(POLYFILL): $(MATHJAX)
@curl -s -o $@ "https://polyfill.io/v3/polyfill.min.js?features=es6"
$(TXT2RST) $(ANCHORCHECK): $(VENV)
@( \

140
doc/README
View File

@ -1,97 +1,60 @@
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:
Depending on how you obtained LAMMPS and whether you have built
the manual yourself, this directory has a varying number of
sub-directories and files. Here is a list with descriptions:
README this 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
Manual.pdf PDF version of entire manual
Developer.pdf PDF with info about how LAMMPS is structured
LAMMPS.epub Manual in ePUB format
LAMMPS.mobi Manual in MOBI (Kindle) format
lammps.1 man page for the lammps command
msi2lmp.1 man page for the msi2lmp command
mathjax code and fonts for rendering math in html
doctree temporary data
docenv python virtual environment for generating the manual
doxygen Doxygen configuration and output
.gitignore list of files and folders to be ignored by git
doxygen-warn.log logfile with warnings from running doxygen
If you downloaded LAMMPS as a tarball from the web site, all these
directories and files should be included.
and:
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:
github-development-workflow.md notes on the LAMMPS development workflow
include-file-conventions.md notes on LAMMPS' include file conventions
documentation_conventions.md notes on writing documentation for LAMMPS
If you downloaded a LAMMPS tarball from lammps.sandia.gov, then the html
folder and the PDF manual should be included. If you downloaded LAMMPS
from GitHub then you either need to download them or build them.
(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).
Manual_www.pdf/Developer_www.pdf files. These files will always
represent the latest published patch/development version of LAMMPS.
(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.
(b) You can build the HTML and PDF files yourself, by typing "make html"
or by "make pdf", respectively. This requires various tools and files.
Some of them have to be installed (more on that below). For the rest the
build process will attempt to download and install into a python virtual
environment and local folders.
----------------
The generation of all documentation is managed by the Makefile in this
dir.
Installing prerequisites for the documentation build
Options:
To run the HTML documention build toolchain, python 3.x, doxygen, git,
and virtualenv have to be installed. Also internet access is initially
required to download external files and tools.
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):
Building the PDF format manual requires in addition a compatible LaTeX
installation with support for PDFLaTeX and several add-on LaTeX packages
installed. This includes:
- amsmath
- anysize
- babel
- capt-of
- cmap
@ -105,24 +68,13 @@ to be installed (e.g. from texlive):
- tabulary
- upquote
- wrapfig
Building the EPUB format requires LaTeX installation with the same packages
as for the PDF format plus the 'dvipng' command to convert the embedded math
into images. The MOBI format is generated from the EPUB format file by using
the tool 'ebook-convert' from the 'calibre' e-book management software
(https://calibre-ebook.com).
----------------
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
More details this can be found in the manual itself. The online
version is at: https://lammps.sandia.gov/doc/Manual_build.html

93
doc/documentation_conventions.md Normal file
View File

@ -0,0 +1,93 @@
# Outline of LAMMPS documentation file conventions
This purpose of this document is to provide a point of reference
for LAMMPS developers and contributors as to what conventions
should be used to structure and format files in the LAMMPS manual.
Last change: 2020-04-23
## File format and tools
In fall 2019, the LAMMPS documentation file format has changed from
a home grown minimal markup designed to generate HTML format files
from a mostly plain text format to using the reStructuredText file
format. For a transition period all files in the old .txt format
were transparently converted to .rst and then processed. The txt2rst
tool is still included in the distribution to obtain an initial .rst
file for integration into the manual. Since the transition to
reStructured text as source format, many of the artifacts or the
translation have been removed though and parts of the documentation
refactored and expanded to take advantage of the capabilities
reStructuredText and associated tools. The conversion from the
source to the final formats (HTML, PDF, and optionally e-book
reader formats ePUB and MOBI) is mostly automated and controlled
by a Makefile in the `doc` folder. This makefile assumes that the
processing is done on a Unix-like machine and Python 3.5 or later
and a matching virtualenv module are available. Additional Python
packages (like the Sphinx tool and several extensions) are
transparently installed into a virtual environment over the
internet using the `pip` package manager. Further requirements
and details are discussed in the manual.
## Work in progress
The refactoring and improving of the documentation is an ongoing
process, so statements in this document may not always be fully
up-to-date. If in doubt, contact the LAMMPS developers.
## General structure
The layout and formatting of added files should follow the example
of the existing files. Since those are directly derived from their
former .txt format versions and the manual has been maintained in
that format for many years, there is a large degree of consistency
already, so comparision with similar files should give you a good
idea what kind of information and sections are needed.
## Formatting conventions
Filenames, folders, paths, (shell) commands, definitions, makefile
settings and similar should be formatted as "literals" with
double backward quotes bracketing the item: \`\`path/to/some/file\`\`
Keywords and options are formatted in italics: \*option\*
Mathematical expressions, equations, symbols are typeset using
either a `.. math:`` block or the `:math:` role.
Groups of shell commands or LAMMPS input script or C/C++ source
code should be typeset into a `.. code-block::` section. A syntax
highlighting extension for LAMMPS input scripts is provided, so
`LAMMPS` can be used to indicate the language in the code block
in addition to `bash`, `c`, or `python`. When no syntax style
is indicated, no syntax highlighting is performed.
As an alternative, e.g. to typeset the syntax of file formats
a `.. parsed-literal::` block can be used, which allows some
formatting directives, which means that related characters need
to be escaped with a preceding backslash: `\*`.
Special remarks can be highlighted with a `.. note::` block and
strong warnings can be put into a `.. warning::` block.
## Required steps when adding a custom style to LAMMPS
When adding a new style (e.g. pair style or a compute or a fix)
or a new command, it is **required** to include the corresponding
documentation. Those are often new files that need to be added.
In order to be included in the documentation, those new files
need to be reference in a `.. toctree::` block. Most of those
use patterns with wildcards, so the addition will be automatic.
However, those additions also need to be added to some lists of
styles or commands. The `make style\_check` command will perform
a test and report any missing entries and list the affected files.
Any references defined with `.. \_refname:` have to be unique
across all documentation files and this can be checked for with
`make anchor\_check`. Finally, a spell-check should be done,
which is triggered via `make spelling`. Any offenses need to
be corrected and false positives should be added to the file
`utils/sphinx-config/false\_positives.txt`.
## Required additional steps when adding a new package to LAMMPS
TODO

1
doc/doxygen/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
/xml

522
doc/doxygen/Doxyfile.in Normal file
View File

@ -0,0 +1,522 @@
# Doxyfile 1.8.15 -*- makefile -*-
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = "LAMMPS Programmer's Guide"
PROJECT_NUMBER = "24 August 2020"
PROJECT_BRIEF = "Documentation of the LAMMPS library interface and Python wrapper"
PROJECT_LOGO = lammps-logo.png
CREATE_SUBDIRS = NO
ALLOW_UNICODE_NAMES = NO
OUTPUT_LANGUAGE = English
OUTPUT_TEXT_DIRECTION = LTR
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = NO
INHERIT_DOCS = YES
TAB_SIZE = 2
# When enabled doxygen tries to link words that correspond to documented
# classes, or namespaces to their corresponding documentation. Such a link can
# be prevented in individual cases by putting a % sign in front of the word or
# globally by setting AUTOLINK_SUPPORT to NO.
# The default value is: YES.
AUTOLINK_SUPPORT = YES
# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
# to include (a tag file for) the STL sources as input, then you should set this
# tag to YES in order to let doxygen match functions declarations and
# definitions whose arguments contain STL classes (e.g. func(std::string);
# versus func(std::string) {}). This also make the inheritance and collaboration
# diagrams that involve STL classes more complete and accurate.
# The default value is: NO.
BUILTIN_STL_SUPPORT = YES
IDL_PROPERTY_SUPPORT = NO
# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This
# cache is used to resolve symbols given their name and scope. Since this can be
# an expensive process and often the same symbol appears multiple times in the
# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small
# doxygen will become slower. If the cache is too large, memory is wasted. The
# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range
# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536
# symbols. At the end of a run doxygen will report the cache usage and suggest
# the optimal cache size from a speed point of view.
# Minimum value: 0, maximum value: 9, default value: 0.
LOOKUP_CACHE_SIZE = 2
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in
# documentation are documented, even if no documentation was available. Private
# class members and static file members will be hidden unless the
# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.
# Note: This will also disable the warnings about undocumented members that are
# normally produced when WARNINGS is set to YES.
# The default value is: NO.
EXTRACT_ALL = NO
# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
# be included in the documentation.
# The default value is: NO.
EXTRACT_PRIVATE = YES
# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
# scope will be included in the documentation.
# The default value is: NO.
EXTRACT_PACKAGE = YES
# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be
# included in the documentation.
# The default value is: NO.
EXTRACT_STATIC = YES
# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
# locally in source files will be included in the documentation. If set to NO,
# only classes defined in header files are included. Does not have any effect
# for Java sources.
# The default value is: YES.
EXTRACT_LOCAL_CLASSES = YES
# If this flag is set to YES, the members of anonymous namespaces will be
# extracted and appear in the documentation as a namespace called
# 'anonymous_namespace{file}', where file will be replaced with the base name of
# the file that contains the anonymous namespace. By default anonymous namespace
# are hidden.
# The default value is: NO.
EXTRACT_ANON_NSPACES = YES
# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all
# undocumented members inside documented classes or files. If set to NO these
# members will be included in the various overviews, but no documentation
# section is generated. This option has no effect if EXTRACT_ALL is enabled.
# The default value is: NO.
HIDE_UNDOC_MEMBERS = YES
# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
# undocumented classes that are normally visible in the class hierarchy. If set
# to NO, these classes will be included in the various overviews. This option
# has no effect if EXTRACT_ALL is enabled.
# The default value is: NO.
HIDE_UNDOC_CLASSES = YES
# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
# (class|struct|union) declarations. If set to NO, these declarations will be
# included in the documentation.
# The default value is: NO.
HIDE_FRIEND_COMPOUNDS = NO
# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
# documentation blocks found inside the body of a function. If set to NO, these
# blocks will be appended to the function's detailed documentation block.
# The default value is: NO.
HIDE_IN_BODY_DOCS = NO
# The INTERNAL_DOCS tag determines if documentation that is typed after a
# \internal command is included. If the tag is set to NO then the documentation
# will be excluded. Set it to YES to include the internal documentation.
# The default value is: NO.
INTERNAL_DOCS = NO
# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file
# names in lower-case letters. If set to YES, upper-case letters are also
# allowed. This is useful if you have classes or files whose names only differ
# in case and if your file system supports case sensitive file names. Windows
# and Mac users are advised to set this option to NO.
# The default value is: system dependent.
CASE_SENSE_NAMES = YES
# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with
# their full class and namespace scopes in the documentation. If set to YES, the
# scope will be hidden.
# The default value is: NO.
HIDE_SCOPE_NAMES = YES
# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will
# append additional text to a page's title, such as Class Reference. If set to
# YES the compound reference will be hidden.
# The default value is: NO.
HIDE_COMPOUND_REFERENCE= NO
# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of
# the files that are included by a file in the documentation of that file.
# The default value is: YES.
SHOW_INCLUDE_FILES = NO
# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
# grouped member an include statement to the documentation, telling the reader
# which file to include in order to use the member.
# The default value is: NO.
SHOW_GROUPED_MEMB_INC = NO
# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include
# files with double quotes in the documentation rather than with sharp brackets.
# The default value is: NO.
FORCE_LOCAL_INCLUDES = NO
# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the
# documentation for inline members.
# The default value is: YES.
INLINE_INFO = YES
# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the
# (detailed) documentation of file and class members alphabetically by member
# name. If set to NO, the members will appear in declaration order.
# The default value is: YES.
SORT_MEMBER_DOCS = NO
# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
# descriptions of file, namespace and class members alphabetically by member
# name. If set to NO, the members will appear in declaration order. Note that
# this will also influence the order of the classes in the class list.
# The default value is: NO.
SORT_BRIEF_DOCS = NO
# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
# (brief and detailed) documentation of class members so that constructors and
# destructors are listed first. If set to NO the constructors will appear in the
# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS.
# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief
# member documentation.
# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting
# detailed member documentation.
# The default value is: NO.
SORT_MEMBERS_CTORS_1ST = NO
# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
# of group names into alphabetical order. If set to NO the group names will
# appear in their defined order.
# The default value is: NO.
SORT_GROUP_NAMES = NO
# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
# fully-qualified names, including namespaces. If set to NO, the class list will
# be sorted only by class name, not including the namespace part.
# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
# Note: This option applies only to the class list, not to the alphabetical
# list.
# The default value is: NO.
SORT_BY_SCOPE_NAME = NO
# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper
# type resolution of all parameters of a function it will reject a match between
# the prototype and the implementation of a member function even if there is
# only one candidate or it is obvious which candidate to choose by doing a
# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still
# accept a match between prototype and implementation in such cases.
# The default value is: NO.
STRICT_PROTO_MATCHING = NO
# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo
# list. This list is created by putting \todo commands in the documentation.
# The default value is: YES.
GENERATE_TODOLIST = YES
# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
# list. This list is created by putting \test commands in the documentation.
# The default value is: YES.
GENERATE_TESTLIST = YES
# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug
# list. This list is created by putting \bug commands in the documentation.
# The default value is: YES.
GENERATE_BUGLIST = YES
# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO)
# the deprecated list. This list is created by putting \deprecated commands in
# the documentation.
# The default value is: YES.
GENERATE_DEPRECATEDLIST= YES
# The ENABLED_SECTIONS tag can be used to enable conditional documentation
# sections, marked by \if <section_label> ... \endif and \cond <section_label>
# ... \endcond blocks.
ENABLED_SECTIONS =
# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the
# initial value of a variable or macro / define can have for it to appear in the
# documentation. If the initializer consists of more lines than specified here
# it will be hidden. Use a value of 0 to hide initializers completely. The
# appearance of the value of individual variables and macros / defines can be
# controlled using \showinitializer or \hideinitializer command in the
# documentation regardless of this setting.
# Minimum value: 0, maximum value: 10000, default value: 30.
MAX_INITIALIZER_LINES = 30
# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at
# the bottom of the documentation of classes and structs. If set to YES, the
# list will mention the files that were used to generate the documentation.
# The default value is: YES.
SHOW_USED_FILES = YES
# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This
# will remove the Files entry from the Quick Index and from the Folder Tree View
# (if specified).
# The default value is: YES.
SHOW_FILES = NO
# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces
# page. This will remove the Namespaces entry from the Quick Index and from the
# Folder Tree View (if specified).
# The default value is: YES.
SHOW_NAMESPACES = YES
# The FILE_VERSION_FILTER tag can be used to specify a program or script that
# doxygen should invoke to get the current version for each file (typically from
# the version control system). Doxygen will invoke the program by executing (via
# popen()) the command command input-file, where command is the value of the
# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided
# by doxygen. Whatever the program writes to standard output is used as the file
# version. For an example see the documentation.
FILE_VERSION_FILTER =
# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
# by doxygen. The layout file controls the global structure of the generated
# output files in an output format independent way. To create the layout file
# that represents doxygen's defaults, run doxygen with the -l option. You can
# optionally specify a file name after the option, if omitted DoxygenLayout.xml
# will be used as the name of the layout file.
#
# Note that if you run doxygen from a directory containing a file called
# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
# tag is left empty.
LAYOUT_FILE =
# The CITE_BIB_FILES tag can be used to specify one or more bib files containing
# the reference definitions. This must be a list of .bib files. The .bib
# extension is automatically appended if omitted. This requires the bibtex tool
# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info.
# For LaTeX the style of the bibliography can be controlled using
# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the
# search path. See also \cite for info how to create references.
CITE_BIB_FILES =
#---------------------------------------------------------------------------
# Configuration options related to warning and progress messages
#---------------------------------------------------------------------------
# The QUIET tag can be used to turn on/off the messages that are generated to
# standard output by doxygen. If QUIET is set to YES this implies that the
# messages are off.
# The default value is: NO.
QUIET = NO
# The WARNINGS tag can be used to turn on/off the warning messages that are
# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
# this implies that the warnings are on.
#
# Tip: Turn warnings on while writing the documentation.
# The default value is: YES.
WARNINGS = YES
# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate
# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
# will automatically be disabled.
# The default value is: YES.
WARN_IF_UNDOCUMENTED = YES
# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
# potential errors in the documentation, such as not documenting some parameters
# in a documented function, or documenting parameters that don't exist or using
# markup commands wrongly.
# The default value is: YES.
WARN_IF_DOC_ERROR = YES
# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that
# are documented, but have no documentation for their parameters or return
# value. If set to NO, doxygen will only warn about wrong or incomplete
# parameter documentation, but not about the absence of documentation. If
# EXTRACT_ALL is set to YES then this flag will automatically be disabled.
# The default value is: NO.
WARN_NO_PARAMDOC = YES
# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
# a warning is encountered.
# The default value is: NO.
WARN_AS_ERROR = NO
# The WARN_FORMAT tag determines the format of the warning messages that doxygen
# can produce. The string should contain the $file, $line, and $text tags, which
# will be replaced by the file and line number from which the warning originated
# and the warning text. Optionally the format may contain $version, which will
# be replaced by the version of the file (if it could be obtained via
# FILE_VERSION_FILTER)
# The default value is: $file:$line: $text.
WARN_FORMAT = "$file:$line: $text"
# The WARN_LOGFILE tag can be used to specify a file to which warning and error
# messages should be written. If left blank the output is written to standard
# error (stderr).
WARN_LOGFILE = "../doxygen-warn.log"
#---------------------------------------------------------------------------
# Configuration options related to the input files
#---------------------------------------------------------------------------
# The INPUT tag is used to specify the files and/or directories that contain
# documented source files. You may enter file names like myfile.cpp or
# directories like /usr/src/myproject. Separate the files or directories with
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
INPUT = @LAMMPS_SOURCE_DIR@/utils.cpp \
@LAMMPS_SOURCE_DIR@/utils.h \
@LAMMPS_SOURCE_DIR@/library.cpp \
@LAMMPS_SOURCE_DIR@/library.h \
@LAMMPS_SOURCE_DIR@/lammps.cpp \
@LAMMPS_SOURCE_DIR@/lammps.h \
@LAMMPS_SOURCE_DIR@/lmptype.h \
@LAMMPS_SOURCE_DIR@/pointers.h \
@LAMMPS_SOURCE_DIR@/atom.cpp \
@LAMMPS_SOURCE_DIR@/atom.h \
@LAMMPS_SOURCE_DIR@/input.cpp \
@LAMMPS_SOURCE_DIR@/input.h \
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded
# from the input.
# The default value is: NO.
EXCLUDE_SYMLINKS = YES
#---------------------------------------------------------------------------
# Configuration options related to output
#---------------------------------------------------------------------------
GENERATE_HTML = NO
GENERATE_LATEX = NO
GENERATE_XML = YES
XML_OUTPUT = xml
XML_PROGRAMLISTING = YES
XML_NS_MEMB_FILE_SCOPE = NO
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all
# C-preprocessor directives found in the sources and include files.
# The default value is: YES.
#ENABLE_PREPROCESSING = YES
ENABLE_PREPROCESSING = NO
# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
# in the source code. If set to NO, only conditional compilation will be
# performed. Macro expansion can be done in a controlled way by setting
# EXPAND_ONLY_PREDEF to YES.
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
MACRO_EXPANSION = NO
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
# EXPAND_AS_DEFINED tags.
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
EXPAND_ONLY_PREDEF = NO
# If the SEARCH_INCLUDES tag is set to YES, the include files in the
# INCLUDE_PATH will be searched if a #include is found.
# The default value is: YES.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
SEARCH_INCLUDES = YES
# The INCLUDE_PATH tag can be used to specify one or more directories that
# contain include files that are not input files but should be processed by the
# preprocessor.
# This tag requires that the tag SEARCH_INCLUDES is set to YES.
INCLUDE_PATH =
# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
# patterns (like *.h and *.hpp) to filter out the header-files in the
# directories. If left blank, the patterns specified with FILE_PATTERNS will be
# used.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
INCLUDE_FILE_PATTERNS =
# The PREDEFINED tag can be used to specify one or more macro names that are
# defined before the preprocessor is started (similar to the -D option of e.g.
# gcc). The argument of the tag is a list of macros of the form: name or
# name=definition (no spaces). If the definition and the "=" are omitted, "=1"
# is assumed. To prevent a macro definition from being undefined via #undef or
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED =
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
# macro definition that is found in the sources will be used. Use the PREDEFINED
# tag if you want to use a different macro definition that overrules the
# definition found in the source code.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
EXPAND_AS_DEFINED =
# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
# remove all references to function-like macros that are alone on a line, have
# an all uppercase name, and do not end with a semicolon. Such function macros
# are typically used for boiler-plate code, and will confuse the parser if not
# removed.
# The default value is: YES.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
SKIP_FUNCTION_MACROS = YES

BIN
doc/doxygen/lammps-logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

3
doc/graphviz/.gitignore vendored Normal file
View File

@ -0,0 +1,3 @@
/*.png
/*.svg
/*.pdf

30
doc/graphviz/Makefile Normal file
View File

@ -0,0 +1,30 @@
# Makefile for generating images with graphviz
#
SHELL = /bin/bash
BUILDDIR = ${CURDIR}/..
IMGDIR = $(BUILDDIR)/src/JPG
IMGSRC = $(wildcard *.dot)
IMGPNG = $(IMGSRC:%.dot=$(IMGDIR)/%.png)
HAS_DOT = NO
ifeq ($(shell which dot >/dev/null 2>&1; echo $$?), 0)
HAS_DOT = YES
endif
all: $(IMGPNG)
clean:
rm -f $(IMGSVG) $(IMGPDF) $(IMGPNG) *~
ifeq ($(HAS_DOT),YES)
$(IMGDIR)/%.png: %.dot
dot -Tpng -o $@ $<
endif
ifeq ($(HAS_DOT),NO)
$(IMGDIR)/%.png: %.dot
@echo '###################################################'
@echo '# Need to install "graphviz" to regenerate graphs #'
@echo '###################################################'
endif

90
doc/graphviz/lammps-classes.dot Normal file
View File

@ -0,0 +1,90 @@
// LAMMPS Class topology
digraph lammps {
rankdir="LR"
La [shape=circle label="LAMMPS"]
At [shape=box label="Atom" color=blue]
Ci [shape=box label="CiteMe"]
Co [shape=box label="Comm" color=blue]
Do [shape=box label="Domain" color=blue]
Er [shape=box label="Error" color=blue]
Fo [shape=box label="Force" color=blue]
Gr [shape=box label="Group" color=blue]
In [shape=box label="Input" color=blue]
Ko [shape=box label="KokkosLMP"]
Ak [shape=box label="AtomKK" color=blue]
Mk [shape=box label="MemoryKK" color=blue]
Me [shape=box label="Memory" color=blue]
Mo [shape=box label="Modify" color=blue]
Ne [shape=box label="Neighbor" color=blue]
Ou [shape=box label="Output" color=blue]
Py [shape=box label="Python" color=blue]
Up [shape=box label="Update" color=blue]
Un [shape=box label="Universe" color=blue]
Ti [shape=box label="Timer" color=blue]
Rg [label="Region" color=red]
Rb [shape=box label="RegionBlock"]
Rs [shape=box label="RegionSphere"]
Av [label="AtomVec" color=red]
It [label="Integrate" color=red]
Mi [label="Min" color=red]
Pa [label="Pair" color=red]
Bo [label="Bond" color=red]
An [label="Angle" color=red]
Di [label="Dihedral" color=red]
Im [label="Improper" color=red]
Ks [label="Kspace" color=red]
Du [label="Dump" color=red]
Fi [label="Fix" color=red]
Cp [label="Compute" color=red]
Th [label="Thermo"]
Va [label="Variable"]
Ew [shape=box label="Ewald"]
Pp [shape=box label="PPPM"]
Ff [label="FFT3d"]
Re [label="Remap"]
Gc [label="GridComm"]
Cb [shape=box label="CommBrick"]
Ct [shape=box label="CommTiled"]
Aa [shape=box label="AtomVecAtomic"]
Am [shape=box label="AtomVecMolecular"]
Lj [shape=box label="PairLJCut"]
Lo [shape=box label="PairLJCutOMP"]
Lg [shape=box label="PairLJCutGPU"]
Te [shape=box label="PairTersoff"]
Bh [shape=box label="BondHarmonic"]
Bf [shape=box label="BondFENE"]
Fa [shape=box label="FixAveTime"]
Fn [shape=box label="FixNVE"]
Fh [shape=box label="FixNH"]
Fp [shape=box label="FixNPT"]
Ft [shape=box label="FixNVT"]
Da [shape=box label="DumpAtom"]
Dc [shape=box label="DumpCustom"]
Dg [shape=box label="DumpCFG"]
Ve [shape=box label="Verlet"]
Rr [shape=box label="Respa"]
Po [shape=box label="PPPMOmp"]
La -> {At Ci Co Do Er Fo Gr In Ko Ak Mk Me Mo Ne Ou Py Ti Up Un} [penwidth=2]
Do -> {Rg} [penwidth=2]
Co -> {Cb Ct} [style=dashed penwidth=2]
Rg -> {Rb Rs} [style=dashed penwidth=2]
In -> Va [penwidth=2]
Mo -> {Fi Cp} [penwidth=2]
Fo -> {Pa Bo An Di Im Ks} [penwidth=2]
Ks -> {Ew Pp} [style=dashed penwidth=2]
Pp -> {Ff Re Gc} [penwidth=2]
Pp -> {Po} [style=dashed penwidth=2]
Up -> {It Mi} [penwidth=2]
It -> {Ve Rr} [style=dashed penwidth=2]
Ou -> {Du Th} [penwidth=2]
Du -> {Da Dc} [style=dashed penwidth=2]
Dc -> {Dg} [style=dashed penwidth=2]
At -> Av [penwidth=2]
Av -> {Aa Am} [style=dashed penwidth=2]
Pa -> {Lj Te} [style=dashed penwidth=2]
Lj -> {Lo Lg} [style=dashed penwidth=2]
Bo -> {Bh Bf} [style=dashed penwidth=2]
Fi -> {Fa Fn Fh} [style=dashed penwidth=2]
Fh -> {Fp Ft} [style=dashed penwidth=2]
}

4
doc/requirements.txt
View File

@ -1,4 +0,0 @@
Sphinx
sphinxcontrib-spelling
breathe
Pygments

8
doc/src/Build_development.rst
View File

@ -378,22 +378,22 @@ The images below illustrate how the data is presented.
.. list-table::
* - .. figure:: JPG/coverage-overview-top.png
:target: JPG/coverage-overview-top.png
:scale: 25%
Top of the overview page
- .. figure:: JPG/coverage-overview-manybody.png
:target: JPG/coverage-overview-manybody.png
:scale: 25%
Styles with good coverage
- .. figure:: JPG/coverage-file-top.png
:target: JPG/coverage-file-top.png
:scale: 25%
Top of individual source page
- .. figure:: JPG/coverage-file-branches.png
:target: JPG/coverage-file-branches.png
:scale: 25%
Source page with branches

3
doc/src/Errors_messages.rst
View File

@ -502,8 +502,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Bond/react: Unknown section in map file*
Please ensure reaction map files are properly formatted.
*Bond/react: Atom type affected by reaction too close to template edge*
*Bond/react: Bond type affected by reaction too close to template edge*
*Bond/react: Atom/Bond type affected by reaction too close to template edge*
This means an atom which changes type or connectivity during the
reaction is too close to an 'edge' atom defined in the map
file. This could cause incorrect assignment of bonds, angle, etc.

12
doc/src/Howto_cmake.rst
View File

@ -191,19 +191,19 @@ You start the command ``ccmake ../cmake`` in the ``build`` folder.
.. list-table::
* - .. figure:: JPG/ccmake-initial.png
:target: JPG/ccmake-initial.png
:scale: 33%
:align: center
Initial ``ccmake`` screen
- .. figure:: JPG/ccmake-config.png
:target: JPG/ccmake-config.png
:scale: 33%
:align: center
Configure output of ``ccmake``
- .. figure:: JPG/ccmake-options.png
:target: JPG/ccmake-options.png
:scale: 33%
:align: center
Options screen of ``ccmake``
@ -236,19 +236,19 @@ not required, it can also be entered from the GUI.
.. list-table::
* - .. figure:: JPG/cmake-gui-initial.png
:target: JPG/cmake-gui-initial.png
:scale: 40%
:align: center
Initial ``cmake-gui`` screen
- .. figure:: JPG/cmake-gui-popup.png
:target: JPG/cmake-gui-popup.png
:scale: 60%
:align: center
Generator selection in ``cmake-gui``
- .. figure:: JPG/cmake-gui-options.png
:target: JPG/cmake-gui-options.png
:scale: 40%
:align: center
Options screen of ``cmake-gui``

BIN
doc/src/JPG/lammps-classes.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 245 KiB

13
doc/src/Manual.rst
View File

@ -60,6 +60,19 @@ every LAMMPS command.
Errors
Manual_build
.. _programmer_documentation:
.. toctree::
:maxdepth: 2
:numbered: 3
:caption: Programmer Documentation
:name: progdoc
:includehidden:
pg_developer
.. pg_library
.. pg_modify
.. pg_base
.. toctree::
:caption: Index
:name: index

6
doc/src/pair_mesodpd.rst
View File

@ -250,8 +250,12 @@ from :ref:`(Li2013_POF) <Li2013_POF>`. The short mDPD run (about 2 minutes
on a single core) generates a particle trajectory which can
be visualized as follows.
.. only:: html
.. image:: JPG/examples_mdpd.gif
:align: center
.. image:: JPG/examples_mdpd_first.jpg
:target: JPG/examples_mdpd.gif
:align: center
.. image:: JPG/examples_mdpd_last.jpg

120
doc/src/pg_developer.rst Normal file
View File

@ -0,0 +1,120 @@
LAMMPS Developer Guide
**********************
This section describes the internal structure and basic algorithms
of the LAMMPS code. This is a work in progress and additional
information will be added incrementally depending on availability
of time and requests from the LAMMPS user community.
LAMMPS source files
===================
The source files of the LAMMPS code are distributed across two
directories of the distribution. The core of the code is located in the
``src`` folder and its sub-directories. Almost all of those are C++ files
(implementation files have a ``.cpp`` extension and and headers a
``.h``). A sizable number of these files are in the ``src`` directory
itself, but there are plenty of :doc:`packages <Packages>`, which can be
included or excluded when LAMMPS is built. See the :doc:`Include
packages in build <Build_package>` section of the manual for more
information about that part of the build process. LAMMPS currently
supports building with :doc:`conventional makefiles <Build_make>` and
through :doc:`CMake <Build_cmake>` which differ in how packages are
enabled or disabled for a LAMMPS binary. The source files for each
package are in all-uppercase sub-directories of the ``src`` folder, for
example ``src/MOLECULE`` or ``src/USER-MISC``. The ``src/STUBS``
sub-directory is not a package but contains a dummy MPI library, that is
used when building a serial version of the code. the ``src/MAKE``
directory contains makefiles with settings and flags for a variety of
configuration and machines for the build process with traditional
makefiles.
The ``lib`` directory contains the source code for several supporting
libraries or files with configuration settings to use globally installed
libraries, that are required by some of the optional packages.
Each sub-directory, like ``lib/poems`` or ``lib/gpu``, contains the
source files, some of which are in different languages such as Fortran
or CUDA. These libraries are linked to during a LAMMPS build, if the
corresponding package is installed.
LAMMPS C++ source files almost always come in pairs, such as
``src/run.cpp`` and ``src/run.h``. The pair of files defines a C++
class, for example the :cpp:class:`LAMMPS_NS::Run` class which contains
the code invoked by the :doc:`run <run>` command in a LAMMPS input script.
As this example illustrates, source file and class names often have a
one-to-one correspondence with a command used in a LAMMPS input script.
Some source files and classes do not have a corresponding input script
command, e.g. ``src/force.cpp`` and the :cpp:class:`LAMMPS_NS::Force`
class. They are discussed in the next section.
Overview of LAMMPS class topology
=================================
Though LAMMPS has a lot of source files and classes, its class topology
is relative flat, as outlined in the :ref:`class-topology` figure. Each
name refers to a class and has a pair of associated source files in the
``src`` folder, for example the class :cpp:class:`LAMMPS_NS::Memory`
corresponds to the files ``memory.cpp`` and ``memory.h``, or the class
:cpp:class:`LAMMPS_NS::AtomVec` corresponds to the files
``atom_vec.cpp`` and ``atom_vec.h``. Full lines in the figure represent
compositing: that is the class to the left holds a pointer to an
instance of the class to the right. Dashed lines instead represent
inheritance: the class to the right is derived from the class on the
left. Classes with a red boundary are not instantiated directly, but
they represent the base classes for "styles". Those "styles" make up
the bulk of the LAMMPS code and only a few typical examples are included
in the figure for demonstration purposes.
.. _class-topology:
.. figure:: JPG/lammps-classes.png
LAMMPS class topology
This figure shows some of the relations of the base classes of the
LAMMPS simulation package. Full lines indicate that a class holds an
instance of the class it is pointing to; dashed lines point to
derived classes that are given as examples of what classes may be
instantiated during a LAMMPS run based on the input commands and
accessed through the API define by their respective base classes. At
the core is the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class, which
holds pointers to class instances with specific purposes. Those may
hold instances of other classes, sometimes directly, or only
temporarily, sometimes as derived classes or derived classes or
derived classes, which may also hold instances of other classes.
The :cpp:class:`LAMMPS_NS::LAMMPS` class is the topmost class and
represents what is referred to an "instance" of LAMMPS. It is a
composite holding references to instances of other core classes
providing the core functionality of the MD engine in LAMMPS and through
them abstractions of the required operations. The constructor of the
LAMMPS class will instantiate those instances, process the command line
flags, initialize MPI (if not already done) and set up file pointers for
input and output. The destructor will shut everything down and free all
associated memory. Thus code for the standalone LAMMPS executable in
``main.cpp`` simply initializes MPI, instantiates a single instance of
LAMMPS, and passes it the command line flags and input script. It
deletes the LAMMPS instance after the method reading the input returns
and shuts down the MPI environment before it exits the executable.
The :cpp:class:`LAMMPS_NS::Pointers` is not shown in the
:ref:`class-topology` figure, it holds references to members of the
`LAMMPS_NS::LAMMPS`, so that all classes derived from
:cpp:class:`LAMMPS_NS::Pointers` have direct access to those reference.
From the class topology all classes with blue boundary are referenced in
this class and all classes in the second and third columns, that are not
listed as derived classes are instead derived from
:cpp:class:`LAMMPS_NS::Pointers`.
Since all storage is encapsulated, the LAMMPS class can also be
instantiated multiple times by a calling code, and that can be either
simultaneously or consecutively. When running in parallel with MPI,
care has to be taken, that suitable communicators are used to not
create conflicts between different instances.
The LAMMPS class currently holds instances of 19 classes representing
different core functionalities
There are a handful of virtual parent classes in LAMMPS that define
what LAMMPS calls ``styles``. They are shaded red in Fig
\ref{fig:classes}. Each of these are parents of a number of child
classes that implement the interface defined by the parent class.

4
doc/utils/requirements.txt
View File

@ -1 +1,5 @@
Sphinx
sphinxcontrib-spelling
sphinx-fortran
breathe
Pygments

7
doc/utils/sphinx-config/_static/css/lammps.css
View File

@ -7,3 +7,10 @@
display: block;
margin-bottom: 0.809em;
}
.lammps_release {
text-align: center;
font-size: 11px;
display: block;
margin-bottom: 0.405em;
}

0
doc/src/JPG/lammps-logo.png → doc/utils/sphinx-config/_static/lammps-logo.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

11
doc/utils/sphinx-config/_themes/lammps_theme/layout.html
View File

@ -103,6 +103,12 @@
{%- endif %}
{%- endblock %}
{%- block extrahead %} {% endblock %}
{# Keep modernizr in head - http://modernizr.com/docs/#installing #}
<script src="{{ pathto('_static/js/modernizr.min.js', 1) }}"></script>
{# for improved browser compatibility #}
<script src="{{ pathto('_static/polyfill.js', 1) }}"></script>
</head>
<body class="wy-body-for-nav">
@ -135,9 +141,8 @@
{%- set nav_version = current_version %}
{% endif %}
{% if nav_version %}
<div class="version">
{{ nav_version }}
</div>
<div class="lammps_version">Version: <b>{{ nav_version }}</b></div>
<div class="lammps_release">git info: {{ release }}</div>
{% endif %}
{% endif %}

49
doc/utils/sphinx-config/conf.py → doc/utils/sphinx-config/conf.py.in
View File

@ -23,11 +23,16 @@ try:
except:
pass
LAMMPS_DOC_DIR = '@LAMMPS_DOC_DIR@'
LAMMPS_SOURCE_DIR = '@LAMMPS_SOURCE_DIR@'
LAMMPS_PYTHON_DIR = '@LAMMPS_PYTHON_DIR@'
LAMMPS_DOXYGEN_XML_DIR = '@DOXYGEN_XML_DIR@'
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
sys.path.append(os.path.join(os.path.dirname(__file__), '../../src/_ext'))
sys.path.append(os.path.join(LAMMPS_DOC_DIR, 'src', '_ext'))
# -- General configuration ------------------------------------------------
@ -41,7 +46,9 @@ extensions = [
'sphinx.ext.mathjax',
'sphinx.ext.imgmath',
'sphinx.ext.autodoc',
'sphinxfortran.fortran_domain',
'table_from_list',
'breathe',
]
# 2017-12-07: commented out, since this package is broken with Sphinx 16.x
# yet we can no longer use Sphinx 15.x, since that breaks with
@ -72,12 +79,24 @@ copyright = '2003-2020 Sandia Corporation'
def get_lammps_version():
import os
script_dir = os.path.dirname(os.path.realpath(__file__))
with open(os.path.join(script_dir, '../../../src/version.h'), 'r') as f:
with open(os.path.join(LAMMPS_SOURCE_DIR, 'version.h'), 'r') as f:
line = f.readline()
start_pos = line.find('"')+1
end_pos = line.find('"', start_pos)
return line[start_pos:end_pos]
def get_git_info():
import subprocess,time
git_n_date = ''
try:
gitinfo = subprocess.run(['git','describe'],stdout=subprocess.PIPE,stderr=subprocess.PIPE)
if gitinfo.returncode == 0:
git_n_date = gitinfo.stdout.decode().replace('_',' ')
except:
pass
return git_n_date
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
@ -85,7 +104,7 @@ def get_lammps_version():
# The short X.Y version.
version = get_lammps_version()
# The full version, including alpha/beta/rc tags.
release = ''
release = get_git_info()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@ -153,7 +172,7 @@ html_title = "LAMMPS documentation"
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = 'lammps-logo.png'
html_logo = '_static/lammps-logo.png'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
@ -314,7 +333,7 @@ texinfo_documents = [
epub_title = 'LAMMPS Documentation - ' + get_lammps_version()
epub_cover = ('lammps-logo.png', '')
epub_cover = ('_static/lammps-logo.png', '')
epub_description = """
This is the Manual for the LAMMPS software package.
@ -342,13 +361,29 @@ if spelling_spec and has_enchant:
spelling_lang='en_US'
spelling_word_list_filename='false_positives.txt'
sys.path.append(os.path.join(os.path.dirname(__file__), '.'))
conf_script_dir = os.path.dirname(os.path.realpath(__file__))
sys.path.append(os.path.join(conf_script_dir, '.'))
import LAMMPSLexer
from sphinx.highlighting import lexers
lexers['LAMMPS'] = LAMMPSLexer.LAMMPSLexer(startinline=True)
sys.path.append(os.path.join(os.path.dirname(__file__), '../../../python'))
sys.path.append(LAMMPS_PYTHON_DIR)
# avoid syntax highlighting in blocks that don't specify language
highlight_language = 'none'
# autodoc configuration
autodoc_member_order = 'bysource'
#autoclass_content = 'both'
# breathe configuration
breathe_projects = { 'progguide' : LAMMPS_DOXYGEN_XML_DIR }
breathe_default_project = 'progguide'
breathe_show_define_initializer = True
breathe_domain_by_extension = { 'h' : 'cpp',
'cpp' : 'cpp',
'c' : 'c',
}

1
doc/utils/sphinx-config/false_positives.txt
View File

@ -437,6 +437,7 @@ Colvars
COLVARS
comID
Commun
compositing
compressibility
compressive
Comput

1
doc/utils/sphinx-config/lammps-logo.png
View File

@ -1 +0,0 @@
../../src/JPG/lammps-logo.png

7
src/reset_mol_ids.cpp
View File

@ -41,14 +41,17 @@ ResetMolIDs::ResetMolIDs(LAMMPS *lmp) : Pointers(lmp) {
compressflag = 1;
singleflag = 0;
offset = -1;
idfrag.clear();
idchunk.clear();
}
/* ---------------------------------------------------------------------- */
ResetMolIDs::~ResetMolIDs()
{
modify->delete_compute(idfrag);
if (compressflag) modify->delete_compute(idchunk);
if (!idfrag.empty()) modify->delete_compute(idfrag);
if (compressflag && !idchunk.empty()) modify->delete_compute(idchunk);
}
/* ----------------------------------------------------------------------

32
src/utils.cpp
View File

@ -352,7 +352,7 @@ tagint utils::tnumeric(const char *file, int line, const char *str,
Return string without leading or trailing whitespace
------------------------------------------------------------------------- */
std::string utils::trim(const std::string & line) {
std::string utils::trim(const std::string &line) {
int beg = re_match(line.c_str(),"\\S+");
int end = re_match(line.c_str(),"\\s+$");
if (beg < 0) beg = 0;
@ -365,7 +365,7 @@ std::string utils::trim(const std::string & line) {
Return string without trailing # comment
------------------------------------------------------------------------- */
std::string utils::trim_comment(const std::string & line) {
std::string utils::trim_comment(const std::string &line) {
auto end = line.find_first_of("#");
if (end != std::string::npos) {
return line.substr(0, end);
@ -377,7 +377,7 @@ std::string utils::trim_comment(const std::string & line) {
return number of words
------------------------------------------------------------------------- */
size_t utils::count_words(const char * text) {
size_t utils::count_words(const char *text) {
size_t count = 0;
const char * buf = text;
char c = *buf;
@ -406,7 +406,7 @@ size_t utils::count_words(const char * text) {
return number of words
------------------------------------------------------------------------- */
size_t utils::count_words(const std::string & text) {
size_t utils::count_words(const std::string &text) {
return utils::count_words(text.c_str());
}
@ -414,7 +414,7 @@ size_t utils::count_words(const std::string & text) {
Return number of words
------------------------------------------------------------------------- */
size_t utils::count_words(const std::string & text, const std::string & separators) {
size_t utils::count_words(const std::string &text, const std::string &separators) {
size_t count = 0;
size_t start = text.find_first_not_of(separators);
@ -435,7 +435,7 @@ size_t utils::count_words(const std::string & text, const std::string & separato
Trim comment from string and return number of words
------------------------------------------------------------------------- */
size_t utils::trim_and_count_words(const std::string & text, const std::string & separators) {
size_t utils::trim_and_count_words(const std::string &text, const std::string &separators) {
return utils::count_words(utils::trim_comment(text), separators);
}
@ -526,7 +526,7 @@ std::vector<std::string> utils::split_words(const std::string &text)
Return whether string is a valid integer number
------------------------------------------------------------------------- */
bool utils::is_integer(const std::string & str) {
bool utils::is_integer(const std::string &str) {
if (str.size() == 0) {
return false;
}
@ -542,7 +542,7 @@ bool utils::is_integer(const std::string & str) {
Return whether string is a valid floating-point number
------------------------------------------------------------------------- */
bool utils::is_double(const std::string & str) {
bool utils::is_double(const std::string &str) {
if (str.size() == 0) {
return false;
}
@ -560,7 +560,7 @@ bool utils::is_double(const std::string & str) {
strip off leading part of path, return just the filename
------------------------------------------------------------------------- */
std::string utils::path_basename(const std::string & path) {
std::string utils::path_basename(const std::string &path) {
#if defined(_WIN32)
size_t start = path.find_last_of("/\\");
#else
@ -580,7 +580,7 @@ std::string utils::path_basename(const std::string & path) {
join two paths
------------------------------------------------------------------------- */
std::string utils::path_join(const std::string & a, const std::string & b) {
std::string utils::path_join(const std::string &a, const std::string &b) {
#if defined(_WIN32)
return fmt::format("{}\\{}", a, b);
#else
@ -592,7 +592,7 @@ std::string utils::path_join(const std::string & a, const std::string & b) {
try to open file for reading
------------------------------------------------------------------------- */
bool utils::file_is_readable(const std::string & path) {
bool utils::file_is_readable(const std::string &path) {
FILE * fp = fopen(path.c_str(), "r");
if(fp) {
fclose(fp);
@ -607,7 +607,7 @@ bool utils::file_is_readable(const std::string & path) {
specified
------------------------------------------------------------------------- */
std::string utils::get_potential_file_path(const std::string& path) {
std::string utils::get_potential_file_path(const std::string &path) {
std::string filepath = path;
std::string filename = utils::path_basename(path);
@ -634,7 +634,7 @@ std::string utils::get_potential_file_path(const std::string& path) {
if it has a DATE field, return the following word
------------------------------------------------------------------------- */
std::string utils::get_potential_date(const std::string & path, const std::string & potential_name) {
std::string utils::get_potential_date(const std::string &path, const std::string &potential_name) {
TextFileReader reader(path, potential_name);
reader.ignore_comments = false;
@ -657,7 +657,7 @@ std::string utils::get_potential_date(const std::string & path, const std::strin
if it has UNITS field, return following word
------------------------------------------------------------------------- */
std::string utils::get_potential_units(const std::string & path, const std::string & potential_name) {
std::string utils::get_potential_units(const std::string &path, const std::string &potential_name) {
TextFileReader reader(path, potential_name);
reader.ignore_comments = false;
@ -710,7 +710,7 @@ double utils::get_conversion_factor(const int property, const int conversion)
the strings "off" and "unlimited" result in -1.0;
------------------------------------------------------------------------- */
double utils::timespec2seconds(const std::string & timespec)
double utils::timespec2seconds(const std::string &timespec)
{
double vals[3];
int i = 0;
@ -728,7 +728,7 @@ double utils::timespec2seconds(const std::string & timespec)
if (!values.has_next()) break;
vals[i] = values.next_int();
}
} catch (TokenizerException & e) {
} catch (TokenizerException &e) {
return -1.0;
}

128
src/utils.h
View File

@ -29,7 +29,7 @@ namespace LAMMPS_NS {
namespace utils {
/** \brief Match text against a simplified regex pattern
/** Match text against a simplified regex pattern
*
* \param text the text to be matched against the pattern
* \param pattern the search pattern, which may contain regexp markers
@ -37,14 +37,14 @@ namespace LAMMPS_NS {
*/
bool strmatch(const std::string &text, const std::string &pattern);
/** \brief Send message to screen and logfile, if available
/** Send message to screen and logfile, if available
*
* \param lmp pointer to LAMMPS class instance
* \param mesg message to be printed
*/
void logmesg(LAMMPS *lmp, const std::string &mesg);
/** \brief return a string representing the current system error status
/** return a string representing the current system error status
*
* This is a wrapper around calling strerror(errno).
*
@ -52,7 +52,7 @@ namespace LAMMPS_NS {
*/
std::string getsyserror();
/** \brief safe wrapper around fgets() which aborts on errors
/** safe wrapper around fgets() which aborts on errors
* or EOF and prints a suitable error message to help debugging
*
* \param srcname name of the calling source file (from FLERR macro)
@ -66,7 +66,7 @@ namespace LAMMPS_NS {
void sfgets(const char *srcname, int srcline, char *s, int size,
FILE *fp, const char *filename, Error *error);
/** \brief safe wrapper around fread() which aborts on errors
/** safe wrapper around fread() which aborts on errors
* or EOF and prints a suitable error message to help debugging
*
* \param srcname name of the calling source file (from FLERR macro)
@ -81,7 +81,7 @@ namespace LAMMPS_NS {
void sfread(const char *srcname, int srcline, void *s, size_t size,
size_t num, FILE *fp, const char *filename, Error *error);
/** \brief Report if a requested style is in a package or may have a typo
/** Report if a requested style is in a package or may have a typo
*
* \param style type of style that is to be checked for
* \param name name of style that was not found
@ -91,8 +91,8 @@ namespace LAMMPS_NS {
std::string check_packages_for_style(const std::string &style,
const std::string &name, LAMMPS *lmp);
/** \brief Convert a string to a floating point number while checking
if it is a valid floating point or integer number
/** Convert a string to a floating point number while checking
* if it is a valid floating point or integer number
*
* \param file name of source file for error message
* \param line in source file for error message
@ -104,8 +104,8 @@ namespace LAMMPS_NS {
double numeric(const char *file, int line, const char *str,
bool do_abort, LAMMPS *lmp);
/** \brief Convert a string to an integer number while checking
if it is a valid integer number (regular int)
/** Convert a string to an integer number while checking
* if it is a valid integer number (regular int)
*
* \param file name of source file for error message
* \param line in source file for error message
@ -117,8 +117,8 @@ namespace LAMMPS_NS {
int inumeric(const char *file, int line, const char *str,
bool do_abort, LAMMPS *lmp);
/** \brief Convert a string to an integer number while checking
if it is a valid integer number (bigint)
/** Convert a string to an integer number while checking
* if it is a valid integer number (bigint)
*
* \param file name of source file for error message
* \param line in source file for error message
@ -130,8 +130,8 @@ namespace LAMMPS_NS {
bigint bnumeric(const char *file, int line, const char *str,
bool do_abort, LAMMPS *lmp);
/** \brief Convert a string to an integer number while checking
if it is a valid integer number (tagint)
/** Convert a string to an integer number while checking
* if it is a valid integer number (tagint)
*
* \param file name of source file for error message
* \param line in source file for error message
@ -143,54 +143,51 @@ namespace LAMMPS_NS {
tagint tnumeric(const char *file, int line, const char *str,
bool do_abort, LAMMPS *lmp);
/**
* \brief Trim leading and trailing whitespace. Like TRIM() in Fortran.
/** Trim leading and trailing whitespace. Like TRIM() in Fortran.
*
* \param line string that should be trimmed
* \return new string without whitespace (string)
*/
std::string trim(const std::string &line);
/**
* \brief Trim anything from '#' onward
/** Trim anything from '#' onward
*
* \param line string that should be trimmed
* \return new string without comment (string)
*/
std::string trim_comment(const std::string &line);
/**
* \brief Count words in string
/** Count words in string
*
* \param text string that should be searched
* \param separators string containing characters that will be treated as whitespace
* \return number of words found
*/
size_t count_words(const std::string & text, const std::string & separators);
size_t count_words(const std::string &text, const std::string &separators);
/**
* \brief Count words in string, ignore any whitespace matching " \t\r\n\f"
/** Count words in string, ignore any whitespace matching " \t\r\n\f"
*
* \param text string that should be searched
* \param separators string containing characters that will be treated as whitespace
* \return number of words found
*/
size_t count_words(const std::string & text);
size_t count_words(const std::string &text);
/**
* \brief Count words in C-string, ignore any whitespace matching " \t\r\n\f"
/** Count words in C-string, ignore any whitespace matching " \t\r\n\f"
*
* \param text string that should be searched
* \param separators string containing characters that will be treated as whitespace
* \return number of words found
*/
size_t count_words(const char * text);
size_t count_words(const char *text);
/**
* \brief Count words in a single line, trim anything from '#' onward
/** Count words in a single line, trim anything from '#' onward
*
* \param text string that should be trimmed and searched
* \param separators string containing characters that will be treated as whitespace
* \return number of words found
*/
size_t trim_and_count_words(const std::string & text, const std::string & separators = " \t\r\n\f");
size_t trim_and_count_words(const std::string &text, const std::string &separators = " \t\r\n\f");
/**
* \brief Take text and split into non-whitespace words.
/** Take text and split into non-whitespace words.
*
* This can handle single and double quotes, escaped quotes,
* and escaped codes within quotes, but due to using an STL
@ -203,21 +200,21 @@ namespace LAMMPS_NS {
*/
std::vector<std::string> split_words(const std::string &text);
/**
* \brief Check if string can be converted to valid integer
* \param text string that should be checked
/** Check if string can be converted to valid integer
*
* \param str string that should be checked
* \return true, if string contains valid integer, false otherwise
*/
bool is_integer(const std::string & str);
bool is_integer(const std::string &str);
/**
* \brief Check if string can be converted to valid floating-point number
* \param text string that should be checked
/** Check if string can be converted to valid floating-point number
*
* \param str string that should be checked
* \return true, if string contains valid floating-point number, false otherwise
*/
bool is_double(const std::string & str);
bool is_double(const std::string &str);
/** \brief try to detect pathname from FILE pointer.
/** Try to detect pathname from FILE pointer.
*
* Currently only supported on Linux, otherwise will report "(unknown)".
*
@ -228,12 +225,12 @@ namespace LAMMPS_NS {
*/
const char *guesspath(char *buf, int len, FILE *fp);
/**
* \brief Strip off leading part of path, return just the filename
/** Strip off leading part of path, return just the filename
*
* \param path file path
* \return file name
*/
std::string path_basename(const std::string & path);
std::string path_basename(const std::string &path);
/**
* \brief Join two paths
@ -241,64 +238,65 @@ namespace LAMMPS_NS {
* \param b second path
* \return combined path
*/
std::string path_join(const std::string & a, const std::string & b);
std::string path_join(const std::string &a, const std::string &b);
/**
* \brief Check if file exists and is readable
* \param path file path
* \return true if file exists and is readable
*/
bool file_is_readable(const std::string & path);
bool file_is_readable(const std::string &path);
/**
* \brief Determine full path of potential file
* If file is not found in current directory, search LAMMPS_POTENTIALS folder
/** Determine full path of potential file. If file is not found in current directory,
* search LAMMPS_POTENTIALS folder
*
* \param path file path
* \return full path to potential file
*/
std::string get_potential_file_path(const std::string& path);
std::string get_potential_file_path(const std::string &path);
/**
* \brief Read potential file and return DATE field if it is present
/** Read potential file and return DATE field if it is present
*
* \param path file path
* \param potential_name name of potential that is being read
* \return DATE field if present
*/
std::string get_potential_date(const std::string & path, const std::string & potential_name);
std::string get_potential_date(const std::string &path, const std::string &potential_name);
/**
* \brief Read potential file and return UNITS field if it is present
/** Read potential file and return UNITS field if it is present
*
* \param path file path
* \param potential_name name of potential that is being read
* \return UNITS field if present
*/
std::string get_potential_units(const std::string & path, const std::string & potential_name);
std::string get_potential_units(const std::string &path, const std::string &potential_name);
enum { NOCONVERT = 0, METAL2REAL = 1, REAL2METAL = 1<<1 };
enum { UNKNOWN = 0, ENERGY };
/**
* \brief Return bitmask of available conversion factors for a given propert
/** Return bitmask of available conversion factors for a given property
*
* \param property property to be converted
* \return bitmask indicating available conversions
*/
int get_supported_conversions(const int property);
/**
* \brief Return unit conversion factor for given property and selected from/to units
/** Return unit conversion factor for given property and selected from/to units
*
* \param property property to be converted
* \param conversion constant indicating the conversion
* \return conversion factor
*/
double get_conversion_factor(const int property, const int conversion);
/**
* \brief Convert a time string to seconds
/** Convert a time string to seconds
*
* The strings "off" and "unlimited" result in -1
*
* \param timespec a string in the following format: ([[HH:]MM:]SS)
* \return total in seconds
*/
double timespec2seconds(const std::string & timespec);
double timespec2seconds(const std::string &timespec);
}
}

2
unittest/force-styles/tests/atomic-pair-reax_c.yaml
View File

@ -1,7 +1,7 @@
---
lammps_version: 21 Aug 2020
date_generated: Sun Aug 23 06:35:54 202
epsilon: 5e-12
epsilon: 7.5e-12
prerequisites: ! |
pair reax/c
fix qeq/reax

2
unittest/force-styles/tests/atomic-pair-reax_c_lgvdw.yaml
View File

@ -1,7 +1,7 @@
---
lammps_version: 21 Aug 2020
date_generated: Sun Aug 23 06:41:04 202
epsilon: 5e-11
epsilon: 1e-10
prerequisites: ! |
pair reax/c
fix qeq/reax