load sphinx extension for content in tabs with html and for transforming them to admonitions for non-html builders
This commit is contained in:
Axel Kohlmeyer
@ -44,29 +44,30 @@ require use of an FFT library to compute 1d FFTs. The KISS FFT
|
||||
library is included with LAMMPS but other libraries can be faster.
|
||||
LAMMPS can use them if they are available on your system.
|
||||
|
||||
CMake build
|
||||
^^^^^^^^^^^
|
||||
.. tabs::
|
||||
|
||||
.. code-block:: bash
|
||||
.. tab:: CMake build
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
-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
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
The values for the FFT variable must be in upper-case. This is
|
||||
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,
|
||||
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:
|
||||
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:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
-D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files
|
||||
-D FFTW3_LIBRARIES=path # path to FFTW3 libraries
|
||||
@ -75,14 +76,13 @@ to assist:
|
||||
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
|
||||
-D MKL_LIBRARIES=path
|
||||
|
||||
Traditional make
|
||||
^^^^^^^^^^^^^^^^
|
||||
.. tab:: Traditional 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.
|
||||
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.
|
||||
|
||||
.. code-block:: make
|
||||
.. code-block:: make
|
||||
|
||||
FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS
|
||||
# default is KISS if not specified
|
||||
@ -90,10 +90,9 @@ could be changed.
|
||||
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
|
||||
|
||||
# default is FFT_PACK_ARRAY if not specified
|
||||
|
||||
.. code-block:: make
|
||||
.. code-block:: make
|
||||
|
||||
FFT_INC = -I/usr/local/include
|
||||
FFT_PATH = -L/usr/local/lib
|
||||
@ -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_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
|
||||
the compiler can find the FFT header and library files in its default search path.
|
||||
You must specify ``FFT_LIB`` with the appropriate FFT libraries to include in the link.
|
||||
|
||||
CMake build
|
||||
^^^^^^^^^^^
|
||||
As with CMake, you do not need to set paths in ``FFT_INC`` or
|
||||
``FFT_PATH``, if the compiler can find the FFT header and library
|
||||
files in its default search path. You must specify ``FFT_LIB``
|
||||
with the appropriate FFT libraries to include in the link.
|
||||
|
||||
The `KISS FFT library <http://kissfft.sf.net>`_ is included in the LAMMPS
|
||||
distribution. It is portable across all platforms. Depending on the size
|
||||
@ -177,34 +174,34 @@ ARRAY mode.
|
||||
|
||||
.. _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
|
||||
4-byte (= 32-bit) or 8-byte (= 64-bit) integers at compile time.
|
||||
The default setting of "smallbig" is almost always adequate.
|
||||
|
||||
CMake build
|
||||
^^^^^^^^^^^
|
||||
.. tabs::
|
||||
|
||||
.. code-block:: bash
|
||||
.. tab:: CMake build
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
-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
|
||||
machine Makefile.
|
||||
If you want a setting different from the default, you need to edit your
|
||||
machine Makefile.
|
||||
|
||||
.. code-block:: make
|
||||
.. code-block:: make
|
||||
|
||||
LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL
|
||||
|
||||
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:
|
||||
|
||||
@ -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
|
||||
more than 2 billion atoms, you need the "bigbig" setting.
|
||||
|
||||
Image flags store 3 values per atom which count the number of times an
|
||||
atom has moved through the periodic box in each dimension. See the
|
||||
:doc:`dump <dump>` doc page for a discussion. If an atom moves through
|
||||
the periodic box more than this limit, the value will "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.
|
||||
Regardless of the total system size limits, the maximum number of atoms
|
||||
per MPI rank (local + ghost atoms) is limited to 2 billion for atomic
|
||||
systems and 500 million for systems with bonds (due to using the 2
|
||||
upper bits of the local atom index for storing special bonds labels).
|
||||
|
||||
Note that the USER-ATC package and the USER-INTEL package are 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.
|
||||
Image flags store 3 values per atom in a single integer which count the
|
||||
number of times an atom has moved through the periodic box in each
|
||||
dimension. See the :doc:`dump <dump>` doc page for a discussion. If an
|
||||
atom moves through the periodic box more than this limit, the value will
|
||||
"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
|
||||
compiled with the same size setting, or the link will fail. A CMake
|
||||
@ -265,10 +268,11 @@ PNG image files. Likewise the :doc:`dump movie <dump_image>` command
|
||||
outputs movie files in MPEG format. Using these options requires the
|
||||
following settings:
|
||||
|
||||
CMake build
|
||||
^^^^^^^^^^^
|
||||
.. tabs::
|
||||
|
||||
.. code-block:: bash
|
||||
.. tab:: CMake build
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
-D WITH_JPEG=value # yes or no
|
||||
# default = yes if CMake finds JPEG files, else no
|
||||
@ -277,11 +281,11 @@ CMake build
|
||||
-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
|
||||
the graphics header, library, executable files, you can set these
|
||||
variables:
|
||||
Usually these settings are all that is needed. If CMake cannot
|
||||
find the graphics header, library, executable files, you can set
|
||||
these variables:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
-D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file
|
||||
-D JPEG_LIBRARIES=path # path to libjpeg.a (.so) file
|
||||
@ -291,10 +295,9 @@ variables:
|
||||
-D ZLIB_LIBRARIES=path # path to libz.a (.so) file
|
||||
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable
|
||||
|
||||
Traditional make
|
||||
^^^^^^^^^^^^^^^^
|
||||
.. tab:: Traditional make
|
||||
|
||||
.. code-block:: make
|
||||
.. code-block:: make
|
||||
|
||||
LMP_INC = -DLAMMPS_JPEG
|
||||
LMP_INC = -DLAMMPS_PNG
|
||||
@ -304,15 +307,12 @@ Traditional make
|
||||
JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them
|
||||
JPG_LIB = -ljpeg -lpng -lz # library names
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
supports the "popen" function in the standard runtime library.
|
||||
|
||||
17
doc/src/_ext/tab_or_note.py
Normal file
17
doc/src/_ext/tab_or_note.py
Normal 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,5 +1,6 @@
|
||||
Sphinx
|
||||
sphinxcontrib-spelling
|
||||
git+https://github.com/akohlmey/sphinx-fortran@parallel-read
|
||||
sphinx_tabs
|
||||
breathe
|
||||
Pygments
|
||||
|
||||
@ -47,7 +47,9 @@ extensions = [
|
||||
'sphinx.ext.imgmath',
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinxfortran.fortran_domain',
|
||||
'sphinx_tabs.tabs',
|
||||
'table_from_list',
|
||||
'tab_or_note',
|
||||
'breathe',
|
||||
]
|
||||
# 2017-12-07: commented out, since this package is broken with Sphinx 16.x
|
||||
|
||||
Reference in New Issue
Block a user