1.  For the impatience

Install Anaconda 3 if needed, use a terminal or command line, run

conda config --add channels conda-forge
conda install simupop

2.  License and supported platforms

simuPOP is distributed under a GPL license (version 3). simuPOP is available on any platform where Python is available, and is currently tested under Windows (Windows 2000 and later), both 32 and 64 bit versions of Linux (Redhat), MacOS X and Sun Solaris systems. Different C++ compilers such as Microsoft Visual C++, gcc and Intel icc are supported under different operating systems.

3.  Prerequisite and recommended tools

Python (version 3) (required)

simuPOP works as a python library so a working version of python is required. Python is widely available on Linux/Mac systems but not for windows. Anaconda 3 is highly recommended because it provides binary distributions of simuPOP.

Python 2 compatibility: simuPOP 1.1.8 and later only supports Python 3. If you are using Python 2, you can use simuPOP 1.1.7 or an Python 2 branch of simuPOP. You will have to compile simuPOP from source because no binary distributions for these releases are provided.

wxPython (optional)

Although simuPOP uses the standard tkInter GUI toolkit when a graphical user interface is needed, it can make use of a wxPython toolkit if it is available. wxPython is recommended because it generally produces nicer and more user-friendly dialogs and some functions can only use wxPython.

numpy and matplotlib (optional)

simuPOP uses matplotlib to plot figures. Lack of these modules does not affect the use of simuPOP.

4.  Using simuPOP with docker

If you would like to test simuPOP without installing it, you can use simuPOP from a Ubuntu docker using command

% docker run -it mdabioinfo/simupop

5.  simuPOP installation (Anaconda 3 for mac/win/linux)

If you are using anaconda 3 Python distribution, you can install simuPOP by running

conda config --add channels conda-forge
conda install simupop

This command will download the appropriate binary installer for your platform (mac/win/linux 64bit) and install it.

6.  simuPOP installation (pip for mac/linux, compile from source, require compiler)

Make sure you have the following before compiling simuPOP from source

  • A C++ Compiler: Get a C++ compiler. This is usually not a problem for Linux/Solaris/MacOS systems because GNU gcc/c++ is widely available on these operating systems. Under windows, you can get a copy of the free Visual C++ Express edition from here.
Note: You will need a recent version of gcc (>= 4.2.1) to have compile simuPOP with openMP support so that it can execute in multiple threads. Due to some internal bugs in llvm-gcc 4.2.1 under MacOSX, openMP is disabled for MacOSX unless a different compiler is used.
Note: Visual C++ 2015 is required under windows. Its free Express version does not support openMP so you will need to buy a professional copy of this software to compile simuPOP with openMP support.
  • Python header files: The Python header files (e.g. Python.h) are usually installed with Python but you should install python-devel (for redhat linux) or similar packages if this file is unavailable.
  • zlib header files (*nix systems only): zlib and its header file zlib.h are usually available under a *nix system. If you get a message stating missing zlib.h, you will need to run yum install zlib-devel for a redhat Linux system, or apt-get install zlib1g-dev for a Ubuntu system. For Ubuntu, please install package build-essential if you still get missing header files.

With all the tools ready, it is usually as easy as running

> pip install simupop

to download and compile simuPOP. You can also download simuPOP source package and compile it with commands

> tar zxf simuPOP-x.x.x.tar.gz
> cd simuPOP-x.x.x
> python setup.py install

6.1  Install simuPOP locally

It is not uncommon that you do not have write permission to the Python site library directory. In this case, you can install simuPOP to some local directory where you have write permission. If you are building simuPOP from source, you can use the prefix option of the setup.py script. For example,

> python setup.py install --prefix=/home/me/PythonModules

or

> scons install prefix=/home/me/PythonModules

if you use scons to build simuPOP.

Python will build and install simuPOP to a local directory such as /home/me/PythonModules/python2.x/lib/site-packages. You then need to tell Python where to look for simuPOP modules, using environment variable PYTHONPATH. For linux bash, the syntax is

> PYTHONPATH=/home/me/PythonModules/python2.x/lib/site-packages
> export PYTHONPATH

You may want to put these lines to your shell configuration file such as $HOME/.bashrc. Note that some Python distributions use dist-packages instead of site-packages for system packages and you will need to explicitly add site-packages (e.g. /usr/lib64/python26/site-packages) to PYTHONPATH.

6.2  Mac Specific

