Merge pull request #1180 from gtribello/master

  USER-BOCS USER-CGDNA USER-MESO USER-CGSDK USER-COLVARS USER-DIFFRACTION

  USER-DPD USER-DRUDE USER-EFF USER-FEP USER-H5MD USER-LB USER-MANIFOLD

  USER-MEAMC USER-MGPT USER-MISC USER-MOFFF USER-MOLFILE USER-NETCDF

  USER-PHONON USER-PTM USER-QTB USER-REAXC USER-SCAFACOS USER-SMD USER-SMTBQ

  USER-SPH USER-TALLY USER-UEF USER-VTK USER-QUIP USER-QMMM)

  USER-PHONON USER-PLUMED USER-PTM USER-QTB USER-REAXC USER-SCAFACOS

  USER-SMD USER-SMTBQ USER-SPH USER-TALLY USER-UEF USER-VTK USER-QUIP

  USER-QMMM)

set(ACCEL_PACKAGES USER-OMP KOKKOS OPT USER-INTEL GPU)

set(OTHER_PACKAGES CORESHELL QEQ)

foreach(PKG ${DEFAULT_PACKAGES})

  include_directories(${SCAFACOS_INCLUDE_DIRS})

endif()

if(PKG_USER-PLUMED)

  find_package(GSL REQUIRED)

  option(DOWNLOAD_PLUMED "Download Plumed (instead of using the system's one)" OFF)

  if(DOWNLOAD_PLUMED)

    include(ExternalProject)

    ExternalProject_Add(plumed_build

      URL https://github.com/plumed/plumed2/releases/download/v2.4.3/plumed-src-2.4.3.tgz 

      URL_MD5 b1be7c48971627febc11c61b70767fc5

      BUILD_IN_SOURCE 1

      CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR> 

                                               $<$<BOOL:${BUILD_SHARED_LIBS}>:--with-pic>                                                  )

    ExternalProject_get_property(plumed_build INSTALL_DIR)

    set(PLUMED_INSTALL_DIR ${INSTALL_DIR})

    list(APPEND LAMMPS_DEPS plumed_build)

    list(APPEND LAMMPS_LINK_LIBS ${PLUMED_INSTALL_DIR}/lib/plumed/obj/kernel.o

      ${PLUMED_INSTALL_DIR}/lib/plumed/obj/PlumedStatic.o ${GSL_LIBRARIES} ${CMAKE_DL_LIBS})

    set(PLUMED_INCLUDE_DIRS "${PLUMED_INSTALL_DIR}/include")

  else()

    find_package(PkgConfig REQUIRED)

    pkg_check_modules(PLUMED plumed REQUIRED)

    include(${PLUMED_LIBDIR}/plumed/src/lib/Plumed.cmake.static)

    list(APPEND LAMMPS_LINK_LIBS ${PLUMED_LOAD})

  endif()

  include_directories(${PLUMED_INCLUDE_DIRS})

endif()

if(PKG_USER-MOLFILE)

  add_library(molfile INTERFACE)

  target_include_directories(molfile INTERFACE ${LAMMPS_LIB_SOURCE_DIR}/molfile)

"USER-ATC"_#user-atc,

"USER-AWPMD"_#user-awpmd,

"USER-COLVARS"_#user-colvars,

"USER-PLUMED" _#user-plumed,

"USER-H5MD"_#user-h5md,

"USER-INTEL"_#user-intel,

"USER-MOLFILE"_#user-molfile,

:line

USER-PLUMED package :h4,link(user-plumed)

[CMake build]:

[Traditional make]:

Before building LAMMPS with this package, you must first build 

PLUMED.  We recommending building PLUMED separately to LAMMPS using 

the instructions that can be found at http://plumed.github.io/doc-master/user-doc/html/_installation.html.

Before compiling LAMMPS you can then install the fix plumed command

and compile LAMMPS in the usual manner:

make yes-user-plumed 

make machine :pre

Once this compilation completes you should be able to run LAMMPS in the usual

way.  When running LAMMPS with an input script that contains a fix

plumed command LAMMPS will try to call the PLUMED runtime library.  PLUMED

must therefore be available in your path if LAMMPS is compiled in this way.

On some machines it is not possible to call runtime libraries in the way described

above.  When compiling on these machines it is thus better to statically link

PLUMED when compiling LAMMPS.  To do this you must either download a PLUMED

tarball from http://www.plumed.org/get-it or clone it using

git clone https://github.com/plumed/plumed2.git.  If you download the tarball

unpack it in the /lib/plumed directory.  Similarly if you clone 

it clone it to the /lib/plumed directory as if there is a version of PLUMED within

this directory LAMMPS will always try to statically link the version of PLUMED

that this directory contains instead of dynamically linking the library.

Once you have downloaded PLUMED into /lib/plumed you must again build the code

here by following the instructions that can be found at

http://plumed.github.io/doc-master/user-doc/html/_installation.html.

You can statically link PLUMED manually and if you want to access the full

range of PLUMED functionalities this is what you should do.  If you only want the

basic range of functionalities, however, (i.e. no user contributed modules) then

you can download and compile PLUMED in one step from the lammps/src dir, using a

command like like those below:

make lib-plumed                       # print help message

make lib-plumed  args="-b"            # download and build the latest stable version of PLUMED

These commands will simply invoke the lib/plumed/Install.py script with

args specified.  Furthermore, once the script has completed you should

