.. _installation-guide:


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`_
- `Required packages`_
- `PyPI`_
- `Ubuntu 24.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`_

---



Download
--------

The zip file containing *XCLASS* (version 1.4.3) can be downloaded
`here <https://xclass.astro.uni-koeln.de/sites/xclass/files/software/pip/xclass_pip_off.zip>`_.

*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

.. code:: shell

    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 <https://launchpad.net/~deadsnakes/+archive/ubuntu/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 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

    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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. 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
     - 7.1.1
   * - matplotlib
     - 3.10.7
   * - numpy
     - 2.3.4
   * - Pillow
     - 10.4.0
   * - regions
     - 0.11
   * - setuptools
     - 74.1.2
   * - xclass
     - 1.4.3
   * - emcee
     - 3.1.6
   * - h5py
     - 3.11.0
   * - lmfit
     - 1.3.4
   * - lxml
     - 6.0.2
   * - meson
     - 1.5.1
   * - ninja
     - 1.11.1.4
   * - pandas
     - 2.3.3
   * - pip
     - 25.3
   * - PyQt5
     - 5.15.11
   * - scikit-image
     - 0.24.0
   * - scipy
     - 1.16.3
   * - spectral-cube
     - 0.6.6
   * - ultranest
     - 4.4.0

----



Installation Steps Summary
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

    # 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
------------------------------------

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):

.. 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.12

.. Install Python dependencies (specify versions to ensure compatibility with XCLASS):

.. .. code-block:: bash

..     /opt/homebrew/bin/python3.12 -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 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``:

.. code-block:: bash

    source ~/.bashrc


Perform Final Installation
^^^^^^^^^^^^^^^^^^^^^^^^^^

Switch to the ``xclass_pip_off`` root directory and run:

.. code-block:: bash

    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.

.. code-block:: bash

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

or

.. code-block:: bash

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