Get a free speed-up estimate
XAD documentation

Install for C++

XAD is open source under AGPL-3.0, to try, for research and for open source. Using it in production? See when a subscription applies.

Prerequisites

Windows
  • CMake, version 3.15 or newer
  • Compiler/IDE options: Visual Studio 2019 or newer (with Clang or Microsoft compilers)
  • Git client

For Windows, we recommend the latest Visual Studio IDE with its integrated CMake support.

Linux
  • CMake, version 3.15 or newer
  • Compiler Options:
    • GCC 7 or newer
    • Clang 11 or newer
  • Git client
MacOS
  • MacOS 10.9.5 or newer
  • CMake, version 3.15 or newer
  • Apple Clang 11 or newer
  • Git client

For the full list of platforms and compilers covered by continuous integration, see tested platforms.

Cloning the Repository

git clone https://github.com/auto-differentiation/xad.git

Building

Visual Studio
  1. Use "Open Folder" to open the cloned directory
  2. Select the desired configuration from the top toolbar (e.g. Release x64), or add a new one using Manage Configurations...
  3. Select Project > Build (or press F7)

See the documentation for Visual Studio's built-in CMake support for more information.

Command Line

Note: The compiler toolset should be in the path. In Windows, start a Visual Studio Developer command prompt with the desired toolset first.

  1. Create a directory for the build artefacts 
    cd xad
mkdir build
cd build
  2. Run cmake to generate the build files 
    cmake ..
  3. Build using the native build system or with the generic cmake build command 
    cmake --build .
CMake GUI
  1. Open the CMake GUI and select the source and build folders
  2. Click the Configure button, selecting the desired compiler toolset
  3. Click Generate, which creates the native build files provided.
  4. If the Visual Studio generator was chosen, click Open Project to start Visual Studio, where the solution can be built

More information about how to use the CMake GUI is available from the official CMake documentation.

Running the Tests

The tests are managed by CMake's CTest tool. They can be executed as:

Visual Studio Test Explorer

Open the Test > Test Explorer to run / debug individual tests or the full suite conveniently. Visual Studio discovers the CTest tests after each build automatically. Refer to the documentation for the test explorer for more information on how to use this convenient tool.

Command Line CTest

Run the ctest tool inside the build folder:

ctest

Note that the flag -j<num_proc> can be given to run <num_proc> parallel processes, and there are more convenient ctest flags for example for controlling output, ordering, or selecting specific tests.

Test Executable

Most tests are combined into a single Google Test executable called xad_test, which can be found in the test directory in the build tree. This can also be executed directly:

cd test
./xad_test

It also provides parameters, e.g. for selecting specific tests or controlling the output, which can be seen when running ./xad_test --help.

Installing

Run the install build target to place the header files, library files, docs, and samples into the CMAKE_INSTALL_PREFIX (configurable with CMake).

Visual Studio

Select Build > Install from the menu.

Command Line

Run the following from the build folder:

cmake --install .

Integration Approaches

In order to use XAD as part of other code, we recommend one of the following approaches.

1: Submodule + CMake

If your codebase is using CMake, XAD can be integrated easily into your project by adding it as a git submodule.

To add the submodule in a subdirectory extern/xad:

git submodule add https://github.com/auto-differentiation/xad.git extern/xad

Users then need to clone recursively (git clone --recursive ...) or initialise and update the submodules (git submodule init && git submodule update). More information about submodules can be found in the Git documentation.

To add XAD to the project, all that is needed in one of the CMakeLists.txt files is to add the xad directory, and then link the relevant libraries or executables to XAD::xad:

add_subdirectory(extern/xad)
add_executable(some_executable ...)
target_link_libraries(some_executable PRIVATE XAD::xad)

2: FetchContent + CMake

The CMake FetchContent module clones the git repository at configure-time into the build folder and adds it to your project:

include(FetchContent)
FetchContent_Declare(XAD
    GIT_REPOSITORY https://github.com/auto-differentiation/xad.git
    GIT_TAG v2.2.0    # pick a tag (e.g. v2.2.0), hash, or branch here
)
FetchContent_MakeAvailable(XAD)

The relevant libraries or executables can then be linked to XAD::xad in the usual way:

add_executable(some_executable ...)
target_link_libraries(some_executable PRIVATE XAD::xad)

Another approach is to install XAD into a convenient prefix (e.g. /usr/local/) first (instructions above, setting CMAKE_INSTALL_PREFIX appropriately). Note that the package can also be zipped on one machine and downloaded/extracted on another.

Warning

Since XAD is built as a static library by default, be careful to use the same compiler and flags for your project and XAD itself. Otherwise the binaries may not be compatible. We therefore recommend the subproject approach, building from source within your project. The library builds very fast.

CMake

Then, when you use CMake, you can setup your project to find the XAD dependency in a CMakeLists.txt file as:

find_package(XAD REQUIRED)

If XAD is installed in a standard location, CMake automatically looks for it there and finds it. Otherwise, the CMAKE_PREFIX_PATH variable can be set at configure-time to add a different directory to its search path:

cmake /path/to/src -DCMAKE_PREFIX_PATH=/path/to/xad/installprefix

Other Build Tools

