Installation

Easy Install

For a basic user installation, we provide the RAIL setup script. This script can be downloaded from the RAIL Setup repository.

Run the following:

wget https://github.com/LSSTDESC/rail_setup/releases/latest/download/install_rail.py
python install_rail.py

Follow the prompts for installation. This script installs RAIL in a conda environment [env] (the name you enter when prompted), which is activated via

conda activate [env]

This script will create a new virtual environment on your machine, and install the mininum set of required packages to use RAIL, along with any additional RAIL packages you specify.

Note that even with this script, some RAIL algorithm packages may require additional setup steps. See the Troubleshooting: Algorithm / Architecture Specific Issues section for more details.

Docker Container

If you wish to run RAIL in a containerized environment, we provide a Docker image in the LSSTDESC Container Repository. This Docker image provides a pre-activated Mamba (Conda) environment with all RAIL packages pre-installed, along with some other useful software such as Jupyter.

To pull the Docker image, run the following:

docker pull ghcr.io/lsstdesc/desc-rail:latest

Manual Install

RAIL is actually distributed as several software packages. However, depending on your use case it is likely that you will be working directly with one of the packages.

Some of the RAIL algorithms have dependencies that are sensitive to out-of-date code versions, therefore it is strongly recommended that you create a new dedicated virtual environment for RAIL to avoid problems with pip/conda failing to update some packages that you have previously installed during installation of RAIL. Also, having multiple versions of RAIL in your path can cause difficult to diagnose problems, so we encourage you to make sure that you don’t have an existing version of RAIL installed in your .local area or in your base conda environment.

Note

In the following instructions you will see the use of both pip and conda. We have found that conda is particularly good at creating virtual environments and installing packages that have compiled libraries. Thus we prefer it over pip and venv for those purposes.

Additionally, we use pip to build and install RAIL code from source because conda does not provide that functionality.

Tip

Throughout the installation documentation we make reference to conda as a tool to create a RAIL virtual environment and install compiled dependencies we acknowledge that it can be potentially very slow. Using mamba can be significantly faster, but it is not as widely adopted in the community.

If you would like to experiment with mamba it can be installed with conda install mamba -n base -c conda-forge. The mamba documentation is here.

Exploration

Here we will be installing the source code from rail to access all of the demonstration notebooks, and use that to install all of the other algorithms.

We have included an environment.yml that makes it easy to create a virtual environment named “[env]” that uses conda to install some packages that have compiled libraries.

Generalzsh (e.g., Mac M1+ default)

git clone https://github.com/LSSTDESC/rail.git
cd rail
conda env create -f environment.yml -n [env]  # or mamba env create, which is much faster
conda activate [env]
pip install -e .[dev]

If for some reason the pip install .[dev] fails (e.g.,because of a problem in building the dependencies for one of the algorithms) you can run a more fault-tolerant installation using a rail script:

pip install -e .
rail dev install --package-file rail_packages.yml

At that point you should be able to run the demonstration notebooks, e.g.;

jupyter-notebook examples/estimation_examples/RAIL_estimation_demo.ipynb

Production

Here we will be installing all of the RAIL algorithms into an existing virtual environment “[env]”. To do this we recommend that you install rail from source, to be sure to get the latest version of the conda-reqs.txt file.

Generalzsh (e.g., Mac M1+ default)

git clone https://github.com/LSSTDESC/rail.git
cd rail
conda activate [env]
conda install -n [env] -c conda-forge --file conda-reqs.txt  # or mamba install, which is much faster
pip install .[algos]

Again, if for some reason the pip install .[algos] fails (e.g.,because of a problem in building the dependencies for one of the algorithms) you can run a more fault-tolerant installation using a rail script:

pip install .
rail dev install --package-file rail_packages.yml

Developer Install

To install RAIL for development, refer to the Developer Installation Instructions page.

Adding your kernel to jupyter

If you want to use the kernel that you have just created to run RAIL example demos, then you may need to explicitly add an ipython kernel. You may need to first install ipykernel with conda install ipykernel. You can then add your kernel with the following command, making sure that you have the conda environment that you wish to add activated. From your environment, execute the command: python -m ipykernel install --user --name [name_to_call_new_kernel] (you may or may not need to prepend sudo depending on your permissions). When you next start up Jupyter you should see a kernel with your new name as an option, including using the Jupyter interface at NERSC.

Troubleshooting: Algorithm / Architecture Specific Issues

Before installing a specific algorithm, please make sure to first install pz-rail-base via

pip install pz-rail-base

Installing bpz_lite

For bpz_lite, you should be able to just do

pip install pz-rail-bpz

But if you run into problems you might need to:

• cd to a directory where you wish to clone the DESC_BPZ package and run git clone https://github.com/LSSTDESC/DESC_BPZ.git

• cd to the DESC_BPZ directory and run python setup.py install (add --user if you are on a shared system such as NERSC)

• try pip install pz-rail-bpz again.

Installing Delight

GeneralMac

For Delight you should be able to just do:

pip install pz-rail-delight

Installing FlexZBoost

For FlexZBoost, you should be able to just do

pip install pz-rail-flexzboost

But if you run into problems you might need to:

• install xgboost with the command pip install xgboost==0.90.0

• install FlexCode with pip install FlexCode[all]

Installing fsps

The fsps package available on PyPI does not include the Fortran-based libraries that are actually needed. After you install pz-rail-fsps, upon running any fsps-based algorithms for the first time, you will see a message indicating the specific instructions for properly setting up fsps.

The cause of this is the use of Git submodules in the python-fsps package, which are not handled by pip.

Using GPU-optimization for pzflow

Note that the Creation Module depends on pzflow, which has an optional GPU-compatible installation. For instructions, see the pzflow Github repo.

On some systems that are slightly out of date, e.g. an older version of python’s setuptools, there can be some problems installing packages hosted on GitHub rather than PyPi. We recommend that you update your system; however, some users have still reported problems with installation of subpackages necessary for flexzboost and bpz_lite. If this occurs, try the following procedure:

Once you have installed RAIL, you can import the package (via import rail) in any of your scripts and notebooks. For examples demonstrating how to use the different pieces, see the notebooks in the examples/ directory.