FEASST: Free Energy and Advanced Sampling Simulation Toolkit

README

https://travis-ci.com/hhatch/feasst.svg?branch=main https://codecov.io/gh/hhatch/feasst/branch/main/graph/badge.svg CodeFactor

The Free Energy and Advanced Sampling Simulation Toolkit (FEASST) is a free, open-source, modular program to conduct molecular and particle-based simulations with flat-histogram Monte Carlo methods.

Features

_images/feasst.png

Plugins contains the list of features available. Some features include but are not limited to the following:

Simulation techniques

  • Metropolis Monte Carlo

  • Wang-Landau Monte Carlo

  • Transition-matrix Monte Carlo

  • Mayer-sampling Monte Carlo

  • Configurational bias

Thermodynamic ensembles

  • Microcanonical ensemble

  • Canonical ensemble

  • Grand canonical ensemble

  • Expanded ensembles

Intermolecular interactions

  • Hard spheres

  • Lennard-Jones with Yukawa, LRC, cut and force shift

  • Patchy particles

  • Charged interactions with the Ewald summation

  • Confinement

  • Cell list and neighbor list

Modern software

  • Interface with C++ or as a Python module

  • OpenMP parallelization

  • Checkpointing to save and restart simulations

Tutorial

Tutorial describes an example Lennard-Jones Monte Carlo simulation. After completing this basic tutorial, check out tutorials specific to each Plugins. For example, see the tutorials of System, MonteCarlo and FlatHistogram.

The search box for the html documentation was disabled for security reasons. But the html is generated entirely from the downloaded code. Thus, the grep command is a great option to search for more information on keywords. For example, if you would like more information on RandomMT19937 but are not sure where to find it, you could search headers files

grep -r --include=*.h RandomMT19937

And find that the class is part of the Math plugin.

Build from source code

To begin, [apt/yum/brew] install g++ cmake git.

Python install

  • SWIG is required. Version 3.0.12 is recommended if your current SWIG version does not work properly.

  • Anaconda with Python 3 is recommended.

  • CMake attempts to find the python libraries during compilation. But you may want to specify them manually.

git clone https://github.com/usnistgov/feasst.git
mkdir feasst/build
cd feasst/build

conda env create -f ../py/feasst.yml
conda activate feasst
# alternatively, without env create, include some tutorial dependencies
# pip install jupyter matplotlib pandas scipy # for tutorials

cmake -DUSE_SWIG=ON ..
# alternatively, for manually setting the python path
# cmake -DUSE_SWIG=ON -DSET_PYTHON_PATH=ON -DPYTHON_INCLUDE_DIR=/path/to/anaconda/include/python3.7m -DPYTHON_LIBRARY=/path/to/anaconda/lib/libpython3.7m.so ..

make -j4
make install -j4
python ../py/test.py # optional test

C++ install

First, install the C++ library.

git clone https://github.com/usnistgov/feasst.git
mkdir feasst/build
cd feasst/build
cmake ..          # optionally, include -DUSE_GTEST=ON for gtest
make install -j4
make test         # optional test

Then, compile the specific simulation you wish to run (e.g., tutorial).

cd /path/to/feasst/tutorial/
mkdir build; cd build
cmake ..
make
./tutorial

CMake defaults to install in the build directory. But you can also specify the path as follows.

cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/dir ..

Later, when you build your tutorial executable, if your build directory is not ~/feasst/build, then specify the path to the build directory as follows:

cmake -DCMAKE_PREFIX_PATH=/path/to/install/dir ..

Sometimes running the executable results in an error that a plugin cannot be found. In that case LD_LIBRARY_PATH needs to be set as follows:

export LD_LIBRARY_PATH="/path/to/feasst/build/:$LD_LIBRARY_PATH

Troubleshooting install

Please Contact us if you run into an issue not listed below.

macOS Mojave
  • SWIG (from Homebrew) is likely version 4, which sometimes causes a SEGFAULT when trying to run feasst. Try SWIG version 3 instead.

  • Sometimes CMake has trouble finding anaconda, and if you use SET_PYTHON_PATH described above, you may need to look out for the .dylib instead of .so

