Tutorial

The Python interface is not recommended for most users. Instead, please use the text interface. The installation is more simple and is described in the README. It does not use SWIG or python environments, etc. All of the tutorials for the text interface instead use python to generate text files from formatted strings, and then input the resulting text file into the compiled executable.

WARNING: these tutorials are not as regularly updated and may have some errors due to changing version.

Installation

SWIG is required. Version 3.0.12 is recommended if your current SWIG version does not work properly. 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

install python virtual environment for feasst usage

sudo apt install python3-dev python3-venv swig
mkdir ~/.pyenv
pushd ~/.pyenv
python3 -m venv feasst
source ~/.pyenv/feasst/bin/activate # may add this to your .bash_profile
pip install jupyter matplotlib pandas scipy # for tutorials
popd
# # alternatively, using Anaconda:
# conda env create -f ../py/feasst.yml
# conda activate feasst

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

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

Python or C++?

Although this tutorial will focus upon the python interface, FEASST may also be utilized as a C++ library. For a C++ example, see the file tutorial/tutorial.cpp which is virtually identical to the Python tutorial. Thus Python tutorials are sufficient for learning the C++ library. While the majority of FEASST users prefer the Python interface, FEASST is written almost entirely in C++ for speed. Thus, both interfaces will be supported in the long term.

Some HPC clusters may not have the required Python libraries. If that is the case, do not hesitate to give the C++ interface a try, even if you have never written C++ before. For example, the only minor differences between tutorial/tutorial.cpp and tutorial/tutorial.py are the argument parsing syntax, semi-colons at the end of every line, and compiling any binary with int main().

Canonical ensemble Lennard-Jones Monte Carlo

The following simulation based on tutorial/tutorial.py demonstrates the basics of FEASST.

To begin, FEASST is imported, and it is recommended to log the exact version used for the simulation. Note that the version shown may not match your version.

[1]:
import feasst
print("version:", feasst.version())
version: v0.19.0-29-g791da1d05f-user/multistate_tunable2

Then a MonteCarlo object is created and the random number generator is initialized using the C++ implementation of the Mersenne Twister seeded by the time and date.

[2]:
monte_carlo = feasst.MonteCarlo()
monte_carlo.set(feasst.MakeRandomMT19937(feasst.args({"seed" : "time"})))

Care must be taken not to run two identical simulations at the same second on an HPC node using the time and date, or they will have the same seed and may be equivalent. Instead, consider using a thread safe random number generator to seed the simulations.

FEASST standard output and error goes to the Jupyter notebook terminal. Thus, you should see output like “# Info 0 [plugin/math/src/random.cpp:30] time(seed): 1572362164” but with a different seed. This seed is provided in case you wanted to reproduce your simulation exactly, which we will do now. Note that your simulation may still be different than presented here, possibly because of different compiler implementations.

[3]:
monte_carlo.set(feasst.MakeRandomMT19937(feasst.args({"seed" : "1572362164"})))

The second step is to add a Configuration. In this example, a simple cubic periodic box of length 8 is defined with a single type of particle as described in particle/lj.fstprt. See Particle for more information about the format of the data file, which is a LAMMPS-inspired file with some major differences.

[4]:
monte_carlo.add(feasst.MakeConfiguration(feasst.args({"cubic_side_length": "8",
     "particle_type": feasst.install_dir() + "/particle/lj.fstprt"})))

FEASST arguments are input as a dictionary of strings with limited type checking. Thus, care must be taken to input strings which follow the documentation.

If there is a typo in the arguments, this may result in an exception which will print to the terminal and crash the notebook kernel. You can test this now by changing the cubic_side_length argument to a non-existent argument such as cubic_box_len.

Next, initializing the Potential proceeds as follows:

[5]:
monte_carlo.add(feasst.MakePotential(feasst.MakeLennardJones()))
monte_carlo.add(feasst.MakePotential(feasst.MakeLongRangeCorrections()))

