From 2b1e4749dd2ea7b45a1921f02ae588f19b655e89 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Fri, 4 Sep 2020 11:39:38 -0400 Subject: [PATCH] first chunk of revised updates to the manual addressing link issues. --- doc/src/Build_basics.rst | 24 ++++++++++++------------ doc/src/Build_development.rst | 8 ++++---- doc/src/Build_extras.rst | 22 +++++++++++----------- doc/src/Build_link.rst | 8 ++++---- doc/src/Build_make.rst | 2 +- doc/src/Build_settings.rst | 5 +++-- doc/src/Build_windows.rst | 2 +- doc/src/Commands_removed.rst | 7 ++++++- doc/src/Errors_bugs.rst | 23 +++++++++++------------ doc/src/Errors_common.rst | 6 ++++-- doc/src/Examples.rst | 3 +-- doc/src/Howto.rst | 2 +- doc/src/Howto_2d.rst | 8 ++++---- doc/src/Howto_body.rst | 6 +++--- doc/src/Howto_chunk.rst | 3 ++- doc/src/Howto_drude.rst | 2 +- doc/src/Howto_drude2.rst | 4 ++-- doc/src/Howto_github.rst | 2 +- doc/src/Howto_spherical.rst | 2 +- doc/src/Howto_thermostat.rst | 31 ++++++++++++++++++++++++------- doc/src/Howto_viscosity.rst | 4 ++-- doc/src/Install_git.rst | 33 ++++++++++++++++----------------- doc/src/Install_patch.rst | 7 +++++-- doc/src/Intro_features.rst | 6 +++--- doc/src/Intro_nonfeatures.rst | 6 ++++-- doc/src/Intro_overview.rst | 2 +- doc/src/Intro_website.rst | 12 ++++++------ doc/src/Manual.rst | 5 ++++- doc/src/Modify.rst | 3 ++- doc/src/Modify_atom.rst | 4 ++-- doc/src/Modify_contribute.rst | 10 +++++----- doc/src/Modify_thermo.rst | 2 +- doc/src/Packages_details.rst | 34 ++++++++++++++++++---------------- doc/src/Packages_standard.rst | 2 +- doc/src/Run_basics.rst | 4 ++-- doc/src/Run_options.rst | 23 ++++++++++++----------- doc/src/Speed_bench.rst | 2 +- doc/src/Speed_kokkos.rst | 21 ++++++++++++++------- 38 files changed, 196 insertions(+), 154 deletions(-) diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index baace2e063..7548a8a6e9 100644 --- a/doc/src/Build_basics.rst +++ b/doc/src/Build_basics.rst @@ -115,12 +115,12 @@ self-installed MPICH or OpenMPI, so you should study the provided documentation to find out how to build and link with it. The majority of OpenMP (threading) support in LAMMPS is provided by the -``USER-OMP`` package; see the :doc:`Speed omp ` doc page for -details. The ``USER-INTEL`` package also includes OpenMP threading (it -is compatible with ``USER-OMP`` and will usually fall back on styles -from that package, if a ``USER-INTEL`` does not exist) and adds -vectorization support when compiled with compatible compilers, in -particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS`` +``USER-OMP`` package; see the :doc:`Speed_omp` +page for details. The ``USER-INTEL`` package also includes OpenMP +threading (it is compatible with ``USER-OMP`` and will usually fall +back on styles from that package, if a ``USER-INTEL`` does not exist) +and adds vectorization support when compiled with compatible compilers, +in particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS`` package can be compiled to include OpenMP threading. In addition, there are a few commands in LAMMPS that have native OpenMP @@ -290,13 +290,13 @@ Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``): compiler that supports C++11; either as a binary package or through compiling from source. -If you build LAMMPS with any :doc:`accelerator packages -` included, there may be specific optimization flags +If you build LAMMPS with any :doc:`Speed_packages` included, there may +be specific compiler or linker flags that are either required or recommended to enable required features and to achieve optimal performance. You need to include these in the CCFLAGS and LINKFLAGS settings above. For details, see the individual -package doc pages listed on the :doc:`Speed packages ` -doc page. Or examine these files in the src/MAKE/OPTIONS directory. +package doc pages listed on the :doc:`Speed_packages` +page. Or examine these files in the src/MAKE/OPTIONS directory. They correspond to each of the 5 accelerator packages and their hardware variants: @@ -418,7 +418,7 @@ recommended to ensure the integrity of the system software installation. .. _debug: -Excluding or removing debug support +Including or removing debug support ----------------------------------- By default the compilation settings will include the *-g* flag which @@ -460,7 +460,7 @@ python packages are installed into that virtual environment via the pip tool. The actual translation is then done via make commands. .. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html -.. _sphinx: https://sphinx-doc.org +.. _sphinx: https://www.sphinx-doc.org Documentation make option ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/src/Build_development.rst b/doc/src/Build_development.rst index cd432dddcb..b8e4c8171b 100644 --- a/doc/src/Build_development.rst +++ b/doc/src/Build_development.rst @@ -37,14 +37,14 @@ Compilers such as GCC and Clang support generating instrumented binaries which use different sanitizer libraries to detect problems in the code during run-time. They can detect issues like: - - `memory leaks `_ + - `memory leaks `_ - `undefined behavior `_ - `data races `_ Please note that this kind of instrumentation usually comes with a performance hit (but much less than using tools like `Valgrind -`_ with a more low level approach). The to enable -these features additional compiler flags need to be added to the +`_ with a more low level approach). To enable +these features, additional compiler flags need to be added to the compilation and linking stages. This is done through setting the ``ENABLE_SANITIZER`` variable during configuration. Examples: @@ -77,7 +77,7 @@ error margin). The status of this automated testing can be viewed on The unit testing facility is integrated into the CMake build process of the LAMMPS source code distribution itself. It can be enabled by setting ``-D ENABLE_TESTING=on`` during the CMake configuration step. -It requires the `YAML `_ library and development +It requires the `PyYAML `_ library and development headers to compile and will download and compile a recent version of the `Googletest `_ C++ test framework for implementing the tests. diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index b72dd95046..9595849b58 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -234,11 +234,10 @@ command, you also need to have libcurl installed with the matching development headers and the curl-config tool. If you would like to use the :doc:`kim_property ` -command, you need to build LAMMPS with the Python 3.6 or later package -installed. See the :doc:`Python ` doc page for more info on building -LAMMPS with the version of Python on your system. -After successfully building LAMMPS with Python, you need to -install the kim-property Python package, which can be easily done using +command, you need to build LAMMPS with the PYTHON package installed +and linked to Python 3.6 or later. See the :ref:`PYTHON package build info ` +for more details on this. After successfully building LAMMPS with Python, you +also need to install the kim-property Python package, which can be easily done using *pip* as ``pip install kim-property``, or from the *conda-forge* channel as ``conda install kim-property`` if LAMMPS is built in Conda. More detailed information is available at: @@ -812,10 +811,11 @@ a corresponding ``Makefile.lammps.machine`` file. PYTHON package --------------------------- -Building with the PYTHON package requires you have a Python shared -library available on your system, which needs to be a Python 2.7 -version or a Python 3.x version. See ``lib/python/README`` for more -details. +Building with the PYTHON package requires you have a the Python development +headers and library available on your system, which needs to be a Python 2.7 +version or a Python 3.x version. Since support for Python 2.x has ended, +using Python 3.x is strongly recommended. See ``lib/python/README`` for +additional details. CMake build ^^^^^^^^^^^ @@ -1095,7 +1095,7 @@ USER-PLUMED package Before building LAMMPS with this package, you must first build PLUMED. PLUMED can be built as part of the LAMMPS build or installed separately -from LAMMPS using the generic `plumed installation instructions `_. +from LAMMPS using the generic `PLUMED installation instructions `_. The USER-PLUMED package has been tested to work with Plumed versions 2.4.x, 2.5.x, and 2.6.x and will error out, when trying to run calculations with a different version of the Plumed kernel. @@ -1262,7 +1262,7 @@ To build with this package, you must choose which hardware you want to build for, either x86 CPUs or Intel KNLs in offload mode. You should also typically :ref:`install the USER-OMP package `, as it can be used in tandem with the USER-INTEL package to good effect, as explained -on the :doc:`Speed intel ` doc page. +on the :doc:`Speed_intel` page. When using Intel compilers version 16.0 or later is required. You can also use the GNU or Clang compilers and they will provide performance diff --git a/doc/src/Build_link.rst b/doc/src/Build_link.rst index 914142b3ce..87899739bc 100644 --- a/doc/src/Build_link.rst +++ b/doc/src/Build_link.rst @@ -4,11 +4,11 @@ Link LAMMPS as a library to another code LAMMPS is designed as a library of C++ objects that can be integrated into other applications including Python scripts. The files ``src/library.cpp`` and ``src/library.h`` define a -C-style API for using LAMMPS as a library. See the :doc:`Howto -library ` page for a description of the interface -and how to use it for your needs. +C-style API for using LAMMPS as a library. See the +:doc:`Howto_library` page +for a description of the interface and how to use it for your needs. -The :doc:`Build basics ` doc page explains how to build +The :doc:`Build_basics` page explains how to build LAMMPS as either a shared or static library. This results in a file in the compilation folder called ``liblammps.a`` or ``liblammps_.a`` in case of building a static library. In case of a shared library diff --git a/doc/src/Build_make.rst b/doc/src/Build_make.rst index af5e319121..cd71fd46e6 100644 --- a/doc/src/Build_make.rst +++ b/doc/src/Build_make.rst @@ -37,7 +37,7 @@ enable (or "install") them first, as discussed on the :doc:`Build package ` doc page. If a packages requires (provided or external) libraries, you must configure and build those libraries **before** building LAMMPS itself and especially **before** enabling -such a package with ``make yes-``. Building :doc:`LAMMPS with +such a package with ``make yes-``. :doc:`Building LAMMPS with CMake ` can automate much of this for many types of machines, especially workstations, desktops, and laptops, so we suggest you try it first when building LAMMPS in those cases. diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index 859bec9889..21107b7203 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -6,7 +6,7 @@ explain how to do this for building both with CMake and make. * :ref:`C++11 standard compliance ` when building all of LAMMPS * :ref:`FFT library ` for use with the :doc:`kspace_style pppm ` command -* :ref:`Size of LAMMPS data types ` +* :ref:`Size of LAMMPS integer types ` * :ref:`Read or write compressed files ` * :ref:`Output of JPG and PNG files ` via the :doc:`dump image ` command * :ref:`Output of movie files ` via the :doc:`dump_movie ` command @@ -123,7 +123,8 @@ per-timestep CPU cost, FFTs are only a portion of long-range Coulombics, and 1d FFTs are only a portion of the FFT cost (parallel communication can be costly). A breakdown of these timings is printed to the screen at the end of a run when using the -:doc:`kspace_style pppm ` command. The :doc:`Run output ` +:doc:`kspace_style pppm ` command. The +:doc:`Screen and logfile output ` doc page gives more details. A more detailed (and time consuming) report of the FFT performance is generated with the :doc:`kspace_modify fftbench yes ` command. diff --git a/doc/src/Build_windows.rst b/doc/src/Build_windows.rst index 4aacea9dfa..2df3fdd24e 100644 --- a/doc/src/Build_windows.rst +++ b/doc/src/Build_windows.rst @@ -38,7 +38,7 @@ optional Windows feature allows you to run the bash shell from Ubuntu from within Windows and from there on, you can pretty much use that shell like you are running on an Ubuntu Linux machine (e.g. installing software via apt-get and more). For more details on that, please -see :doc:`this tutorial ` +see :doc:`this tutorial `. .. _gnu: diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst index e137e39a08..1f6da57945 100644 --- a/doc/src/Commands_removed.rst +++ b/doc/src/Commands_removed.rst @@ -17,6 +17,11 @@ ways through the :doc:`compute chunk/atom ` command and then averaging is done using :doc:`fix ave/chunk `. Please refer to the :doc:`chunk HOWTO ` section for an overview. +Reset_ids command +----------------- + +The reset_ids command has been renamed to :doc:`reset_atom_ids `. + MEAM package ------------ @@ -27,7 +32,7 @@ which removes several restrictions (e.g. there can be multiple instances in hybrid pair styles) and allows for some optimizations leading to better performance. The new pair style :doc:`meam/c ` has the exact same syntax as the old "meam" pair style and thus pair style -:doc:`meam ` is an alias to the new style and backward +meam is an alias to the new style and backward compatibility of old inputs is preserved. REAX package diff --git a/doc/src/Errors_bugs.rst b/doc/src/Errors_bugs.rst index ff0b155795..d2714c86b1 100644 --- a/doc/src/Errors_bugs.rst +++ b/doc/src/Errors_bugs.rst @@ -6,23 +6,25 @@ the steps outlined below: * Check the `New features and bug fixes `_ section of the `LAMMPS WWW site - `_ to see if the bug has already been addressed in a patch. + `_ or the + `GitHub Releases page `_ to + see if the bug has already been addressed in a patch release. * Check that your issue can be reproduced with the latest development version of LAMMPS. * Check the manual carefully to verify that the unexpected behavior you are observing is indeed in conflict with the documentation - * Check the `GitHub Issue page `_ + * Check the `GitHub Issue page `_ if your issue has already been reported and if it is still open. - * Check the `GitHub Pull Requests page `_ - if there is already a fix for your bug pending. + * Check the `GitHub Pull Requests page `_ + to see if there is already a fix for your bug pending. * Check the `mailing list archives `_ to see if the issue has been discussed before. If none of these steps yields any useful information, please file a new -bug report on the `GitHub Issue page `_. The website will offer -you to select a suitable template with explanations and then you should -replace those explanations with the information that you can provide to -reproduce your issue. +bug report on the `GitHub Issue page `_. +The website will offer you to select a suitable template with explanations +and then you should replace those explanations with the information that +you can provide to reproduce your issue. The most useful thing you can do to help us verify and fix a bug is to isolate the problem. Run it on the smallest number of atoms and fewest @@ -33,7 +35,7 @@ Please avoid using binary restart files unless the issue requires it. In the latter case you should also include an input deck to quickly generate this restart from a data file or a simple additional input. This input deck can be used with tools like a debugger or `valgrind -`_ to further :doc:`debug the crash `. +`_ to further :doc:`debug the crash `. You may also send an email to the LAMMPS mailing list at "lammps-users at lists.sourceforge.net" describing the problem with the @@ -44,6 +46,3 @@ is overlooked and then forgotten. Issues on GitHub have to be explicitly closed, so that will *guarantee* that at least one LAMMPS developer will have looked at it. -.. _lws: https://lammps.sandia.gov -.. _gip: https://github.com/lammps/issues -.. _valgrind: https://valgrind.org diff --git a/doc/src/Errors_common.rst b/doc/src/Errors_common.rst index 34567db385..4d4483efec 100644 --- a/doc/src/Errors_common.rst +++ b/doc/src/Errors_common.rst @@ -48,8 +48,10 @@ to see it on the screen. If you get an error like "Invalid ... style", with ... being fix, compute, pair, etc, it means that you mistyped the style name or that the command is part of an optional package which was not compiled into your executable. The list of -available styles in your executable can be listed by using :doc:`the -h command-line swith `. The installation and -compilation of optional packages is explained on the :doc:`Build packages ` doc page. +available styles in your executable can be listed by using +:doc:`the -h command-line switch `. The installation and +compilation of optional packages is explained on the +:doc:`Build packages ` doc page. For a given command, LAMMPS expects certain arguments in a specified order. If you mess this up, LAMMPS will often flag the error, but it diff --git a/doc/src/Examples.rst b/doc/src/Examples.rst index dc122f2c78..8a76dca66e 100644 --- a/doc/src/Examples.rst +++ b/doc/src/Examples.rst @@ -27,7 +27,7 @@ be quickly post-processed into a movie using commands described on the :doc:`dump image ` doc page. Animations of many of the examples can be viewed on the Movies section -of the `LAMMPS web site `_. +of the `LAMMPS web site `_. There are two kinds of sub-directories in the examples folder. Lower case named directories contain one or a few simple, quick-to-run @@ -223,4 +223,3 @@ instructions. See the :doc:`Packages_details ` doc page for more info on specific USER packages. .. _openkim: https://openkim.org -.. _lws: https://lammps.sandia.gov diff --git a/doc/src/Howto.rst b/doc/src/Howto.rst index 89c0ce9ffe..6d8f6e9054 100644 --- a/doc/src/Howto.rst +++ b/doc/src/Howto.rst @@ -3,7 +3,7 @@ Howto discussions These doc pages describe how to perform various tasks with LAMMPS, both for users and developers. The -`glossary `_ website page also lists MD +`glossary `_ website page also lists MD terminology with links to corresponding LAMMPS manual pages. The example input scripts included in the examples directory of the LAMMPS distribution and highlighted on the :doc:`Examples ` doc page diff --git a/doc/src/Howto_2d.rst b/doc/src/Howto_2d.rst index 1b4be32106..9cf76ac3b0 100644 --- a/doc/src/Howto_2d.rst +++ b/doc/src/Howto_2d.rst @@ -6,14 +6,14 @@ Use the :doc:`dimension ` command to specify a 2d simulation. Make the simulation box periodic in z via the :doc:`boundary ` command. This is the default. -If using the :doc:`create box ` command to define a +If using the :doc:`create_box ` command to define a simulation box, set the z dimensions narrow, but finite, so that the -create_atoms command will tile the 3d simulation box with a single z -plane of atoms - e.g. +:doc:`create_atoms ` command will fill the 3d simulation +box with a single z plane of atoms - e.g. .. code-block:: LAMMPS - :doc:`create box ` 1 -10 10 -10 10 -0.25 0.25 + create box 1 -10 10 -10 10 -0.25 0.25 If using the :doc:`read data ` command to read in a file of atom coordinates, set the "zlo zhi" values to be finite but narrow, diff --git a/doc/src/Howto_body.rst b/doc/src/Howto_body.rst index 36e40a88bd..0c0a930221 100644 --- a/doc/src/Howto_body.rst +++ b/doc/src/Howto_body.rst @@ -32,9 +32,9 @@ thus how they can be used to compute pairwise body/body or bond/non-body (point particle) interactions. More details of each style are described below. -More styles may be added in the future. See the :doc:`Modify body -` doc page for details on how to add a new body style to -the code. +More styles may be added in the future. See the +:doc:`page on creating new body styles ` for details on +how to add a new body style to the code. ---------- diff --git a/doc/src/Howto_chunk.rst b/doc/src/Howto_chunk.rst index 75fb30815b..c0a7792448 100644 --- a/doc/src/Howto_chunk.rst +++ b/doc/src/Howto_chunk.rst @@ -198,7 +198,8 @@ explained on the :doc:`compute chunk/spread/atom ` co (7) An example for using one set of per-chunk values for molecule chunks, to create a second set of micelle-scale chunks (clustered -molecules, due to hydrophobicity), is explained on the :doc:`compute chunk/reduce ` command doc page. +molecules, due to hydrophobicity), is explained on the +:doc:`compute reduce/chunk ` command doc page. (8) An example for using one set of per-chunk values (dipole moment vectors) for molecule chunks, spreading the values to each atom in diff --git a/doc/src/Howto_drude.rst b/doc/src/Howto_drude.rst index 62659711c4..c866340e77 100644 --- a/doc/src/Howto_drude.rst +++ b/doc/src/Howto_drude.rst @@ -29,7 +29,7 @@ molecular systems (:ref:`Lamoureux and Roux `): to the total charge of the core atom). A detailed tutorial covering the usage of Drude induced dipoles in -LAMMPS is on the :doc:`Howto drude2e ` doc page. +LAMMPS is on the :doc:`here `. As with the core-shell model, the cores and Drude particles should appear in the data file as standard atoms. The same holds for the diff --git a/doc/src/Howto_drude2.rst b/doc/src/Howto_drude2.rst index cbdbc2d250..3dacf99dec 100644 --- a/doc/src/Howto_drude2.rst +++ b/doc/src/Howto_drude2.rst @@ -377,7 +377,7 @@ For our phenol example, the groups would be defined as Note that with the fixes *drude/transform*\ , it is not required to specify *comm_modify vel yes* because the fixes do it anyway (several times and for the forces also). To avoid the flying ice cube artifact -:ref:`(Lamoureux) `, where the atoms progressively freeze and the +:ref:`(Lamoureux and Roux) `, where the atoms progressively freeze and the center of mass of the whole system drifts faster and faster, the *fix momentum* can be used. For instance: @@ -456,7 +456,7 @@ NPT ensemble using Nose-Hoover thermostat: .. _Lamoureux2: -**(Lamoureux)** Lamoureux and Roux, J Chem Phys, 119, 3025-3039 (2003) +**(Lamoureux and Roux)** Lamoureux and Roux, J Chem Phys, 119, 3025-3039 (2003) .. _Schroeder: diff --git a/doc/src/Howto_github.rst b/doc/src/Howto_github.rst index 795af96e0a..63cb8945e8 100644 --- a/doc/src/Howto_github.rst +++ b/doc/src/Howto_github.rst @@ -20,7 +20,7 @@ work required by the LAMMPS developers. Consequently, creating a pull request will increase your chances to have your contribution included and will reduce the time until the integration is complete. For more information on the requirements to have your code included into LAMMPS -please see the :doc:`Modify contribute ` doc page. +please see :doc:`this page `. ---------- diff --git a/doc/src/Howto_spherical.rst b/doc/src/Howto_spherical.rst index 7ca8a1b060..aa17e6ce21 100644 --- a/doc/src/Howto_spherical.rst +++ b/doc/src/Howto_spherical.rst @@ -114,7 +114,7 @@ will only rotate and experience torque if the force field computes such interactions. These are the various :doc:`pair styles ` that generate torque: * :doc:`pair_style gran/history ` -* :doc:`pair_style gran/hertzian ` +* :doc:`pair_style gran/hertz ` * :doc:`pair_style gran/no_history ` * :doc:`pair_style dipole/cut ` * :doc:`pair_style gayberne ` diff --git a/doc/src/Howto_thermostat.rst b/doc/src/Howto_thermostat.rst index 77745efa57..7bddb1c89d 100644 --- a/doc/src/Howto_thermostat.rst +++ b/doc/src/Howto_thermostat.rst @@ -42,12 +42,12 @@ particles. DPD thermostatting alters pairwise interactions in a manner analogous to the per-particle thermostatting of :doc:`fix langevin `. -Any of the thermostatting fixes can use :doc:`temperature computes ` that remove bias which has two -effects. First, the current calculated temperature, which is compared -to the requested target temperature, is calculated with the velocity -bias removed. Second, the thermostat adjusts only the thermal -temperature component of the particle's velocities, which are the -velocities with the bias removed. The removed bias is then added back +Any of the thermostatting fixes can be instructed to use custom temperature +computes that remove bias which has two effects: first, the current +calculated temperature, which is compared to the requested target temperature, +is calculated with the velocity bias removed; second, the thermostat adjusts +only the thermal temperature component of the particle's velocities, which are +the velocities with the bias removed. The removed bias is then added back to the adjusted velocities. See the doc pages for the individual fixes and for the :doc:`fix_modify ` command for instructions on how to assign a temperature compute to a @@ -55,7 +55,24 @@ thermostatting fix. For example, you can apply a thermostat to only the x and z components of velocity by using it in conjunction with :doc:`compute temp/partial `. Of you could thermostat only the thermal temperature of a streaming flow of -particles without affecting the streaming velocity, by using :doc:`compute temp/profile `. +particles without affecting the streaming velocity, by using +:doc:`compute temp/profile `. + +Below is a list of some custom temperature computes that can be used like that: + +* :doc:`compute_temp_asphere` +* :doc:`compute_temp_body` +* :doc:`compute_temp_chunk` +* :doc:`compute_temp_com` +* :doc:`compute_temp_deform` +* :doc:`compute_temp_partial` +* :doc:`compute_temp_profile` +* :doc:`compute_temp_ramp` +* :doc:`compute_temp_region` +* :doc:`compute_temp_rotate` +* :doc:`compute_temp_sphere` + + .. note:: diff --git a/doc/src/Howto_viscosity.rst b/doc/src/Howto_viscosity.rst index 8c7eb91b12..cfe9497665 100644 --- a/doc/src/Howto_viscosity.rst +++ b/doc/src/Howto_viscosity.rst @@ -5,8 +5,8 @@ The shear viscosity eta of a fluid can be measured in at least 6 ways using various options in LAMMPS. See the examples/VISCOSITY directory for scripts that implement the 5 methods discussed here for a simple Lennard-Jones fluid model and 1 method for SPC/E water model. -Also, see the :doc:`Howto kappa ` doc page for an analogous discussion for -thermal conductivity. +Also, see the :doc:`page on calculating thermal conductivity ` +for an analogous discussion for thermal conductivity. Eta is a measure of the propensity of a fluid to transmit momentum in a direction perpendicular to the direction of velocity or momentum diff --git a/doc/src/Install_git.rst b/doc/src/Install_git.rst index 2f6e8096dc..868f679dbc 100644 --- a/doc/src/Install_git.rst +++ b/doc/src/Install_git.rst @@ -46,20 +46,19 @@ between them at any time using "git checkout ".) Once the command completes, your directory will contain the same files as if you unpacked a current LAMMPS tarball, with the exception, that the HTML documentation files are not included. They can be fetched -from the LAMMPS website by typing "make fetch" in the doc directory. +from the LAMMPS website by typing ``make fetch`` in the doc directory. Or they can be generated from the content provided in doc/src by -typing "make html" from the doc directory. +typing ``make html`` from the doc directory. After initial cloning, as bug fixes and new features are added to -LAMMPS, as listed on :doc:`this page `, you can stay -up-to-date by typing the following git commands from within the -"mylammps" directory: +LAMMPS you can stay up-to-date by typing the following git commands +from within the "mylammps" directory: .. code-block:: bash $ git checkout unstable # not needed if you always stay in this branch - $ git checkout stable # use one of the 3 checkout commands - $ git checkout master + $ git checkout stable # use one of these 3 checkout commands + $ git checkout master # to choose the branch to follow $ git pull Doing a "pull" will not change any files you have added to the LAMMPS @@ -70,8 +69,8 @@ repository file with your version of the file and tell you if there are any conflicts. See the git documentation for details. If you want to access a particular previous release version of LAMMPS, -you can instead "checkout" any version with a published tag. See the -output of "git tag -l" for the list of tags. The git command to do +you can instead "check out" any version with a published tag. See the +output of ``git tag -l`` for the list of tags. The git command to do this is as follows. .. code-block:: bash @@ -79,14 +78,14 @@ this is as follows. $ git checkout tagID Stable versions and what tagID to use for a particular stable version -are discussed on :doc:`this page `. Note that this command -will print some warnings, because in order to get back to the latest -revision and to be able to update with "git pull" again, you first -will need to first type "git checkout unstable" (or check out any -other desired branch). +are discussed on `this page `_. +Note that this command will print some warnings, because in order to get +back to the latest revision and to be able to update with ``git pull`` +again, you will need to do ``git checkout unstable`` (or +check out any other desired branch) first. -Once you have updated your local files with a "git pull" (or "git -checkout"), you still need to re-build LAMMPS if any source files have +Once you have updated your local files with a ``git pull`` (or ``git +checkout``), you still need to re-build LAMMPS if any source files have changed. To do this, you should cd to the src directory and type: .. code-block:: bash @@ -95,7 +94,7 @@ changed. To do this, you should cd to the src directory and type: $ make package-update # sync package files with src files $ make foo # re-build for your machine (mpi, serial, etc) -just as described on the :doc:`Install patch ` doc page, +just as described on the :doc:`Apply patch ` doc page, after a patch has been installed. .. warning:: diff --git a/doc/src/Install_patch.rst b/doc/src/Install_patch.rst index 3acd72753f..0bbd7bbf00 100644 --- a/doc/src/Install_patch.rst +++ b/doc/src/Install_patch.rst @@ -6,9 +6,12 @@ if you use git to track the LAMMPS development. Instructions for how to stay current are on the :doc:`Download the LAMMPS source with git ` page. -If you prefer to download a tarball, as described on the :doc:`Install git ` doc page, you can stay current by +If you prefer to download a tarball, as described on the +:doc:`tarball download ` page, you can stay current by downloading "patch files" when new patch releases are made. A link to -a patch file is posted on the `bug and feature page `_ of the LAMMPS website, along +a patch file is posted on the +`bugf fixes and new feature page `_ +of the LAMMPS website, along with a list of changed files and details about what is in the new patch release. This page explains how to apply the patch file to your local LAMMPS directory. diff --git a/doc/src/Intro_features.rst b/doc/src/Intro_features.rst index cff198da70..acf27455cf 100644 --- a/doc/src/Intro_features.rst +++ b/doc/src/Intro_features.rst @@ -181,7 +181,7 @@ Pre- and post-processing * A handful of pre- and post-processing tools are packaged with LAMMPS, some of which can convert input and output files to/from formats used - by other codes; see the :doc:`Toos ` doc page. + by other codes; see the :doc:`Tools ` doc page. * Our group has also written and released a separate toolkit called `Pizza.py `_ which provides tools for doing setup, analysis, plotting, and visualization for LAMMPS simulations. Pizza.py is @@ -197,7 +197,7 @@ Specialized features ---------------------------------- LAMMPS can be built with optional packages which implement a variety -of additional capabilities. See the :doc:`Packages ` doc +of additional capabilities. See the :doc:`Optional Packages ` page for details. These are LAMMPS capabilities which you may not think of as typical @@ -214,7 +214,7 @@ classical MD options: * Monte Carlo via :doc:`GCMC ` and :doc:`tfMC ` and :doc:`atom swapping ` * :doc:`path-integral molecular dynamics (PIMD) ` and :doc:`this as well ` * :doc:`Direct Simulation Monte Carlo ` for low-density fluids -* :doc:`Peridynamics mesoscale modeling ` +* :doc:`Peridynamics modeling ` * :doc:`Lattice Boltzmann fluid ` * :doc:`targeted ` and :doc:`steered ` molecular dynamics * :doc:`two-temperature electron model ` diff --git a/doc/src/Intro_nonfeatures.rst b/doc/src/Intro_nonfeatures.rst index fb41b9a054..a22a726bdc 100644 --- a/doc/src/Intro_nonfeatures.rst +++ b/doc/src/Intro_nonfeatures.rst @@ -66,8 +66,10 @@ Here are suggestions on how to perform these tasks: on-the-fly via its :doc:`dump image ` command and pass them to an external program, `FFmpeg `_ to generate movies from them. For high-quality, interactive visualization there are - many excellent and free tools available. See the `Other Codes page `_ page of the LAMMPS website for - visualization packages that can use LAMMPS output data. + many excellent and free tools available. See the + `Visualization Tools `_ page of the + LAMMPS website for + visualization packages that can process LAMMPS output data. * **Plotting:** See the next bullet about Pizza.py as well as the :doc:`Python ` doc page for examples of plotting LAMMPS output. Scripts provided with the *python* tool in the tools diff --git a/doc/src/Intro_overview.rst b/doc/src/Intro_overview.rst index 776002354a..df6bfad33d 100644 --- a/doc/src/Intro_overview.rst +++ b/doc/src/Intro_overview.rst @@ -15,7 +15,7 @@ that supports the `MPI `_ message-passing library. This includes shared-memory boxes and distributed-memory clusters and supercomputers. -.. _mpi: http://www-unix.mcs.anl.gov/mpi +.. _mpi: https://en.wikipedia.org/wiki/Message_Passing_Interface .. _lws: https://lammps.sandia.gov LAMMPS is written in C++. Earlier versions were written in F77 and diff --git a/doc/src/Intro_website.rst b/doc/src/Intro_website.rst index 125d2e0f4c..7abc78e7e4 100644 --- a/doc/src/Intro_website.rst +++ b/doc/src/Intro_website.rst @@ -2,22 +2,22 @@ Additional website links ======================== The `LAMMPS website `_ has a variety of additional info about -LAMMPS, beyond what is in this manual. Some of the other pages in -this Intr are included in this list. +LAMMPS, beyond what is in this manual. Some other useful resources +available online are listed below. .. _lws: https://lammps.sandia.gov * `Brief intro and recently added significant features `_ -* `List of features `_ -* `List of non-features `_ +* `List of features `_ +* `List of non-features `_ * `Recent bug fixes and new features `_ * `Download info `_ * `GitHub site `_ * `SourceForge site `_ -* `LAMMPS open-source license `_ +* `LAMMPS open-source license `_ -* `Glossary of MD terms relevant to LAMMPS `_ +* `Glossary of terms relevant to LAMMPS `_ * `LAMMPS highlights with images `_ * `LAMMPS highlights with movies `_ * `Mail list `_ diff --git a/doc/src/Manual.rst b/doc/src/Manual.rst index 2ec830a0b7..ba6c40b255 100644 --- a/doc/src/Manual.rst +++ b/doc/src/Manual.rst @@ -27,7 +27,10 @@ all LAMMPS development is coordinated. The content for this manual is part of the LAMMPS distribution. You can build a local copy of the Manual as HTML pages or a PDF file, by following the steps on the :doc:`Manual build ` doc page. -The manual is split into two parts: 1) User documentation and 2) Programmer documentation. +The manual is organized in two parts: +1) A :ref:`User documentation ` for how to install +and use LAMMPS and 2) a :ref:`Programmer documentation ` +for how to write programs using the LAMMPS library or how to modify LAMMPS. ---------- diff --git a/doc/src/Modify.rst b/doc/src/Modify.rst index fa45c4818e..2a727dfd0f 100644 --- a/doc/src/Modify.rst +++ b/doc/src/Modify.rst @@ -8,7 +8,8 @@ this. If you add a new feature to LAMMPS and think it will be of interest to general users, we encourage you to submit it for inclusion in LAMMPS -as a pull request on our `GitHub site `_, after reading the :doc:`Modify contribute ` doc page. +as a pull request on our `GitHub site `_, +after reading :doc:`this page `. .. toctree:: :maxdepth: 1 diff --git a/doc/src/Modify_atom.rst b/doc/src/Modify_atom.rst index 34a529020a..5c3a96789e 100644 --- a/doc/src/Modify_atom.rst +++ b/doc/src/Modify_atom.rst @@ -47,13 +47,13 @@ other strings. * - fields_comm - list of properties communicated to ghost atoms every step * - fields_comm_vel - - additional properties communicated if :doc:`comm_modify vel ` is used + - additional properties communicated if :doc:`comm_modify vel ` is used * - fields_reverse - list of properties summed from ghost atoms every step * - fields_border - list of properties communicated with ghost atoms every reneighboring step * - fields_border_vel - - additional properties communicated if :doc:`comm_modify vel ` is used + - additional properties communicated if :doc:`comm_modify vel ` is used * - fields_exchange - list of properties communicated when an atom migrates to another processor * - fields_restart diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst index 8bc320a9b0..27de36f30c 100644 --- a/doc/src/Modify_contribute.rst +++ b/doc/src/Modify_contribute.rst @@ -31,14 +31,14 @@ send an e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you are working on. Only discussions related to LAMMPS development are tolerated, so this is **NOT** for people that look for help with compiling, installing, or using LAMMPS. Please contact the `lammps-users mailing -list `_ for those purposes instead. +list `_ for those purposes instead. How quickly your contribution will be integrated depends largely on how much effort it will cause to integrate and test it, how much it requires changes to the core codebase, and of how much interest it is to the larger LAMMPS community. Please see below for a checklist of typical -requirements. Once you have prepared everything, see the :doc:`Using -GitHub with LAMMPS Howto ` doc page for instructions on +requirements. Once you have prepared everything, see the :doc:`LAMMPS GitHub +Tutorial ` page for instructions on how to submit your changes or new files through a GitHub pull request. If you prefer to submit patches or full files, you should first make certain, that your code works correctly with the latest patch-level @@ -58,8 +58,8 @@ are listed and described on the :doc:`Packages details ` doc p Note that by providing us files to release, you are agreeing to make them open-source, i.e. we can release them under the terms of the GPL, -used as a license for the rest of LAMMPS. See the `Open source `_ page on the LAMMPS -website for details. +used as a license for the rest of LAMMPS. See the :doc:`LAMMPS license +` doc page for details. With user packages and files, all we are really providing (aside from the fame and fortune that accompanies having your name in the source diff --git a/doc/src/Modify_thermo.rst b/doc/src/Modify_thermo.rst index 564df9ec7a..ea09e30c1d 100644 --- a/doc/src/Modify_thermo.rst +++ b/doc/src/Modify_thermo.rst @@ -20,7 +20,7 @@ for output. Search for the word "customize" with references to "keyword" in thermo.cpp to see the several locations where code will need to be added. -Note that the :doc:`thermo_style custom ` command already allows +Note that the :doc:`thermo_style custom ` command already allows for thermo output of quantities calculated by :doc:`fixes `, :doc:`computes `, and :doc:`variables `. Thus, it may be simpler to compute what you wish via one of those constructs, than diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index 3d21232a8f..1beeeff5b4 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -299,7 +299,8 @@ Dozens of pair styles and a version of the PPPM long-range Coulombic solver optimized for GPUs. All such styles have a "gpu" as a suffix in their style name. The GPU code can be compiled with either CUDA or OpenCL, however the OpenCL variants are no longer actively maintained -and only the CUDA versions are regularly tested. The :doc:`Speed gpu ` doc page gives details of what hardware and GPU +and only the CUDA versions are regularly tested. The +:doc:`Speed_gpu` page gives details of what hardware and GPU software is required on your system, and details on how to build and use this package. Its styles can be invoked at run time via the "-sf gpu" or "-suffix gpu" :doc:`command-line switches `. See @@ -318,8 +319,8 @@ This package has :ref:`specific installation instructions ` on the :doc:`Bu * src/GPU: filenames -> commands * src/GPU/README * lib/gpu/README -* :doc:`Speed packages ` -* :doc:`Speed gpu ` +* :doc:`Accelerator packages ` +* :doc:`GPU package ` * :doc:`Section 2.6 -sf gpu ` * :doc:`Section 2.6 -pk gpu ` * :doc:`package gpu ` @@ -433,7 +434,7 @@ Dozens of atom, pair, bond, angle, dihedral, improper, fix, compute styles adapted to compile using the Kokkos library which can convert them to OpenMP or CUDA code so that they run efficiently on multicore CPUs, KNLs, or GPUs. All the styles have a "kk" as a suffix in their -style name. The :doc:`Speed kokkos ` doc page gives +style name. The :doc:`KOKKOS package ` doc page gives details of what hardware and software is required on your system, and how to build and use this package. Its styles can be invoked at run time via the "-sf kk" or "-suffix kk" :doc:`command-line switches `. Also see the :ref:`GPU `, :ref:`OPT `, @@ -463,8 +464,8 @@ This package has :ref:`specific installation instructions ` on the :doc: * src/KOKKOS: filenames -> commands * src/KOKKOS/README * lib/kokkos/README -* :doc:`Speed packages ` -* :doc:`Speed kokkos ` +* :doc:`Accelerator packages ` +* :doc:`KOKKOS package ` * :doc:`Section 2.6 -k on ... ` * :doc:`Section 2.6 -sf kk ` * :doc:`Section 2.6 -pk kokkos ` @@ -665,7 +666,7 @@ A general interface for machine-learning interatomic potentials. **Install:** -To use this package, also the :ref:`SNAP package` needs to be installed. +To use this package, also the :ref:`SNAP package ` needs to be installed. **Author:** Aidan Thompson (Sandia). @@ -773,7 +774,7 @@ OPT package A handful of pair styles which are optimized for improved CPU performance on single or multiple cores. These include EAM, LJ, CHARMM, and Morse potentials. The styles have an "opt" suffix in -their style name. The :doc:`Speed opt ` doc page gives +their style name. The :doc:`OPT package ` doc page gives details of how to build and use this package. Its styles can be invoked at run time via the "-sf opt" or "-suffix opt" :doc:`command-line switches `. See also the :ref:`KOKKOS `, :ref:`USER-INTEL `, and :ref:`USER-OMP ` packages, which @@ -789,8 +790,8 @@ This package has :ref:`specific installation instructions ` on the :doc:`Bu **Supporting info:** * src/OPT: filenames -> commands -* :doc:`Speed packages ` -* :doc:`Speed opt ` +* :doc:`Accelerator packages ` +* :doc:`OPT package ` * :doc:`Section 2.6 -sf opt ` * Search the :doc:`pair style ` page for styles followed by (t) * `Benchmarks page `_ of web site @@ -1541,7 +1542,8 @@ USER-INTEL package Dozens of pair, fix, bond, angle, dihedral, improper, and kspace styles which are optimized for Intel CPUs and KNLs (Knights Landing). -All of them have an "intel" in their style name. The :doc:`Speed intel ` doc page gives details of what hardware and +All of them have an "intel" in their style name. The +:doc:`USER-INTEL package ` page gives details of what hardware and compilers are required on your system, and how to build and use this package. Its styles can be invoked at run time via the "-sf intel" or "-suffix intel" :doc:`command-line switches `. Also see @@ -1567,8 +1569,8 @@ This package has :ref:`specific installation instructions ` on the : * src/USER-INTEL: filenames -> commands * src/USER-INTEL/README -* :doc:`Speed packages ` -* :doc:`Speed intel ` +* :doc:`Accelerator packages ` +* :doc:`USER-INTEL package ` * :doc:`Section 2.6 -sf intel ` * :doc:`Section 2.6 -pk intel ` * :doc:`package intel ` @@ -1915,7 +1917,7 @@ USER-OMP package Hundreds of pair, fix, compute, bond, angle, dihedral, improper, and kspace styles which are altered to enable threading on many-core CPUs via OpenMP directives. All of them have an "omp" in their style name. -The :doc:`Speed omp ` doc page gives details of what hardware +The :doc:`USER-OMP package ` page gives details of what hardware and compilers are required on your system, and how to build and use this package. Its styles can be invoked at run time via the "-sf omp" or "-suffix omp" :doc:`command-line switches `. Also see @@ -1947,8 +1949,8 @@ This package has :ref:`specific installation instructions ` on the :do * src/USER-OMP: filenames -> commands * src/USER-OMP/README -* :doc:`Speed packages ` -* :doc:`Speed omp ` +* :doc:`Accelerator packages ` +* :doc:`USER-OMP package ` * :doc:`Section 2.6 -sf omp ` * :doc:`Section 2.6 -pk omp ` * :doc:`package omp ` diff --git a/doc/src/Packages_standard.rst b/doc/src/Packages_standard.rst index ca22515590..ab9be69ab3 100644 --- a/doc/src/Packages_standard.rst +++ b/doc/src/Packages_standard.rst @@ -37,7 +37,7 @@ package: +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+ | :ref:`CORESHELL ` | adiabatic core/shell model | :doc:`Howto coreshell ` | coreshell | no | +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+ -| :ref:`DIPOLE ` | point dipole particles | :doc:`pair_style dipole/cut ` | dipole | no | +| :ref:`DIPOLE ` | point dipole particles | :doc:`pair_style lj/.../dipole ` | dipole | no | +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+ | :ref:`GPU ` | GPU-enabled styles | :doc:`Section gpu ` | `Benchmarks `_ | int | +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+ diff --git a/doc/src/Run_basics.rst b/doc/src/Run_basics.rst index d02873a8be..35d5f829a0 100644 --- a/doc/src/Run_basics.rst +++ b/doc/src/Run_basics.rst @@ -27,11 +27,11 @@ executable itself can be placed elsewhere. As LAMMPS runs it prints info to the screen and a logfile named *log.lammps*\ . More info about output is given on the -:doc:`Run output ` doc page. +:doc:`screen and logfile output ` page. If LAMMPS encounters errors in the input script or while running a simulation it will print an ERROR message and stop or a WARNING -message and continue. See the :doc:`Errors ` doc page for a +message and continue. See the :doc:`Common Problems ` page for a discussion of the various kinds of errors LAMMPS can or can't detect, a list of all ERROR and WARNING messages, and what to do about them. diff --git a/doc/src/Run_options.rst b/doc/src/Run_options.rst index 054ed66d57..f5435ec3a9 100644 --- a/doc/src/Run_options.rst +++ b/doc/src/Run_options.rst @@ -80,7 +80,7 @@ stdin. Explicitly enable or disable KOKKOS support, as provided by the KOKKOS package. Even if LAMMPS is built with this package, as described -in :doc:`Speed kokkos `, this switch must be set to enable +in the :doc:`the KOKKOS package page `, this switch must be set to enable running with KOKKOS-enabled styles the package provides. If the switch is not set (the default), LAMMPS will operate as if the KOKKOS package were not installed; i.e. you can run standard LAMMPS or with @@ -98,7 +98,8 @@ Either the full word or an abbreviation can be used for the keywords. Note that the keywords do not use a leading minus sign. I.e. the keyword is "t", not "-t". Also note that each of the keywords has a default setting. Examples of when to use these options and what -settings to use on different platforms is given on the :doc:`Speed kokkos ` doc page. +settings to use on different platforms is given on the :doc:`KOKKOS package ` +doc page. * d or device * g or gpus @@ -268,7 +269,7 @@ machine (e.g. your desktop), you can run on more (virtual) processors than you have physical processors. To run multiple independent simulations from one input script, using -multiple partitions, see the :doc:`Howto multiple ` doc +multiple partitions, see the :doc:`Howto multiple ` page. World- and universe-style :doc:`variables ` are useful in this context. @@ -326,7 +327,7 @@ cores within each node are ranked in a desired order. Or when using the :doc:`run_style verlet/split ` command with 2 partitions to insure that a specific Kspace processor (in the second partition) is matched up with a specific set of processors in the first partition. -See the :doc:`Speed tips ` doc page for more details. +See the :doc:`General tips ` page for more details. If the keyword *nth* is used with a setting *N*\ , then it means every Nth processor will be moved to the end of the ranking. This is useful @@ -385,7 +386,7 @@ implementations, either by environment variables that specify how to order physical processors, or by config files that specify what physical processors to assign to each MPI rank. The -reorder switch simply gives you a portable way to do this without relying on MPI -itself. See the :doc:`processors out ` command for how +itself. See the :doc:`processors file ` command for how to output info on the final assignment of physical processors to the LAMMPS simulation domain. @@ -523,10 +524,10 @@ lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style can be specified explicitly in your input script, e.g. pair_style lj/cut/gpu. If the -suffix switch is used the specified suffix (gpu,intel,kk,omp,opt) is automatically appended whenever your input -script command creates a new :doc:`atom `, -:doc:`pair `, :doc:`fix `, :doc:`compute `, or -:doc:`run ` style. If the variant version does not exist, -the standard version is created. +script command creates a new :doc:`atom style `, +:doc:`pair style `, :doc:`fix `, +:doc:`compute `, or :doc:`run style `. If the +variant version does not exist, the standard version is created. For the GPU package, using this command-line switch also invokes the default GPU settings, as if the command "package gpu 1" were used at @@ -579,8 +580,8 @@ index variable in the input script, since index variables cannot be re-defined. See the :doc:`variable ` command for more info on defining -index and other kinds of variables and the :doc:`Commands parse ` page for more info on using variables in -input scripts. +index and other kinds of variables and the :doc:`Parsing rules ` +page for more info on using variables in input scripts. .. note:: diff --git a/doc/src/Speed_bench.rst b/doc/src/Speed_bench.rst index 45b5b21d8a..66db03e360 100644 --- a/doc/src/Speed_bench.rst +++ b/doc/src/Speed_bench.rst @@ -38,7 +38,7 @@ of these 5 problems on 1 or 4 cores of Linux desktop. The bench/FERMI and bench/KEPLER directories have input files and scripts and instructions for running the same (or similar) problems using OpenMP or GPU or Xeon Phi acceleration options. See the README files in those directories and the -:doc:`Speed packages ` doc pages for instructions on how +:doc:`Accelerator packages ` pages for instructions on how to build LAMMPS and run on that kind of hardware. The bench/POTENTIALS directory has input files which correspond to the diff --git a/doc/src/Speed_kokkos.rst b/doc/src/Speed_kokkos.rst index 3269564d21..5df53ec2cd 100644 --- a/doc/src/Speed_kokkos.rst +++ b/doc/src/Speed_kokkos.rst @@ -9,7 +9,7 @@ different back end languages such as CUDA, OpenMP, or Pthreads. The Kokkos library also provides data abstractions to adjust (at compile time) the memory layout of data structures like 2d and 3d arrays to optimize performance on different hardware. For more information on -Kokkos, see `GitHub `_. +Kokkos, see `the Kokkos GitHub page `_. The LAMMPS KOKKOS package contains versions of pair, fix, and atom styles that use data structures and macros provided by the Kokkos @@ -20,20 +20,20 @@ including Sikandar Mashayak (UIUC), Ray Shan (Sandia), and Dan Ibanez (Sandia). For more information on developing using Kokkos abstractions see the Kokkos `Wiki `_. -Kokkos currently provides support for 3 modes of execution (per MPI +Kokkos currently provides support for 4 modes of execution (per MPI task). These are Serial (MPI-only for CPUs and Intel Phi), OpenMP -(threading for many-core CPUs and Intel Phi), and CUDA (for NVIDIA -GPUs). You choose the mode at build time to produce an executable -compatible with specific hardware. +(threading for many-core CPUs and Intel Phi), CUDA (for NVIDIA +GPUs) and HIP (for AMD GPUs). You choose the mode at build time to +produce an executable compatible with a specific hardware. -.. note:: +.. admonition:: NVIDIA CUDA support To build with Kokkos support for NVIDIA GPUs, the NVIDIA CUDA toolkit software version 9.0 or later must be installed on your system. See the discussion for the :doc:`GPU package ` for details of how to check and do this. -.. note:: +.. admonition:: CUDA and MPI library compatibility Kokkos with CUDA currently implicitly assumes that the MPI library is CUDA-aware. This is not always the case, especially when using @@ -45,6 +45,13 @@ compatible with specific hardware. LAMMPS command line or by using the command :doc:`package kokkos cuda/aware off ` in the input file. +.. admonition:: AMD GPU support + + To build with Kokkos the HIPCC compiler from the AMD ROCm software + version 3.5 or later is required. Supporting this Kokkos mode in + LAMMPS is still work in progress. Please contact the LAMMPS developers + if you run into problems. + Building LAMMPS with the KOKKOS package """""""""""""""""""""""""""""""""""""""