2. Installing FATSLiM¶

2.1. Requirements¶

FATSLiM is written in Python and, consequently, a Python environment with header files is required. FATSLiM is developed and daily tested with Python 2.7 to 3.5 on GNU/Linux, but it also works on Windows and Mac OS (far less tested on both, though).

FATSLiM only depends on NumPy, but, if you want to run the tests (recommended), pytest is also needed.

Computationally intensive tasks are written in Cython. Cython is not a requirement per se as C-translated code is provided but the latest version of Cython is recommended.

Obviously, a C compiler is required to compile C extensions. Additionally, openMP is strongly recommended as it is needed to enable parallelism.

2.2. Pre-installation¶

This section describes briefly how to install all the requirements needed by FATSLiM. One caveat though: the goal here is not to provide a complete "How to install Python and stuff on your OS" guide (which would be out of the scope of this documentation) but rather to give rough guidelines.

2.2.1. GNU/Linux¶

Python is most probably already installed on your system (at least for the vast majority of Linux distributions). To install the rest of the requirements you should use the package manager shipped with your system. Here will be described only a few examples that may need to be adapted for your specific distro. In such case, please refer to the distribution's documentation and/or package list.

Note

In the following, the package manager commands are given as if they are executed as root. Depending on your distro, you may also use sudo to run the commands (very probably available). Please refer to your distribution manual.

Note

Please also note that the provided command install the default packages. Depending on your distro, the packages may correspond to Python version 2 or 3.

2.2.1.1. APT-based distributions (Debian, Ubuntu, Linux Mint)¶

You should use apt to install the requirements:

apt-get install gcc python-dev python-numpy cython python-pytest

2.2.1.2. YUM-based distributions (Fedora, RHEL, CentOS)¶

You should use yum to install the requirements:

yum install gcc python-devel numpy Cython pytest

2.2.1.3. ZYpp-based distributions (OpenSUSE, SUSE)¶

You should use zypper to install the requirements:

zypper install gcc python-devel python-numpy python-Cython python-pytest

2.2.1.4. Pacman-based distributions (Arch Linux, Manjaro)¶

You should use pacman to install the requirements:

pacman -S gcc python-numpy cython python-pytest

2.2.2. Mac OS X¶

The latest version of Mac OS X (10.11 - El Capitan) comes with Python 2.7 pre-installed. Yet, the shipped version may be outdated and it is generally recommended by "Mac OS pythonistas" to use homebrew to install a fully-functional and up-to-date Python version. A complete guide to do so is available here:

http://docs.python-guide.org/en/latest/starting/install/osx/.

2.2.3. Windows¶

Installing Python and python packages on Windows can be cumbersome. Thankfully, several Python distributions exist and contain Python plus widely-used packages such as Numpy or Matplotlib. Anaconda is such Python distribution which has the advantage to be oriented toward science and is then well-suited to run FATSLiM.

This distribution can be downloaded from https://www.continuum.io/downloads.

Once Anaconda is installed, you can access your Python environment via a dedicated command prompt called Anaconda prompt accessible from the Windows Start menu.

2.3. Installation¶

The easiest, and then recommended, way to install FATSLiM is probably to use pip and the Python Package Index (aka PyPI). Alternately, you can also install FATSLiM from GitHub.

Note

Installation of FATSLiM inside a Python virtual environment is of course possible but it will not be described here as setting up such environment is out of this documentation's scope. If you want to take this path, just follow the system-wide installation instructions once your virtual environment is activated.

2.3.1. Python Package Index (recommended)¶

Installation-ready packages for FATSLiM are hosted on PyPI. You can then use pip to install FATSLiM, independently of your OS.

2.3.1.1. User-specific installation¶

If you do not have a administrator privileges on your machine (or simply do not want to mess with your system), you can install (or upgrade) FATSLiM in your home directory with the following command:

pip install --user --upgrade fatslim

2.3.1.2. System-wide installation¶

Note

This also works for an installation inside a virtual environment (without the need for admin rights)

If you want to install/upgrade FATSLiM for all users, run the following command as root/superuser/administrator:

pip install --upgrade fatslim

2.3.2. GitHub¶

The main source code repository for FATSLiM is hosted on GitHub at the following address: https://github.com/FATSLiM/fatslim. This repository can be used as an alternative to PyPI.

2.3.2.1. End user installation¶

For each FATSLiM release, the corresponding package is accessible via the "releases" page where you can download the source code as a compressed archive (.zip or .tar.gz). Once you have downloaded and extracted the archive, go to the source folder (fatslim-x.y.z).

