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.

:doc:`/plugin/README` contains the list of features available. Some features include but are not limited to the following:

Simulation techniques

• Wang-Landau Monte Carlo
• Transition-matrix Monte Carlo
• Metropolis Monte Carlo
• Mayer-sampling Monte Carlo
• Configurational bias

Thermodynamic ensembles

• Microcanonical ensemble
• Canonical ensemble
• Grand canonical ensemble

Intermolecular interactions

• Hard spheres
• Lennard-Jones with Yukawa, LRC, force shift
• Patchy particles
• Charged interactions with the Ewald summation
• Cylindrical and slit pore confinement

Modern software

• Interface with C++ or as a Python module
• OpenMP parallelization
• Checkpointing to save and restart simulations

The following example Lennard-Jones Monte Carlo simulation may be found in Tutorial.

.. literalinclude:: tutorial/tutorial.py
   :language: py

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

• 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
cmake -DUSE_SWIG=ON ..
make _feasst -j4
make install -j4
python ../py/test.py  # optional test
pip install jupyter matplotlib pandas scipy # for tutorials

• 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 ..

First, install the C++ library.

git clone https://github.com/usnistgov/feasst.git
mkdir feasst/build
cd feasst/build
cmake ..
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 ..

• 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

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

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

• Update to CMake 3 (https://cmake.org/download/)
• sudo apt install swig

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

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"