From d802817ccad57f755c8cde20bcd39b62c6cea3f5 Mon Sep 17 00:00:00 2001 From: Gareth Tribello Date: Fri, 7 Dec 2018 10:39:10 +0000 Subject: [PATCH] Small changes to the documentation for building and using PLUMED --- doc/src/Build_extras.txt | 65 +++++++++++++++++++++------------------- doc/src/fix_plumed.txt | 6 ++-- 2 files changed, 37 insertions(+), 34 deletions(-) diff --git a/doc/src/Build_extras.txt b/doc/src/Build_extras.txt index fb2fe95341..c35418ae5f 100644 --- a/doc/src/Build_extras.txt +++ b/doc/src/Build_extras.txt @@ -735,28 +735,31 @@ from LAMMPS using the generic "plumed installation instructions"_plumedinstall. :link(plumedinstall,http://plumed.github.io/doc-master/user-doc/html/_installation.html) PLUMED can be linked into MD codes in three different modes: static, -shared, and runtime. With the "static" mode, all required PLUMED code -is linked statically into the MD code. The MD code is then fully -independent from the PLUMED installation, but also you have to -rebuild/relink the MD code to update the PLUMED code inside it. With -"shared" linkage mode, the MD code is linked to a shared library -containing the PLUMED code, preferably after it was installed in a -globally accessible location. This way the same installed PLUMED code -can be shared across multiple MD packages and can be updated, for as -long as the shared PLUMED library is ABI-compatible. The third linkage -mode is "runtime" which allows to switch the PLUMED kernel at runtime -between different variants through setting the PLUMED_KERNEL environment -variable, which has to point to the location of the libplumedKernel.so -dynamical shared object, which is then loaded at runtime. This is +shared, and runtime. With the "static" mode, all the code that PLUMED requires +is linked statically into LAMMPS. LAMMPS is then fully +independent from the PLUMED installation, but you have to +rebuild/relink it in order to update the PLUMED code inside it. With +the "shared" linkage mode, LAMMPS is linked to a shared library +that contains the PLUMED code. This library should preferably be installed in a +globally accessible location. When PLUMED is linked in this way the same library +can be used by multiple MD packages. Furthermore, the PLUMED library LAMMPS uses can be updated +without the need for a recompile of LAMMPS for as +long as the shared PLUMED library is ABI-compatible. + +The third linkage +mode is "runtime" which allows the user to specify which PLUMED kernel should be used at runtime +by using the PLUMED_KERNEL environment +variable. This variable should point to the location of the libplumedKernel.so +dynamical shared object, which is then loaded at runtime. This mode of linking is particularly convenient for doing PLUMED development and comparing -multiple PLUMED versions without having to recompile the hosting MD +multiple PLUMED versions as these sorts of comparisons can be done without recompiling the hosting MD code. All three linkage modes are supported by LAMMPS on selected operating systems (e.g. Linux) and using either CMake or traditional -make build. The "static" mode should be most portable, the "runtime" +make build. The "static" mode should be the most portable, while the "runtime" mode support in LAMMPS makes the most assumptions about operating system and compiler environment. If one mode does not work, try a -different one, or switch to a different build system, or consider -a global PLUMED installation or downloading it during building LAMMPS. +different one, switch to a different build system, consider +a global PLUMED installation or consider downloading PLUMED during the LAMMPS build. [CMake build]: @@ -764,25 +767,25 @@ a global PLUMED installation or downloading it during building LAMMPS. -D PLUMED_MODE=value # Linkage mode for PLUMED, value = static (default), shared, or runtime :pre If DOWNLOAD_PLUMED is set to "yes", the PLUMED library will be -downloaded (the version of that is hard-coded to a vetted version of +downloaded (the version of PLUMED that will be downloaded is hard-coded to a vetted version of PLUMED, usually a recent stable release version) and built inside the CMake build directory. If DOWNLOAD_PLUMED is set to "no" (the default), -CMake will try to detect an installed version of PLUMED and link to -that. For this to work, the PLUMED library has to be installed into a +CMake will try to detect and link to an installed version of PLUMED. +For this to work, the PLUMED library has to be installed into a location where the pkg-config tool can find it or the PKG_CONFIG_PATH -environment variable has to be set up accordingly. +environment variable has to be set up accordingly. PLUMED should be installed +in such a location if you compile it using the default make; make install commands. -The PLUMED_MODE setting determines the linkage mode of the PLUMED -library. Allowed values are "static" (default), "shared", or "runtime". +The PLUMED_MODE setting determines the linkage mode for the PLUMED +library. The allowed values for this flag are "static" (default), "shared", or "runtime". For a discussion of PLUMED linkage modes, please see above. When -enabling DOWNLOAD_PLUMED, the static linkage mode is recommended. +DOWNLOAD_PLUMED is enabled the static linkage mode is recommended. [Traditional make]: -Before installing the USER-PLUMED package, first the PLUMED library -needs to be configured so that LAMMPS can find the right settings when -compiling and linking the LAMMPS executable itself. You can either -download and build PLUMED inside the LAMMPS plumed library folder or use +PLUMED needs to be installed before the USER-PLUMED package is installed +so that LAMMPS can find the right settings when compiling and linking the LAMMPS executable. +You can either download and build PLUMED inside the LAMMPS plumed library folder or use a previously installed PLUMED library and point LAMMPS to its location. You also have to choose the linkage mode: "static" (default), "shared" or "runtime". For a discussion of PLUMED linkage modes, please @@ -799,9 +802,9 @@ make lib-plumed args="-p /usr/local -m shared" # use existing PLUMED installati :pre Note that 2 symbolic (soft) links, "includelink" and "liblink" are -created in lib/plumed to point into the location of the PLUMED build to -use and also a new file lib/plumed/Makefile.lammps is created with -settings suitable for LAMMPS to compile and link PLUMED in the desired +created in lib/plumed that point to the location of the PLUMED build to +use. A new file lib/plumed/Makefile.lammps is also created with +settings suitable for LAMMPS to compile and link PLUMED using the desired linkage mode. After this step is completed, you can install the USER-PLUMED package and compile LAMMPS in the usual manner: diff --git a/doc/src/fix_plumed.txt b/doc/src/fix_plumed.txt index 30e8b2766c..1f548d11ea 100644 --- a/doc/src/fix_plumed.txt +++ b/doc/src/fix_plumed.txt @@ -32,7 +32,7 @@ enhance the sampling of phase space. The documentation included here only describes the fix plumed command itself. This command is LAMMPS specific, whereas most of the -functionality implemented in PLUMED, however, will work with a range of +functionality implemented in PLUMED will work with a range of MD codes, and when PLUMED is used as a stand alone code for analysis. The full "documentation for PLUMED"_plumeddocs is available online and included in the PLUMED source code. The PLUMED library development is @@ -54,8 +54,8 @@ have been set. The {group-ID} entry is ignored. LAMMPS will always pass all the atoms to PLUMED and there can only be one instance of the plumed fix at a -time. The plumed fix communicates the minimum amount of information -required and the PLUMED supports multiple, completely independent +time. The way the plumed fix is implmented ensures that the minimum amount of information +required is communicated. Furthremore, PLUMED supports multiple, completely independent collective variables, multiple independent biases and multiple independent forms of analysis. There is thus really no restriction in functionality by only allowing only one plumed fix in the LAMMPS input.