How to install

Creating an environment

We recommend installing conda if you don’t already have it. Follow instructions at https://github.com/conda-forge/miniforge/#download

Once you have that working, you can test that you can create an environment and activate it.

Below we then provide a few different ways of getting Paicos up and running inside your conda environment:

Option 1: Installing directly via PyPi or conda-forge

This is probably the simplest way of installing Paicos. Note however, that these installations do not include the tests, examples and example data. You can always download these separately or simply peruse the examples documented online.

Installation using the conda-forge distribution

Copy-paste below commands into a terminal:

conda create -q -n paicos-conda python=3.11 --yes
conda activate paicos-conda
conda install paicos --yes
# conda install pytest pytest-order cython --yes # Uncomment this line to also install developer dependencies

Installation using the PyPi distribution

Copy-paste below commands into a terminal:

conda create -q -n paicos-pypi python=3.10 --yes
conda activate paicos-pypi
pip install paicos[dev]

On MacOs you might have to do something like this (see details below in “Compiling on MacOs”)

CC=gcc-13 pip install paicos[dev]

Check that the installation succeeded

If the installation succeeded then you can proceed:

# Check if installation worked and that you can import Paicos 
python -c "import paicos"

Option 2 (Developer installation): Compile the code and add its path to your PYTHONPATH

You should use this option if you intend to make changes to Paicos ([this would be very welcome, see here for details on making contributions])(https://github.com/tberlok/paicos/blob/main/.github/CONTRIBUTING.md)

git clone git@github.com:tberlok/paicos.git
cd paicos
pip install -r requirements.txt
pip install -r dev_requirements.txt
make

Add the directory to your PYTHONPATH, e.g., I have

export PYTHONPATH=$PYTHONPATH:/Users/berlok/projects/paicos

in my .bash_profile. Finally, run the tests

make checks

Compiling on MacOs

You will need an openmp-enabled compiler. On MacOs, you can install gcc via homebrew. You can then either modify setup.py with your compiler option, .e.g.,

if sys.platform == 'darwin':
    os.environ['CC'] = 'gcc-13'
    os.environ['CXX'] = 'g++-13'

or by running CC=gcc-13 make instead of simply make.

If you have installed gcc via homebrew, then you can get your compiler version by running brew info gcc, which you can use to modify the instructions above accordingly.

Compiling Paicos inside a notebook

It can sometimes also be useful to compile Paicos inside a Jupyter notebook, i.e., by running a notebook cell with the following content:

%%bash

cd /path/to/paicos/
make clean
make

GPU/CUDA requirements

The visualization routines that run on GPU require installing CuPy (a drop-in replacement for NumPy that runs on the GPU) and Numba CUDA (just-in-time compilation of kernel and device functions on the GPU). These packages only work on CUDA-enabled GPUs, which means that you need a recent Nvidia GPU. An Nvidia GPU with good FP64 performance is desirable.

These packages (CuPy and Numba) are not automatically included in Paicos. Up-to-date instructions for installing them can be found at:

CuPy: https://docs.cupy.dev/en/stable/install.html
Numba: https://numba.readthedocs.io/en/stable/cuda/overview.html#supported-gpus

At the time of writing, we have had success installing for CUDA version 11.2 using

pip install numba
pip install cupy-cuda112

and then setting the path to the CUDA installation in .bashrc as e.g. (substitute with the path to the CUDA installation on your system)

export CUDA_HOME=/software/astro/cuda/11.2 # numba
export CUDA_PATH=/software/astro/cuda/11.2 # cupy

If it worked, you should be able to do this:

import cupy as cp
from numba import cuda

The parts of Paicos that are GPU-enabled need to be initialized, i.e., running

import paicos as pa
pa.gpu_init()

will enable the GPU-code. You can add

# Whether to load GPU/cuda functionality on startup
pa.load_cuda_functionality_on_startup(True)

to your paicos_user_settings.py (see details under ‘User configuration’) to do this automatically when paicos is imported.