ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

load sphinx extension for content in tabs with html and for transforming them to admonitions for non-html builders

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-09-05 23:42:13 -04:00
parent d995ed0d87
commit 7b6d07a812
4 changed files with 135 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
doc/src/Build_settings.rst
View File

@ -44,74 +44,71 @@ require use of an FFT library to compute 1d FFTs. The KISS FFT
library is included with LAMMPS but other libraries can be faster. library is included with LAMMPS but other libraries can be faster.
LAMMPS can use them if they are available on your system. LAMMPS can use them if they are available on your system.
CMake build .. tabs::
^^^^^^^^^^^
.. code-block:: bash .. tab:: CMake build
-D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS .. code-block:: bash
-D FFT_SINGLE=value # yes or no (default), no = double precision
-D FFT_PACK=value # array (default) or pointer or memcpy
.. note:: -D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS
-D FFT_SINGLE=value # yes or no (default), no = double precision
-D FFT_PACK=value # array (default) or pointer or memcpy
The values for the FFT variable must be in upper-case. This is .. note::
an exception to the rule that all CMake variables can be specified
with lower-case values.
Usually these settings are all that is needed. If FFTW3 is selected, The values for the FFT variable must be in upper-case. This is
then CMake will try to detect, if threaded FFTW libraries are available an exception to the rule that all CMake variables can be specified
and enable them by default. This setting is independent of whether with lower-case values.
OpenMP threads are enabled and a packages like KOKKOS or USER-OMP is
used. If CMake cannot detect the FFT library, you can set these variables
to assist:
.. code-block:: bash Usually these settings are all that is needed. If FFTW3 is
selected, then CMake will try to detect, if threaded FFTW
libraries are available and enable them by default. This setting
is independent of whether OpenMP threads are enabled and a
packages like KOKKOS or USER-OMP is used. If CMake cannot detect
the FFT library, you can set these variables to assist:
-D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files .. code-block:: bash
-D FFTW3_LIBRARIES=path # path to FFTW3 libraries
-D FFT_FFTW_THREADS=on # enable using threaded FFTW3 libraries
-D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
-D MKL_LIBRARIES=path
Traditional make -D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files
^^^^^^^^^^^^^^^^ -D FFTW3_LIBRARIES=path # path to FFTW3 libraries
-D FFT_FFTW_THREADS=on # enable using threaded FFTW3 libraries
-D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
-D MKL_LIBRARIES=path
To change the FFT library to be used and its options, you have to edit .. tab:: Traditional make
your machine Makefile. Below are examples how the makefile variables
could be changed.
.. code-block:: make To change the FFT library to be used and its options, you have to edit
your machine Makefile. Below are examples how the makefile variables
could be changed.
FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS .. code-block:: make
# default is KISS if not specified
FFT_INC = -DFFT_SINGLE # do not specify for double precision
FFT_INC = -DFFT_FFTW_THREADS # enable using threaded FFTW3 libraries
FFT_INC = -DFFT_MKL_THREADS # enable using threaded FFTs with MKL libraries
FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY
# default is FFT_PACK_ARRAY if not specified FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS
# default is KISS if not specified
FFT_INC = -DFFT_SINGLE # do not specify for double precision
FFT_INC = -DFFT_FFTW_THREADS # enable using threaded FFTW3 libraries
FFT_INC = -DFFT_MKL_THREADS # enable using threaded FFTs with MKL libraries
FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY
# default is FFT_PACK_ARRAY if not specified
.. code-block:: make .. code-block:: make
FFT_INC = -I/usr/local/include FFT_INC = -I/usr/local/include
FFT_PATH = -L/usr/local/lib FFT_PATH = -L/usr/local/lib
FFT_LIB = -lfftw3 # FFTW3 double precision FFT_LIB = -lfftw3 # FFTW3 double precision
FFT_LIB = -lfftw3 -lfftw3_omp # FFTW3 double precision with threads (needs -DFFT_FFTW_THREADS) FFT_LIB = -lfftw3 -lfftw3_omp # FFTW3 double precision with threads (needs -DFFT_FFTW_THREADS)
FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision
FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler, serial interface FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler, serial interface
FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compiler, serial interface FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compiler, serial interface
FFT_LIB = -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # MKL with Intel compiler, threaded interface FFT_LIB = -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # MKL with Intel compiler, threaded interface
FFT_LIB = -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core # MKL with GNU compiler, threaded interface FFT_LIB = -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core # MKL with GNU compiler, threaded interface
FFT_LIB = -lmkl_rt # MKL with automatic runtime selection of interface libs FFT_LIB = -lmkl_rt # MKL with automatic runtime selection of interface libs
As with CMake, you do not need to set paths in ``FFT_INC`` or ``FFT_PATH``, if As with CMake, you do not need to set paths in ``FFT_INC`` or
the compiler can find the FFT header and library files in its default search path. ``FFT_PATH``, if the compiler can find the FFT header and library
You must specify ``FFT_LIB`` with the appropriate FFT libraries to include in the link. files in its default search path. You must specify ``FFT_LIB``
with the appropriate FFT libraries to include in the link.
CMake build
^^^^^^^^^^^
The `KISS FFT library <http://kissfft.sf.net>`_ is included in the LAMMPS The `KISS FFT library <http://kissfft.sf.net>`_ is included in the LAMMPS
distribution. It is portable across all platforms. Depending on the size distribution. It is portable across all platforms. Depending on the size
@ -177,34 +174,34 @@ ARRAY mode.
.. _size: .. _size:
Size of LAMMPS integer types Size of LAMMPS integer types and size limits
------------------------------------ --------------------------------------------
LAMMPS has a few integer data types which can be defined as either LAMMPS has a few integer data types which can be defined as either
4-byte (= 32-bit) or 8-byte (= 64-bit) integers at compile time. 4-byte (= 32-bit) or 8-byte (= 64-bit) integers at compile time.
The default setting of "smallbig" is almost always adequate. The default setting of "smallbig" is almost always adequate.
CMake build .. tabs::
^^^^^^^^^^^
.. code-block:: bash .. tab:: CMake build
-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall .. code-block:: bash
Traditional build -D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall
^^^^^^^^^^^^^^^^^
If you want a setting different from the default, you need to edit your .. tab:: Traditional build
machine Makefile.
.. code-block:: make If you want a setting different from the default, you need to edit your
machine Makefile.
LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL .. code-block:: make
LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL
The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified
CMake and make info LAMMPS system size restrictions
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default "smallbig" setting allows for simulations with: The default "smallbig" setting allows for simulations with:
@ -235,18 +232,24 @@ IDs are required for molecular systems with bond topology (bonds,
angles, dihedrals, etc). Thus if you model a molecular system with angles, dihedrals, etc). Thus if you model a molecular system with
more than 2 billion atoms, you need the "bigbig" setting. more than 2 billion atoms, you need the "bigbig" setting.
Image flags store 3 values per atom which count the number of times an Regardless of the total system size limits, the maximum number of atoms
atom has moved through the periodic box in each dimension. See the per MPI rank (local + ghost atoms) is limited to 2 billion for atomic
:doc:`dump <dump>` doc page for a discussion. If an atom moves through systems and 500 million for systems with bonds (due to using the 2
the periodic box more than this limit, the value will "roll over", upper bits of the local atom index for storing special bonds labels).
e.g. from 511 to -512, which can cause diagnostics like the
mean-squared displacement, as calculated by the :doc:`compute msd <compute_msd>` command, to be faulty.
Note that the USER-ATC package and the USER-INTEL package are currently Image flags store 3 values per atom in a single integer which count the
not compatible with the "bigbig" setting. Also, there are limitations number of times an atom has moved through the periodic box in each
when using the library interface. Some functions with known issues dimension. See the :doc:`dump <dump>` doc page for a discussion. If an
have been replaced by dummy calls printing a corresponding error rather atom moves through the periodic box more than this limit, the value will
than crashing randomly or corrupting data. "roll over", e.g. from 511 to -512, which can cause diagnostics like the
mean-squared displacement, as calculated by the :doc:`compute msd
<compute_msd>` command, to be faulty.
Note that the USER-ATC package is currently not compatible with the
"bigbig" setting. Also, there are limitations when using the library
interface. Some functions with known issues have been replaced by dummy
calls printing a corresponding error rather than crashing randomly or
corrupting data.
Also note that the GPU package requires its lib/gpu library to be Also note that the GPU package requires its lib/gpu library to be
compiled with the same size setting, or the link will fail. A CMake compiled with the same size setting, or the link will fail. A CMake
@ -265,54 +268,51 @@ PNG image files. Likewise the :doc:`dump movie <dump_image>` command
outputs movie files in MPEG format. Using these options requires the outputs movie files in MPEG format. Using these options requires the
following settings: following settings:
CMake build .. tabs::
^^^^^^^^^^^
.. code-block:: bash .. tab:: CMake build
-D WITH_JPEG=value # yes or no .. code-block:: bash
# default = yes if CMake finds JPEG files, else no
-D WITH_PNG=value # yes or no
# default = yes if CMake finds PNG and ZLIB files, else no
-D WITH_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no
Usually these settings are all that is needed. If CMake cannot find -D WITH_JPEG=value # yes or no
the graphics header, library, executable files, you can set these # default = yes if CMake finds JPEG files, else no
variables: -D WITH_PNG=value # yes or no
# default = yes if CMake finds PNG and ZLIB files, else no
-D WITH_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no
.. code-block:: bash Usually these settings are all that is needed. If CMake cannot
find the graphics header, library, executable files, you can set
these variables:
-D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file .. code-block:: bash
-D JPEG_LIBRARIES=path # path to libjpeg.a (.so) file
-D PNG_INCLUDE_DIR=path # path to png.h header file
-D PNG_LIBRARIES=path # path to libpng.a (.so) file
-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file
-D ZLIB_LIBRARIES=path # path to libz.a (.so) file
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable
Traditional make -D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file
^^^^^^^^^^^^^^^^ -D JPEG_LIBRARIES=path # path to libjpeg.a (.so) file
-D PNG_INCLUDE_DIR=path # path to png.h header file
-D PNG_LIBRARIES=path # path to libpng.a (.so) file
-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file
-D ZLIB_LIBRARIES=path # path to libz.a (.so) file
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable
.. code-block:: make .. tab:: Traditional make
LMP_INC = -DLAMMPS_JPEG .. code-block:: make
LMP_INC = -DLAMMPS_PNG
LMP_INC = -DLAMMPS_FFMPEG
JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them LMP_INC = -DLAMMPS_JPEG
JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them LMP_INC = -DLAMMPS_PNG
JPG_LIB = -ljpeg -lpng -lz # library names LMP_INC = -DLAMMPS_FFMPEG
As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``, JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them
if make can find the graphics header and library files. You must JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them
specify ``JPG_LIB`` JPG_LIB = -ljpeg -lpng -lz # library names
with a list of graphics libraries to include in the link. You must
insure ffmpeg is in a directory where LAMMPS can find it at runtime,
that is a directory in your PATH environment variable.
CMake and make info As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``,
^^^^^^^^^^^^^^^^^^^ if make can find the graphics header and library files. You must
specify ``JPG_LIB`` with a list of graphics libraries to include
in the link. You must insure ffmpeg is in a directory where
LAMMPS can find it at runtime, that is a directory in your PATH
environment variable.
Using ``ffmpeg`` to output movie files requires that your machine Using ``ffmpeg`` to output movie files requires that your machine
supports the "popen" function in the standard runtime library. supports the "popen" function in the standard runtime library.