CentOS 7

CMake and SWIG versions are usually too old. Try the command cmake3 instead of cmake. Otherwise, install SWIG 3.

Windows 10
  • Install Windows subsystem for Linux (Ubuntu 16)

  • See Ubuntu 16

Ubuntu 16
Ubuntu 18 or 20
  • We are not aware of any issues with an Ubuntu 18 or 20 install.

Cray (NERSC CORI)
  • OpenMP functions apparently do not work unless the cray programming environment is disabled.

Build from Docker

The Docker is no longer being updated and contains a very old version of the code. Installation via Docker is an alternative if you are experiencing installation issues. Unfortunately there is a performance penalty using this method.

First, install docker

  • Ubuntu: apt install docker

  • macOS: download and install Docker Desktop.

  • CentOS: yum install docker

On a mac, run Docker.app, login, startup and skip this step. Otherwise, start docker and create a docker group to avoid root.

sudo service docker start
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker
git clone https://github.com/usnistgov/feasst.git
docker build -t hhatch/feasst:firsttry feasst/

Alternatively you could pull feasst from docker hub (version may be old):

docker pull hhatch/feasst:firsttry

Then you can interactively run feasst via

docker run -v ~/scripts:/mnt/scripts -it hhatch/feasst:firsttry
cd /mnt/scripts

Or with ~/notebooks

docker run -v ~/notebooks:/mnt/notebooks -i -t -p 8888:8888 hhatch/feasst:firsttry /bin/bash -c "jupyter notebook --notebook-dir=/mnt/notebooks --ip='*' --port=8888 --no-browser --allow-root"

Contact

Bug reporting

Any and all bug reports are greatly appreciated in order to improve FEASST.

The following checklist is recommended to improve reproducibility so that I can get back to you more quickly.

  • Reproduce the issue with minimal example to reduce the complexity, run time and file size.

  • Provide all output.

  • Provide the version (e.g. bash command “git describe –abbrev=10 –dirty –always –tags”).

  • Provide the user code (e.g., C++ with int main() or .py).

Disclaimer

Certain commercial firms and trade names are identified in this document in order to specify the installation and usage procedures adequately. Such identification is not intended to imply recommendation or endorsement by the National Institute of Standards and Technology, nor is it intended to imply that related products are necessarily the best available for the purpose.

License

This license was obtained from https://www.nist.gov/director/licensing (revised as of July 2017).

This data/software was developed by employees of the National Institute of Standards and Technology (NIST), an agency of the Federal Government. Pursuant to title 15 United States Code Section 105, works of NIST employees are not subject to copyright protection in the United States and are considered to be in the public domain.

The data/software is provided by NIST as a public service and is expressly provided “AS IS.” NIST MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND DATA ACCURACY. NIST does not warrant or make any representations regarding the use of the data/software or the results thereof, including but not limited to the correctness, accuracy, reliability or usefulness of the data/software. NIST SHALL NOT BE LIABLE AND YOU HEREBY RELEASE NIST FROM LIABILITY FOR ANY INDIRECT, CONSEQUENTIAL, SPECIAL, OR INCIDENTAL DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, AND THE LIKE), WHETHER ARISING IN TORT, CONTRACT, OR OTHERWISE, ARISING FROM OR RELATING TO THE DATA (OR THE USE OF OR INABILITY TO USE THIS DATA), EVEN IF NIST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

To the extent that NIST may hold copyright in countries other than the United States, you are hereby granted the non-exclusive irrevocable and unconditional right to print, publish, prepare derivative works and distribute the NIST data/software, in any medium, or authorize others to do so on your behalf, on a royalty-free basis throughout the World.

You may improve, modify, and create derivative works of the data/software or any portion of the data/software, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the data/software and should note the date and nature of any such change. Please explicitly acknowledge the National Institute of Standards and Technology as the source of the data/software.

Permission to use this data/software is contingent upon your acceptance of the terms of this agreement and upon your providing appropriate acknowledgments of NIST’s creation of the data/software.

Contents:

_images/feasst.png

Index