diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7d1f1a417b86085e0c9f0630b070b4f7ef51663c..a4fc5b7b4f111296f4ae1ddcf5dad2cc2a74fa22 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -111,6 +111,7 @@ src/exceptions.h @rbberger src/fix_nh.* @athomps src/info.* @akohlmey @rbberger src/timer.* @akohlmey +src/min* @sjplimp @stanmoore1 # tools tools/msi2lmp/* @akohlmey diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 3ff672a05d3ffba38dace3c11ecb3b98270cfeef..0f15bf02be262268e29d00fa3c1558e0f357cb63 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -68,12 +68,12 @@ How quickly your contribution will be integrated depends largely on how much eff Here is a checklist of steps you need to follow to submit a single file or user package for our consideration. Following these steps will save both you and us time. See existing files in packages in the source directory for examples. If you are uncertain, please ask on the lammps-users mailing list. * All source files you provide must compile with the most current version of LAMMPS with multiple configurations. In particular you need to test compiling LAMMPS from scratch with `-DLAMMPS_BIGBIG` set in addition to the default `-DLAMMPS_SMALLBIG` setting. Your code will need to work correctly in serial and in parallel using MPI. -* For consistency with the rest of LAMMPS and especially, if you want your contribution(s) to be added to main LAMMPS code or one of its standard packages, it needs to be written in a style compatible with other LAMMPS source files. This means: 2-character indentation per level, no tabs, no lines over 80 characters. I/O is done via the C-style stdio library, style class header files should not import any system headers, STL containers should be avoided in headers, and forward declarations used where possible or needed. All added code should be placed into the LAMMPS_NS namespace or a sub-namespace; global or static variables should be avoided, as they conflict with the modular nature of LAMMPS and the C++ class structure. There MUST NOT be any "using namespace XXX;" statements in headers. In the implementation file (.cpp) system includes should be placed in angular brackets (<>) and for c-library functions the C++ style header files should be included ( instead of , or instead of ). This all is so the developers can more easily understand, integrate, and maintain your contribution and reduce conflicts with other parts of LAMMPS. This basically means that the code accesses data structures, performs its operations, and is formatted similar to other LAMMPS source files, including the use of the error class for error and warning messages. -* Source, style name, and documentation file should follow the following naming convention: style names should be lowercase and words separated by a forward slash; for a new fix style 'foo/bar', the class should be named FixFooBar, the name of the source files should be 'fix_foo_bar.h' and 'fix_foo_bar.cpp' and the corresponding documentation should be in a file 'fix_foo_bar.txt'. +* For consistency with the rest of LAMMPS and especially, if you want your contribution(s) to be added to main LAMMPS code or one of its standard packages, it needs to be written in a style compatible with other LAMMPS source files. This means: 2-character indentation per level, no tabs, no trailing whitespace, no lines over 80 characters. I/O is done via the C-style stdio library, style class header files should not import any system headers, STL containers should be avoided in headers, and forward declarations used where possible or needed. All added code should be placed into the LAMMPS_NS namespace or a sub-namespace; global or static variables should be avoided, as they conflict with the modular nature of LAMMPS and the C++ class structure. There MUST NOT be any "using namespace XXX;" statements in headers. In the implementation file (.cpp) system includes should be placed in angular brackets (<>) and for c-library functions the C++ style header files should be included ( instead of , or instead of ). This all is so the developers can more easily understand, integrate, and maintain your contribution and reduce conflicts with other parts of LAMMPS. This basically means that the code accesses data structures, performs its operations, and is formatted similar to other LAMMPS source files, including the use of the error class for error and warning messages. +* Source, style name, and documentation file should follow the following naming convention: style names should be lowercase and words separated by a forward slash; for a new fix style 'foo/bar', the class should be named FixFooBar, the name of the source files should be 'fix_foo_bar.h' and 'fix_foo_bar.cpp' and the corresponding documentation should be in a file 'fix_foo_bar.rst'. * If you want your contribution to be added as a user-contributed feature, and it is a single file (actually a `.cpp` and `.h` file) it can be rapidly added to the USER-MISC directory. Include the one-line entry to add to the USER-MISC/README file in that directory, along with the 2 source files. You can do this multiple times if you wish to contribute several individual features. * If you want your contribution to be added as a user-contribution and it is several related features, it is probably best to make it a user package directory with a name like USER-FOO. In addition to your new files, the directory should contain a README text file. The README should contain your name and contact information and a brief description of what your new package does. If your files depend on other LAMMPS style files also being installed (e.g. because your file is a derived class from the other LAMMPS class), then an Install.sh file is also needed to check for those dependencies. See other README and Install.sh files in other USER directories as examples. Send us a tarball of this USER-FOO directory. * Your new source files need to have the LAMMPS copyright, GPL notice, and your name and email address at the top, like other user-contributed LAMMPS source files. They need to create a class that is inside the LAMMPS namespace. If the file is for one of the USER packages, including USER-MISC, then we are not as picky about the coding style (see above). I.e. the files do not need to be in the same stylistic format and syntax as other LAMMPS files, though that would be nice for developers as well as users who try to read your code. -* You **must** also create or extend a documentation file for each new command or style you are adding to LAMMPS. For simplicity and convenience, the documentation of groups of closely related commands or styles may be combined into a single file. This will be one file for a single-file feature. For a package, it might be several files. These are simple text files with a specific markup language, that are then auto-converted to HTML and PDF. The tools for this conversion are included in the source distribution, and the translation can be as simple as doing "make html pdf" in the doc folder. Thus the documentation source files must be in the same format and style as other `.txt` files in the lammps/doc/src directory for similar commands and styles; use one or more of them as a starting point. A description of the markup can also be found in `lammps/doc/utils/txt2html/README.html` As appropriate, the text files can include links to equations (see doc/Eqs/*.tex for examples, we auto-create the associated JPG files), or figures (see doc/JPG for examples), or even additional PDF files with further details (see doc/PDF for examples). The doc page should also include literature citations as appropriate; see the bottom of doc/fix_nh.txt for examples and the earlier part of the same file for how to format the cite itself. The "Restrictions" section of the doc page should indicate that your command is only available if LAMMPS is built with the appropriate USER-MISC or USER-FOO package. See other user package doc files for examples of how to do this. The prerequisite for building the HTML format files are Python 3.x and virtualenv, the requirement for generating the PDF format manual is the htmldoc software. Please run at least "make html" and carefully inspect and proofread the resulting HTML format doc page before submitting your code. +* You **must** also create or extend a documentation file for each new command or style you are adding to LAMMPS. For simplicity and convenience, the documentation of groups of closely related commands or styles may be combined into a single file. This will be one file for a single-file feature. For a package, it might be several files. These are files in the [reStructuredText](https://docutils.sourceforge.io/rst.html) markup language, that are then converted to HTML and PDF. The tools for this conversion are included in the source distribution, and the translation can be as simple as doing "make html pdf" in the doc folder. Thus the documentation source files must be in the same format and style as other `.rst` files in the lammps/doc/src directory for similar commands and styles; use one or more of them as a starting point. An introduction to reStructuredText can be found at [https://docutils.sourceforge.io/docs/user/rst/quickstart.html](https://docutils.sourceforge.io/docs/user/rst/quickstart.html). As appropriate, the text files can include mathematical expressions in MathJAX markup or links to equations (see doc/Eqs/*.tex for examples, we auto-create the associated JPG files), or figures (see doc/JPG for examples), or even additional PDF files with further details (see doc/PDF for examples). The doc page should also include literature citations as appropriate; see the bottom of doc/fix_nh.rst for examples and the earlier part of the same file for how to format the cite itself. The "Restrictions" section of the doc page should indicate that your command is only available if LAMMPS is built with the appropriate USER-MISC or USER-FOO package. See other user package doc files for examples of how to do this. The prerequisite for building the HTML format files are Python 3.x and virtualenv. Please run at least `make html` and `make spelling` and carefully inspect and proofread the resulting HTML format doc page as well as the output produced to the screen. Make sure that all spelling errors are fixed or the necessary false positives are added to the `doc/utils/sphinx-config/false_positives.txt` file. For new styles, those usually also need to be added to lists on the respective overview pages. This can be checked for also with `make style_check`. * For a new package (or even a single command) you should include one or more example scripts demonstrating its use. These should run in no more than a couple minutes, even on a single processor, and not require large data files as input. See directories under examples/USER for examples of input scripts other users provided for their packages. These example inputs are also required for validating memory accesses and testing for memory leaks with valgrind * If there is a paper of yours describing your feature (either the algorithm/science behind the feature itself, or its initial usage, or its implementation in LAMMPS), you can add the citation to the *.cpp source file. See src/USER-EFF/atom_vec_electron.cpp for an example. A LaTeX citation is stored in a variable at the top of the file and a single line of code that references the variable is added to the constructor of the class. Whenever a user invokes your feature from their input script, this will cause LAMMPS to output the citation to a log.cite file and prompt the user to examine the file. Note that you should only use this for a paper you or your group authored. E.g. adding a cite in the code for a paper by Nose and Hoover if you write a fix that implements their integrator is not the intended usage. That kind of citation should just be in the doc page you provide. diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index ddad6c2626991c197f7b70de9e0f9db923452d7c..92293f294b96f2b77671cf1927259df4e8552f06 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -588,8 +588,9 @@ if(BUILD_TOOLS) install(TARGETS binary2txt DESTINATION ${CMAKE_INSTALL_BINDIR}) # ninja-build currently does not support fortran. thus we skip building this tool - if(NOT CMAKE_GENERATOR STREQUAL "Ninja") + if(CMAKE_GENERATOR STREQUAL "Ninja") message(STATUS "Skipping building 'chain.x' with Ninja build tool due to lack of Fortran support") + else() enable_language(Fortran) add_executable(chain.x ${LAMMPS_TOOLS_DIR}/chain.f) target_link_libraries(chain.x ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES}) diff --git a/cmake/Modules/Documentation.cmake b/cmake/Modules/Documentation.cmake index 99f570820ad439eb71448c24241efca83cc50624..feff66a9b2520b4f54b214d7873337ae48269064 100644 --- a/cmake/Modules/Documentation.cmake +++ b/cmake/Modules/Documentation.cmake @@ -9,9 +9,7 @@ if(BUILD_DOC) set(VIRTUALENV ${PYTHON_EXECUTABLE} -m virtualenv) - file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.txt) - file(GLOB PDF_EXTRA_SOURCES ${LAMMPS_DOC_DIR}/src/lammps_commands*.txt ${LAMMPS_DOC_DIR}/src/lammps_support.txt ${LAMMPS_DOC_DIR}/src/lammps_tutorials.txt) - list(REMOVE_ITEM DOC_SOURCES ${PDF_EXTRA_SOURCES}) + file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.rst) add_custom_command( OUTPUT docenv @@ -28,25 +26,10 @@ if(BUILD_DOC) COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters ) - set(RST_FILES "") - set(RST_DIR ${CMAKE_BINARY_DIR}/rst) - file(MAKE_DIRECTORY ${RST_DIR}) - foreach(TXT_FILE ${DOC_SOURCES}) - get_filename_component(FILENAME ${TXT_FILE} NAME_WE) - set(RST_FILE ${RST_DIR}/${FILENAME}.rst) - list(APPEND RST_FILES ${RST_FILE}) - add_custom_command( - OUTPUT ${RST_FILE} - DEPENDS requirements.txt docenv ${TXT_FILE} - COMMAND ${DOCENV_BINARY_DIR}/txt2rst -o ${RST_DIR} ${TXT_FILE} - ) - endforeach() - add_custom_command( OUTPUT html - DEPENDS ${RST_FILES} - COMMAND ${CMAKE_COMMAND} -E copy_directory ${LAMMPS_DOC_DIR}/src ${RST_DIR} - COMMAND ${DOCENV_BINARY_DIR}/sphinx-build -j ${NPROCS} -b html -c ${LAMMPS_DOC_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${RST_DIR} html + DEPENDS ${DOC_SOURCES} docenv requirements.txt + COMMAND ${DOCENV_BINARY_DIR}/sphinx-build -j ${NPROCS} -b html -c ${LAMMPS_DOC_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${LAMMPS_DOC_DIR}/src html ) add_custom_target( diff --git a/cmake/Modules/FindNetCDF.cmake b/cmake/Modules/FindNetCDF.cmake index a28c959acf626318a5bf00e7a2e1ca0c4c3eef7e..2a992b6b3b532513d1f2886cd5e76aeaba32df20 100644 --- a/cmake/Modules/FindNetCDF.cmake +++ b/cmake/Modules/FindNetCDF.cmake @@ -46,10 +46,14 @@ endif() find_path (NETCDF_INCLUDE_DIR netcdf.h HINTS "${NETCDF_DIR}/include") mark_as_advanced (NETCDF_INCLUDE_DIR) + set (NETCDF_C_INCLUDE_DIRS ${NETCDF_INCLUDE_DIR}) +string(REGEX REPLACE "/include/?$" "" + NETCDF_LIB_HINT ${NETCDF_INCLUDE_DIR}) + find_library (NETCDF_LIBRARY NAMES netcdf - HINTS "${NETCDF_DIR}/lib") + HINTS "${NETCDF_DIR}" "${NETCDF_LIB_HINT}" PATH_SUFFIXES lib lib64) mark_as_advanced (NETCDF_LIBRARY) set (NETCDF_C_LIBRARIES ${NETCDF_LIBRARY}) diff --git a/cmake/Modules/FindPNetCDF.cmake b/cmake/Modules/FindPNetCDF.cmake new file mode 100644 index 0000000000000000000000000000000000000000..bc3a5f9538b17c82201437f3ee378e9be0bf49fa --- /dev/null +++ b/cmake/Modules/FindPNetCDF.cmake @@ -0,0 +1,55 @@ +# source: https://ftp.space.dtu.dk/pub/Ioana/pism0.6.1-10/CMake/FindPNetCDF.cmake +# license: GPL v3 (https://ftp.space.dtu.dk/pub/Ioana/pism0.6.1-10/COPYING) +# +# - Find PNetCDF +# Find the native PNetCDF includes and library +# +# PNETCDF_INCLUDES - where to find netcdf.h, etc +# PNETCDF_LIBRARIES - Link these libraries when using NetCDF +# PNETCDF_FOUND - True if PNetCDF was found +# +# Normal usage would be: +# find_package (PNetCDF REQUIRED) +# target_link_libraries (uses_pnetcdf ${PNETCDF_LIBRARIES}) + +if (PNETCDF_INCLUDES AND PNETCDF_LIBRARIES) + # Already in cache, be silent + set (PNETCDF_FIND_QUIETLY TRUE) +endif (PNETCDF_INCLUDES AND PNETCDF_LIBRARIES) + +find_path (PNETCDF_INCLUDES pnetcdf.h + HINTS "${PNETCDF_ROOT}/include" "$ENV{PNETCDF_ROOT}/include") + +string(REGEX REPLACE "/include/?$" "" + PNETCDF_LIB_HINT ${PNETCDF_INCLUDES}) + +find_library (PNETCDF_LIBRARIES + NAMES pnetcdf + HINTS ${PNETCDF_LIB_HINT} PATH_SUFFIXES lib lib64) + +if ((NOT PNETCDF_LIBRARIES) OR (NOT PNETCDF_INCLUDES)) + message(STATUS "Trying to find PNetCDF using LD_LIBRARY_PATH (we're desperate)...") + + file(TO_CMAKE_PATH "$ENV{LD_LIBRARY_PATH}" LD_LIBRARY_PATH) + + find_library(PNETCDF_LIBRARIES + NAMES pnetcdf + HINTS ${LD_LIBRARY_PATH}) + + if (PNETCDF_LIBRARIES) + get_filename_component(PNETCDF_LIB_DIR ${PNETCDF_LIBRARIES} PATH) + string(REGEX REPLACE "/(lib|lib64)/?$" "/include" + PNETCDF_H_HINT ${PNETCDF_LIB_DIR}) + + find_path (PNETCDF_INCLUDES pnetcdf.h + HINTS ${PNETCDF_H_HINT} + DOC "Path to pnetcdf.h") + endif() +endif() + +# handle the QUIETLY and REQUIRED arguments and set PNETCDF_FOUND to TRUE if +# all listed variables are TRUE +include (FindPackageHandleStandardArgs) +find_package_handle_standard_args (PNetCDF DEFAULT_MSG PNETCDF_LIBRARIES PNETCDF_INCLUDES) + +mark_as_advanced (PNETCDF_LIBRARIES PNETCDF_INCLUDES) diff --git a/cmake/Modules/Packages/KIM.cmake b/cmake/Modules/Packages/KIM.cmake index 8d172257600317ba4964f3ca167430cbd223476d..a75e248097c670957bcf91419b7c2db24582002f 100644 --- a/cmake/Modules/Packages/KIM.cmake +++ b/cmake/Modules/Packages/KIM.cmake @@ -5,6 +5,16 @@ if(PKG_KIM) include_directories(${CURL_INCLUDE_DIRS}) list(APPEND LAMMPS_LINK_LIBS ${CURL_LIBRARIES}) add_definitions(-DLMP_KIM_CURL) + set(LMP_DEBUG_CURL OFF CACHE STRING "Set libcurl verbose mode on/off. If on, it displays a lot of verbose information about its operations.") + mark_as_advanced(LMP_DEBUG_CURL) + if(LMP_DEBUG_CURL) + add_definitions(-DLMP_DEBUG_CURL) + endif() + set(LMP_NO_SSL_CHECK OFF CACHE STRING "Tell libcurl to not verify the peer. If on, the connection succeeds regardless of the names in the certificate. Insecure - Use with caution!") + mark_as_advanced(LMP_NO_SSL_CHECK) + if(LMP_NO_SSL_CHECK) + add_definitions(-DLMP_NO_SSL_CHECK) + endif() endif() find_package(KIM-API QUIET) if(KIM-API_FOUND) diff --git a/cmake/Modules/Packages/USER-NETCDF.cmake b/cmake/Modules/Packages/USER-NETCDF.cmake index a90725bbbc65114fbc546006848a7a0c68b49304..f60c046ab99aa36fc26577e4225bed9b5edd46fc 100644 --- a/cmake/Modules/Packages/USER-NETCDF.cmake +++ b/cmake/Modules/Packages/USER-NETCDF.cmake @@ -1,6 +1,24 @@ if(PKG_USER-NETCDF) - find_package(NetCDF REQUIRED) - include_directories(${NETCDF_INCLUDE_DIRS}) - list(APPEND LAMMPS_LINK_LIBS ${NETCDF_LIBRARIES}) - add_definitions(-DLMP_HAS_NETCDF -DNC_64BIT_DATA=0x0020) + # USER-NETCDF can use NetCDF, Parallel NetCDF (PNetCDF), or both. At least one necessary. + # NetCDF library enables dump sytle "netcdf", while PNetCDF enables dump style "netcdf/mpiio" + find_package(NetCDF) + if(NETCDF_FOUND) + find_package(PNetCDF) + else(NETCDF_FOUND) + find_package(PNetCDF REQUIRED) + endif(NETCDF_FOUND) + + if(NETCDF_FOUND) + include_directories(${NETCDF_INCLUDE_DIRS}) + list(APPEND LAMMPS_LINK_LIBS ${NETCDF_LIBRARIES}) + add_definitions(-DLMP_HAS_NETCDF) + endif(NETCDF_FOUND) + + if(PNETCDF_FOUND) + include_directories(${PNETCDF_INCLUDES}) + list(APPEND LAMMPS_LINK_LIBS ${PNETCDF_LIBRARIES}) + add_definitions(-DLMP_HAS_PNETCDF) + endif(PNETCDF_FOUND) + + add_definitions(-DNC_64BIT_DATA=0x0020) endif() diff --git a/doc/Makefile b/doc/Makefile index 5dcb070f4f5ddebbc17c893fbfcde5d77c468438..a3c4906cec8ecd369a7b0877a4df88e8a4885328 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -31,7 +31,7 @@ SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocess SOURCES=$(filter-out $(wildcard $(TXTDIR)/lammps_commands*.txt) $(TXTDIR)/lammps_support.txt $(TXTDIR)/lammps_tutorials.txt,$(wildcard $(TXTDIR)/*.txt)) OBJECTS=$(SOURCES:$(TXTDIR)/%.txt=$(RSTDIR)/%.rst) -.PHONY: help clean-all clean epub mobi rst html pdf venv spelling anchor_check +.PHONY: help clean-all clean epub mobi rst html pdf venv spelling anchor_check style_check # ------------------------------------------ @@ -46,6 +46,7 @@ help: @echo " clean remove all intermediate RST files" @echo " clean-all reset the entire build environment" @echo " anchor_check scan for duplicate anchor labels" + @echo " style_check check for complete and consistent style lists" @echo " spelling spell-check the manual" # ------------------------------------------ @@ -69,6 +70,7 @@ html: $(OBJECTS) $(ANCHORCHECK) echo "############################################" ;\ rst_anchor_check src/*.rst ;\ env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\ + python utils/check-styles.py -s ../src -d src ;\ echo "############################################" ;\ deactivate ;\ ) @@ -122,24 +124,27 @@ pdf: $(OBJECTS) $(ANCHORCHECK) cd ../../; \ ) @(\ - . $(VENV)/bin/activate ;\ - sphinx-build $(SPHINXEXTRA) -b latex -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\ - echo "############################################" ;\ - rst_anchor_check src/*.rst ;\ - echo "############################################" ;\ - deactivate ;\ + . $(VENV)/bin/activate ;\ + sphinx-build $(SPHINXEXTRA) -b latex -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\ + echo "############################################" ;\ + rst_anchor_check src/*.rst ;\ + env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\ + python utils/check-styles.py -s ../src -d src ;\ + echo "############################################" ;\ + deactivate ;\ ) @cd latex && \ - sed 's/latexmk -pdf -dvi- -ps-/pdflatex/g' Makefile > temp && \ - mv temp Makefile && \ - sed 's/\\begin{equation}//g' LAMMPS.tex > tmp.tex && \ - mv tmp.tex LAMMPS.tex && \ - sed 's/\\end{equation}//g' LAMMPS.tex > tmp.tex && \ - mv tmp.tex LAMMPS.tex && \ - make && \ - make && \ - mv LAMMPS.pdf ../Manual.pdf && \ - cd ../; + sed 's/latexmk -pdf -dvi- -ps-/pdflatex/g' Makefile > temp && \ + mv temp Makefile && \ + sed 's/\\begin{equation}//g' LAMMPS.tex > tmp.tex && \ + mv tmp.tex LAMMPS.tex && \ + sed 's/\\end{equation}//g' LAMMPS.tex > tmp.tex && \ + mv tmp.tex LAMMPS.tex && \ + make && \ + make && \ + make && \ + mv LAMMPS.pdf ../Manual.pdf && \ + cd ../; @rm -rf latex/_sources @rm -rf latex/PDF @rm -rf latex/USER @@ -166,9 +171,16 @@ anchor_check : $(ANCHORCHECK) deactivate ;\ ) +style_check : + @(\ + . $(VENV)/bin/activate ;\ + python utils/check-styles.py -s ../src -d src ;\ + deactivate ;\ + ) + # ------------------------------------------ -$(RSTDIR)/%.rst : src/%.txt $(TXT2RST) +$(RSTDIR)/%.rst : $(TXTDIR)/%.txt $(TXT2RST) @(\ mkdir -p $(RSTDIR) ; \ . $(VENV)/bin/activate ;\ diff --git a/doc/README b/doc/README index 6db4ba3ca76d604a41a6d19097a91cc0d1ac3efd..1416584eed4abbf9334370e5e6e326e377f0ea6a 100644 --- a/doc/README +++ b/doc/README @@ -5,7 +5,7 @@ sub-directories and optionally 2 PDF files and an ePUB file: src content files for LAMMPS documentation html HTML version of the LAMMPS manual (see html/Manual.html) -tools tools and settings for building the documentation +utils utilities and settings for building the documentation Manual.pdf large PDF version of entire manual Developer.pdf small PDF with info about how LAMMPS is structured LAMMPS.epub Manual in ePUB format @@ -25,17 +25,12 @@ the fetched documentation will include those changes (but your source code will not, unless you update your local repository). (b) You can build the HTML and PDF files yourself, by typing "make -html" followed by "make pdf". Note that the PDF make requires the -HTML files already exist. This requires various tools including -Sphinx, which the build process will attempt to download and install -on your system, if not already available. See more details below. - -(c) You can genererate an older, simpler, less-fancy style of HTML -documentation by typing "make old". This will create an "old" -directory. This can be useful if (b) does not work on your box for -some reason, or you want to quickly view the HTML version of a doc -page you have created or edited yourself within the src directory. -E.g. if you are planning to submit a new feature to LAMMPS. +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. ---------------- @@ -46,11 +41,10 @@ Options: make html # generate HTML in html dir using Sphinx make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf) - # in this dir via htmldoc and pdflatex -make old # generate old-style HTML pages in old dir via txt2html + # 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 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 @@ -94,8 +88,17 @@ This will install virtualenv from the Python Package Index. Installing prerequisites for PDF build -[TBA] - +Same as for HTML plus a compatible LaTeX installation with +support for PDFLaTeX. Also the following LaTeX packages need +to be installed (e.g. from texlive): +- amsmath +- babel +- cmap +- fncychap +- geometry +- hyperref +- hypcap +- times ---------------- Installing prerequisites for epub build @@ -103,7 +106,11 @@ Installing prerequisites for epub build ## ePUB Same as for HTML. This uses the same tools and configuration -files as the HTML tree. +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 diff --git a/doc/github-development-workflow.md b/doc/github-development-workflow.md index ee6470370708b218e6e2319de47b982adc0d1769..a000dbe453df3eb2743915b744d7c7cc59a048c8 100644 --- a/doc/github-development-workflow.md +++ b/doc/github-development-workflow.md @@ -104,14 +104,17 @@ Here are some items to check: * every new command or style should have documentation. The names of source files (c++ and manual) should follow the name of the style. (example: `src/fix_nve.cpp`, `src/fix_nve.h` for `fix nve` command, - implementing the class `FixNVE`, documented in `doc/src/fix_nve.txt`) + implementing the class `FixNVE`, documented in `doc/src/fix_nve.rst`) * all new style names should be lower case, the must be no dashes, blanks, or underscores separating words, only forward slashes. * new style docs should be added to the "overview" files in - `doc/src/Commands_*.txt`, `doc/src/{fixes,computes,pairs,bonds,...}.txt` - and `doc/src/lammps.book` + `doc/src/Commands_*.rst`, `doc/src/{fixes,computes,pairs,bonds,...}.rst` * check whether manual cleanly translates with `make html` and `make pdf` + * if documentation is (still) provided as a .txt file, convert to .rst + and remove the .txt file. For files in doc/txt the conversion is automatic. + * remove all .txt files in `doc/txt` that are out of sync with their .rst counterparts in `doc/src` * check spelling of manual with `make spelling` in doc folder + * check style tables and command lists with `make style_check` * new source files in packages should be added to `src/.gitignore` * removed or renamed files in packages should be added to `src/Purge.list` * C++ source files should use C++ style include files for accessing @@ -136,7 +139,7 @@ Here are some items to check: * Code should follow the C++-98 standard. C++-11 is only accepted in individual special purpose packages * indentation is 2 spaces per level - * there should be NO tabs and no trailing whitespace + * there should be NO tabs and no trailing whitespace (review the "checkstyle" test on pull requests) * header files, especially of new styles, should not include any other headers, except the header with the base class or cstdio. Forward declarations should be used instead when possible. diff --git a/doc/lammps.1 b/doc/lammps.1 index ec31d19b740cf24dfff2bac5c8ecdf0e31a5a74d..4355e6496157ec57648426b9ac98377f32a581e8 100644 --- a/doc/lammps.1 +++ b/doc/lammps.1 @@ -1,4 +1,4 @@ -.TH LAMMPS "30 October 2019" "2019-10-30" +.TH LAMMPS "9 January 2020" "2020-01-09" .SH NAME .B LAMMPS \- Molecular Dynamics Simulator. diff --git a/doc/src/.gitignore b/doc/src/.gitignore index be126ab4aa080ebeff3bbe0079444df02cfb57cc..e0b9693457ca0dfc081cfc7da4d53a6fa6286b94 100644 --- a/doc/src/.gitignore +++ b/doc/src/.gitignore @@ -1,2 +1,3 @@ -Eqs -JPG +/Eqs +/JPG +/false_positives.txt diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index 61629400159e30e2b120d27bae37678cc83f2908..2cba59bde0e68bff498cf6881bf790d43cfd64f5 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -195,12 +195,32 @@ minutes to hours) to build. Of course you only need to do that once.) .. parsed-literal:: -D DOWNLOAD_KIM=value # download OpenKIM API v2 for build, value = no (default) or yes + -D LMP_DEBUG_CURL=value # set libcurl verbose mode on/off, value = off (default) or on + -D LMP_NO_SSL_CHECK=value # tell libcurl to not verify the peer, value = no (default) or yes If DOWNLOAD\_KIM is set, the KIM library will be downloaded and built inside the CMake build directory. If the KIM library is already on your system (in a location CMake cannot find it), set the PKG\_CONFIG\_PATH environment variable so that libkim-api can be found. +For using OpenKIM web queries in LAMMPS. + +If LMP\_DEBUG\_CURL is set, the libcurl verbose mode will be on, and any +libcurl calls within the KIM web query display a lot of information about +libcurl operations. You hardly ever want this set in production use, you will +almost always want this when you debug/report problems. + +The libcurl performs peer SSL certificate verification by default. This +verification is done using a CA certificate store that the SSL library can +use to make sure the peer's server certificate is valid. If SSL reports an +error ("certificate verify failed") during the handshake and thus refuses +further communication with that server, you can set LMP\_NO\_SSL\_CHECK. +If LMP\_NO\_SSL\_CHECK is set, libcurl does not verify the peer and connection +succeeds regardless of the names in the certificate. This option is insecure. +As an alternative, you can specify your own CA cert path by setting the +environment variable CURL\_CA\_BUNDLE to the path of your choice. A call to the +KIM web query would get this value from the environmental variable. + **Traditional make**\ : You can download and build the KIM library manually if you prefer; diff --git a/doc/src/Commands.rst b/doc/src/Commands.rst index e845faa90318f01bb597e7547ddf8e5ecc9e640b..f192d6a59dd193c36cde8a7627ee3aee84a79622 100644 --- a/doc/src/Commands.rst +++ b/doc/src/Commands.rst @@ -27,8 +27,3 @@ commands in it are used to define a LAMMPS simulation. :maxdepth: 1 Commands_removed - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst index 583e9e3c3ab34101585385b9e7d40d327a3ba733..6e87ffbad6e51a514c1dafac5a6b75f7ea6e9f4f 100644 --- a/doc/src/Commands_all.rst +++ b/doc/src/Commands_all.rst @@ -1,59 +1,139 @@ -+----------------------------------------+------------------------------------+------------------------------------------+ -| :doc:`General commands ` | :doc:`Fix styles ` | :doc:`Compute styles ` | -+----------------------------------------+------------------------------------+------------------------------------------+ -| :doc:`Pair styles ` | :doc:`Bond styles ` | :ref:`Angle styles ` | -+----------------------------------------+------------------------------------+------------------------------------------+ -| :ref:`Dihedral styles ` | :ref:`Improper styles ` | :doc:`KSpace styles ` | -+----------------------------------------+------------------------------------+------------------------------------------+ +.. table_from_list:: + :columns: 3 + + * :doc:`General commands ` + * :doc:`Fix styles ` + * :doc:`Compute styles ` + * :doc:`Pair styles ` + * :ref:`Bond styles ` + * :ref:`Angle styles ` + * :ref:`Dihedral styles ` + * :ref:`Improper styles ` + * :doc:`KSpace styles ` General commands ================ An alphabetic list of all general LAMMPS commands. -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`angle\_coeff ` | :doc:`angle\_style ` | :doc:`atom\_modify ` | :doc:`atom\_style ` | :doc:`balance ` | :doc:`bond\_coeff ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`bond\_style ` | :doc:`bond\_write ` | :doc:`boundary ` | :doc:`box ` | :doc:`change\_box ` | :doc:`clear ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`comm\_modify ` | :doc:`comm\_style ` | :doc:`compute ` | :doc:`compute\_modify ` | :doc:`create\_atoms ` | :doc:`create\_bonds ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`create\_box ` | :doc:`delete\_atoms ` | :doc:`delete\_bonds ` | :doc:`dielectric ` | :doc:`dihedral\_coeff ` | :doc:`dihedral\_style ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`dimension ` | :doc:`displace\_atoms ` | :doc:`dump ` | :doc:`dump adios ` | :doc:`dump image ` | :doc:`dump movie ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`dump netcdf ` | :doc:`dump netcdf/mpiio ` | :doc:`dump vtk ` | :doc:`dump\_modify ` | :doc:`dynamical\_matrix ` | :doc:`echo ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`fix ` | :doc:`fix\_modify ` | :doc:`group ` | :doc:`group2ndx ` | :doc:`hyper ` | :doc:`if ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`info ` | :doc:`improper\_coeff ` | :doc:`improper\_style ` | :doc:`include ` | :doc:`jump ` | :doc:`kim\_init ` | -+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`kim\_interactions ` | :doc:`kim\_query ` | :doc:`kspace\_modify ` | :doc:`kspace\_style ` | :doc:`label