ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Small changes to the documentation for building and using PLUMED

Browse Source
This commit is contained in:
Gareth Tribello
2018-12-07 10:39:10 +00:00
parent 67041a5446
commit d802817cca
2 changed files with 37 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
doc/src/Build_extras.txt
View File

@ -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) :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, PLUMED can be linked into MD codes in three different modes: static,
shared, and runtime. With the "static" mode, all required PLUMED code shared, and runtime. With the "static" mode, all the code that PLUMED requires
is linked statically into the MD code. The MD code is then fully is linked statically into LAMMPS. LAMMPS is then fully
independent from the PLUMED installation, but also you have to independent from the PLUMED installation, but you have to
rebuild/relink the MD code to update the PLUMED code inside it. With rebuild/relink it in order to update the PLUMED code inside it. With
"shared" linkage mode, the MD code is linked to a shared library the "shared" linkage mode, LAMMPS is linked to a shared library
containing the PLUMED code, preferably after it was installed in a that contains the PLUMED code. This library should preferably be installed in a
globally accessible location. This way the same installed PLUMED code globally accessible location. When PLUMED is linked in this way the same library
can be shared across multiple MD packages and can be updated, for as can be used by multiple MD packages. Furthermore, the PLUMED library LAMMPS uses can be updated
long as the shared PLUMED library is ABI-compatible. The third linkage without the need for a recompile of LAMMPS for as
mode is "runtime" which allows to switch the PLUMED kernel at runtime long as the shared PLUMED library is ABI-compatible.
between different variants through setting the PLUMED_KERNEL environment
variable, which has to point to the location of the libplumedKernel.so The third linkage
dynamical shared object, which is then loaded at runtime. This is 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 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 code. All three linkage modes are supported by LAMMPS on selected
operating systems (e.g. Linux) and using either CMake or traditional 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 mode support in LAMMPS makes the most assumptions about operating
system and compiler environment. If one mode does not work, try a system and compiler environment. If one mode does not work, try a
different one, or switch to a different build system, or consider different one, switch to a different build system, consider
a global PLUMED installation or downloading it during building LAMMPS. a global PLUMED installation or consider downloading PLUMED during the LAMMPS build.
[CMake 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 -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 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 PLUMED, usually a recent stable release version) and built inside the
CMake build directory. If DOWNLOAD_PLUMED is set to "no" (the default), 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 CMake will try to detect and link to an installed version of PLUMED.
that. For this to work, the PLUMED library has to be installed into a 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 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 The PLUMED_MODE setting determines the linkage mode for the PLUMED
library. Allowed values are "static" (default), "shared", or "runtime". library. The allowed values for this flag are "static" (default), "shared", or "runtime".
For a discussion of PLUMED linkage modes, please see above. When 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]: [Traditional make]:
Before installing the USER-PLUMED package, first the PLUMED library PLUMED needs to be installed before the USER-PLUMED package is installed
needs to be configured so that LAMMPS can find the right settings when so that LAMMPS can find the right settings when compiling and linking the LAMMPS executable.
compiling and linking the LAMMPS executable itself. You can either You can either download and build PLUMED inside the LAMMPS plumed library folder or use
download and build PLUMED inside the LAMMPS plumed library folder or use
a previously installed PLUMED library and point LAMMPS to its a previously installed PLUMED library and point LAMMPS to its
location. You also have to choose the linkage mode: "static" (default), location. You also have to choose the linkage mode: "static" (default),
"shared" or "runtime". For a discussion of PLUMED linkage modes, please "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 :pre
Note that 2 symbolic (soft) links, "includelink" and "liblink" are Note that 2 symbolic (soft) links, "includelink" and "liblink" are
created in lib/plumed to point into the location of the PLUMED build to created in lib/plumed that point to the location of the PLUMED build to
use and also a new file lib/plumed/Makefile.lammps is created with use. A new file lib/plumed/Makefile.lammps is also created with
settings suitable for LAMMPS to compile and link PLUMED in the desired settings suitable for LAMMPS to compile and link PLUMED using the desired
linkage mode. After this step is completed, you can install the linkage mode. After this step is completed, you can install the
USER-PLUMED package and compile LAMMPS in the usual manner: USER-PLUMED package and compile LAMMPS in the usual manner:

6
doc/src/fix_plumed.txt
View File

@ -32,7 +32,7 @@ enhance the sampling of phase space.
The documentation included here only describes the fix plumed command The documentation included here only describes the fix plumed command
itself. This command is LAMMPS specific, whereas most of the 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. MD codes, and when PLUMED is used as a stand alone code for analysis.
The full "documentation for PLUMED"_plumeddocs is available online and The full "documentation for PLUMED"_plumeddocs is available online and
included in the PLUMED source code. The PLUMED library development is 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 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 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 time. The way the plumed fix is implmented ensures that the minimum amount of information
required and the PLUMED supports multiple, completely independent required is communicated. Furthremore, PLUMED supports multiple, completely independent
collective variables, multiple independent biases and multiple collective variables, multiple independent biases and multiple
independent forms of analysis. There is thus really no restriction in independent forms of analysis. There is thus really no restriction in
functionality by only allowing only one plumed fix in the LAMMPS input. functionality by only allowing only one plumed fix in the LAMMPS input.