Installing msprime and pyslim with conda
========================================

If you use the conda package manager, it's easy to install msprime and pyslim.
The only problem arises when package dependencies downloaded from the conda
defaults channel conflict with the ones from the conda-forge channel; the
following instructions walk you through the process of installation to avoid
this.

First, we need to make sure that conda-forge is a lower priority channel than
the defaults channel. On a terminal, type the following:

    conda config --get channels

If you don't see `conda-forge` at all in the output, that's good - it means
it's not configured as one of the default channels. If you do, make sure it is
listed as lower priority than the channel called `defaults`.

If `conda-forge` is higher priority, , you need to edit your `.condarc` file,
which is probably located in `~/.condarc`. Just edit it so that `conda-forge`
appears below `defaults` in the channel listing, or delete the `conda-forge`
line altogether.

Now things should be straightforward. First, we create a new environment with
Python 3 and matplotlib.

    conda create -n slim-workshop python=3 matplotlib

Next, we activate it.

    source activate slim-workshop

Now, we install the packages: `msprime` is found in `conda-forge`, and `pyslim`
has to be installed using `pip`.

    conda install -c conda-forge msprime
    pip install pyslim

And you should be ready to go.

**Optional: installing R.** If you want to have the workshop environment hold
its own version of R, you need to do it *after* all the previous steps - again,
to avoid dependency conflicts with `conda-forge`. At this point, you can safely
type
    
    conda install -c r r-essentials

And R should be installed correctly in your environment.

---------------------------------------

Some conda users have reported a problem with the openblas library and msprime.
The problem manifests something like this:

Traceback (most recent call last):
  File "ts_overlay.py", line 1, in <module>
    import msprime, pyslim
  File "/home/username/anaconda3/envs/slim-workshop/lib/python3.8/site-packages/msprime/__init__.py", line 49, in <module>
    from msprime.provenance import __version__
  File "/home/username/anaconda3/envs/slim-workshop/lib/python3.8/site-packages/msprime/provenance.py", line 25, in <module>
    import _msprime
ImportError: libopenblas.so.0: cannot open shared object file: No such file or directory

The issue here is apparently that conda is installing blas from MKL instead of openblas.  An issue related to this can be found here:

https://github.com/conda-forge/numpy-feedstock/issues/108

The issue has been closed; it is unclear why it continues to bite people, but it sounds like they would welcome new issues being filed by people when this occurs.  In any case, the workaround is apparently to do this:

conda uninstall blas --force --offline 
conda install conda-forge::blas=*=openblas

A discussion of this on slim-discuss can be found here:

https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!msg/slim-discuss/GMVvcp4sjkY/k9EnPGacBQAJ

It pretty much just recapitulates the information above, however.  If someone finds a better fix for this issue (or a way to avoid it arising in the first place!), that feedback would be welcome.

- Ben Haller, 7/7/2020