# User Installation

If you are using TOAST to build simulation and analysis workflows,
including mixing built-in functionality with your own custom tools, then
you can use one of these methods to get started. If you want to hack on
the TOAST package itself, see the section `devinstall`{.interpreted-text
role="ref"}.

If you want to use TOAST at NERSC, see `nersc`{.interpreted-text
role="ref"}.

## Pip Binary Wheels

If you already have a newer Python3 (\>= 3.7), then you can install
pre-built TOAST packages from PyPI. You should always use virtualenv or
similar tools to manage your python environments rather than
pip-installing packages as root.

On Ubuntu Linux, you should install these minimal packages:

    apt update
    apt install python3 python3-pip python3-venv

On Redhat / Centos we need to take extra steps to install a recent
python3:

    yum update
    yum install centos-release-scl
    yum install rh-python37
    scl enable rh-python37 bash

On MacOS, you can use homebrew or macports to install a recent python3.
Now verify that your python is at least 3.7:

    python3 --version

Next create a virtualenv (name it whatever you like):

    python3 -m venv ${HOME}/cmb

Now activate this environment:

    source ${HOME}/cmb/bin/activate

Within this virtualenv, update pip to the latest version. This is needed
in order to install more recent wheels from PyPI:

    python3 -m pip install --upgrade pip

Next, use pip to install toast and its requirements:

    pip install toast

At this point you have toast installed and you can use it from serial
scripts and notebooks. If you want to enable effective parallelism with
toast (useful if your computer has many cores), then you need to install
the mpi4py package. This package requires MPI compilers (usually MPICH
or OpenMPI). Your system may already have some MPI compilers installed-
try this:

    which mpicc
    mpicc -show

If the mpicc command is not found, you should use your OS package
manager to install the development packages for MPICH or OpenMPI. Now
you can install mpi4py:

    pip install mpi4py

For more details about custom installation options for mpi4py, read the
[documentation for that
package](https://mpi4py.readthedocs.io/en/stable/install.html). You can
test your TOAST installation by running the unit test suite:

    python -c 'import toast.tests; toast.tests.run()'

And test running in parallel with:

    mpirun -np 2 python -c 'import toast.tests; toast.tests.run()'

The runtime configuration of toast can also be checked with an included
script:

    toast_env

## Conda Packages

If you already use the conda python stack, then you can install TOAST
and all of its optional dependencies with the conda package manager. The
conda-forge ecosystem allows us to create packages that are built
consistently with all their dependencies. If you already have Anaconda /
miniconda installed **and** it is a recent version, then skip ahead to
\"activating the root environment below\".

If you are starting from scratch, we recommend following the [setup
guidelines used by
conda-forge](https://conda-forge.org/docs/user/introduction.html#how-can-i-install-packages-from-conda-forge),
specifically:

> 1.  Install a \"miniconda\" base system (not the full Anaconda
>     distribution).
> 2.  Set the conda-forge channel to be the top priority package source,
>     with strict ordering if available.
> 3.  Leave the base system (a.k.a. the \"root\" environment) with just
>     the bare minimum of packages.
>
> 4\. Always create a new environment (i.e. not the base one) when
> setting up a python stack for a particular purpose. This allows you to
> upgrade the conda base system in a reliable way, and to wipe and
> recreate whole conda environments whenever needed.

Here are the detailed steps of how you could do this from the UNIX
shell, installing the base conda system to `${HOME}/conda`. First
download the installer. For OS X you would do:

    curl -SL \
    https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh \
    -o miniconda.sh

For Linux you would do this:

    curl -SL \
    https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh \
    -o miniconda.sh

Next we will run the installer. The install prefix should not exist
previously:

    bash miniconda.sh -b -p "${HOME}/conda"

Now load this conda \"root\" environment:

    source ${HOME}/conda/etc/profile.d/conda.sh
    conda activate

We are going to make sure to preferentially get packages from the
conda-forge channel:

    conda config --add channels conda-forge
    conda config --set channel_priority strict

Next, we are going to create a conda environment for a particular
purpose (installing TOAST). You can create as many environments as you
like and install different packages within them- they are independent.
In this example, we will call this environment \"toast\", but you can
call it anything:

    conda create -y -n toast

Now we can activate our new (and mostly empty) toast environment:

    conda activate toast

Finally, we can install the toast package:

    conda install python=3 toast

Assuming this isthe only conda installation on your system, you can add
the line `source ${HOME}/conda/etc/profile.d/conda.sh` to your shell
resource file (usually `~/.bashrc` on Linux or `~/.profile` on OS X).
You can read many articles on login shells versus non-login shells and
decide where to put this line for your specific use case.

Now you can always activate your toast environment with:

    conda activate toast

And leave that environment with:

    conda deactivate

If you want to use other packages with TOAST (e.g. Jupyter Lab), then
you can activate the toast environment and install them with conda. See
the conda documentation for more details on managing environments,
installing packages, etc.

If you want to use PySM with TOAST for sky simulations, you should
install the `pysm3` and `libsharp` packages. For example:

    conda install pysm3 libsharp

If you want to enable effective parallelism with toast, then you need to
install the mpi4py package:

    conda install mpi4py

As mentioned previously, you can test your TOAST installation by running
the unit test suite:

    python -c 'import toast.tests; toast.tests.run()'

And test running in parallel with:

    mpirun -np 2 python -c 'import toast.tests; toast.tests.run()'

## Something Else

If you have a custom install situation that is not met by the above
solutions, then you should follow the instructions below for a
\"Developer install\".