https://github.com/tskit-dev/msprime
Tip revision: d0fb9ed0f66dd2d1f7403283023925d6bbb51cbe authored by Jerome Kelleher on 28 August 2015, 12:51:28 UTC
Version bump.
Version bump.
Tip revision: d0fb9ed
README.txt
=======
msprime
=======
Msprime is a reimplementation of Hudson's classical ms program for modern
datasets. The Python API and storage format are currently under development
and are not fully documented, but the command line interface ``mspms`` is
reliable and ready for use. This program provides a fully ``ms`` compatible
interface, and can be used as a drop-in replacement in existing workflows.
Msprime can simulate the coalescent with recombination much
faster than programs based on the Sequentially Markov Coalescent
for large sample sizes and has very reasonable memory requirements. Msprime
makes it possible to simulate chromosome sized regions with hundreds of
thousands of samples.
Please see the `documentation <https://msprime.readthedocs.org/en/latest/>`_
for further details.
***********
Quick Start
***********
To install and run ``msprime`` on a Ubuntu 14.10 installation do the
following::
$ sudo apt-get install python-dev libgsl0-dev libhdf5-serial-dev
$ sudo pip install msprime
$ mspms 2 1 -t 1
/usr/local/bin/mspms 2 1 -t 1
5338 8035 23205
//
segsites: 3
positions: 0.014 0.045 0.573
100
011
If you do not wish to install ``msprime`` to your system, you can try
it out in a `virtualenv <http://virtualenv.pypa.io/en/latest/>`_ as
follows::
$ virtualenv msprime-env
$ source msprime-env/bin/activate
(msprime-env) $ pip install msprime
(msprime-env) $ mspms
*************
Requirements
*************
Msprime requires Python 2.7+ (Python 3 versions are fully supported from
3.1 onwards), the `GNU Scientific Library <http://www.gnu.org/software/gsl/>`_,
and `HDF5 <https://www.hdfgroup.org/HDF5/>`_ version 1.8 or later. These
packages are available for all major platforms. For example, to install on
Debian/Ubuntu use::
# apt-get install python-dev libgsl0-dev libhdf5-serial-dev pkg-config
For Redhat/Fedora use::
# yum install gsl-devel hdf5-devel
On FreeBSD we can use ``pkg`` to install the requirements::
# pkg install gsl hdf5-18
----
TODO
----
- Add instructions for HomeBrew/MacPorts.
************
Installation
************
The simplest method of installation is to use PyPI and pip::
# pip install msprime
This will work in most cases, once the `Requirements`_ have been
satisfied. See below for platform specific build instructions when this
fails.
If you do not have root access to your machine, you can install
``msprime`` into your local Python installation as follows::
$ pip install msprime --user
To use the ``mspms`` program you must ensure
that the ``~/.local/bin`` directory is in your ``PATH``, or
simply run it using::
$ ~/.local/bin/mspms
To uninstall ``msprime``, simply run::
$ pip uninstall msprime
------------------------------
Platform specific installation
------------------------------
This section contains instructions to build on platforms
that require build time flags for GSL and HDF5.
++++++++++++
FreeBSD 10.0
++++++++++++
Install the prerequisitites, and build ``msprime`` as follows::
# pkg install gsl hdf5-18
# CFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib pip install msprime
This assumes that root is logged in using a bash shell. For other shells,
different methods are need to set the ``CFLAGS`` and ``LDFLAGS`` environment
variables.
---
OSX
---
*TODO*
****************
Tested platforms
****************
Msprime is highly portable, and has been successfully built and tested
on the following platforms:
==================== ======== ====== ===========
Operating system Platform Python Compiler
==================== ======== ====== ===========
Debian jessie x86-64 2.7.9 gcc 4.9.2
Debian jessie x86-64 3.4.2 gcc 4.9.2
Debian wheezy i686 2.7.3 gcc 4.7.2
Fedora 20 x86-64 2.7.5 gcc 4.8.3
FreeBSD 10 x86-64 2.7.6 clang 3.4.1
SunOS 5.10 SPARC 3.4.1 gcc 3.4.3
==================== ======== ====== ===========