- CMake, version 3.15 or newer
- Linux: GCC 5.4 or newer, or Clang 11 or newer
- 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¶
- Create a directory for the build artefacts
- Run cmake to generate the build files
- Build using the native build system or with the generic cmake build command
Running the tests¶
The tests are executed with the
ctest can be used to run them:
Or if only the unit tests should be run, the
xad_test executable in the bin directory can be executed directly.
install build target to place the header files, library files, docs, and samples into the
CMAKE_INSTALL_PREFIX (configurable with CMake).
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
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
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.
Then, when you use CMake, you can setup your project to find the XAD dependency in a
CMakeLists.txt file as:
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:
Other Build Tools¶
If your project does not use CMake, an installed package can also be linked by adding the following settings:
/path/to/XAD/includeto the compiler's include path
- Enable at least C++ 11 support (
- Enable threading (requires
-pthreadin GCC for compile and link)
- Add the library path
/path/to/XAD/libto the linker search paths
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:
| ||Enable building tests and samples.|| |
| ||Enable a high warning level and flag warnings as errors.|| |
| ||Use the static multi-threaded runtime in Visual C++ (default is dynamic)|
| ||Generate position-indepent code, i.e. allow linking into a shared library.|| |
| ||Enable address sanitizer (leak detector) - GCC/Clang only.|| |
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:
| ||Select between || |
| ||Keep track of unused slots in tape and re-use them (less memory, more compute)|| |
| ||Disable thread-local tapes (use with single-threaded code only|| |
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):
| ||Force inlining expression templates, rather than letting the compiler decide. (faster, slow compilation, possible compiler crashes)|| |
| ||Add real -> integer conversion operator, similar to || |
Building the Documentation¶
The user documentation uses the popular MkDocs Material tool. It is entirely generated from the markdown files located in the
Approach 1: Docker¶
The docs can be generated easily using docker by running in the project root:
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).
- Setup the environment and dependencies:
- Run mkdocs (in the activated environment):
This will also serve the documentation locally on http://127.0.0.1:8000 and watch for changes in the
docs folder automatically.
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.
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.
|Operating System||Compiler||Configurations||Test Coverage Recorded|
|Windows Server 2019||Visual Studio 2015 (Toolset 14.0)||Debug, Release||no|
|Windows Server 2022||Visual Studio 2017 (Toolset 14.1)||Debug, Release||no|
|Windows Server 2022||Visual Studio 2019 (Toolset 14.2)||Debug, Release||no|
|Windows Server 2022||Visual Studio 2022 (Toolset 14.3)||Debug, Release||no|
|Windows Server 2022||Clang 14.0 (Toolset 14.3)||Debug, Release||no|
|Ubuntu 16.04||GCC 5.4.0||Debug, Release, Release with ||no|
|Ubuntu 17.10||GCC 6.4.0||Debug, Release, Release with ||no|
|Ubuntu 17.10||GCC 7.2.0||Debug, Release, Release with ||no|
|Ubuntu 18.04||GCC 8.4.0||Debug, Release, Release with ||no|
|Ubuntu 19.10||GCC 9.2.0||Debug, Release, Release with ||no|
|Ubuntu 20.04||GCC 10.3.0||Debug, Release, Release with ||no|
|Ubuntu 20.04||GCC 11.1.0||Debug, Release, + both with ||yes|
|Ubuntu 20.04||Clang 11.0.0||Debug, Release, Release with ||no|
|Ubuntu 22.04||Clang 12.0.1||Debug, Release, Release with ||no|
|Ubuntu 22.04||Clang 13.0.1||Debug, Release, Release with ||no|
|Ubuntu 22.04||Clang 14.0.0||Debug, Release, Release with ||no|
|MacOS 12.6.5||AppleClang 14.0.0||Debug, Release||yes|