Skip to main content

Forward-time population genetic simulation in Python

Project description

This is the README for fwdpy11, which is a Python package for forward-time population genetic simulation. It uses fwdpp as its C++ back-end.

https://anaconda.org/bioconda/fwdpy11/badges/license.svg https://anaconda.org/bioconda/fwdpy11/badges/installer/conda.svg https://anaconda.org/bioconda/fwdpy11/badges/version.svg https://anaconda.org/bioconda/fwdpy11/badges/platforms.svg

Build status

Master:

https://travis-ci.org/molpopgen/fwdpy11.svg?branch=master https://circleci.com/gh/molpopgen/fwdpy11/tree/master.svg?style=svg

Development:

https://travis-ci.org/molpopgen/fwdpy11.svg?branch=dev https://circleci.com/gh/molpopgen/fwdpy11/tree/dev.svg?style=svg

Manual

Latest/master:

https://readthedocs.org/projects/fwdpy11/badge/?version=latest

Development branch:

https://readthedocs.org/projects/fwdpy11/badge/?version=dev

Features

  • Picklable population objects
  • Parallel computation via multiprocessing or concurrent.futures.
  • Custom temporal samplers to analyze populations during a simulation may be written in pure Python.

Dependencies

The following must be present on your system:

  • GSL. This is a C library. It is available via conda. fwdpy11 requires version 2.3 or greater.
  • pybind11. This should be installed conda as appropriate for your system, or via your system’s package manager or manually. See note below.
  • cmake. This should be installed by conda or your favorite package manager.

fwdpy11 also uses fwdpp, which is included as a submodule.

Note

The C++ modules are built using cmake, which requires that pybind11’s cmake macros are visible. Installing pybind11 via pip does not install the macros. However, installs using conda, apt-get, or manual installation from source will install both the Python module and the cmake macros.

License

GPLv3 or later (See COPYING)

Suppored Python version

fwdpy11 is written for Python 3. We will not modify the package to be compatible with Python 2.7.

Installation

Building from the git repository:

git submodule init
git submodule update
python setup.py build_ext -i
python -m unittest discover tests

Using pip on OS X and Linux (or pip3 as appropriate for your system):

pip install --upgrade fwdpy11

It is possible that the cmake macros to detect the GSL can fail to detect the correct version. Issues like this are a basic weakness of cmake. I’ve seen this in conda environments, where the macro prefers the system version over the newer version in the environment. To “fix” this, give it a hint:

GSL_ROOT_DIR=/path/to/gsl python3 setup.py build_ext -i

OS X

On Apple’s OS X, we strongly encourage that you use conda with the clang-4.0 compiler packages:

conda install clang_osx_64 clangxx_osx-64

Installing these packages will mean that you can get away from the relatively old versions of these compilers that ship with Xcode. However, you do need to add the following flag when building the package:

CONDA_BUILD_SYSROOT=/ python3 setup.py build_ext -i

Do the same for a pip install from the source directory.

Caution

We use the GitHub “release” mechanism to make stable versions available. However, GitHub releases to not include the sub-modules, meaning that the releases themselves cannot be used for installation. (A related irony is that the Zenodo DOI for the releases are somewhat meaningless.)

To install a specific release:

  1. Use pip (see above). This is the recommended approach if you do not use conda.
  2. Install from bioconda. This is the recommended approach.
  3. Clone the repo, checkout the release, and update submodules:
git clone http://github.com/molpopgen/fwdpy11
cd fwdpy11
git submodule init
git submodule update

The latter method is probably the least appealing.

We have a strict policy of putting releases on PyPi and bioconda. If there is a release on PyPi but not on bioconda, then that is because we identified a bug and pushed a new release before the bioconda build happend. It happens. That’s life.

Enabling code profiling

By default, fwdpy11 is compiled with aggressive optimizations to help reduce the library size. One side effect is that it becomes impossible to accurately profile the code. To override these defaults:

python setup.py build_ext -i --enable-profiling

Note

The package should not be installed with profiling enabled. This method of building is for developers who need to accurately profile the C++ back-end. Also note that only the main package is affected. Building the unit test modules is not affected.

Enabling debugging symbols in the C++ code

python setup.py build_ext -i --debug

Debug mode disables all compiler optimizations, allows C-like assertions, and generated debug symbols.

Note

Never install the package compiled in debug mode! First, things will run much more slowly. Second, triggering an assertion will cause the Python interpreter to crash. These assertions exist as a brute-force method to help developers quickly identify bugs.

Enabling assertions in the C++ code

The fwdpp library code uses C’s assert macros in several places. These are disabled by default. However, it can be useful to enable them when hacking the code. To do so, you must manually set your compiler flags with cmake:

cmake . -DCMAKE_CXX_FLAGS="-UNDEBUG -O2 -g"

When compiling this way, fwdpy11 makes some extra checks that will throw RuntimeError if they fail. The fwdpp back end also makes extra checks. If those fail, abort will be called, which will crash the Python interpreter. Thus, compiling with this option is a “serious debugging mode only” option.

Bioconda

fwdpy11 is available through bioconda for Linux and for OS X:

conda install -c bioconda fwdpy11

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for fwdpy11, version 0.5.2
Filename, size File type Python version Upload date Hashes
Filename, size fwdpy11-0.5.2.tar.gz (1.4 MB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page