If your project does not use CMake, an installed package can also be linked by adding the following settings:

  • Add /path/to/xad/include to the compiler's include search path
  • Enable at least C++ 11 support (-std=c++11 in GCC)
  • Enable threading in Linux (requires -pthread in GCC for compile and link)
  • Add the library path /path/to/XAD/lib to the linker search paths
  • Link one of the following depending on the configuration:
  • Linux or Mac, Release: libxad.a
  • Linux or Mac, Debug: libxad_d.a
  • Windows 64bit, Release, toolset 14.5 (VS 2026): xad64_vc145_md.lib
  • Windows 64bit, Debug, toolset 14.5 (VS 2026): xad64_vc145_mdd.lib
  • Windows 64bit, Release, toolset 14.4 (VS 2022): xad64_vc144_md.lib
  • Windows 64bit, Debug, toolset 14.4 (VS 2022): xad64_vc144_mdd.lib
  • Windows 64bit, Release, toolset 14.2 (VS 2019): xad64_vc142_md.lib
  • Windows 64bit, Debug, toolset 14.2 (VS 2019): xad64_vc142_mdd.lib

With XAD_STATIC_MSVC_RUNTIME, the Windows names end in _mt / _mtd instead of _md / _mdd. With XAD_SHARED_LIBS, the library is libxad.so / libxad_d.so (libxad.dylib / libxad_d.dylib on Mac), or xad.dll / xad_d.dll with the import libraries xad.lib / xad_d.lib on Windows.

Tuning Behaviour and Performance

A number of options are available via CMake configuration variables to control the build and tune the performance. They can be configured as:

Visual Studio

From the Configurations dropdown in the top toolbar, select Manage Configurations... to see the available configuration and adjust the CMake variables.

Command Line

Within the build directory, variables can be set either with the initial cmake command or at a later point as:

cmake . -DVARIABLE=value
CMake GUI

The variables with their default settings are listed in the main part of the GUI and can be changed directly.

Influential variables controlling the build are:

Variable Description Default
XAD_ENABLE_TESTS Enable building tests and samples. ON if main project
OFF if sub project
XAD_ENABLE_EIGEN_TESTS Also build the tests with Eigen (uses an installed Eigen, else downloads it). OFF
XAD_WARNINGS_PARANOID Enable a high warning level and flag warnings as errors. ON
XAD_STATIC_MSVC_RUNTIME Use the static multi-threaded runtime in Visual C++ (default is dynamic). OFF
XAD_POSITION_INDEPENDENT_CODE Generate position-independent code, i.e. allow linking into a shared library. ON
XAD_ENABLE_ADDRESS_SANITIZER Enable address sanitizer (leak detector) - GCC/Clang only. OFF
XAD_SHARED_LIBS Build XAD as a shared library, with one active tape per thread across all modules linking it. OFF
XAD_EXTRA_MODES Additional vector and second-order tape types to compile into the library (see Vector Adjoint Mode). forward:2:adjoint:4:float
XAD_ENABLE_CODEGEN Enable the JIT interface with the xad-codegen backend (XAD_CODEGEN_DIR points to its sources; separate commercial licence). OFF

The following options have an impact on the performance of the tape in adjoint mode (application-specific). They are set when XAD is built and should not be changed in client code afterwards. The Build Options page explains what each one does, when it helps or hurts, and which set to start from for common workloads.

Variable Summary Default
XAD_SIMD_OPTION Instruction set: SSE2, AVX, AVX2, AVX512 or NATIVE. Only enable what the target CPU supports. AVX (NATIVE on Linux ARM, APPLE_M1 on Apple silicon)
XAD_NO_THREADLOCAL One global active tape instead of one per thread (single-threaded code only) OFF
XAD_TLS_INITIAL_EXEC Faster thread-local active tape with GCC/Clang; OFF for libraries loaded with dlopen OFF
XAD_SKIP_ZERO_PARTIALS Do not record partial derivatives that are exactly zero OFF
XAD_REDUCED_MEMORY Keep the tape's multipliers and slots in separate arrays OFF
XAD_COPY_ELISION Copies share the slot of their source and record nothing (supported for some usage patterns only) OFF
XAD_LINEAR_SLOTS Copies share the slot of their source, every assignment takes a new slot OFF
XAD_HUGE_PAGES Back large tape chunks with transparent huge pages on Linux OFF
XAD_TAPE_REUSE_SLOTS Reuse freed slots in the tape (less memory, slower) OFF
XAD_TAPE_TRACK_LIVE_SLOTS resetTo keeps the slots of variables still alive; newRecording reuses the previous recording's slots once none of them is alive OFF
XAD_TAPE_CHECKS Variables use and free slots only on their own tape (slower, more memory) ON in Debug builds

Options that can be set by client code as well, adjusting settings after the XAD library has already been compiled and installed (in Config.hpp or client code pre-processor definitions):

Variable Description Default
XAD_USE_STRONG_INLINE Force inlining of XAD's operators and expression templates, rather than letting the compiler decide (faster, slower compilation). OFF
XAD_OUTLINE_RECORDING Record each operation with one out-of-line call, for faster compiles with XAD_USE_STRONG_INLINE. OFF
XAD_ALLOW_INT_CONVERSION Add a real -> integer conversion operator, similar to double. This may result in missing some variable dependency tracking for AAD. ON

Related

Questions or issues: GitHub Discussions · issues. Would you rather we AAD-enabled your code? Get a free speed-up estimate.