.. _installation-guide: XCLASS Installation Guide ========================= This section is divided into two parts, detailing the installation steps for XCLASS (v1.4.3) on Ubuntu 22.04 LTS and Apple Silicon (M3) macOS. The installation processes, encountered issues, and solutions for the two systems are described separately. --- Table of Contents ----------------- - `Ubuntu 22.04 LTS Installation Process`_ - `Common Issues and Solutions During Installation`_ - `Recommended Dependency Versions`_ - `Installation Steps Summary`_ - `Testing the Installation`_ - `Installing XCLASS (v1.4.3) on Mac M3`_ --- Ubuntu 22.04 LTS Installation Process ------------------------------------- Preparation ^^^^^^^^^^^ - **Operating System:** Ubuntu 22.04 LTS - **Python Version:** 3.10.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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash sudo apt update && sudo apt upgrade -y sudo apt install -y build-essential git cmake gfortran libfftw3-dev libgsl-dev \ libhdf5-dev liblapack-dev libblas-dev zlib1g-dev libcurl4-openssl-dev libgomp1 Python 3.10 Installation and Setup ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash sudo add-apt-repository ppa:deadsnakes/ppa -y sudo apt update sudo apt install -y python3.10 python3.10-dev python3.10-venv python3-pip sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1 sudo update-alternatives --config python3 # Select Python 3.10 OpenMPI 1.8.6 Compilation and Installation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash 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 ^^^^^^^^^^^^^^ .. code-block:: bash 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:** .. code-block:: bash python3 -m pip uninstall Pillow PIL -y python3 -m pip install Pillow setuptools Version Incompatibility ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - **Error Message:** ``AttributeError: install_layout`` - **Solution:** .. code-block:: bash sudo python3 -m pip uninstall setuptools -y sudo python3 -m pip install setuptools==58.0.4 matplotlib API Conflict ^^^^^^^^^^^^^^^^^^^^^^^ - **Error Message:** ``ImportError: cannot import name 'register_cmap'`` - **Solution:** .. code-block:: bash python3 -m pip install matplotlib==3.5.3 NumPy Major Version Incompatibility ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - **Error Message:** ``A module that was compiled using NumPy 1.x cannot be run in NumPy 2.x`` - **Solution:** .. code-block:: bash python3 -m pip install numpy==1.25.0 astropy and regions Dependency Conflict ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - **Solution:** .. code-block:: bash python3 -m pip install astropy==5.1 regions==0.10 ---- Recommended Dependency Versions ------------------------------- .. list-table:: :header-rows: 1 * - Package - Version * - APLpy - 2.2.0 * - astropy - 5.1 * - matplotlib - 3.5.3 * - numpy - 1.25.0 * - Pillow - 11.3.0 * - regions - 0.10 * - setuptools - 58.0.4 * - xclass - 1.4.3 ---- Installation Steps Summary -------------------------- .. code-block:: bash # 1. Uninstall potentially conflicting packages python3 -m pip uninstall Pillow matplotlib numpy astropy setuptools -y # 2. Install exact versions of core dependencies python3 -m pip install setuptools==58.0.4 numpy==1.25.0 matplotlib==3.5.3 astropy==5.1 Pillow==11.3.0 # 3. Install other dependencies python3 -m pip install scipy spectral_cube regions PyQt5 h5py lxml emcee ultranest # 4. 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: .. code-block:: python 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 ------------------------------------ **Goal:** Successfully install the XCLASS software package and all required components on macOS with Apple Silicon (M3 chip). 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): .. code-block:: bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" Install required dependencies: .. code-block:: bash brew install gcc@12 brew install open-mpi brew install python@3.10 Install Python dependencies (specify versions to ensure compatibility with XCLASS): .. code-block:: bash /opt/homebrew/bin/python3.10 -m pip install numpy==1.25.0 scipy matplotlib==3.5.3 astropy==5.1 .. note:: These package versions are chosen based on XCLASS official recommendations and compatibility tests to avoid installation or runtime errors due to API changes in newer versions. XCLASS Environment Variable Setup ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Add environment variables to your ``.bashrc`` (not ``.zshrc``): .. code-block:: bash # --- XCLASS Environment Variable Setup --- # Set Fortran and C compiler paths, explicitly pointing to Homebrew-installed versions 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.10/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``: .. code-block:: bash source ~/.bashrc 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 be manually modified to ensure numpy.f2py is always invoked via the Homebrew-installed Python 3.10. Please make precise modifications to the following two files: - ``~/yourpathto/xclass_pip_off/xclass/xclass/interface/Makefile`` - ``~/yourpathto/xclass_pip_off/xclass/xclass/lite/Makefile`` Modification steps (repeat for each file): a. Enter the corresponding directory: .. code-block:: bash cd ~/yourpathto/xclass_pip_off/xclass/xclass/interface/ b. Backup the Makefile: .. code-block:: bash cp Makefile Makefile.bak c. Edit the Makefile: .. code-block:: bash vim Makefile d. Modify the definition of FCPY: Find or add the following line to ensure FCPY points to Homebrew Python's f2py: .. code-block:: make # interface/Makefile # set f2py compiler and flags FCPY = /opt/homebrew/bin/python3.10 -m numpy.f2py And in lite, redefine FC as FCPY: .. code-block:: make # lite/Makefile # set f2py compiler and flags FCPY = /opt/homebrew/bin/python3.10 -m numpy.f2py e. Modify the invocation of f2py and sig rules in lite/Makefile: Before (old): .. code-block:: make # lite/Makefile f2py: $(FC) -c $(FFLAGS) -m $(EXEC) $(FSRC) sig: $(FC) -h CalculateXCLASS.pyf -m $(EXEC) $(FSRC) After (new): .. code-block:: make # lite/Makefile f2py: $(FCPY) -c $(FFLAGS) -m $(EXEC) $(FSRC) sig: $(FCPY) -h CalculateXCLASS.pyf -m $(EXEC) $(FSRC) ---- Perform Final Installation ^^^^^^^^^^^^^^^^^^^^^^^^^^ Switch to the ``xclass_pip_off`` root directory and run: .. code-block:: bash cd ~/yourpathto/xclass/xclass_pip_off/ python3.10 -m pip install . -v If there are no fatal errors, XCLASS is successfully installed.