Skip to content

installation.md

Latest commit

 

History

History
233 lines (163 loc) · 5.95 KB

installation.md

File metadata and controls

233 lines (163 loc) · 5.95 KB

(sec_installation)=

Installation

There are two main options for installing msprime:

  1. {ref}sec_installation_conda: the recommended options for most users
  2. {ref}sec_installation_pip: more flexibility and control for advanced users

(sec_installation_conda)=

Via Conda

Convenient conda packages are available for Python {{ min_python_version }} and greater on Linux, macOS and Windows. These pre-built binary packages are built using conda-forge.

Quick Start

  1. Install conda using miniconda. Make sure you follow the instructions to fully activate your conda installation!
  2. Set up the conda-forge channel using conda config --add channels conda-forge.
  3. Create a conda environment and install msprime into it: conda create -n msprime-env msprime
  4. Activate the environment: conda activate msprime-env
  5. Try out msprime: msp --version.
Always use an environment when installing conda packages as installing
can lead to many difficult to debug issues.

There are several different ways to obtain conda. Please see the anaconda installation documentation for full details.

Full example

In this example we create a conda environment and install msprime into it on a macOS machine. We assume that conda has been installed and bash shell is being used (Windows users will need to modify the commands slightly).


$ conda create --name msprime-env
...

  environment location: /home/jean/miniconda3/envs/msprime-env

Proceed ([y]/n)? y

Preparing transaction: ...working... done
Verifying transaction: ...working... done
Executing transaction: ...working... done
#
# To activate this environment, use
#
#     $ conda activate msprime-env
#
# To deactivate an active environment, use
#
#     $ conda deactivate

$ conda activate msprime-env
(msprime-env) $ conda install -c conda-forge msprime
...

  added / updated specs:
    - msprime

The following NEW packages will be INSTALLED:
...

Proceed ([y]/n)? y

Downloading and Extracting Packages

Preparing transaction: ...working... done
Verifying transaction: ...working... done
Executing transaction: ...working... done

(msprime-env) $ python
Python 3.8.5
[GCC 7.3.0] :: Anaconda, Inc. on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import msprime
>>> ts = msprime.sim_ancestry(3)
>>> print(ts.draw_text())
3.18┊      10     ┊
    ┊    ┏━━┻━━┓  ┊
2.08┊    9     ┃  ┊
    ┊  ┏━┻━┓   ┃  ┊
0.80┊  ┃   ┃   8  ┊
    ┊  ┃   ┃  ┏┻┓ ┊
0.42┊  ┃   7  ┃ ┃ ┊
    ┊  ┃  ┏┻┓ ┃ ┃ ┊
0.34┊  6  ┃ ┃ ┃ ┃ ┊
    ┊ ┏┻┓ ┃ ┃ ┃ ┃ ┊
0.00┊ 0 4 1 3 2 5 ┊
  0.00          1.00

Please see the conda documentation for more details on managing packages and environments.

(sec_installation_pip)=

Via Pip

Installing using pip is more flexible than conda as it can support more versions of Python and dependencies can be customised.

:::{warning}

If you installed Python using anaconda/miniconda, please install msprime using conda. Link/load time errors will occur if you mix a conda installed Python with system libraries.

:::

To install msprime via pip, first {ref}sec_installation_system_requirements, then {ref}sec_run_pip.

(sec_installation_system_requirements)=

check system requirements

Msprime requires Python {{ min_python_version }} or greater and pip. Run


$ python3 -m pip --version

to make sure you see Python {{ min_python_version }} or greater. If you do not, do installation {ref}via conda <sec_installation_conda>.

On most platforms, pip will install msprime pre-built binaries without any additional requirements. Follow {ref}sec_pip_install_source to install from sources instead pre-built binaries.

(sec_run_pip)=

run pip install

We can install msprime easily using pip:

$ python3 -m pip install msprime

(It is generally better to use python3 -m pip rather than call pip directly since this allows you to control which installation of Python the package is installed to.)

If you do not have root access to your machine, you can install msprime into your local Python installation as follows:

$ python3 -m 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:

$ python3 -m pip uninstall msprime

(sec_pip_install_source)=

pip install from source

Install from source if {ref}sec_run_pip fails or you do not want to use pre-built binaries.

There may be additional requirements depending on the specific platform. In particular, installation of GNU Scientific Library (GSL) is sometimes needed:

.. glossary::

    Debian/Ubuntu
        ::

            $ apt-get install python-dev libgsl0-dev

    Redhat/Fedora
        ::

            $ yum install gsl-devel

    FreeBSD
        ::

            $ pkg install gsl

    OS X
        We recommend using :ref:`sec_installation_conda` to install ``msprime`` on OS X.
        However, it is also possible to install using `Homebrew <http://brew.sh/>`_:
        ::

            $ brew update
            $ brew install gsl

    Windows
        Use :ref:`sec_installation_conda`, do not install via ``pip`` on Windows.

With GSL installed, install from source by doing:

python3 -m pip install msprime --no-binary msprime