In adition to these instructions, we also provide a complete step-by-step installation guide> for CIANNA and its dependencies on a fresh Ubuntu 20.04.

Pip Installation

The most straightforward way to install CIANNA is by using the python package installer pip. For this, one has to clone the CIANNA repository and then install it using pip as follows : 
git clone https://github.com/Deyht/CIANNA.git
cd CIANNA
python3 -m pip install -v .
CIANNA is then installed in the with other python3 packages and can be loaded in any python script through a simple : 
import CIANNA
It is also possible to pass options to pip using the more comprehensive command: 
CMAKE_ARGS="-D[OPTION]=[VALUE]" python3 -m pip install -v .
All possible options being detailed in the following cmake installation section.

It is worth noting that this way of installing CIANNA requires cmake (at least version 3.16) to be available to the user. Please note that issues may arise depending on how python3 packages are handled or if cmake is installed both on the system and as a python package. In which case the easiest solution is to create a dedicated virtual environnment with "python3 -m venv ./[venv-name] then activate it with "source ./[venv-name]/bin/activate" and then perform the previously described installation (in this new virtual environment you may need to install numpy and other basic python packages).

Installation using cmake

If you have access to the cmake library (version 3.16 or later), it can be used to install CIANNA with minimal efforts: 
git clone https://github.com/Deyht/CIANNA.git
cd CIANNA
cmake -B build
cmake --build build
The library will be installed in CIANNA/build/ and can be loaded in any python script using: 
import sys
sys.path.insert(0,glob.glob('path/to/CIANNA/build/')[-1])
import CIANNA
It is also possible to pass compilation option to cmake using the more comprehensive command: 
cmake -B build -D [OPTION1]=[value1] -D [OPTION2]=[value2] ...
cmake --build build
The following compilation options are available:

Manual Installation

Dependencies

CIANNA is coded in C99 and requires at least a C compiler. Additionally, it supports several computing methods:

More details are provided on the wiki page.

Note: verify that you updated your PATH and LD_LIBRARY_PATH with the appropriate elements for OpenBLAS and CUDA before compiling CIANNA.

Compilation and installation

  1. Clone the git repository

  2. Edit the shell script compile.cp to update the few paths regarding your system environment
    • Check the various paths (GCC, OpenBLAS, CUDA, ...)
    • (CUDA only) Check all the references to cublas and nvcc Edit cuda_arg="...":
      • Update the -arch parameter to fit your GPU architecture (sm_35 and below are not supported)
      • Add "-D CUDA_OLD" if using CUDA < 11.1
      • Add "-D GEN_VOLTA" (some Pascal cards, Volta and Turing) or -D GEN_AMPERE (Ampere, Ada Lovelace, Hopper, and Blackwell) for various mixed-precision type support

  3. Use the compile.cp command with the appropriate arguments to compile the source code. Each of the following optional arguments adds support for a given compute meth
    • CUDA: compile additional CUDA files
    • OPEN_MP: add multi-thread for some operations (for C_NAIV and C_BLAS)
    • BLAS: add OpenBLAS gemm (multi-threaded) operations
    • PY_INTERF: build the Python interface at the end (need modifications described in step 5)

    Multiple arguments can be used simultaneously:

    ./compile.cp CUDA OPEN_MP BLAS PY_INTERF

    These parameters allow the use of specific features; they do not enable them. For example, one can compile using all the arguments and choose to use CUDA or BLAS at execution time.


  4. The previous compilation script creates a main executable that trains a simple network to perform MNIST classification (note that it relies on data downloaded by the MNIST Python example script). The C interface works by editing src/main.c and re-compiling with compile.cp.

Python interface steps (optional)

Python dependencies: building the python interface requires to have the setuptools package installed. It also requires the Numpy library.

First, check if any path or compile option needs to be adapted for your need in src/python_module_setup.py (GCC, CUDA, OpenBLAS, ...). Then, the interface can be built automatically by adding the PY_INTERF argument to the compile.cp command (re-compile with all arguments), or manually by going into the src directory and executing:

python3 python_module_setup.py build

To use the locally built interface, the explicit build path must be given to the Python script (see example).

To provide system-wide access to the framework (must also be done when using the PY_INTERF option), execute into the src directory:

sudo python3 python_module_setup.py install

The Python interface module has no dependency on main.c. Any Python code invoking CIANNA can be written without a new compilation.

To remove a system-wide install of CIANNA (e.g., to update to a new version), go to /usr/local/lib/pythonX.X/dist-packages/ (or the corresponding setuptools path for your distro), and delete any CIANNA-related files/directories.

Dockerfile installer

We provide different Dockerfiles corresponding to the available compute methods.

  • CPU compute with pre-compiled OpenBLAS (lightest):
  • CPU compute with locally-compiled OpenBLAS (medium):
  • GPU compute with CUDA (heavy): not available yet

To use these files, you must first install Docker. See .

To start the installation through one of the Dockerfile, use:

docker build -f cianna-cpu.Dockerfile -t cianna-cpu-precompiled-openblas:1.0 .

To run the installed docker, use:

docker run -it --init cianna-cpu:1.0

APT install

We recently added the option to install cianna through APT. It should work for Ubuntu from 20.04 to 24.04, although only minimal testing has been carried out so far. Note that this installation will allow access to CPU NAIV and CPU BLAS compute methods but it does not allow GPU CUDA at the moment.

sudo add-apt-repository ppa:dcornu/cianna
sudo apt update
sudo apt install cianna-cpu-blas

Once installed, you should be able to call "import CIANNA" in your Python scripts.