This document gives instructions on how to build and install the FFEA package, consisting of the FFEA runner and FFEA tools. Compiling FFEA from the source code is very easy, and essentially consists of three commands: "cmake", "make", and "make install". If you don't want to compile FFEA, then you can download the latest x86_64 binary release. Once FFEA has been installed, you can learn how to use it in the tutorial.
1: A Shkurti, et al., "pyPcazip: A PCA-based toolkit for compression and analysis of molecular simulation data" (2016), SoftwareX, 7:44-50.
2: P L'Ecuyer, "Good Parameter Sets for Combined Multiple Recursive Random Number Generators" (1999), Oper. Res., 47(1):159-164.
3: P L'Ecuyer et al., "An Objected-Oriented Random-Number Package with Many Long Streams and Substreams" (2002), Oper. Res., 50(6):1073-1075.
4: F Ganovelli, et al., "Fast tetrahedron-tetrahedron overlap algorithm" (2002), J. Graph. Tools, 7(2):17-25.
FFEA uses CMake to find the compiler, dependencies and to configure files and Makefiles automatically (a short introduction to CMake can be read here). It is generally advisable to configure and compile FFEA outside of the source tree. E.g.
git clone https://bitbucket.org/FFEA/ffea.git mkdir FFEA_build cd FFEA_build cmake ../ffea [OPTIONS]
There is a list of cmake
[OPTIONS]
later in this section. Our favourite option is to specify the installation directory, since the default (/usr/local/) may not be available if you do not have administrator privileges. You should also tell cmake to use a Python 2.7.X interpreter if it isn't already the system default (/usr/bin/python), so that ffeatools can be correctly imported into Python:
cmake ../ffea -DCMAKE_INSTALL_PREFIX=$HOME/softw/ffea -DPYTHON_EXECUTABLE=/usr/bin/python2.7
where $HOME/softw/ffea can be replaced with an installation directory of your choice. CMake default options seeks to build FFEA for production, and will suit most of the users. The following subsection gives greater detail, but if you are happy with defaults, you can jump to build.
After configuring you will be able to build FFEA typing:
make
Then, the following command will install FFEA:
make install
either to the folder specified through -DCMAKE_INSTALL_PREFIX
or into a default folder (where you may need administrative privileges).
Two parallel versions of the FFEA_runner, ffea
and ffea_mb
, as well as the ffeatools, ffeatools
will be found in $FFEA_HOME/bin
. Instructions on how to use them can be read here and here respectively. In addition, the ffeatools
Python package will be found in $FFEA_HOME/lib/python<version>/site-packages
.
If you built the documentation you will be able to read it with a web browser, and so if firefox was the browser of your choice, and you installed FFEA in $FFEA_HOME
, the command would be:
firefox $FFEA_HOME/share/ffea/doc/html/index.html &
Install a plugin to visualise systems and trajectories in PyMOL. The plugin should be found in:
$FFEA_HOME/share/ffea/plugins/pymol/FFEAplugin.tar.gz
and in order to install it, one would need to run PyMOL, and then click on Plugin
-> Plugin Manager
, and on the new window, go to tab Install New Plugin
, click Choose file...
and finally find and select FFEAplugin.tar.gz
from your disk. You will be asked to install the plugin either into a local folder or a global folder. If the folder does not exist, PyMOL will ask your permission on creating the folder, and will install the plugin properly. However, and just in this case, it will bump Plugin FFEAplugin has been installed but initialization failed
. All you need to do is to restart PyMOL to use the plugin.
Executing ffea
, ffea_mb
and ffeatools
is probably what most users will wish, so UNIX users may find convenient to add the install folder in the PATH
:
export PATH=$FFEA_HOME/bin:$PATH
In addition, in order to have direct access to the python modules that integrate the FFEA tools, and specially to those users willing to write new measure tools, the PYTHONPATH
environment variable should be also updated:
export PYTHONPATH=$FFEA_HOME/lib/python<version>/site-packages
ffeatools provides a suite of command-line tools to initialise FFEA systems. FFEA also provides a python API to accomplish these tasks. You can install it by entering the ffea source folder and running
python setup.py install
The FFEA API may then be used within python by running import ffeatools
. Note: KOBRA/FFEA_rod requires this module. Information on how to use ffeatools
can be found in the FFEA analysis tutorial and the KOBRA/rods tutorial.
You may now want to check that the code was correctly compiled. Do so running the provided suite of tests, either sequentially (using a single processor, one tests after the other):
make test
or concurrently (multiple tests running independently on different processors):
ctest -j <number-of-processes>
The following configuration flags are either fundamental to CMake or specific to FFEA:
-DCMAKE_INSTALL_PREFIX=<install_dir>
- (default /usr/local) installation directory-DPYTHON_EXECUTABLE=<program>
- (default /usr/bin/python) Python interpreter-DCMAKE_BUILD_TYPE=<Debug|Release>
- (default Release) build type-DCMAKE_CXX_COMPILER=<program>
- (default g++) C++ compiler.By default, CMake will use the subset of Boost we bundled, and will download Eigen 3.3.7. If you want to use your own installations you can still do so through:
-DUSE_BOOST_INTERNAL=<ON|OFF>
- default ON
-DUSE_EIGEN3_INTERNAL=<ON|OFF>
- default ON
If you decide to do so, CMake will look for the required Boost and/or Eigen libraries. In the case they are not installed in a standard place, you can help CMake either through:
-DCMAKE_PREFIX_PATH="Path-to-Eigen;Path-to-Boost"
,-DEIGEN_HOME="Path-to-Eigen"
and -DBOOST_ROOT="Path-to-Boost"
EIGEN_HOME
and BOOST_ROOT
to the corresponding software foldersAdditional specific FFEA flags include:
USE_FAST
(default ON) will try to find the best compiler flags in terms of performance. Disable USE_FAST
if you intend to debug the code.USE_OPENMP
(default ON) will enable OpenMP parallel calculations.BUILD_DOC
(default TRY) where:NO
will not build the documentation.TRY
will try to find Doxygen and build the documentation.YES
will try to find Doxygen (raising an error if not found) and build the documentation.ONLY
will try to find Doxygen (raising an error if not found) and only build the documentation.Now that you've installed FFEA, proceed to the tutorial!