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

100
doc/src/Build_settings.rst
View File

@ -44,8 +44,9 @@ 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::
^^^^^^^^^^^
.. tab:: CMake build
.. code-block:: bash .. code-block:: bash
@ -59,12 +60,12 @@ CMake build
an exception to the rule that all CMake variables can be specified an exception to the rule that all CMake variables can be specified
with lower-case values. with lower-case values.
Usually these settings are all that is needed. If FFTW3 is selected, Usually these settings are all that is needed. If FFTW3 is
then CMake will try to detect, if threaded FFTW libraries are available selected, then CMake will try to detect, if threaded FFTW
and enable them by default. This setting is independent of whether libraries are available and enable them by default. This setting
OpenMP threads are enabled and a packages like KOKKOS or USER-OMP is is independent of whether OpenMP threads are enabled and a
used. If CMake cannot detect the FFT library, you can set these variables packages like KOKKOS or USER-OMP is used. If CMake cannot detect
to assist: the FFT library, you can set these variables to assist:
.. code-block:: bash .. code-block:: bash
@ -75,8 +76,7 @@ to assist:
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries -D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
-D MKL_LIBRARIES=path -D MKL_LIBRARIES=path
Traditional make .. tab:: Traditional make
^^^^^^^^^^^^^^^^
To change the FFT library to be used and its options, you have to edit 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 your machine Makefile. Below are examples how the makefile variables
@ -90,7 +90,6 @@ could be changed.
FFT_INC = -DFFT_FFTW_THREADS # enable using threaded FFTW3 libraries 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_MKL_THREADS # enable using threaded FFTs with MKL libraries
FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY
# default is FFT_PACK_ARRAY if not specified # default is FFT_PACK_ARRAY if not specified
.. code-block:: make .. code-block:: make
@ -106,12 +105,10 @@ could be changed.
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,22 +174,22 @@ 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::
^^^^^^^^^^^
.. tab:: CMake build
.. code-block:: bash .. code-block:: bash
-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall -D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall
Traditional build .. tab:: Traditional build
^^^^^^^^^^^^^^^^^
If you want a setting different from the default, you need to edit your If you want a setting different from the default, you need to edit your
machine Makefile. machine Makefile.
@ -203,8 +200,8 @@ machine Makefile.
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,8 +268,9 @@ 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::
^^^^^^^^^^^
.. tab:: CMake build
.. code-block:: bash .. code-block:: bash
@ -277,9 +281,9 @@ CMake build
-D WITH_FFMPEG=value # yes or no -D WITH_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no # default = yes if CMake can find ffmpeg, else no
Usually these settings are all that is needed. If CMake cannot find Usually these settings are all that is needed. If CMake cannot
the graphics header, library, executable files, you can set these find the graphics header, library, executable files, you can set
variables: these variables:
.. code-block:: bash .. code-block:: bash
@ -291,8 +295,7 @@ variables:
-D ZLIB_LIBRARIES=path # path to libz.a (.so) file -D ZLIB_LIBRARIES=path # path to libz.a (.so) file
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable -D FFMPEG_EXECUTABLE=path # path to ffmpeg executable
Traditional make .. tab:: Traditional make
^^^^^^^^^^^^^^^^
.. code-block:: make .. code-block:: make
@ -306,13 +309,10 @@ Traditional make
As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``, 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 if make can find the graphics header and library files. You must
specify ``JPG_LIB`` specify ``JPG_LIB`` with a list of graphics libraries to include
with a list of graphics libraries to include in the link. You must in the link. You must insure ffmpeg is in a directory where
insure ffmpeg is in a directory where LAMMPS can find it at runtime, LAMMPS can find it at runtime, that is a directory in your PATH
that is a directory in your PATH environment variable. environment variable.
CMake and make info
^^^^^^^^^^^^^^^^^^^
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