FEASST: Free Energy and Advanced Sampling Simulation Toolkit
README
The Free Energy and Advanced Sampling Simulation Toolkit (FEASST) is a free, open-source, public domain software to conduct molecular and particle-based simulations with Monte Carlo methods.
Note
Manuscript: https://doi.org/10.6028/jres.123.004
Website: https://pages.nist.gov/feasst/
Website DOI: https://doi.org/10.18434/M3S095
Code repository: https://github.com/usnistgov/feasst
Discussion list: https://groups.google.com/a/list.nist.gov/d/forum/feasst
Features

The List of all capabilities is 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
Monte Carlo trials
Translation, rotation, crankshaft, pivot
Rigid cluster rotation and translation
Configurational bias transfers and partial regrowth
Dual-cut configurational bias
Aggregation volume bias
Reptation
Branches
Interaction potentials
Hard spheres
Lennard-Jones with LRC, cut and force shift
Patchy 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
Modern software
Interface with C++ or as a Python module
OpenMP parallelization and prefetching
Checkpoint files to save, restart and analyze simulations
How to install (e.g., compile the executables).
[apt/yum/brew] install g++ cmake git python3
git clone https://github.com/usnistgov/feasst.git
mkdir feasst/build
cd feasst/build
cmake ..
make install -j4
# optional python packages for feasst tutorials
pip install ../pyfeasst jupyter matplotlib pandas scipy
The executables fst, which is used to start a simulation, and rst, which is used to restart a simulation, should now be located in /path/to/feasst/build/bin/.
Troubleshooting install
Please Contact us if you run into an issue not listed below.
CentOS 7
CMake version is usually too old. Try the command cmake3 instead of cmake.
Rocky 8
yum install gcc-c++
Ubuntu 16
Update to CMake 3 (https://cmake.org/download/)
Ubuntu 18, 20, 22
We are not aware of any install issues with these OS.
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
Documentation for a specific version of FEASST
You can access the documentation of a specific version of FEASST as follows.
git clone https://github.com/usnistgov/feasst.git
cd feasst
git checkout nist-pages
git log
# find the commit of your version from git log
# (e.g., 0.19.0 is a50b4fe943832f012373f23658a9497990d70d21)
git checkout a50b4fe943832f012373f23658a9497990d70d21
google-chrome index.html
Contact
Project lead
Harold Wickes Hatch
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., text file, C++ with int main() or .py file).
Optionally, the following information may also be useful:
the output of the “cmake ..” command on an empty build directory in order to see which compilers and libraries are used in the installation.
Email list
Github issue tracker
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:

- README
- Tutorials
- Lennard Jones in the canonical ensemble
- HPC/SLURM script with checkpointed restarts
- Lennard Jones potential test
- Reference configuration of SPC/E water in non-cuboid domain
- Average energy of a bulk SPC/E fluid in the canonical ensemble
- Lennard Jones Alpha potential test
- User defined tabular potentials
- Example TwoBodyAlpha potential: Feynman-Hibbs
- Make your own custom two body model
- Make your own custom analysis
- Make your own custom Action
- Ideal gas equation of state using grand canonical ensemble transition-matrix Monte Carlo
- Grand canonical ensemble transition-matrix Monte Carlo
- Analysis of a one-phase (supercritical) simulation
- Analysis of a two-phase (phase separated) simulation
- Grand Canonical Flat Histogram Simulation of Lennard-Jones
- Grand Canonical Flat Histogram Simulation of SPC/E
- Grand Canonical Flat Histogram Simulation of RPM
- Grand Canonical Flat Histogram Simulation of Hard Spheres.
- Grand Canonical Flat Histogram Simulation of Patchy Trimers
- Grand Canonical Flat Histogram Simulation of Kern-Frenkel Patches
- Grand Canonical Flat Histogram Simulation at low temperature
- Grand Canonical Flat Histogram Simulation of TraPPE alkanes
- Efficiency of 1 or 2 bin Grand Canonical Flat Histogram Simulations
- Slab, cylindrical, spherical and mixed confinement
- Simulation of a single freely-jointed chain
- Simulation of a single chain
- Simulation of a single 20-bead linear chain
- Scattering calculations for hard sphere coarse-grained mAb models
- Temperature extrapolation of the radius of gyration
- Monte Carlo with rigid cluster moves
- Compare scattering calculations for hard spheres
- Post process scattering calculations from file.
- Beta expanded ensemble
- Expanded Ensemble Grand Canonical Flat Histogram Simulation of RPM
- Second virial coefficient calculation of a Trimer using Mayer-Sampling
- Second virial coefficient calculation of TraPPE ethane using Mayer-Sampling
- Second virial coefficient calculation of a Kern-Frenkel patch using Mayer-Sampling
- Virial coefficients of all-atom mAb domains.
- Virial coefficients of 7-bead coarse-grained mAb model.
- Block average analysis for correlated data
- Prefetch example
- Test of an anisotropic, textured square well potential.
- Compare standard vs FFTW scattering calculations for hard spheres
- Semi-Grand Canonical Flat Histogram Simulation of a binary LJ mixture
- Semi-Grand Canonical Flat Histogram Simulation of CO2 and N2
- Compare XYZ (ascii) with netCDF
- Text file interface
- Python and C++ interface
- Particle files and units
- List of all capabilities
- List of plugins
- Threads
- Utilities
- Math
- math/include/utils_math
- math/include/constants
- math/include/quadratic_equation
- Minimize
- GoldenSearch
- Solver
- SolverBisection
- SolverBrentDekker
- SolverNewtonRaphson
- Formula
- FormulaPolynomial
- FormulaExponential
- Accumulator
- Position
- Matrix
- Euler
- Random
- RandomMT19937
- RandomModulo
- Table
- Histogram
- Tutorial
- FEASST plugin dependencies
- Configuration
- System
- FEASST plugin dependencies
- API
- SynchronizeData
- Model
- ThermoParams
- EnergyMap
- VisitModelInner
- BondTwoBody
- RigidBond
- BondSquareWell
- BondThreeBody
- AngleSquareWell
- RigidAngle
- BondFourBody
- RigidDihedral
- BondVisitor
- VisitModel
- ModelOneBody
- ModelEmpty
- DontVisitModel
- LongRangeCorrections
- ModelTwoBody
- IdealGas
- ModelTwoBodyFactory
- HardSphere
- ModelThreeBody
- ModelTwoBodyTable
- Cells
- VisitModelCell
- Potential
- PotentialFactory
- System
- VisitModelIntra
- VisitModelIntraMap
- VisitModelBond
- LennardJones
- CutoffOuter
- Monte Carlo
- Tutorial
- FEASST plugin dependencies
- API
- Action
- Run
- Rosenbluth
- Acceptance
- Stepper
- Criteria
- Metropolis
- Constraint
- ConstrainNumParticles
- TrialSelect
- Tunable
- Perturb
- PerturbMove
- PerturbDistance
- PerturbDistanceAngle
- PerturbDihedral
- PerturbRotate
- PerturbTranslate
- PerturbAnywhere
- PerturbRemove
- PerturbAdd
- TrialStage
- PerturbVolume
- TrialSelectBond
- TrialSelectAngle
- TrialSelectDihedral
- TrialSelectAll
- TrialSelectParticle
- TrialCompute
- TrialComputeMove
- TrialComputeTranslate
- TrialComputeVolume
- Trial
- TrialVolume
- TrialMove
- TrialRotate
- TrialAdd
- TrialFactory
- SeekNumParticles
- TrialTransfer
- Analyze
- AnalyzeFactory
- Modify
- ModifyFactory
- MonteCarlo
- TrialComputeAdd
- TrialComputeRemove
- TrialRemove
- TrialTranslate
- Models
- Steppers
- Volume
- CheckPhysicality
- ProfileTrials
- DensityProfile
- Movie
- CPUTime
- MeanSquaredDisplacement
- NumParticles
- Check
- AnalyzeData
- Chirality2D
- WallClockLimit
- Energy
- ExtensiveMoments
- CriteriaWriter
- Log
- Density
- Scattering
- LogAndMovie
- CheckProperties
- CriteriaUpdater
- SeekModify
- IncrementPhase
- WrapParticles
- ReadConfigFromFile
- PairDistributionInner
- Tune
- CheckEnergy
- Tutorial
- FEASST plugin dependencies
- Flat histogram
- Tutorial
- Ideal gas equation of state using grand canonical ensemble transition-matrix Monte Carlo
- Grand canonical ensemble transition-matrix Monte Carlo
- Analysis of a one-phase (supercritical) simulation
- Analysis of a two-phase (phase separated) simulation
- Grand Canonical Flat Histogram Simulation of Lennard-Jones
- Grand Canonical Flat Histogram Simulation of SPC/E
- Grand Canonical Flat Histogram Simulation of RPM
- Grand Canonical Flat Histogram Simulation of Hard Spheres.
- Grand Canonical Flat Histogram Simulation of Patchy Trimers
- Grand Canonical Flat Histogram Simulation of Kern-Frenkel Patches
- Grand Canonical Flat Histogram Simulation at low temperature
- Grand Canonical Flat Histogram Simulation of TraPPE alkanes
- Efficiency of 1 or 2 bin Grand Canonical Flat Histogram Simulations
- FEASST plugin dependencies
- API
- Tutorial
- Patch
- Mayer
- MayerSampling
- Tutorial
- Second virial coefficient calculation of a Trimer using Mayer-Sampling
- Second virial coefficient calculation of TraPPE ethane using Mayer-Sampling
- Second virial coefficient calculation of a Kern-Frenkel patch using Mayer-Sampling
- Virial coefficients of all-atom mAb domains.
- Virial coefficients of 7-bead coarse-grained mAb model.
- FEASST plugin dependencies
- XTC
- Chain
- SelectPerturbed
- SelectSiteOfType
- PerturbConnector
- PerturbDistanceAngleConnector
- PerturbBranch
- PerturbReptate
- PerturbToAnchor
- PerturbPositionSwap
- PerturbParticlePivot
- PerturbCrankshaftSmall
- PerturbPivot
- PerturbCrankshaft
- PerturbLibrary
- PerturbSiteType
- SelectTwoSites
- SelectSegment
- SelectEndSegment
- SelectReptate
- SelectCrankshaftSmall
- SelectBranch
- TrialGrowLinear
- TrialSwapSites
- TrialReptate
- TrialCrankshaftSmall
- TrialCrankshaft
- TrialParticlePivot
- AnalyzeBonds
- RadiusOfGyration
- EndToEndDistance
- TrialGrow
- TrialPivot
- SelectParticlePivot
- Tutorial
- FEASST plugin dependencies
- Shape
- Confinement
- Charge
- Optimized Lennard-Jones
- Cluster
- Monte Carlo with rigid cluster moves
- FEASST plugin dependencies
- API
- EnergyMapAll
- EnergyMapAllCriteria
- EnergyMapNeighbor
- EnergyMapNeighborCriteria
- PerturbPointReflect
- PerturbRotateCOM
- PerturbMoveAVB
- PerturbAddAVB
- SelectCluster
- SelectParticleAVBDivalent
- SelectParticleAVB
- ComputeAVB4
- ComputeAVB2
- TrialAVB4
- TrialAddAVB
- TrialAddAVBDivalent
- TrialTranslateCluster
- TrialAVB2Half
- AnalyzeCluster
- ComputeRemoveAVBDivalent
- ComputeGCA
- ComputeAddAVBDivalent
- ComputeRemoveAVB
- ComputeAddAVB
- ComputeMoveCluster
- Expanded Grand Canonical Ensemble
- Morph
- Beta expanded
- Prefetch
- Aniso
- Modify FEASST
- FFTW
- NetCDF
- List of plugins
- Modify FEASST
- pyfeasst
- accumulator
- cd
- fstio
- fstplot
- macrostate_distribution
MacrostateDistribution
MacrostateDistribution.__init__()
MacrostateDistribution.set_dataframe()
MacrostateDistribution.concat_dataframe()
MacrostateDistribution.dataframe()
MacrostateDistribution.set_macrostates()
MacrostateDistribution.macrostates()
MacrostateDistribution.set_ln_prob()
MacrostateDistribution.ln_prob()
MacrostateDistribution.set_minimum_smoothing()
MacrostateDistribution.minimum_smoothing()
MacrostateDistribution.normalize()
MacrostateDistribution.average_macrostate()
MacrostateDistribution.ensemble_average()
MacrostateDistribution.plot()
MacrostateDistribution.minimums()
MacrostateDistribution.split()
MacrostateDistribution.reweight()
MacrostateDistribution.reweight_to_macrostate()
MacrostateDistribution.equilibrium()
splice()
splice_files()
read_appended()
splice_collection_matrix()
- multistate_accumulator
- physical_constants
- Python interface
- Contact
- Contributing
- Acknowledgement
- Citation