Installation
The instructions that follow explain how to configure, compile and install a single version of plumed on a local machine. For most users the instructions below will work fine. A small fraction of users will want to do something more complicated at install time. Such users can use the “How would you like to build PLUMED” button below to get instructions on what to do in these more exotic cases.
It is perhaps easiest to install PLUMED using the macports or conda package manager. For instructions on how to install PLUMED in this way “How would you like to build PLUMED” button.
You will find a “show defaults” button by the boxes that shows a configure command below. If you click this button the default flags that are used when that command is executed are shown. Information on what is controlled by each flag is provided through tooltips, which you are shown if you hover over the flag.
Some flags are shown in bold in the short versions of the configure commands below. Clicking on these commands will open a pop-up window that contains further information about the flag. You will most likely not need to worry about the information in these pop ups but it may be worth considering as these options can affect the performance of the compiled code.
PLUMED can be used in tandem with the MD codes shown in the table on the right below. To see instructions on what you must do in order have versions of these codes that work with PLUMED click the checkbox associated with the code you require. Instructions on patching the code you select with PLUMED will appear at the bottom of the web page.
Building PLUMED on a cluster
Some general advice
If you are compiling PLUMED on a cluster and if several users will take advantage of the code we would recomment that you:
- Follow the advice given below about using modules and the module file that PLUMED provides to set up the environment. N.B you will need to edit this file to make it suitable for your environment.
- Compile with all the modules enabled so that users can use the full range of features. In addition, ensure that features that are provided by specific libraries are enabled. For example, users employing gromacs will likely want to use libxdrfile to write trr/xtc files. If gromacs is installed before PLUMED, and if the location of libxdrfile is provided to PLUMED during the configure stage then this feature will be available.
- Try to patch all MD codes using the
--runtimeoption. When codes are patched in this way users are able to combine any of the installed gromacs/amber/etc versions with any of the installed PLUMED versions. It is sometimes claimed that statically linked codes are faster. In our experience, however, this is not true. Furthermore, we have found that non-trivial linking issues are often encountered when building static executables because PLUMED is written in C++ and thus requires the appropriate C++ library to be linked as well as other additional libraries (e.g. libxdrfile). - Keep track of the version of PLUMED you used to patch each of the MD codes. You might do this by giving the MD code modules names such as
gromacs/4.6.7p2.2.0to indicate that this is gromacs patched with PLUMED 2.2.0. By keeping track of this information you make it more straightforward for users to report errors on our forum. - Use the environment variables descsribed below to control the compiler flags and to build an optimized executable.
Advice on specific topics and architectures is provided by the drop down menu below. If you have advice on compiling PLUMED on specific architecture please share your tricks! You can post information in your blog, or ask as to update the list of topics in this dropdown. The advice you can provide others on compiling PLUMED is very useful and we will happily post it here.
On Cray machines you often have to set the CRAYPE_LINK_TYPE environmental variable
before configuring and building both PLUMED and the MD code that you want to patch with PLUMED.
You can set this variable using the command:
export CRAYPE_LINK_TYPE=dynamic
Our thanks to Marco De La Pierre for reporting this requirement
To build PLUMED with Intel MPI you need to include the flags -lmpi_mt -mt_mpi -DMPICH_IGNORE_CXX_SEEK when compiling and the
flags -lmpi_mt -mt_mpi when linking. To do so you can use the configure command:
./configure LDFLAGS=-lmpi_mt CXXFLAGS="-DMPICH_IGNORE_CXX_SEEK -mt_mpi" STATIC_LIBS=-mt_mpi
./configure LDFLAGS=-lmpi_mt CXXFLAGS="-DMPICH_IGNORE_CXX_SEEK -mt_mpi" STATIC_LIBS=-mt_mpi--enable-modules=resetall/none/reset or : separated list such as +crystallization:-bias default: reset--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-rpathenable store rpath, default: no--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-mpienable search for mpi, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
This tip was provided by Abhishek Acharya. You can read more about it in this thread.
PLUMED needs to be well optimized to run efficiently. If you need a single PLUMED binary to run efficiency on machines with different levels of hardware (for example, if some of your workstations support AVX and some do not), then with then intel compiler you can use a configure command like the one shown below:
./configure CXX=mpicxx CXXFLAGS="-O3 -axSSE2,AVX"
./configure CXX=mpicxx CXXFLAGS="-O3 -axSSE2,AVX"--enable-modules=resetall/none/reset or : separated list such as +crystallization:-bias default: reset--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-rpathenable store rpath, default: no--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-mpienable search for mpi, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
This will take more time to compile but it will allow you to use a single module. If you cannot use this option, you should install two PLUMED versions with different optimization levels.
It is usually not necessary to install both an MPI and a non-MPI PLUMED version of PLUMED. The PLUMED library only calls MPI functions
when the MD code is compiled with MPI. Furthermore, the PLUMED executable can be invked with a --no-mpi flag on the login node
as shown below:
> plumed --no-mpi
This command will run even if PLUMED was compiled with MPI and the login node does not support MPI. The only cases where you might need two different PLUMED installations for the compute and login node is when you are cross compiling.
On Blue Gene Q (likely on AIX) the prelinking made with ld -r is not
working properly. There is no easy way to detect this at configure time.
If, however, you receive an error in the form:
ld: TOC section size exceeds 64k
when you run make please configure PLUMED again using the flag --disable-ld-r
Configuring PLUMED
As a bare minimum we would recommend using a command like the one shown below when configuring PLUMED on a cluster
./configure --enable-modules=all --enable-rpath
./configure --enable-modules=all --enable-rpath--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-mpienable search for mpi, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
The --enable-rpath flag is recommended as by including this flag you ensure that PLUMED will remember the locations of any runtime libraries that were used at compile time.
The locations of these libraries will thus not need to provided at runtime. This trick often does not work for fundamental libraries such as the C++ and MPI library. The PLUMED module
should thus load the compiler and MPI modules.
Building PLUMED for development purposes
Configuring PLUMED
The first step in building PLUMED is to configure the makefiles based on the setup of your computer. If you are developing PLUMED, we recommend that you configure using the options below:
./configure --enable-modules=all --enable-mpi --enable-debug
./configure --enable-modules=all --enable-mpi --enable-debug--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-rpathenable store rpath, default: no--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
Once you are confident that your feature is working correctly you can then reconfigure and compile an optimized version of the code.
You can control the compilers and compiler flags that are used to build PLUMED by setting the environment variables. For example, if you wanted to use the icpc and icc compilers you might use the command shown in the example below:
./configure CXX=icpc CC=icc CXXFLAGS=-O3 LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include LIBS=-lmyxdrfile
./configure CXX=icpc CC=icc CXXFLAGS=-O3 LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include LIBS=-lmyxdrfile--enable-modules=resetall/none/reset or : separated list such as +crystallization:-bias default: reset--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-rpathenable store rpath, default: no--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-mpienable search for mpi, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
Testing PLUMED
If you have compiled the executable on a machine that is different from the one on which you will ultimately run it the
plumed executable is not available in the compilation environment. You thus cannot perform the regtests on
the machine and you cannot compile the manual.
You might try to run the regtests on the computing nodes in this case. You may need to do some tweaks to get this to work as machines where people do cross-compiling often have architectures with limited capabilities on the compute nodes.
Patching MD codes with a cross compiled code
As discussed in the previous section, if PLUMED has been cross compiled the plumed executable is not available in the compilation environment.
You thus cannot run plumed patch on the compiler nodes. It is also likely that it will not be possible to run this command on the compute nodes
as on machines where cross compilation is necessary it is often not possible to fork new processes from the compute nodes. To get around these issues you can
use the command:
> plumed-patch
instead. This script provides a "shell only" implementation of plumed patch and thus does not launch of the plumed executable.
You can thus run this command (and patch MD codes) on the compiler nodes. If you have installed PLUMED you can find the plumed-patch code
script (and some other similar shell scripts that allow you to run various plumed command line tools without launching the plumed executable)
in the directory $(prefix)/plumed/plumed-. The reason these files are not included in the execution path (prefix/bin) is to avoid clashes.
The easiest way to setup the environment is to use the module framework. If you have installed plumed into a system directory such
as /usr/local then the environment should already be setup correctly.
If you see errors when you run the regression tests using the commands:
> cd regtest > make
The first thing you should try to work out is the version of PLUMED that is being used to run the tests. When the tests are run using the commands above the version of PLUMED that is found in the PATH is used. If the version of PLUMED in your path is not the same as the version that you just downloaded and compiled then you may observe one of two innocuous errors:
- If the PLUMED executable in your path is older than the test suite you are running on the tests might fail. In this case the tests fail as some feature was introduced to PLUMED in a newer version.
- The tests might also fail if the PLUMED executable in your path is newer than the test suite. In this case some non-backward compatible change was made in PLUMED. We try to keep the number of non-backward compatible changes small, but as you can see from the ChangeLog there are typically a few non-compatable changes at every new major release.
Compiling PLUMED
PLUMED can be compiled using the following command once the configure script has finished running:
> make -j 4
This command compiles the entire code and produces a number of files in the src/lib directory, including the executable
src/lib/plumed. If the shared libraries are enabled a shared libraries called src/lib/libKernel.so should also be generated.
The extension for this file will be .dylib if you are building PLUMED on a Mac. There are some rare occasions when this command fails
because the configure script fails to find some of the required libraries. If this happens you can edit the Makefile.conf file so that the suitable
compilation options are set up.
You can control the compilers and compiler flags that are used to build PLUMED by setting the environmental variables. For example, if you wanted to use the icpc and icc compilers you might use the command shown in the example below:
./configure CXX=icpc CC=icc CXXFLAGS=-O3 LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include LIBS=-lmyxdrfile
./configure CXX=icpc CC=icc CXXFLAGS=-O3 LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include LIBS=-lmyxdrfile--enable-modules=resetall/none/reset or : separated list such as +crystallization:-bias default: reset--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-rpathenable store rpath, default: no--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-mpienable search for mpi, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
You can enable and disable various features within PLUMED by using the --enable-FEATURE and --disable-FEATURE options during the configure step. We would recommend using a configure command with the following options enabled.
./configure LIBRARY_PATH=/path --enable-rpath --enable-modules=all --enable-mpi --enable-asmjit --enable-external-lapack --enable-molfile-plugins --prefix=/usr/local
./configure LIBRARY_PATH=/path --enable-rpath --enable-modules=all --enable-mpi --enable-asmjit --enable-external-lapack --enable-molfile-plugins --prefix=/usr/local--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-external-blasenable search for external blas, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
Installing PLUMED with conda
If you use the conda package manager you can quictkly install a pre-compiled PLUMED binary by using the following command:
> conda install -c conda-forge plumed
Similarly, the python wrappers can be installed by using the command:
> conda install -c conda-forge py-plumed
These packages are part of conda-forge. They should thus be binary compatible with other codes from
the same distribution. Furthermore, it should also be possible to combine the PLUMED kernel installed from conda with an MD code that has been compiled outside
of conda (or within a different conda environment) if PLUMED is linked in runtime mode. The only variable that you need to set in order to access to the PLUMED kernel
that is installed through conda is PLUMED_KERNEL (e.g., export PLUMED_KERNEL=/conda/prefix/lib/libplumedKernel.so).
Conda binaries are only available for Linux and macOS. The installed conda binaries were configured using the command:
./configure --prefix=$PREFIX --disable-python --disable-libsearch --disable-static-patch --disable-static-archive
./configure --prefix=$PREFIX --disable-python --disable-libsearch --disable-static-patch --disable-static-archive--enable-modules=resetall/none/reset or : separated list such as +crystallization:-bias default: reset--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-rpathenable store rpath, default: no--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-mpienable search for mpi, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
so the features are limited accordindly. Notice that there additional conda packages are available on the plumed channel. These packages are for testing only.
Setting up your environment
Once the installation and testing has been completed you are ready to use PLUMED. Running PLUMED will be more straightforward if you set up the environment correctly. If the environment is setup correctly you should be able to:
- use the
plumedexecutable from the command line. Notice that you can also use this executable before installing. - link against the PLUMED library using the
-lplumedflag for the linker. If this flag can be employed then it is possible to use PLUMED library in general purpose programs - use PLUMED internal functionality (C++ classes) including header files such as
#include <plumed/tools/Vector.h>in general purpose programs
Building PLUMED on a local machine
Configuring PLUMED
The first step in building PLUMED is to configure the makefiles based on the setup of your computer. You can do this by issuing the following command:
./configure
./configure--enable-modules=resetall/none/reset or : separated list such as +crystallization:-bias default: reset--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-rpathenable store rpath, default: no--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-mpienable search for mpi, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
Building multiple PLUMED versions
Configuring PLUMED
The first step in building PLUMED is to configure the makefiles based on the setup of your computer. If you would like to have multiple versions of the code installed on your computer, you will also need to give them all different names and place them in different locations. You will thus need to use a configure command such as the one below:
./configure prefix=$HOME/opt --program-suffix=2.2 --program-prefix=mpi-
./configure prefix=$HOME/opt --program-suffix=2.2 --program-prefix=mpi---enable-modules=resetall/none/reset or : separated list such as +crystallization:-bias default: reset--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-rpathenable store rpath, default: no--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-mpienable search for mpi, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
By using this command you ensure that the PLUMED executible will be named mpi-plumed2.2 and that other PLUMED files will be named similarly. To load this PLUMED library
you will thus need to use the flag -lmpi-plumed2.2. PLUMED header files would then be included by using #include <mpi-plumed_2.2/tools/Vector.h>.
It is also possible to use arbitrary scripts to edit the name of the executable by adding the option --program-transform-name=PROGRAM to your configure command.
(see autoconf documentation for more info).
This options is useful if you do not want to set up modules. As detailed below, however, we believe that using modules is more flexible.
The easiest way to setup the environment is to use the module framework.
A suitable module file for PLUMED can be found in $(prefix)/lib/plumed/src/lib/modulefile after installation is completed.
You can edit this file or just put it into your modulefile directory directly. If you do so it is then straightforward to
set up the environment.
Notice that if you have installed more than one version of PLUMED on your machine you can use the module framework to easily switch between them.
Lastly note that even if you do not want to use modules it may still be useful to look at the modulefile as this file will tell you which environment variables need to be set for PLUMED to work correctly.
Installing PLUMED
You can install PLUMED using the command:
> make install
or the command:
> sudo make install
If you want to install PLUMED in a system directory. Unless modifications are made to the standard autoconf directories this command copies the
executable to $(prefix)/bin, the libraries to $(prefix)/lib,
the include files to $(prefix)/include, and the documentation to $(prefix)/shared/doc/plumed. A directory called
$(prefix)/lib/plumed is also created by this command. This directory contains several other files, including
the patch files and the object files that are used for static patching.
$(prefix) here is the directory specified using the --prefix keyword of the configure script.
Once PLUMED has been installed using the make install command you can delete the original compilation directory
or you can recompile a different PLUMED version in the same place. You should not delete any of the installed files, however, as
PLUMED will not run if there are files missing from these directories
Testing PLUMED
It is important to test PLUMED every time you install PLUMED, as Even though we regularly perform tests on GitHub actions, it is possible that aggressive optimization or even architecture dependent features trigger bugs that do not show up on GitHub. To test the PLUMED executable that you have installed you should, therefore, type
> make installcheck
Running this command tells PLUMED to run all the tests in the test suite using the version of PLUMED that was just installed. If you would like to test PLUMED using some other PLUMED version then you can. The tests can be run using the PLUMED executable that is in your current path by using the commands:
> cd regtest > make
To determine the version of PLUMED that has been run using the commands above you can use the command:
> which plumed
When you do this you might get certain innocous errors
The most important variables to edit in the Makefile.conf file are:
- DYNAMIC_LIB : the libraries (e.g. BLAS and LAPACK) that are linked when the the PLUMED library is compiled are listed here.
Flags such as -L/path/to/xdrfile -lxdrfile that were specified using the environment variables
LDFLAGSandLIBSin the call toconfigurewill appear here. The fact that the flags specified usingLIBSis perhaps confusing but this is necessary to keep the configuration files compatible with PLUMED 2.0. Notice that for the PLUMED shared library to be compiled correctly only dynamic libraries should be listed here. - LIBS : the libraries that are needed to patching the MD codes (typically only
-ldlwhich is needed to have functions for dynamic loading) are specified here. - CPPFLAGS : definitions that are needed to enable specific optional functions (e.g. -D__PLUMED_HAS_XDRFILE to enable the xdrfile library) are specified here.
- SOEXT : the extension for shared libraries on your system is specified here. Typically an "so" extension is used on UNIX and a "dylib" extension is used on mac.
If your system does not support dynamic libraries or if you would like a static executable you can just set this variable blank i.e.
SOEXT=.
Running PLUMED
If you are developing PLUMED you are probably compiling the code regularly. You thus might choose to not run the make install command
every time you recompile the code. If you are working in this way and if you use the bash shell you can can run PLUMED from the compilation directory by using the sourceme.sh
file that was created by configure script. This file appears in the main PLUMED directory and can be "sourced" as shown below:
> source sourceme.sh
Running this command ensures that the "plumed" executable appears in your path. To test this executable you might run:
> plumed -h
Testing PLUMED
You can test if plumed has been compiled correctly by using the commands:
> make check
Alternatively, you can run all tests using the following command:
> source sourceme.sh > cd regtest > make
You can even run a particular test by changing to the directory that contains it and by running the command make within that directory.
Merging your changes
Before starting work on a new feature that you plan to share with the PLUMED community we would ask you to read this brief summary of best practise.
If you finish your coding a new feature in PLUMED and if you want to share it with the community then you can open a pull request on the PLUMED repository. Before doing so we would ask that you:
- Write suitable documentation for your new feature
- Add a new regtest or modified an existing regtest to validate your changes
- Modify the configure script so that any libraries your feature uses can be setup at configure time
- Check the format of your code using plumedcheck and astyle
Building PLUMED with macports
If you are using PLUMED on a Mac, you can intall it using MacPorts. To take advantage of this option you proceed as follows:
- Install MacPorts
- Type
sudo port install plumed
The default variant that is installed using sudo port install plumed is shipped as a compiled
binary and is thus significantly faster to install. A number of different PLUMED versions can be installed using MacPorts, however.
You can get a list of the versions that are available by using the command:
> sudo port info plumed
The various options that can be viewed using this command allow you to install PLUMED using multiple different compilers. You can thus install plumed with mpich using the command:
> sudo port install plumed +mpich
We would recommend using the recent clang compiler instead of native compilers to take advantage of openMP. To install using this option you can use the command:
> sudo port install plumed +mpich +clang50
Notice that support for c++11 with gcc compilers in MacPorts is difficult as it is not possible to use the system's c++ library. For this reason, we, therefore, only support the clang compilers. If you are interested reading more about this issue we would direct you to this discussion
In addition to the variants that allow you to use MacPorts with a range of compilers there are also options that
allow you to compile with debug flags (+debug), to pick a linear algebra library
(e.g. +openblas) and to enable all the optional modules (+allmodules).
You can also install a developer version of PLUMED by using the command:
> sudo port install plumed-devel
This developer version is typically a later version of PLUMED that is not yet considered stable. When installing
plumed-devel using MacPorts you can use all the variants that were available for plumed to
customize the compilation. You cannot, however, install plumed-devel and plumed at the same time.
You can also use MacPorts to install a plumed-patched version of gromacs. To install gromacs patched with a stable version of PLUMED that was compiled using the clang-5.0 compiler and mpich you would use the following sequence of commands:
> sudo port install plumed +mpich +clang50 > sudo port install gromacs-plumed +mpich +clang50
If, by contract, the objective was to use a version of gromacs patched with the development version of PLUMED you would use the commands:
> sudo port install plumed-devel +mpich +clang50 > sudo port install gromacs-plumed +mpich +clang50
Notice that the same compiler variants must be used for gromacs and PLUMED (in this example +mpich +clang50). If gromacs and PLUMED are built using different
compiler variants then compilation will fail.
The patched version of gromacs that can be installed using MacPorts links PLUMED in runtime mode. The path for libplumedKernel.dylib in the MacPorts tree is hardcoded, however. As a consequence:
- If gromacs is run and if the
PLUMED_KERNELenvironment variable is unset (or set to empty), then the version of PLUMED that was installed using MacPorts is used. - If gromacs is run and if the
PLUMED_KERNELenvironment variable points to another instance of the PLUMED library then this other instance of PLUMED is used in place of the version that was installed using MacPorts
Having the PLUMED_KERNEL operate in this way is useful if you are developing PLUMED as you can install gromacs once using MacPorts and then combine it with any version of
PLUMED on your computer.
Calling PLUMED from python
It is possible to call PLUMED 2.5 and later versions in a python script. If you would like to do so you simply add the command below in your python script:
The interface is designed with developers in mind rather than users as the interface from python to PLUMED is similar to the interface that is used to link PLUMED with the various MD codes. If you are only compiling one version of PLUMED you might configure using the command:
./configure PYTHON_BIN=python3.6 --prefix=$HOME/opt
./configure PYTHON_BIN=python3.6 --prefix=$HOME/opt--enable-modules=resetall/none/reset or : separated list such as +crystallization:-bias default: reset--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-rpathenable store rpath, default: no--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-mpienable search for mpi, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
Once you have compiled and installed PLUMED by following the instructions that are laid out in the sections that follow, the python wrappers for PLUMED will be in
$HOME/opt/plumed/python. To use plumed in a python script the location of these wrappers must be added PYTHONPATH environment variable using
a command such as the one shown below:
> PYTHONPATH="$HOME/opt/lib/plumed/python:$PYTHONPATH"
If you have installed muliple PLUMED versions you might find it easier to install the Python wrappers and PLUMED separately. The simplest way to install the python
wrappers by themselves is with pip as shown below:
> pip3.6 install --user plumed
In the command above the --user flag allows you to install the packages on your home. Notice also that you don't even need to download
PLUMED in order to install the wrappers. The command above can be run before you configure, compile and install PLUMED. You will, however, need PLUMED
in order to use it within a python script. You can tell the wrappers where PLUMED is by setting the PLUMED_KERNEL environment variable as shown
below:
> PLUMED_KERNEL=$HOME/opt/lib/libplumedKernel.so
When you install the wrappers in this manner described above you will download those that are packaged on [Pypi]. If you want to install the development version of the wrappers using pip you should download the PLUMED repository and use the following commands:
> pip3.6 install --user cython > cd plumed2/python > make pip > pip3.6 install --user .
You are highly recommended to use a virtualenv when installing the development version as you will then ensure that the code you install does not interfere with the released pacakages.
Customising your complation environment
Cross compiling PLUMED
Configuring PLUMED
If you are cross compiling PLUMED on a different machine than you intend to run it on then you will need to begin by configuring using the usual command.
./configure
./configure--enable-modules=resetall/none/reset or : separated list such as +crystallization:-bias default: reset--enable-libsearchenable search for libraries, default: yes--enable-static-patchenable allow statically linking plumed, default: yes--enable-docenable documentation, default: yes--disable-pdfdocenable pdf version of the manual, default: no--disable-debugenable debugging, default: no--disable-gcovenable gcov to estimate code coverage, default: no--enable-cxx17, 20, or 23. To link libraries with headers that need this C++ level. Use --enable-cxx=none to remove -std=c++ flag--enable-basic-warningsenable basic warnings, default: yes--disable-fussyenable fussy warnings, default: no--disable-debug-glibcxxenable enable boundary check, default: no--enable-sharedenable shared libs, default: yes--enable-dependency-trackingenable dependency tracking, default: yes--enable-no-gnu-uniqueenable a flag to avoid gnu unique symbols, default: yes--disable-rpathenable store rpath, default: no--disable-absolute-sonameenable store absolute soname (Linux only - this is the default behavior on OSX). Only enable for testing!, default: no--enable-absolute-install-nameenable store absolute relative (OSX only - disable to have a behavior similar to Linux). Only disable for testing!, default: yes--enable-loader-pathenable use @loader_path to find libplumedKernel.dylib (OSX only), default: yes--enable-bsymbolicenable use -Bsymbolic flag in making shared libraries (Linux only), default: yes--enable-ld-renable group object files, default: yes--enable-ar-crenable use ar to build libplumedWrapper.a, default: yes--enable-static-archiveenable try to build libplumed.a for static linking, default: yes--enable-asmjitenable enable embedded asmjit, default: yes--enable-mpienable search for mpi, default: yes--enable-external-lapackenable search for external lapack, default: yes--enable-external-blasenable search for external blas, default: yes--enable-molfile-pluginsenable use molfile_plugins, default: yes--enable-external-molfile-pluginsenable search for external molfile_plugins, default: yes--enable-zlibenable search for zlib, default: yes--enable-dlopenenable search for dlopen, default: yes--enable-dladdrenable search for dladdr, default: yes--enable-rtld_defaultenable search for RTLD_DEFAULT macro, default: yes--enable-subprocessenable search for functions needed to manage a subprocess, default: yes--enable-execinfoenable search for execinfo, default: yes--enable-gslenable search for gsl, default: yes--disable-boost_graphenable search for boost graph, default: no--disable-boost_serializationenable search for boost serialization, default: no--enable-fftwenable search for fftw, default: yes--enable-pythonenable search for python, default: yes--enable-pycvenable set up the pycv plugin, default: yes--disable-af_oclenable search for arrayfire_ocl, default: no--disable-af_cudaenable search for arrayfire_cuda, default: no--disable-af_cpuenable search for arrayfire_cpu, default: no--disable-libtorchenable search for libtorch, default: no--disable-libmetatomicenable search for libmetatomic, default: no--disable-openaccenable search for openacc, default: no--disable-openmpdo not use OpenMP
You will likely need to use the options detailed below from controlling the compilers and compiler flags as detailed below, however.
--enable-external-lapack option
PLUMED uses the blas and lapack libraries to perform linear algebra and the source code for these two libraries is included. For production calculations, however, we would strongly encourage you to link to libraries containing suitably-optimized versions of these libraries and to not rely on the versions of blas and lapack that are included within PLUMED.
You can use a specific version of BLAS or LAPACK availble to configure using the LDFLAGS and LIBS environment variables as shown
below:
> ./configure LDFLAGS=-L/path/to/blas/lib LIBS=-lnameoflib
The configure script will check if the functions that are required from this library are found in the usual way (i.e. by checking without additional
-llapack and -lblas options added to the LIBS environmental variable first and then with these options added to these variabels). Furthermore, two checks
for any required functions are performed. In the first, of these checks the name of the functions are searched for. If this search is unsucessful then a
search for a version of the function with a final underscore added to the name is then performed. If no functions are found in these two steps then the versions of
blas and lapack that are internal to PLUMED are used.
If you prefer to disable the search for external versions of blas and lapack because, for example, the system libraries have problems you can configure using the command
> ./configure --disable-external-blas
You can also only disable the external LAPACK. In other words, you can use the internal version of LAPACK with an external version of BLAS by using the command:
> ./configure --disable-external-lapack
Using this option is quite sensible as one can typically only heavily optimize the BLAS library. Using the internal LAPACK with an external version of BLAS should, therefore, not slow your calculations down significantly. You could thus use this option on systems where the native LAPACK libraries have problems
We have had numerous emails from users who have struggled to link PLUMED with BLAS and LAPACK. We have even struggled with this ourselves. From these experiences, however,
some sensible steps that you can use to check whether or not the configuration has been setup correctly have emerged. If you are having difficulties you should
Open the Makefile.conf file that is output after configure has finished running. Check that the flags necessary for loading the
BLAS and LAPACK libraries are included in the the DYNAMIC_LIB variable that is contained in this file. If BLAS and LAPACK have been detected correctly
-llapack, -lblas and, in some cases, -lgfortran will appear after this variable. On some machines full path specification with -L may be necessary in place of -llapack,
-lblas anmd -gfortran. Depending on system configuration, your libraries may even not be called -llapack and -lblas. You will thus have to ensure that the correct names
for these libraries are used. If the correct libraries appear after DYNAMIC_LIB in the Makefile.conf file and if PLUMED still doesn't compile some other things
to try include:
- If the linker complains and suggests recompiling LAPACK with -fPIC, it means that you have static LAPACK libraries. Either install dynamic LAPACK libraries or switch to static compilation of PLUMED by unsetting the SOEXT variable in the configuration file.
- If the linker complains about other missing functions (typically functions with names that start with the prefix "for_") you need to link some additional Fortran libraries. PLUMED is written in C++ and C++ linkers often do not include Fortran libraries by default, which is unfortunate as the fortran libraries are required for LAPACK and BLAS to work. If you encounter this problem we woudl recommend checking the documentation for your compiler.
- If the linker complains that dsyevr_ cannot be found, try adding the flag -DF77_NO_UNDERSCORE to
CPPFLAGS. "./configure" will automatically try this solution but maybe you have more luck.
--enable-asmjit option
If there are a lot of CUSTOM functions or switching functions
in your input then you may be heavilty using the lepton library that is included in PLUMED.
The calls to this library can be made significantly faster by using a
just-in-time compiler. Furthermore,
as of PLUMED 2.6, ASMJIT is embedded in PLUMED. To enable it you use the --enable-asmjit flag in configure
If, for any reason, you want to disable ASMJIT at runtime you can do by setting the PLUMED_USE_ASMJIT environment variable as shown below:
export PLUMED_USE_ASMJIT=no
--disable-libsearch option
By default PLUMED uses a two step procedure when searching for a library. If, for example, PLUMED is searching for the xdr library it will first try to link a routine from this library
without adding any additional flags. If this command fails the additional flag, "-lxdrfile" is then added to the LIBS envrionmental variable and the test is run again.
The --disable-libsearch command ensures that this second step in the search is ommitted. Consequently, when this option is used only those libraries that are
explicitly passed through the LIBS environmental variable are linked. For example if the command:
> ./configure --disable-libsearch LIBS=-lxdrfile
is used then only xdrfile is linked. The BLAS and LAPACK libraries are not be linked and the internal versions of these libraries are used. This option is
useful when installing PLUMED within package managers such as MacPorts as it ensures that only the desired libraries are linked. In other words, no spurious
dependencies are introduced. The only exception to this rule is -ldl, which is a system library on Linux.
--enable-debug option
CXXFLAGS Environment Variable
The CXXFLAGS environmental variable allows you to control the compilation options just as you might expect.
--enable-mpi option
An MPI search is enabled by default and so the --enable-mpi flag is not strictly necessary. It is important to note, however, that
if MPI search is enabled then compilers named "mpic++" and "mpicxx" are searched for first, which may be confusing as many
other programs behave in a different way.
When PLUMED is configured with MPI enabled (as it is by default) autoconf checks if a code containing MPI calls can be compiled using the specified
compiler. If this code can be compiled then MPI is enabled. If it cannot then MPI will be disabled. If you thus specify a non-MPI compiler using the
CXX environmental variable there is no reason to also specify --disable-mpi. The --disable-mpi command is only
necessary if you specifed an MPI compiler to the CXX environmental variable but you don't want PLUMED to be compiled with MPI support.
In other words, the correct way to enable MPI is to pass ./configure an MPI C++ compiler by using the CXX environmental variable.
If this is done you can then treat the MPI library in the same way that all the other libraries that PLUMED tries to link by default.
LIBRARY_PATH envrionmental variable
In a typical environment configured using the module framework the LIBRARY_PATH environment variable
contains the path to all the modules loaded at compilation time. When PLUMED is compiled using the --enable-rpath
option the paths defined in LIBRARY_PATH are automatically hard coded into the PLUMED library.
LDFLAGS Environment Variable
The main purpose of the configure script is to locate all the libraries that are required to build PLUMED. PLUMED will by default check for these libraries in
certain standard places. If the libraries are not in these standard places, however, then you will need to provide information the configure script on where to find them by using the
LDFLAGS, CPPFLAGS and LIBS flags. If suitable libraries are not found during the execution of the configure script then these
features will be disabled. You should thus carefully check the log that is output by the configure command to ensure that all the libraries you require have been found.
The LDFLAGS variable tells the configure script the names of directories in which the libraries can be found. If the xdrfile libraries are
in /opt/local (i.e. where MacPorts puts them) then you would use the command below to tell PLUMED where to find them.
> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include
CXX Environment Variable
The CXX environmental variable controls the c++ compiler that will be used to build PLUMED. If you would like to compile PLUMED with
MPI the compiler that is passed to this variable should be an MPI compiler. Consequently, if you work on a machine where CXX is
set to a serial compiler and MPICXX is set to a MPI compiler you should configure PLUMED using the command:
> ./configure CXX="$MPICXX"
If the CXX environmental variable is not set equal to an MPI compiler then MPI is not enabled. This behaviour differs
from what some other configure scripts do. To be clear, when PLUMED is complied variables such as MPICXX are completely ignored.
PLUMED does search for MPI and non-MPI compilers with common names even if the CXX environmental variable is not set.
The search is only a few of the possible compiler names, however. If your compiler is named "g++-mp-4.8" you will need to explicitly specify this
by using the CXX environmental variable.
PLUMED 2.4 requires a compiler that supports C++11. The following compilers (or later versions) should be sufficient:
- gcc 4.8.1
- clang 3.3
- intel 15
The ./configure script will check whether or not your compiler supports C++11.
Some compilers that do not declare full C++11 support have several C++11 features enabled and can thus be used
to compile PLUMED (this is the case for the intel 15 compiler for instance).
If you see a warning about C++11 support during ./configure it is then important to check that
PLUMED compiles correctly. The best way to do this to to execute the regtests using the command make regtest.
We regularly test a number of compilers on GitHub Actions. These compilers should thus always compile PLUMED correctly.
--standalone-executable option
The PLUMED executable which relies on the resource files present in the compilation directory.
During installation these files are copied to $(prefix)/lib/plumed and the compilation directory can therefore be deleted.
If you do not install PLUMED, however, you need to ensure that none of the files in src/lib/plumed are not
moved or renamed.
The path to the PLUMED root directory is hard coded in the plumed executable as can be verified by using the command:
> plumed info --root
If you try to run a non-installed plumed executable and if the src/lib/plumed
directory is not in place PLUMED will throw an error as shown below:
> plumed help ERROR: I cannot find /xxx/yyy/patches directory
You can force plumed to ignore this error and to run anyway by using the option --standalone-executable as shown below
> plumed --standalone-executable help
Many features are not be available if you run in this way. This is currently the only way to use the PLUMED static executable on Windows, however.
--enable-rpath option
On OSX it is common practice to hard code the full path to all the libraries that were used during the compilation within the compiled library.
The consequence of this is that, if an executable is linked to shared library, then that executable can find all the libraries which are required to run the
functions within the linked library. The operating system knows where to search for the libraries that were used when the linked libraries was compiled as the
path to these libraries is stored within the linked library. When the libplumed.dylib library is compiled on a system running OSX there is thus no
problem in finding external blas or lapack libraries at later times.
On Linux it is not common practice to hard code paths into libraries in the manner described above. Consequently, if you use the
LDFLAGS option to specify the path to a library at compile time. In other words, if you configure PLUMED using the command:
> ./configure LDFLAGS="-L/opt/local/lib"
Then the libraries in /opt/local/lib may not be found at runtime. One visible symptom of this problem is that src/lib/plumed-shared will
not be linked correctly. The consequence of this is that it is not possible to dynamically link PLUMED with an MD code later, which is only a problem if you
would like to link PLUMED dynamically.
You can resolve this issue by using the command below when configuring PLUMED:
> ./configure LIBRARY_PATH=/path --enable-rpath
This command will hard code the paths defined in LIBRARY_PATH into the PLUMED library and is equivalent to the command:
> ./configure LDFLAGS="-L/path -Wl,-rpath,/path"
STATIC_LIBS Environment Variable
By adding libararies to the STATIC_LIBS environmental variable you ensure that they are used in all linking steps. Those libraries that are speicified in the LIBS
environmental variable are only used when the PLUMED kernel library is linked.
CC Environment Variable
The CC environmental variable controls the c compiler that is used in the building of PLUMED. The majority of PLUMED is built using the c++ compiler that is
specified using the CXX environmental variable. A C compiler must still be specified nonetheless as the wrapper that is used to interface PLUMED with the MD codes is
written in C.
PLUMED does seach for MPI and non-MPI compilers with a number of standard names even if the CC environmental variable is not set.
Only a few of the possible compiler name are searched, however. If your compiler is named "gcc-mp-4.8" you will need to explicitly specify this
by using the CC environmental variable.
CPPFLAGS Environment Variable
The main purpose of the configure script is to locate all the libraries that are required to build PLUMED. PLUMED will by default check for these libraries in
certain standard places. If the libraries are not in these standard places, however, then you will need to provide information the configure script on where to find them by using the
LDFLAGS, CPPFLAGS and LIBS flags. If suitable libraries are not found during the execution of the configure script then these
features will be disabled. You should thus carefully check the log that is output by the configure command to ensure that all the libraries you require have been found.
The CPPFLAGS variable tells the configure script the names of directories in which the include files for the libraries can be found. If the xdrfile libraries are
in /opt/local (i.e. where MacPorts puts them) then you would use the command below to tell PLUMED where to find them.
> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include
--enable-molfile-plugins option
The --enable-molfile-plugins flag ensures that PLUMED is linked with VMD plugins. If PLUMED is configured with this flag you will thus be able to
read all the trajectory formats that VMD can read with plumed driver.
To be clear the PLUMED source code contains VMD plugins for a small number of trajectory formats (dcd, gromacs files, pdb and amber files) so you will most likely not need this flag.
You will only need it you would like to be able to read in some a particularly exotic trajectory file type. If you do need to work with these other types of file can get the molfile plugins by
downloading the SOURCE of VMD. This sourcecode contains
a plugins directory. You will need to adapt the build.sh script within this directory and then compile the code within the directory. Once this process is completed
you should get the molfile plugins compiled as a static library called libmolfile_plugin.a. The location of this library, the libmolfile_plugin.h and
the molfile_plugin.h include files will then need to be passed to configure using a command similar to:
> ./configure LDFLAGS="-L/pathtovmdplugins/ARCH/molfile" CPPFLAGS="-I/pathtovmdplugins/include -I/pathtovmdplugins/ARCH/molfile"
It may also be necessary to add the location of the TCL interpreter to the LDFLAGS using a command such as:
> ./configure LDFLAGS="-ltcl8.5 -L/mypathtotcl -L/pathtovmdplugins/ARCH/molfile" \
CPPFLAGS="-I/pathtovmdplugins/include -I/pathtovmdplugins/ARCH/molfile"
To be clear, however, some of the molfile plugin sourcecode is included in PLUMED and you can thus use some of the most common types of trajectory file even if you do not download VMD on your machine.
LIBS Environment Variable
The main purpose of the configure script is to locate all the libraries that are required to build PLUMED. PLUMED will by default check for these libraries in
certain standard places. If the libraries are not in these standard places, however, then you will need to provide information the configure script on where to find them by using the
LDFLAGS, CPPFLAGS and LIBS flags. If suitable libraries are not found during the execution of the configure script then these
features will be disabled. You should thus carefully check the log that is output by the configure command to ensure that all the libraries you require have been found.
You are required to set the LIBS environmental variable if your libraries have non-standard names. If, for example, your xdrfile library is
called /opt/local/lib/libmyxdrfile.so you can link it using:
> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include LIBS=-lmyxdrfile
This command works because PLUMED first tries to link a routine from the xdr library without adding any additional flag. If and only if this command fails the additional flag,
"-lxdrfile" is added to the LIBS envrionmental variable. Consequently, if the user has specified the name of the xdr library using the LIBS environmental
flag this custom version will be used in place of the standardly-named "-lxdrfile" library.
If, for any reason, you would like more control over the libraries that are used to build PLUMED you can use the --disable-libsearch option.
--prefix option
The --prefix environmental variable controls the location in which PLUMED is installed when the make install command is run. By default
PLUMED is installed in /usr/local/ and you will thus have to run make install with super-user permissions i.e. using sudo make install.
You can, however, specify the location in which to install PLUMED by using the --prefix environmental variable. For example, to install PLUMED in $(HOME)/opt
you would configure using:
> ./configure --prefix=$HOME/opt
Upon install, the executable would then be copied to $(HOME)/opt/bin, the libraries to $(HOME)/opt/lib, the include files to $(HOME)/opt/include, and the
documentation to $(HOME)/opt/shared/doc/plumed. In addition, a directory called $(HOME)/opt/lib/plumed will be created containing files such as the
patch files and the object files (for static patches). Advanced users can further customise the install directories using
using standard autoconf directories (e.g. ./configure --bindir=/usr/bin64). Further information on these options can be obtained by running the command:
> ./configure --help
--enable-modules option
PLUMED is made up of modules. Some of these are used more frequently than others and so the ones that we believe that are used
less often are disabled in a default compilation. If you configure using the option --enable-modules=all then PLUMED will compile
all these modules. This option would be recommended if you are compiling the code for multiple users and if you are not sure of those
users need.
If, however, you are compiling the code for yourself only then it may be better to only compile those modules you specifically need.
If you would like to compile with the core modules and the dimred and ves modules you could use the command --enable-modules=dimred:ves.
PYTHON_BIN Environment Variable
The PYTHON_BIN environment variable tells configure which version of python should be used to construct the PLUMED wrappers. Oftetimes this flag is unecessary
as configure will find any python executable that also has the cython module available automatically. If your python interpreter has a name
that is different from python you will have to set this environment variable.