User Installation
Contents
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. 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, specifically:
Install a “miniconda” base system (not the full Anaconda distribution).
Set the conda-forge channel to be the top priority package source, with strict ordering if available.
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”.