4. Compile from Source

4.1. When to Compile detkit

Generally, it is not required to compile detkit as the installation through pip and conda. You may compile detkit if you want to:

• modify detkit.

• enable debugging mode.

• or, build this documentation.

Otherwise, install detkit through the Python Wheels.

This section walks you through the compilation process.

4.2. Install C++ Compiler (Required)

You can compile detkit with any of the following compilers:

• GCC (Linux, macOS, Windows via MinGW or Cygwin)

• LLVM/Clang (Linux, macOS, Windows via MinGW, or LLVM’s own Windows support) and LLVM/Clang by Apple

• Intel OneAPI (Linux, Windows)

• Microsoft Visual Studio (MSVC) Compiler for C++ (Windows)

• Arm Compiler for Linux (Linux on AARCH64 architecture)

Below are short description of setting up a few major compilers:

Install GNU GCC Compiler

Ubuntu/Debian

sudo apt install build-essential

CentOS 7

sudo yum group install "Development Tools"

RHEL 9

sudo dnf group install "Development Tools"

macOS

sudo brew install gcc libomp

Then, export CC and CXX variables by

export CC=/usr/local/bin/gcc
export CXX=/usr/local/bin/g++

Install Clang/LLVN Compiler

Ubuntu/Debian

sudo apt install clang libomp-dev

CentOS 7

sudo yum install yum-utils
sudo yum-config-manager --enable extras
sudo yum makecache
sudo yum install clang libomp-devel

RHEL 9

sudo dnf install yum-utils
sudo dnf config-manager --enable extras
sudo dnf makecache
sudo dnf install clang libomp-devel

macOS

sudo brew install llvm libomp-dev

Then, export CC and CXX variables by

export CC=/usr/local/bin/clang
export CXX=/usr/local/bin/clang++

Install Intel oneAPI Compiler

To install Intel Compiler see Intel oneAPI Base Toolkit. Once installed, set the compiler’s required environment variables by

UNIX

source /opt/intel/oneapi/setvars.sh

Windows (Powershell)

C:\Program Files (x86)\Intel\oneAPI\setvars.bat

In UNIX, export CC and CXX variables by

export CC=`which icpx`
export CXX=`which icpx`

4.3. Install OpenMP (Required)

OpenMP comes with the C++ compiler installed. However, you may alternatively install it directly on UNIX. Install OpenMP library on UNIX as follows:

Ubuntu/Debian

sudo apt install libgomp1 -y

CentOS 7

sudo yum install libgomp -y

RHEL 9

sudo dnf install libgomp -y

macOS

sudo brew install libomp

Note

In macOS, for libomp versions 15 and above, Homebrew installs OpenMP as keg-only. To utilize the OpenMP installation, you should establish the following symbolic links:

libomp_dir=$(brew --prefix libomp)
ln -sf ${libomp_dir}/include/omp-tools.h  /usr/local/include/omp-tools.h
ln -sf ${libomp_dir}/include/omp.h        /usr/local/include/omp.h
ln -sf ${libomp_dir}/include/ompt.h       /usr/local/include/ompt.h
ln -sf ${libomp_dir}/lib/libomp.a         /usr/local/lib/libomp.a
ln -sf ${libomp_dir}/lib/libomp.dylib     /usr/local/lib/libomp.dylib

4.4. Configure Compile-Time Environment Variables (Optional)

Set the following environment variables as desired to configure the compilation process.

CYTHON_BUILD_IN_SOURCE

By default, this variable is set to 0, in which the compilation process generates source files outside of the source directory, in /build directry. When it is set to 1, the build files are generated in the source directory. To set this variable, run

UNIX

export CYTHON_BUILD_IN_SOURCE=1

Windows (Powershell)

$env:CYTHON_BUILD_IN_SOURCE = "1"

Hint

If you generated the source files inside the source directory by setting this variable, and later you wanted to clean them, see Clean Compilation Files.

CYTHON_BUILD_FOR_DOC

Set this variable if you are building this documentation. By default, this variable is set to 0. When it is set to 1, the package will be built suitable for generating the documentation. To set this variable, run

UNIX

export CYTHON_BUILD_FOR_DOC=1

Windows (Powershell)

$env:CYTHON_BUILD_FOR_DOC = "1"

Warning

Do not use this option to build the package for production (release) as it has a slower performance. Building the package by enabling this variable is only suitable for generating the documentation.

Hint

By enabling this variable, the build will be in-source, similar to setting CYTHON_BUILD_IN_SOURCE=1. To clean the source directory from the generated files, see Clean Compilation Files.

DEBUG_MODE

By default, this variable is set to 0, meaning that detkit is compiled without debugging mode enabled. By enabling debug mode, you can debug the code with tools such as gdb. Set this variable to 1 to enable debugging mode by

UNIX

export DEBUG_MODE=1

Windows (Powershell)

$env:DEBUG_MODE = "1"

Attention

With the debugging mode enabled, the size of the package will be larger and its performance may be slower, which is not suitable for production.

LONG_INT

When set to 1, long integers are used. By default, this variable is set to 0.

UNIX

export LONG_INT=1

Windows (Powershell)

$env:LONG_INT = "1"

UNSIGNED_LONG_INT

When set to 1, unsigned long integers are used. By default, this variable is set to 0.

UNIX

export UNSIGNED_LONG_INT=1

Windows (Powershell)

$env:UNSIGNED_LONG_INT = "1"

USE_OPENMP

To enable shared-memory parallelization uisng OpenMP, set this variable to 1 and make sure OpenMP is installed (see Install OpenMP). Setting this variable to 0 disables this feature. By default, this variable is set to 0.

UNIX

export USE_OPENMP=1

Windows (Powershell)

$env:USE_OPENMP = "1"

COUNT_PERF

When set to 1, the processor instructions are counted and returned by each function This functionalit is only available on Linux and requires that perf_tool is installed. By default, this variable is set to 1.

UNIX

export COUNT_PERF=1

USE_LOOP_UNROLLING

When set to 1, matrix and vector multiplications are peroformed in chunks of 5 conseqqutive addition-multiplication operations. By default, this variable is set to 1.

UNIX

export USE_LOOP_UNROLLING=1

Windows (Powershell)

$env:USE_LOOP_UNROLLING = "1"

USE_SYMMETRY

When set to 1, Gramian matrices are computed using symmetry of the Gamian matrix. By default, this variable is set to 1.

UNIX

export USE_SYMMETRY=1

Windows (Powershell)

$env:USE_SYMMETRY = "1"

4.5. Compile and Install

Get the source code of detkit from the GitHub repository by

git clone https://github.com/ameli/detkit.git
cd detkit

To compile and install, run

python -m pip install .

The above command may need sudo privilege.

A Note on Using sudo

If you are using sudo for the above command, add -E option to sudo to make sure the environment variables (if you have set any) are accessible to the root user. For instance

UNIX

export CYTHON_BUILD_FOR_DOC=1
sudo -E python -m pip install .

Windows (Powershell)

$env:CYTHON_BUILD_FOR_DOC = "1"
sudo -E python setup.py install

Once the installation is completed, check the package can be loaded by

cd ..  # do not load detkit in the same directory of the source code
python -c "import detkit"

Attention

Do not load detkit if your current working directory is the root directory of the source code of detkit, since python cannot load the installed package properly. Always change the current directory to somewhere else (for example, cd .. as shown in the above).

Cleaning Compilation Files

If you set CYTHON_BUILD_IN_SOURCE or CYTHON_BUILD_FOR_DOC to 1, the output files of Cython’s compiler will be generated inside the source code directories. To clean the source code from these files (optional), run the following:

python setup.py clean