You may then install FATSLiM in user site-package (recommended):

python setup.py install --user

Or, you can install FATSLiM for all users (this requires administrator privileges):

python setup.py install

2.3.2.2. Coder/advanced user installation¶

Warning

This section is targeted to people with a bit of practice with git.

If you are a code/git guru, you can clone the repository to update FATSLiM continously instead of waiting for new releases (But you probably know that!) For that matter, you need to clone the main repository using, for instance, the following:

git clone https://github.com/FATSLiM/fatslim.git

The repository contains two branches that you may use:

master: Same code as the last public release
develop: Code not officially released but validated by unit testing

You can use this local repository to run FATSLiM but you will need to run python setup.py build_ext -i every time you switch between branches or pull the code. You may then run FATSLiM by running fatslim (just besides setup.py).

2.4. Post-installation¶

2.4.1. Adding FATSLiM to your PATH¶

If you performed a system-wide installation, FATSLiM executable is most likely already in your PATH and the fatslim command should be available. Unfortunately, if you installed FATSLiM as a regular user and the fatslim command is not available, you need to add it to your PATH.

2.4.1.1. On Mac OS and GNU/Linux¶

Note

It is assumed that your shell is BASH.

Simply add the following lines to your .bashrc file:

# Add Python user directory to PATH
PYTHON_USER_PATH=`python -c "import site; print site.getuserbase()"`/bin
if [ -d "$PYTHON_USER_PATH" ]
then
  export PATH=$PATH:$PYTHON_USER_PATH
fi

2.4.1.2. On Windows¶

If you installed FATSLiM using Anaconda and the pip install --upgrade, the fatslim script is located inside the folder %CONDA_DEFAULT_ENV%\Scripts which is already in your %PATH%. Unfortunately, Windows does not recognize shebang lines and then the script is not executable. The trick is to create a Batch file that will actually launch FATSLiM. To do so, follow these steps:

Open a Anaconda prompt (from Start menu) and run to get the default folder for Anaconda:

echo %CONDA_DEFAULT_ENV%

With the file explorer, go to the Scripts folder inside the Anaconda folder. You should see the fatslim script there. Create a file named fatslim.cmd and paste the following code inside this new file:

@echo off
echo About to run FATSLiM with the following arguments: %*
pause
python %CONDA_DEFAULT_ENV%\Scripts\fatslim %*

Verify that can run FATSLiM from the Anaconda prompt by running fatslim --version. The output should be similar to the following:

[Anaconda2] C:\Users\IEUser>fatslim --version
About to run FATSLiM with arguments: --version
Press any key to continue . . .
FATSLiM - Fast Analysis Toolbox for Simulations of Lipid Membranes
version 0.1.2
Copyright (c) 2013-2016 Sebastien Buchoux <sebastien.buchoux@gmail.com>

FATSLiM - Fast Analysis Toolbox for Simulations of Lipid Membranes

FATSLiM version: 0.1.2
Python version: 2.7.11 (C:\Users\IEUser\Anaconda2\python.exe)
Cython version (file generation): 0.23.4
Python compiler: MSC v.1500 64 bit (AMD64)
CPU architecture: 64bit
OpenMP: 8 CPUs (default number of threads: 8 - max: 8)
NumPy version: 1.11.0
'version' command executed in 31.000 ms (CPU)
Goodbye!

[Anaconda2] C:\Users\IEUser>

2.4.2. Enable autocompletion¶

2.4.2.1. On Mac OS and GNU/Linux¶

Note

Currently, only Bash shell is supported for autocompletion. (This is the default shell for Mac OS and the vast majority of Linux distros)

Autocompletion for FATSLiM is enabled by the fatslim-autocompletion.bash script which is shipped with FATSLiM First thing is to locate the fatslim-autocompletion.bash which is coherent with the FATSLiM version. To do so, run:

which fatslim

This will output the actual path to the fatslim executable. This path is formatted like [ROOT]/bin/fatslim where [ROOT] is the root directory where FATSLiM-related files are installed. For example, if which fatslim returns /usr/local/bin/python, it means that the root directory is /usr/local/. Once you have, you know the root directory you can enable autocompletion by running the command (of course you need to replace [ROOT] by the actual value):

source [ROOT]/share/fatslim/fatslim-autocompletion.bash

This will enable autocompletion only for the current session: if you close the terminal, autocompletion will be disabled. To enable it by default, simply add the whole source command to your .bashrc.

2.4.2.2. On Windows¶

Unfortunately for Windows users, autocompletion with a command prompt is rather limited and à la bash fully-fledged autocompletion is not feasable on Windows (at least easily).