You will need to use the same compiler that is used to compile your Python distribution, which is usually gcc 4.2 on a modern Mac OSX system. To compile simuPOP from source, please

  • Type python from a command line and check the required compiler from the banner message.
  • Type gcc -v to check if gcc exists, and if it is the right version.
  • If gcc is not installed on your system, you can install Xcode from here or from Apple app store. However,
    • Earlier versions of gcc 4.0 might not have tr1 support. If you are having trouble using gcc 4.0.0, please check update your gcc/tr1/hashtable following these instructions.
    • Xcode 4.2.1 comes with a LLVM-gcc version of gcc4.2.1. You will however need to create an alias command gcc-4.2 from /usr/bin/gcc, using command ln -s /usr/bin/gcc /usr/bin/gcc-4.2 in order to use command gcc-4.2.
    • Xcode 4.3.2 comes with gcc without command line support. You will get an error message for linking error when you compile a simple "hello world" program. To add command line support, you will need to go to the Apple developer center to download "Command Line Tools for Xcode".
    • Some versions of Xcode do not install gcc 4.2 by default so you will need to either use an older version of Xcode (e.g. Xcode 3.2.6, if you can find it), or install gcc 4.2 separately after installing a newer version of Xcode. According to these instructions, you will need to install Xcode 4.1, MacPorts 2.0, and then use command sudo port install gcc42 to install gcc 4.2.
    • The downloaded version of Python might not use the same version of Xcode and OS SDK that is available on your system. For example, the official package for Python 3.2.3 assumes a SDK path of /Developer/SDKs/MacOSX10.6.sdk, and will not work for Xcode 4.3.3 on OSX 10.7 with a SDK path of /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk. To correct this problem, you will need to set CFLAGS explicitly, namely running
export CFLAGS=-sysroot,/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk
export LDFLAGS=-L/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk/usr/lib

before you call python3 setup.py install to compile simuPOP.

  • Download the simuPOP source package, unpack and use command python setup.py install to compile it.

6.3  Linux/Ubuntu Specific

If build script can not find zlib.h, you may need to use some command like

> python setup.py config --include-dirs=/usr/include/linux install

if zlib.h is not in standard directories.

6.4  Compile simuPOP using Intel i++

Because Python has to be compiled with the same compiler as simuPOP, you will have to build python by yourself as well. I assume that you do not want to override system python, so here is what you need to do

  • Download and intall intel C++ compiler.
  • Download python source. Run, for example (assume you are running csh),
> tar zxf Python-x.x.x.tgz
> cd Python-x.x.x
> setenv CC icc 
> setenv CXX icpc
> ./configure --with-cxx=icpc --prefix=/home/username/Python24
> make
> make install
  • Build and install simuPOP
> cd simuPOP
> /home/username/PythonXX/bin/python setup.py install

simuPOP modules will be put under /home/username/Python24/lib(or lib64)/site-packages.

6.5  Compile simuPOP using mingw under windows

The problem with cygwin is that it has its own gcc, zlib and boost and it is tricky to not use them. Using a system without cygwin, you can

  • download mingw.exe, choose g++ and install, add c:/mingw/bin to $PATH
  • download zlib, unpack to c:\zlib
  • (Optional) download and install boost, using commands like:
> cd \boost\boost-1_39_0\tools\build\jam_src
> build.bat
Copy bjam.exe to c:\boost\boost-1_39_0, and
> cd \boost\boost-1_39_0
> bjam.exe -j4 "-sBUILD=debug release <cxxflags>-fPIC" "-sTOOLS=mingw" \
    -sNO_COMPRESSION=0 -sNO_BZIP2=1 -sNO_ZLIB=0 -sZLIB_INCLUDE=c:/zlib/include \
    -sZLIB_LIBRARY=c:/zlib/lib -sZLIB_BINARY=zdll --prefix=c:/boost \
    --with-iostreams --with-serialization --with=regex install
  • download python, install to c:\python24, add c:\python24 to $PATH
  • download and unpack simuPOP source to c:\simuPOP
  • if needed, download swig, unpack to c:\swigwin and add c:\swigwin to $PATH
  • from the simuPOP directory, do
> python setup.py bdist_wininst

setup.py looks in the win32 directory for boost and zlib libraries. If you would like to link to your versions of them, remove this directory and add --library-dirs option to point to your libraries.

For python2.4, you may get an error message saying

import error: DSLL load failed: The specified procedure could not be found

This is because of a compatibility problem of mingw32/msvcrt and msv/msvcrt71. Please see http://jove.prohosting.com/iwave/ipython/issues.html for details. My fix is go to python24/Lib/distutils/cygwinccompiler.py, at line 139, change

self.dll_libraries = []

to

self.dll_libraries = ['msvcrt', 'python' + ''.join(sys.winver.split('.'))]

and comment out the following if/else block. This will force simuPOP to use msvcrt, not msvcrt70 or msvcrt71 with msvc.