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.
LAMMPS can use them if they are available on your system.
CMake build
^^^^^^^^^^^
.. tabs::
.. tab:: CMake build
.. code-block:: bash
@ -59,12 +60,12 @@ CMake build
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
@ -75,8 +76,7 @@ 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
@ -90,7 +90,6 @@ 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
.. 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_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,22 +174,22 @@ 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::
.. 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.
@ -203,8 +200,8 @@ machine Makefile.
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,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
following settings:
CMake build
^^^^^^^^^^^
.. tabs::
.. tab:: CMake build
.. code-block:: bash
@ -277,9 +281,9 @@ 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
@ -291,8 +295,7 @@ 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
@ -306,13 +309,10 @@ Traditional make
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
^^^^^^^^^^^^^^^^^^^
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
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
sphinxcontrib-spelling
git+https://github.com/akohlmey/sphinx-fortran@parallel-read
sphinx_tabs
breathe
Pygments

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

@ -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