Getting Started¶

Building XAD¶

Prerequisites¶

• CMake, version 3.15 or newer
• Linux: GCC 5.4 or newer, or Clang 11 or newer
• Windows:
  • Visual Studio 2015 or newer
  • Visual Studio with Clang toolset, 2019 or newer
• MacOS: 10.9 or higher, with Apple Clang 11 or newer
• Git client

(See tested platforms for the list of platforms covered by continuous integration.)

Cloning the Repository¶

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

Building¶

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 .
   

Running the tests¶

The tests are executed with the test target:

cmake --build . --target test

Alternatively, ctest can be used to run them:

ctest

Or if only the unit tests should be run, the xad_test executable in the bin directory can be executed directly.

Installing¶

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

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 allows to clone the git repository at configure-time into the build folder and add it to your project after:

include(FetchContent)

FetchContent_Declare(XAD
    GIT_REPOSITORY https://github.com/auto-differentiation/XAD.git
    GIT_TAG 1.1.0    # pick a tag, hash, or branch here
)
FetchContent_MakeAvailable(XAD)

Note that this requires at least CMake version 3.14.

3: Install XAD and Link¶

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.

Important: Since XAD is built as a static library, be careful to use the same compiler and flags for your project as well as XAD itself. Otherwise the binaries may not be compatible. We therefore recommend to 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 path
• Enable at least C++ 11 support (-std=c++11 in GCC)
• Enable threading (requires -pthread in GCC for compile and link)
• Add the library path /path/to/XAD/lib to the linker search paths
• Link libxad.a (Release) or libxad_d.a (Debug) - or the alternative names on Windows

Tuning Behaviour and Performance¶

A number of options are available via CMake to control the build and tune the performance. They can be specified using the CMake command-line with -DVARIABLE=value, or with the CMake GUI.

Influential variables controlling the build are:

Options with an impact on the performance of the tape in adjoint mode (application-specific). These should not be changed in client code after the tape has been compiled:

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

Building the Documentation¶

The user documentation uses the popular MkDocs Material tool. It is entirely generated from the markdown files located in the docs folder.

Approach 1: Docker¶

The docs can be generated easily using docker by running in the project root:

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

This will serve the documentation on http://127.0.0.1:8000 and watch for changes in the docs folder automatically. The files can now be modified and conveniently viewed.

Approach 2: Local Python¶

Alternatively, MkDocs can be installed locally into a python environment and executed as follows (we recommend a virtual environment as shown below).

1. Setup the environment and dependencies:

   python -m venv .venv
   source .venv/bin/activate
   pip install mkdocs-material mkdocs-minify-plugin mkdocs-redirects "pillow<10" "cairosvg>=2.5"
   

2. Run mkdocs (in the activated environment):

   mkdocs serve
   

This will also serve the documentation locally on http://127.0.0.1:8000 and watch for changes in the docs folder automatically.

Getting Help¶

If you have found an issue, want to report a bug, or have a feature request, please raise a GitHub issue.

For general questions about XAD, sharing ideas, engaging with community members, etc, please use GitHub Discussions.

Tested Platforms¶

The following platforms are part of the continuous integration workflow, i.e. they are tested on each commit. You can use other configurations at your own risk, or submit a PR to include it in the CI workflow.