Overview

The Free Energy and Advanced Sampling Simulation Toolkit (FEASST) is a free and open-source software to conduct molecular- and particle-based simulations with Monte Carlo methods. New users can start with the website (DOI), manuscript, GitHub discussion and a five minute video. Support FEASST with a GitHub star or manuscript citation!

Features

_images/feasst.png

The features available in the Text Interface are summarized as follows:

Monte Carlo simulation techniques

  • Metropolis

  • Wang-Landau

  • Transition-matrix

  • Mayer-sampling

Thermodynamic ensembles

  • Microcanonical ensemble

  • Canonical ensemble

  • Grand-canonical ensemble

  • Temperature and growth expanded ensembles

  • Gibbs ensemble

Interaction potentials

  • Lennard-Jones and Mie with cut/force shift and corrections

  • Hard spheres and square wells

  • Patchy and anisotropic particles

  • Yukawa and charged interactions

  • Ewald summation and 2D slab correction

  • Bonds, angles and dihedrals

  • TraPPE small molecules and n-alkanes

  • Slab, cylindrical and spherical confinement

  • Cell list and neighbor list

Monte Carlo trials

  • Translation, rotation, crankshaft and pivot

  • Rigid cluster rotation and translation

  • Configurational bias transfers and partial regrowth

  • Dual-cut configurational bias

  • Aggregation volume bias

  • Reptation

  • Branches

Modern software

  • Interface as text input, C++ or Python module

  • Server interface to C++ or Python clients

  • OpenMP parallelization and prefetching

  • Checkpoint files to save, restart and analyze simulations

How to compile

FEASST requires C++14 and CMake, and is compiled with the following BASH commands:

# [apt/yum/dnf/brew] install g++ cmake curl tar. On HPC, try "module avail/load"
cd $HOME # replace this with your preference throughout
curl -OL https://github.com/usnistgov/feasst/archive/refs/tags/v0.25.10.tar.gz # download
tar -xf v0.25.10.tar.gz           # uncompress
mkdir feasst-0.25.10/build; cd $_ # out-of-source build
cmake ..                         # find prerequisites
make install -j 4                # compile on 4 threads
# Optional Python packages used in tutorials. Virtual environment recommended:
# https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments
pip install jupyter matplotlib pandas scipy ../pyfeasst # ../ ensures pyfeasst matches feasst
# Because online documentation changes with verison, open local version documentation.
xdg-open ../html/index.html      # on macOS, replace "xdg-open" with "open"

How to run a simulation

Input a text file to the compiled executable.

$HOME/feasst-0.25.10/build/bin/fst < $HOME/feasst-0.25.10/tutorial/example.txt

The following text input file is explained in detail in the first tutorial.

# Comments begin with the # symbol.
# Usage: ./fst < example.txt
MonteCarlo
RandomMT19937 seed 1572362164
Configuration cubic_side_length 55.0321208149104 particle_type0 /feasst/particle/lj.fstprt
Potential Model LennardJones VisitModel VisitModelCell
Potential VisitModel LongRangeCorrections
ThermoParams beta 1.111111111111111 chemical_potential0 -1
Metropolis
TrialTranslate weight 1 tunable_param 2
Tune
CheckEnergy trials_per_update 1e4 decimal_places 8
TrialAdd weight 2 particle_type 0
Run until_num_particles 500
Remove name TrialAdd
Run num_trials 1e5
Remove name Tune
Log    trials_per_write 1e4 output_file lj.csv
Energy trials_per_write 1e4 output_file lj_en.csv
Movie  trials_per_write 1e4 output_file lj.xyz
Metropolis trials_per_cycle 1e4 cycles_to_complete 1e2
Run until complete

How to learn more

Troubleshooting install

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

Ubuntu 18, 20, 22, 24 and Rocky 8 and 9

  • We are not aware of any install issues with these OS.

Ubuntu 16

CentOS 7

CMake version is usually too old. Try the command cmake3 instead of cmake.

Cray (NERSC CORI)

  • OpenMP functions may not work unless the cray programming environment is disabled.

macOS Mojave

  • for omp, try brew install libomp

Windows 10

  • Install Windows subsystem for Linux (Ubuntu 16)

  • See Ubuntu 16

Contact

Project lead

Harold Wickes Hatch

https://www.nist.gov/people/harold-wickes-hatch

Messages about FEASST are preferred in GitHub discussion, GitHub issues or Google group, if possible, so that all users can see the questions and answers. The following email is also an option: harold.hatch@nist.gov.

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 a minimal example to reduce the complexity, run time and file size.

  • Provide all output.

  • Provide the version (for a git install, bash command “git describe –abbrev=10 –dirty –always –tags” and commit from git log).

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

  • For installation errors, include the output of the “cmake ..” command on an empty build directory.

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.