Installation

This section describes the installation procedure for XCLASS and gives information on how to install XCLASS on Ubuntu 24.04 LTS and macOS with Apple Silicon (M3 chip)

—

Table of Contents

—

Download

The zip file containing XCLASS (version 1.4.3) can be downloaded here.

XCLASS has only been tested on Linux and Mac systems. We have no experience with Windows!

Required packages

XCLASS requires the following packages:

  • gcc (version 7.4.0 or newer),

  • gfortran (version 7.4.0 or newer) with OpenMP,

  • OpenMPI (version 1.8.6),

  • python 3.x (recommended >= 3.12),

  • setuptools (version 74.1.2),

  • numpy (version 2.3.4),

  • Pillow (version 11.3.0),

  • scipy (version 1.16.3 or newer),

  • matplotlib (version 3.10.7),

  • APLpy (version 2.2.0),

  • astropy (version 7.1.1),

  • spectral-cube (version 0.6.6 or newer),

  • regions (version 0.11),

  • PyQt5 (version 5.15.11 or newer),

  • h5py (version 3.11.0 or newer),

  • lxml (version 6.0.2 or newer),

  • emcee (version 3.1.6 or newer),

  • ultranest (version 4.4.0 or newer),

  • libraries: libz, libm, libdl, libcurl, libpthread, and libgomp.

PyPI

In order to install the XCLASS package just execute

python3 -m pip install xclass_pip_off/

Ubuntu 24.04 LTS Installation Process

The following section (created by Chung-Chen Chang) contains detailed information about the installation steps for XCLASS (v1.4.3) on Ubuntu 24.04 LTS. The installation processes, problems encountered, and solutions are described here.

Preparation

  • Operating System: Ubuntu 24.04 LTS

  • Python Version: 3.12.x (recommended: deadsnakes PPA)

  • OpenMPI Version: 1.8.6 (needs to be compiled manually)

  • XCLASS Source: Offline installation package xclass_pip_off/

  • Note: This guide does not use virtual environments; all operations are performed on the main system. Please assess the risks.

System and Basic Tools Installation

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3-dev python3-pip gfortran build-essential libopenmpi-dev \
openmpi-bin libopenmpi-dev python3-pyqt5 texlive-extra-utils libx11-6 libx11-xcb1 libxcb1 \
libxcb-xinerama0 libxkbcommon-x11-0 libgl1-mesa-glx libsm6 libxrender1 libfontconfig1 \
libxext6 git cmake libopenblas-dev libcurl4-openssl-dev cmake libfftw3-dev libgsl-dev \
libhdf5-dev liblapack-dev libblas-dev zlib1g-dev libgomp1

Python 3.12 Installation and Setup

sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install -y python3.12 python3.12-dev python3.12-venv python3-pip
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1
sudo update-alternatives --config python3  # Select Python 3.12

OpenMPI 1.8.6 Compilation and Installation

mkdir -p ~/tmp/openmpi_install && cd ~/tmp/openmpi_install
wget https://www.open-mpi.org/software/ompi/v1.8/downloads/openmpi-1.8.6.tar.gz
tar -xzf openmpi-1.8.6.tar.gz && cd openmpi-1.8.6
./configure --prefix=/opt/openmpi-1.8.6
make -j$(nproc)
echo 'export PATH="/opt/openmpi-1.8.6/bin:$PATH"' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH="/opt/openmpi-1.8.6/lib:$LD_LIBRARY_PATH"' >> ~/.bashrc
source ~/.bashrc

pip Path Setup

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Common Issues and Solutions During Installation

Pillow Import Error

  • Error Message: ImportError: cannot import name '_imaging' from 'PIL'

  • Solution:

    python3 -m pip uninstall Pillow PIL -y
python3 -m pip install Pillow

Installation Steps Summary

# Install XCLASS offline package
cd ~/Desktop/xclass/xclass_pip_off
python3 -m pip install . -v

Testing the Installation

Enter the Python interactive shell and test imports:

import xclass
from xclass import task_DatabaseQuery, task_myXCLASS, task_myXCLASSFit
from xclass.task_myXCLASSFit import task_myXCLASSMapFit
# All imports should succeed without errors.

Installing XCLASS (v1.4.3) on Mac M3

The following section (created by Chung-Chen Chang) contains detailed information about the installation steps for XCLASS (v1.4.3) on macOS with Apple Silicon (M3 chip). The installation processes, problems encountered, and solutions are described here.

Problem Overview

On Mac M3, following the official pip installation guide directly will result in multiple compilation errors, mainly due to incompatibilities and path issues among Fortran/C compilers, Python interface (numpy.f2py), Xcode Command Line Tools SDK, and Homebrew-installed GCC/Gfortran.

Common errors include:

  • ModuleNotFoundError: No module named 'numpy' (numpy not found during compilation)

  • unknown type name 'FILE', unknown type name 'size_t' (C compilation errors)

  • gfortran: error: unrecognized command-line option '--fcompiler=gnu95' (Fortran compilation error)

Prerequisites (Install Dependencies via Homebrew)

Install Homebrew (if not already installed):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install required dependencies:

brew install gcc@12
brew install open-mpi
brew install python@3.12

XCLASS Environment Variable Setup

Add environment variables to your .bashrc (not .zshrc):

# --- XCLASS Environment Variable Setup ---

# Set Fortran and C compiler paths, explicitly pointing to Homebrew-installed versions
export XCLASS_FORTRAN_COMPILER="/opt/homebrew/bin/gfortran"
export FC="/opt/homebrew/bin/gfortran"
export CC="/opt/homebrew/bin/gcc-12"

# Force GCC to use its own standard library header paths to avoid conflicts with system SDK
export CFLAGS="-I/opt/homebrew/Cellar/gcc@12/$(brew list --version gcc@12 | cut -d' ' -f2)/lib/gcc/aarch64-apple-darwin$(uname -r | cut -d'.' -f1)/12/include -isystem /usr/local/include -isystem /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include -isystem /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include"
export CPPFLAGS="-I/opt/homebrew/Cellar/gcc@12/$(brew list --version gcc@12 | cut -d' ' -f2)/lib/gcc/aarch64-apple-darwin$(uname -r | cut -d'.' -f1)/12/include -isystem /usr/local/include -isystem /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include -isystem /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include"

# Set linker flags
export LDFLAGS="-L/opt/homebrew/lib -lcurl -lz"

# Ensure Homebrew's bin directory and Homebrew Python's bin directory are at the front of PATH for priority
export PATH="/opt/homebrew/bin:$PATH"
export PATH="/opt/homebrew/opt/python@3.12/bin:$PATH"

# (Optional but recommended) Increase OpenMP stack size for parallel computation
ulimit -s unlimited
export KMP_STACKSIZE='3999M'
export OMP_STACKSIZE='3999M'
export GOMP_STACKSIZE='3999M'
# --- End of XCLASS Environment Variable Setup ---

Reload .bashrc:

source ~/.bashrc

Perform Final Installation

Switch to the xclass_pip_off root directory and run:

cd ~/yourpathto/xclass/xclass_pip_off/
python3.12 -m pip install . -v

If there are no fatal errors, XCLASS is successfully installed.

Modify XCLASS Source Makefile Files

The XCLASS installation script setup.py calls Makefiles in different subdirectories to compile Fortran code and the Python interface. These Makefiles need to find the command for executing f2py. If the installation procedure fails, please use the environment variable XCLASS_F2PY_COMPILER to specify the location of the f2oy command, i.e.

export XCLASS_F2PY_COMPILER="/opt/homebrew/bin/python3.12 -m numpy.f2py"

or

cd ~/yourpathto/xclass/xclass_pip_off/
export XCLASS_F2PY_COMPILER="/opt/homebrew/bin/python3.12 -m numpy.f2py"
python3.12 -m pip install . -v