Merge pull request #34 from lammps/master

src/USER-MOFFF/*      @hheenen

src/USER-MOLFILE/*    @akohlmey

src/USER-NETCDF/*     @pastewka

src/USER-PLUMED/*     @gtribello

src/USER-PHONON/*     @lingtikong

src/USER-PTM/*        @pmla

src/USER-OMP/*        @akohlmey

find_package(OpenMP QUIET)

option(BUILD_OMP "Build with OpenMP support" ${OpenMP_FOUND})

if(BUILD_OMP OR PKG_USER-OMP OR PKG_KOKKOS OR PKG_USER-INTEL)

if(BUILD_OMP OR PKG_KOKKOS OR PKG_USER-INTEL)

  find_package(OpenMP REQUIRED)

  set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${OpenMP_C_FLAGS}")

  set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${OpenMP_CXX_FLAGS}")

  endif()

endif()

if(PKG_MSCG OR PKG_USER-ATC OR PKG_USER-AWPMD OR PKG_USER-QUIP OR PKG_LATTE)

if(PKG_MSCG OR PKG_USER-ATC OR PKG_USER-AWPMD OR PKG_USER-QUIP OR PKG_LATTE OR PKG_USER-PLUMED)

  find_package(LAPACK)

  find_package(BLAS)

  if(NOT LAPACK_FOUND OR NOT BLAS_FOUND)

if(PKG_USER-PLUMED)

  find_package(GSL REQUIRED)

  set(PLUMED_MODE "static" CACHE STRING "Linkage mode for Plumed2 library")

  set(PLUMED_MODE_VALUES static shared runtime)

  set_property(CACHE PLUMED_MODE PROPERTY STRINGS ${PLUMED_MODE_VALUES})

  validate_option(PLUMED_MODE PLUMED_MODE_VALUES)

  string(TOUPPER ${PLUMED_MODE} PLUMED_MODE)

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

  if(DOWNLOAD_PLUMED)

    include(ExternalProject)

    ExternalProject_get_property(plumed_build INSTALL_DIR)

    set(PLUMED_INSTALL_DIR ${INSTALL_DIR})

    list(APPEND LAMMPS_DEPS plumed_build)

    if(PLUMED_MODE STREQUAL "STATIC")

      add_definitions(-D__PLUMED_WRAPPER_CXX=1)

      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})

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

    elseif(PLUMED_MODE STREQUAL "SHARED")

      list(APPEND LAMMPS_LINK_LIBS ${PLUMED_INSTALL_DIR}/lib/libplumed.so ${CMAKE_DL_LIBS})

    elseif(PLUMED_MODE STREQUAL "RUNTIME")

      add_definitions(-D__PLUMED_HAS_DLOPEN=1 -D__PLUMED_DEFAULT_KERNEL=${PLUMED_INSTALL_DIR}/lib/libplumedKernel.so)

      list(APPEND LAMMPS_LINK_LIBS ${PLUMED_INSTALL_DIR}/lib/libplumedWrapper.a -rdynamic ${CMAKE_DL_LIBS})

    endif()

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

  else()

    find_package(PkgConfig REQUIRED)

    pkg_check_modules(PLUMED plumed REQUIRED)

    if(PLUMED_MODE STREQUAL "STATIC")

      add_definitions(-D__PLUMED_WRAPPER_CXX=1)

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

    elseif(PLUMED_MODE STREQUAL "SHARED")

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

    elseif(PLUMED_MODE STREQUAL "RUNTIME")

      add_definitions(-D__PLUMED_HAS_DLOPEN=1 -D__PLUMED_DEFAULT_KERNEL=${PLUMED_LIBDIR}/libplumedKernel.so)

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

    endif()

    list(APPEND LAMMPS_LINK_LIBS ${PLUMED_LOAD})

  endif()

  include_directories(${PLUMED_INCLUDE_DIRS})

    if(PKG_LIB STREQUAL awpmd)

      target_include_directories(awpmd PUBLIC ${LAMMPS_LIB_SOURCE_DIR}/awpmd/systems/interact ${LAMMPS_LIB_SOURCE_DIR}/awpmd/ivutils/include)

    elseif(PKG_LIB STREQUAL h5md)

      target_include_directories(h5md PUBLIC ${LAMMPS_LIB_SOURCE_DIR}/h5md/include)

      target_include_directories(h5md PUBLIC ${LAMMPS_LIB_SOURCE_DIR}/h5md/include ${HDF5_INCLUDE_DIRS})

    elseif(PKG_LIB STREQUAL colvars)

      target_compile_options(colvars PRIVATE -DLEPTON)

      target_include_directories(colvars PRIVATE ${LAMMPS_LIB_SOURCE_DIR}/colvars/lepton/include)

  find_package(HDF5 REQUIRED)

  target_link_libraries(h5md ${HDF5_LIBRARIES})

  target_include_directories(h5md PRIVATE ${HDF5_INCLUDE_DIRS})

  include_directories(${HDF5_INCLUDE_DIRS})

endif()

  </dl>

  </td>

</tr>

<tr>

  <td><code>BIN2C</code> (CUDA only)</td>

  <td>Path to bin2c executable, will automatically pick up the first one in your $PATH.</td>

  <td>(automatic)</td>

</tr>

</tbody>

</table>

</tr>

<tr>

  <td><code>GZIP_EXECUTABLE</code></td>

  <td></td>

  <td>

  </td>

  <td>Path to gzip executable, will automatically pick up the first one in your $PATH.</td>

  <td>(automatic)</td>

</tr>

</tbody>

</table>

</tr>

<tr>

  <td><code>FFMPEG_EXECUTABLE</code></td>

  <td></td>

  <td>

  </td>

  <td>Path to ffmpeg executable, will automatically pick up the first one in your $PATH.</td>

  <td>(automatic)</td>

</tr>

</tbody>

</table>

# Outline of the GitHub Development Workflow

This purpose of this document is to provide a point of reference for the

core LAMMPS developers and other LAMMPS contributors to understand the

choices the LAMMPS developers have agreed on. Git and GitHub provide the

tools, but do not set policies, so it is up to the developers to come to

an agreement as to how to define and interpret policies. This document

is likely to change as our experiences and needs change and we try to

adapt accordingly. Last change 2018-11-15.

## Table of Contents

  * [GitHub Merge Management](#github-merge-management)

  * [Pull Requests](#pull-requests)

    * [Pull Request Assignments](#pull-request-assignments)

    * [Pull Request Reviews](#pull-request-reviews)

    * [Pull Request Discussions](#pull-request-discussions)

    * [Checklist for Pull Requests](#checklist-for-pull-requests)

  * [GitHub Issues](#github-issues)

  * [Milestones and Release Planning](#milestones-and-release-planning)

## GitHub Merge Management

In the interest of consistency, ONLY ONE of the core LAMMPS developers

should doing the merging itself.  This is currently

[@akohlmey](https://github.com/akohlmey) (Axel Kohlmeyer).

If this assignment needs to be changed, it shall be done right after a

stable release.  If the currently assigned developer cannot merge outstanding pull 

requests in a timely manner, or in other extenuating circumstances, 

other core LAMMPS developers with merge rights can merge pull requests,

when necessary. 

## Pull Requests

ALL changes to the LAMMPS code and documentation, however trivial, MUST

be submitted as a pull request to GitHub. All changes to the "master"

branch must be made exclusively through merging pull requests. The

"unstable" and "stable" branches, respectively are only to be updated

upon patch or stable releases with fast-forward merges based on the

associated tags. Pull requests may also be submitted to (long-running)

feature branches created by LAMMPS developers inside the LAMMPS project,

if needed. Those are not subject to the merge and review restrictions

discussed in this document, though, but get managed as needed on a

case-by-case basis.

### Pull Request Assignments

Pull requests can be "chaperoned" by one of the LAMMPS core developers.

This is indicated by who the pull request is assigned to. LAMMPS core

developers can self-assign or they can decide to assign a pull request

to a different LAMMPS developer. Being assigned to a pull request means,

that this pull request may need some work and the assignee is tasked to

determine what this might be needed or not, and may either implement the

required changes or ask the submitter of the pull request to implement

them.  Even though, all LAMMPS developers may have write access to pull

requests (if enabled by the submitter, which is the default), only the

submitter or the assignee of a pull request may do so.  During this

period the "work_in_progress" label shall be applied to the pull

request.  The assignee gets to decide what happens to the pull request

next, e.g. whether it should be assigned to a different developer for

additional checks and changes, or is recommended to be merged.  Removing

the "work_in_progress" label and assigning the pull request to the

developer tasked with merging signals that a pull request is ready to be

merged.

### Pull Request Reviews

People can be assigned to review a pull request in two ways:

  * They can be assigned manually to review a pull request

    by the submitter or a LAMMPS developer

  * They can be automatically assigned, because a developers matches

    a file pattern in the `.github/CODEOWNERS` file, which associates

    developers with the code they contributed and maintain.

Reviewers are requested to state their appraisal of the proposed changes

and either approve or request changes. People may unassign themselves

from review, if they feel not competent about the changes proposed. At

least one review from a LAMMPS developer with write access is required

before merging in addition to the automated compilation tests.  The

feature, that reviews from code owners are "hard" reviews (i.e. they

must all be approved before merging is allowed), is currently disabled

and it is in the discretion of the merge maintainer to assess when

a sufficient degree of approval has been reached.  Reviews may be

(automatically) dismissed, when the reviewed code has been changed,

and then approval is required a second time.

### Pull Request Discussions

All discussions about a pull request should be kept as much as possible

on the pull request discussion page on GitHub, so that other developers

can later review the entire discussion after the fact and understand the

rationale behind choices made.  Exceptions to this policy are technical

discussions, that are centered on tools or policies themselves

(git, github, c++) rather than on the content of the pull request.

### Checklist for Pull Requests

Here are some items to check:

  * source and text files should not have CR/LF line endings (use dos2unix to remove)

  * every new command or style should have documentation. The names of

  source files (c++ and manual) should follow the name of the style.

  (example: `src/fix_nve.cpp`, `src/fix_nve.h` for `fix nve` command,

  implementing the class `FixNVE`, documented in `doc/src/fix_nve.txt`)

  * all new style names should be lower case, the must be no dashes,

  blanks, or underscores separating words, only forward slashes.

  * new style docs should be added to the "overview" files in

  `doc/src/Commands_*.txt`, `doc/src/{fixes,computes,pairs,bonds,...}.txt`

  and `doc/src/lammps.book`

  * new files in packages should be added to `src/.gitignore`

  * removed or renamed files in packages should be added to `src/Purge.list`

  * C++ source files should use C++ style include files for accessing

  C-library APIs, e.g. `#include <cstdlib>` instead of `#include <stdlib.h>`.

  And they should use angular brackets instead of double quotes. Full list:

    * assert.h -> cassert

    * ctype.h -> cctype

    * errno.h -> cerrno

    * float.h -> cfloat

    * limits.h -> climits

    * math.h -> cmath

    * omplex.h -> complex

    * setjmp.h -> csetjmp

    * signal.h -> csignal

    * stddef.h -> cstddef

    * stdint.h -> cstdint

    * stdio.h -> cstdio

    * stdlib.h -> cstdlib

    * string.h -> cstring

    * time.h -> ctime

  Do not replace (as they are C++-11): `inttypes.h` and `stdint.h`.

  * Code should follow the C++-98 standard. C++-11 is only accepted

  in individual special purpose packages

  * indentation is two spaces per level

  * there should be no tabs and no trailing whitespace

  * header files, especially of new styles, should not include any

  other headers, except the header with the base class or cstdio.

  Forward declarations should be used instead when possible.

  * iostreams should be avoided. LAMMPS uses stdio from the C-library.

  * use of STL in headers and class definitions should be avoided.

  * static class members should be avoided at all cost.

  * anything storing atom IDs should be using `tagint` and not `int`.

  This can be flagged by the compiler only for pointers and only when

  compiling LAMMPS with `-DLAMMPS_BIGBIG`.

  * when including both `lmptype.h` (and using defines or macros from it)

  and `mpi.h`, `lmptype.h` must be included first.

## GitHub Issues

The GitHub issue tracker is the location where the LAMMPS developers

and other contributors or LAMMPS users can report issues or bugs with

the LAMMPS code or request new features to be added. Feature requests

are usually indicated by a `[Feature Request]` marker in the subject.

Issues are assigned to a person, if this person is working on this

feature or working to resolve an issue. Issues that have nobody working

on them at the moment, have the label `volunteer needed` attached.

When an issue, say `#125` is resolved by a specific pull request,

the comment for the pull request shall contain the text `closes #125`

or `fixes #125`, so that the issue is automatically deleted when

the pull request is merged.

## Milestones and Release Planning

LAMMPS uses a continuous release development model with incremental

changes, i.e. significant effort is made - including automated pre-merge

testing - that the code in the branch "master" does not get broken.

More extensive testing (including regression testing) is performed after

code is merged to the "master" branch. There are patch releases of

LAMMPS every 1-3 weeks at a point, when the LAMMPS developers feel, that

a sufficient amount of changes have happened, and the post-merge testing

has been successful. These patch releases are marked with a

`patch_<version date>` tag and the "unstable" branch follows only these

versions (and thus is always supposed to be of production quality,

unlike "master", which may be temporary broken, in the case of larger

change sets or unexpected incompatibilities or side effects.

About 3-4 times each year, there are going to be "stable" releases

of LAMMPS.  These have seen additional, manual testing and review of

results from testing with instrumented code and static code analysis.

Also, in the last 2-3 patch releases before a stable release are

"release candidate" versions which only contain bugfixes and

documentation updates.  For release planning and the information of

code contributors, issues and pull requests being actively worked on

are assigned a "milestone", which corresponds to the next stable

release or the stable release after that, with a tentative release

date.

"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,

"USER-NETCDF"_#user-netcdf,

"USER-PLUMED"_#user-plumed,

"USER-OMP"_#user-omp,

"USER-QMMM"_#user-qmmm,

"USER-QUIP"_#user-quip,

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

Before building LAMMPS with this package, you must first build PLUMED.

PLUMED can be built as part of the LAMMPS build or installed separately

from LAMMPS using the generic "plumed installation instructions"_plumedinstall.

:link(plumedinstall,http://plumed.github.io/doc-master/user-doc/html/_installation.html)

PLUMED can be linked into MD codes in three different modes: static,

shared, and runtime.  With the "static" mode, all required PLUMED code

is linked statically into the MD code. The MD code is then fully

independent from the PLUMED installation, but also you have to

rebuild/relink the MD code to update the PLUMED code inside it.  With

"shared" linkage mode, the MD code is linked to a shared library

containing the PLUMED code, preferably after it was installed in a

globally accessible location. This way the same installed PLUMED code

can be shared across multiple MD packages and can be updated, for as

long as the shared PLUMED library is ABI-compatible. The third linkage

mode is "runtime" which allows to switch the PLUMED kernel at runtime

between different variants through setting the PLUMED_KERNEL environment

varible, which has to point to the location of the libplumedKernel.so

dynamical shared object, which is then loaded at runtime. This is

particularly convenient for doing PLUMED development and comparing

multiple PLUMED versions without having to recompile the hosting MD

code. All three linkage modes are supported by LAMMPS on selected

operating systems (e.g. Linux) and using either CMake or traditional

make build. The "static" mode should be most portable, the "runtime"

mode support in LAMMPS makes the most assumptions about operating

system and compiler environment. If one mode does not work, try a

different one, or switch to a different build system, or consider

a global PLUMED installation or downloading it during building LAMMPS.

[CMake build]:

[Traditional make]:

-D DOWNLOAD_PLUMED=value   # download PLUMED for build, value = no (default) or yes

-D PLUMED_MODE=value       # Linkage mode for PLUMED, value = static (default), shared, or runtime :pre

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:

If DOWNLOAD_PLUMED is set to "yes", the PLUMED library will be

downloaded (the version of that is hardcoded to a vetted version of

PLUMED, usually a recent stable release version) and built inside the

CMake build directory.  If DOWNLOAD_PLUMED is set to "no" (the default),

CMake will try to detect an installed version of PLUMED and link to

that. For this to work, the PLUMED library has to be installed into a

location where the pkg-config tool can find it or the PKG_CONFIG_PATH

environment variable has to be set up accordingly.

make yes-user-plumed 

make machine :pre

The PLUMED_MODE setting determines the linkage mode of the PLUMED

library.  Allowed values are "static" (default), "shared", or "runtime".

For a discussion of PLUMED linkage modes, please see above.  When

enabling DOWNLOAD_PLUMED, the static linkage mode is recommended.

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:

[Traditional make]:

Before installing the USER-PLUMED package, first the PLUMED library

needs to be configured so that LAMMPS can find the right settings when

compiling and linking the LAMMPS executable itself. You can either

download and build PLUMED inside the LAMMPS plumed library folder or use

a previously installed PLUMED library and point LAMMPS to its

location. You also have to choose the linkage mode: "static" (default),

"shared" or "runtime".  For a discussion of PLUMED linkage modes, please

see above.

Download/compilation/configuration of the plumed library can be done

from the src folder through the following make args:

make lib-plumed                         # print help message

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

make lib-plumed args="-b"               # download and build PLUMED in lib/plumed/plumed2

make lib-plumed args="-p $HOME/.local"  # use existing PLUMED installation in $HOME/.local

make lib-plumed args="-p /usr/local -m shared"  # use existing PLUMED installation in

                                                # /usr/local and use shared linkage mode

:pre

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:

Note that 2 symbolic (soft) links, "includelink" and "liblink" are

created in lib/plumed to point into the location of the PLUMED build to

use and also a new file lib/plumed/Makefile.lammps is created with

settings suitable for LAMMPS to compile and link PLUMED in the desired

linkage mode. After this step is compleded, you can install the

USER-PLUMED package and compile LAMMPS in the usual manner:

make yes-user-plumed 

make machine :pre

make no-user-plumed

make machine :pre

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

usual way.  For shared linkage mode, libplumed.so must be found by the

LAMMPS executable, which on many operating systems means, you have to

set the LD_LIBRARY_PATH environment variable accordingly.

Support for the different linkage modes in LAMMPS varies for different

operating systems, using the static linkage is expected to be the most

portable, and thus set to be the default.

If you want to change the linkage mode, you have to re-run "make

lib-plumed" with the desired settings [and] do a reinstall if the

USER-PLUMED package with "make yes-user-plumed" to update the required

makefile settings with the changes in the lib/plumed folder.

:line