Clad Installation

This page covers both installation and usage details for Clad.

At the moment, LLVM/Clang 7.0.x - 17.0.x are supported.

Conda Installation

Clad is available using conda <https://anaconda.org/conda-forge/clad>:

conda install -c conda-forge clad

If you have already added conda-forge as a channel, the -c conda-forge is unnecessary. Adding the channel is recommended because it ensures that all of your packages use compatible versions:

conda config --add channels conda-forge
conda update --all

Building from source

Building from source (example was tested on Ubuntu 20.04 LTS)

#sudo apt install clang-11 libclang-11-dev llvm-11-tools llvm-11-dev
sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
sudo -H pip install lit
git clone https://github.com/vgvassilev/clad.git
cd clad
mkdir build && cd build
cmake ../ -DLLVM_DIR=/usr/lib/llvm-11 -DLLVM_EXTERNAL_LIT="``which lit``"
make && sudo make install

Building from source (example was tested on macOS Catalina 10.15.7)

brew install llvm@12
brew install python
python -m pip install lit
git clone https://github.com/vgvassilev/clad.git clad
mkdir build; cd build
cmake ../clad -DLLVM_DIR=/usr/local/Cellar/llvm/12.0.0_1/lib/cmake/llvm -DClang_DIR=/usr/local/Cellar/llvm/12.0.0_1/lib/cmake/clang -DLLVM_EXTERNAL_LIT="``which lit``"
make && make install
make check-clad

Run the Clad tests:

make -j8 check-clad

How to use Clad

With Jupyter Notebooks

xeus-cling <https://github.com/jupyter-xeus/xeus-cling> provides a Jupyter kernel for C++ with the help of the C++ interpreter Cling and the native implementation of the Jupyter protocol xeus. Within the xeus-cling framework, Clad can enable automatic differentiation (AD) such that users can automatically generate C++ code for their computation of derivatives of their functions.

To set up your environment, use:

mamba create -n xeus-clad -c conda-forge clad xeus-cling jupyterlab
conda activate xeus-clad
jupyter notebook

The above will launch Jupyter with 3 Clad attached kernels for C++ 11/14/17.

Try out a Clad tutorial interactively in your browser through binder, here <https://mybinder.org/v2/gh/vgvassilev/clad/master?labpath=%2Fdemos%2FJupyter%2FIntro.ipynb>.

As a plugin for Clang

Since Clad is a Clang plugin, it must be properly attached when the Clang compiler is invoked. First, the plugin must be built to get libclad.so (or .dylib). Thus, to compile SourceFile.cpp with Clad enabled use:

clang -cc1 -x c++ -std=c++11 -load /full/path/to/lib/clad.so -plugin clad SourceFile.cpp

To compile using Clang < 10 , for example with clang-9, use:

clang-9 -I /full/path/to/include/  -x c++ -std=c++11 -fplugin=/full/path/to/lib/clad.so SourceFile.cpp -o sourcefile -lstdc++ -lm

To save the Clad generated derivative code to Derivatives.cpp add:

-Xclang -plugin-arg-clad -Xclang -fgenerate-source-file

To print the Clad generated derivative add:

-Xclang -plugin-arg-clad -Xclang -fdump-derived-fn

Note: Clad does not work with the Apple releases of Clang