17
doc/src/_ext/tab_or_note.py Normal file
View File

@ -0,0 +1,17 @@
def replace_tabs_handler(app, docname, source):
""" When builder is not 'html', remove 'tabs' directive
and replace 'tab' directive with 'admonition'"""
if app.builder.name != 'html':
for i in range(len(source)):
str = source[i].replace('.. tabs::','')
str = str.replace('.. tab::','.. admonition::')
source[i] = str
def setup(app):
app.connect('source-read', replace_tabs_handler)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}

1
doc/utils/requirements.txt
View File

@ -1,5 +1,6 @@
Sphinx Sphinx
sphinxcontrib-spelling sphinxcontrib-spelling
git+https://github.com/akohlmey/sphinx-fortran@parallel-read git+https://github.com/akohlmey/sphinx-fortran@parallel-read
sphinx_tabs
breathe breathe
Pygments Pygments

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

@ -47,7 +47,9 @@ extensions = [
'sphinx.ext.imgmath', 'sphinx.ext.imgmath',
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
'sphinxfortran.fortran_domain', 'sphinxfortran.fortran_domain',
'sphinx_tabs.tabs',
'table_from_list', 'table_from_list',
'tab_or_note',
'breathe', 'breathe',
] ]
# 2017-12-07: commented out, since this package is broken with Sphinx 16.x # 2017-12-07: commented out, since this package is broken with Sphinx 16.x