have a compiled version of PLUMED.  With this built you can install/un-install

PLUMED and build LAMMPS in the usual manner:

make yes-user-plumed

make machine :pre

make no-user-plumed

make machine :pre

:line

USER-H5MD package :h4,link(user-h5md)

To build with this package you must have the HDF5 software package

:line

USER-PLUMED package :link(USER-PLUMED),h4

[Contents:]

The fix plumed command allows you to use the plugin for molecular

dynamics PLUMED to analyse and bias your LAMMPS trajectory on the fly.

In practise PLUMED is called from within the lammps input script by using

the "fix plumed _fix_plumed.html command.

[Authors:] The PLUMED library is written and maintained by

Massimilliano Bonomi, Giovanni Bussi, Carlo Camiloni and

Gareth Tribello. 

[Install:]

This package has "specific installation

instructions"_Build_extras.html#gpu on the "Build

extras"_Build_extras.html doc page.

[Supporting info:]

src/USER-PLUMED/README

lib/plumed/README

"fix plumed "_fix_plumed.html

examples/USER/plumed :ul

:line

USER-DIFFRACTION package :link(PKG-USER-DIFFRACTION),h4

[Contents:]

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Commands_all.html)

:line

fix plumed command :h3

[Syntax:]

fix ID group-ID plumed keyword value ... :pre

ID, group-ID are documented in "fix"_fix.html command :ulb,l

plumed = style name of this fix command :l

keyword = {plumedfile} or {outfile} :l

  {plumedfile} arg = name of PLUMED input file to use (default: NULL)

  {outfile} arg = name of file on which to write the PLUMED log (default: NULL) :pre

:ule

[Examples:]

fix pl all plumed all plumed plumedfile plumed.dat outfile p.log

[Description:]

This fix instructs LAMMPS to call the PLUMED library, which allows one

to perform various forms of trajectory analysis on the fly and to also

use methods such as umbrella sampling and metadynamics to enhance the

sampling of phase space.

The documentation included here only describes the fix plumed command.

This command is LAMMPS specific whereas most of the functionality

implemented in PLUMED will work with a range of MD codes and also when

PLUMED is used as a stand alone code.  The full documentation for PLUMED

is available at "this website"_http://www.plumed.org/documentation

The PLUMED library is developed at

"https://github.com/plumed/plumed2"_https://github.com/plumed/plumed2 A

detailed discussion of the code can be found in "(PLUMED)"_#PLUMED.

There are some example scripts for using this package with LAMMPS in the

examples/USER/plumed directory.

:line

The command to call PLUMED above is reasonably self explanatory.  Within

the input file for lammps the user is required to specify the input file

for PLUMED and a file on which to output the PLUMED log.  The user must

specify both of these arguments every time PLUMED is to be used.

Furthermore, the fix plumed command should appear in the LAMMPS input

file after the relevant input paramters (e.g. the timestep) have been

set.

The {group-ID} entry is ignored. LAMMPS will always pass all the atoms

to PLUMED and there can only be one instance of the plumed fix at a

time. The plumed fix communicates the minimum amount of information

required and the PLUMED supports multiple, completely independent

collective variables, multiple independent biases and multiple

independent forms of analysis.  There is thus really no restriction in

functionality by only allowing only one plumed fix in the LAMMPS input.

The {plumedfile} keyword allows the user to specify the name of the

PLUMED input file.  Instructions as to what should be included in a

plumed input file can be found in the "documentation for

PLUMED"_http://www.plumed.org/documentation.

The {outfile} keyword allows the user to specify the name of a file on

which to output the PLUMED log.  This log file normally just parots the

information that is contained in the input file.  The names of the files

on which the results from the various analyses that have been performed

using PLUMED will be specified by the user in the PLUMED input file.

[Restart, fix_modify, output, run start/stop, minimize info:]

When performing a restart of a calculation that involves PLUMED you must

include a RESTART command in the PLUMED input file as detailed in the

"PLUMED documentation"_http://www.plumed.org/documentation.  When the

restart command is found in the PLUMED input PLUMED will append to the

files that were generated in the run that was performed previously.

Furthermore, any history dependent bias potentials that were accumulated

in previous calculations will be read in when the restart command is

included in the PLUMED input.

The "fix_modify"_fix_modify.html {energy} option is not supported by

this fix.

Nothing is computed by this fix that can be accessed by any of the

"output commands"_Howto_output.html within LAMMPS.  All the quantities

of interest can be output by commands that are native to PLUMED,

however.

[Restrictions:]

This fix is part of the USER-PLUMED package.  It is only enabled if

LAMMPS was built with that package.  See the "Build

package"_Build_package.html doc page for more info.

There can only be one plumed fix active at a time. Since the interface

communicates only the minimum amount of information and since the PLUMED

module itself can handle an arbitrary number of analysis and biasing

methods, this is not a limitation of functionality.

[Related commands:]

"fix smd"_fix_smd.html

"fix colvars"_fix_colvars.html

[Default:]

The default options are plumedfile = NULL and outfile = NULL

:line

:link(PLUMED)

[(PLUMED)] G.A. Tribello, M. Bonomi, D. Branduardi, C. Camilloni and G. Bussi, Comp. Phys. Comm 185, 604 (2014)

   fix_phonon

   fix_pimd

   fix_planeforce

   fix_plumed

   fix_poems

   fix_pour

   fix_precession_spin