In this example, we introduce both the pair-wise Lennard-Jones (LJ) model, and also long-range corrections, which approximately account for the cut off of the LJ potential by assuming a pair-wise radial distance distribution function of unity. A FEASST convention is to use a helper function which appends the word Make onto the class name when creating pointers to FEASST derived class objects. This serves two purposes involving C++11 smart pointers and brace enclosed initializer lists.

Initialize ThermoParams, such as temperature, and the acceptance Criteria. Note that the initial configuration will be generated with grand canonical particle additions, so a large chemical potential is included, but will not contribute to canonical ensemble production simulations.

[6]:
monte_carlo.set(feasst.MakeThermoParams(feasst.args({"beta": "1.5", "chemical_potential0": "1"})))
monte_carlo.set(feasst.MakeMetropolis())

A TrialTranslate is then introduced which attempts to translate a random particle by a random distance which is bound in each dimension by a tunable_param. This parameter may be adjusted to obtain a desired acceptance ratio, tunable_target_acceptance, with the help of Tune.

[7]:
monte_carlo.add(feasst.MakeTrialTranslate(feasst.args(
    {"tunable_param": "2.", "tunable_target_acceptance": "0.2"})))
trials_per = "1e3"
monte_carlo.add(feasst.MakeTune())

With the help of TrialTranslate and TrialAdd, we can now generate an initial configuration with the desired number of particles.

[8]:
monte_carlo.add(feasst.MakeTrialAdd(feasst.args({"particle_type": "0"})))
monte_carlo.run(feasst.MakeRun(feasst.args({"until_num_particles": "50"})))
monte_carlo.run(feasst.MakeRemoveTrial(feasst.args({"name": "TrialAdd"})))

A grand canonical simulation is performed here by utilizing a temporary TrialAdd, which is why chemical potential was input to Criteria.

Additional Analyze or Modify may be added at any time to perform some task contingent upon the number of attempted trials.

[9]:
monte_carlo.add(feasst.MakeLog(feasst.args({"trials_per_write" : str(trials_per),
                                            "output_file" : "log.txt",
                                            "clear_file" : "true"})))
monte_carlo.add(feasst.MakeMovie(feasst.args(
    {"trials_per_write" : str(trials_per), "output_file" : "movie.xyz"})))
monte_carlo.add(feasst.MakeCheckEnergy(feasst.args(
    {"trials_per_update" : str(trials_per), "tolerance" : "1e-8"})))

In this example, Log outputs the current status of the trials, Movie outputs the configuration, and CheckEnergy asserts that the optimized energy calculations match the unoptimized ones.

The simulation is finally run for a number of trial attempts.

[10]:
%time  # Note: any line starting with % is only to be used with ipynb
monte_carlo.attempt(int(1e5))
CPU times: user 3 µs, sys: 0 ns, total: 3 µs
Wall time: 5.72 µs

Now we can analyze the simulation by, for example, plotting the instantaneous energy as a function of the number of attempts.

[11]:
# Note: any line starting with % is only to be used with ipynb
# import matplotlib.pyplot as plt  # uncomment this line if using plain python, not ipynb
%matplotlib inline
%config InlineBackend.figure_format = 'svg'
import pandas as pd
pd.read_csv("log.txt").plot('trial', 'energy')
# plt.show()  # uncomment this line if using plain python, not ipynb
[11]:
<AxesSubplot:xlabel='attempt'>
../../_images/tutorial_library_tutorial_21_1.svg

You should also find the movie.xyz trajectory file with an automatically-generated movie.xyz.vmd file for use with VMD (e.g., vmd -e movie.xyz.vmd).

Did this tutorial work as expected? Did you find any inconsistencies or have any comments? Please contact us. Any feedback is appreciated!

Comparison between Python and C++ interfaces

Compare the files /path/to/feasst/tutorial/library/tutorial.cpp and /path/to/feasst/tutorial/library/tutorial.py .

Additional tutorials

See additional examples in the directory /path/to/feasst/tutorial/library/. After completing this basic tutorial, check out the tutorials specific to each Plugin. For example, see the tutorials of the MonteCarlo and flat histogram plugins.

[ ]: