diff --git a/docs/userDocs/source/user/DevelopersDocumentation.rst b/docs/userDocs/source/user/DevelopersDocumentation.rst index 18e268a07..e88b16ccd 100644 --- a/docs/userDocs/source/user/DevelopersDocumentation.rst +++ b/docs/userDocs/source/user/DevelopersDocumentation.rst @@ -46,8 +46,8 @@ To build clad and its documentation, use the following CMake command: The built user documentation can be found in `build/docs/userDocs/build`; while the built internal documentation can be found in `build/docs/internalDocs/build`. -Linux (Ubuntu) with debug build of LLVM ------------------------------------------ +Developers Environment (Linux) - debug build of LLVM, Clang and Clad from source +---------------------------------------------------------------------------------- Clad is a plugin for LLVM Clang compiler infrastructure. Clad uses Clang and LLVM APIs. Therefore, to properly debug Clad, you will also @@ -62,18 +62,32 @@ instructions: .. code-block:: bash - sudo -H pip install lit + python -m pip install lit git clone https://github.com/llvm/llvm-project.git cd llvm-project - git checkout release/12.x - cd ../ - mkdir obj inst - cd obj - cmake ../llvm-project/llvm -DCMAKE_BUILD_TYPE=Debug -DLLVM_TARGETS_TO_BUILD=host -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_INSTALL_PREFIX=../inst - make install + git checkout llvmorg-16.0.0 -Please note that it is recommended to have at least 16 GB of total memory (RAM + swap) to build LLVM in debug mode. +Build Clang: + +.. code-block:: bash + + mkdir build && cd build + cmake -DLLVM_ENABLE_PROJECTS="clang" -DCMAKE_BUILD_TYPE="DEBUG" -DLLVM_TARGETS_TO_BUILD=host -DLLVM_INSTALL_UTILS=ON ../llvm + cmake --build . --target clang --parallel $(nproc --all) + make -j8 check-clang # this installs llvm-config required by lit + cd ../.. +Clone and build Clad: + +.. code-block:: bash + + git clone https://github.com/vgvassilev/clad.git + cd clad + mkdir build && cd build + cmake -DLLVM_DIR=PATH/TO/llvm-project/build -DCMAKE_BUILD_TYPE=DEBUG -DLLVM_EXTERNAL_LIT="$(which lit)" ../ + make -j8 clad + +Please note that it is recommended to have at least 16 GB of total memory (RAM + swap) to build LLVM in debug mode. To build Clad with Debug build of LLVM, adjust the ``-DClang_DIR`` and ``-DLLVM_DIR`` options to point to installation home of debug build of LLVM. diff --git a/docs/userDocs/source/user/InstallationAndUsage.rst b/docs/userDocs/source/user/InstallationAndUsage.rst index d63bcf4ad..1673c936b 100644 --- a/docs/userDocs/source/user/InstallationAndUsage.rst +++ b/docs/userDocs/source/user/InstallationAndUsage.rst @@ -3,7 +3,7 @@ Clad Installation This page covers both installation and usage details for Clad. -At the moment, LLVM/Clang 5.0.x - 15.0.6 are supported. +At the moment, LLVM/Clang 7.0.x - 17.0.x are supported. Conda Installation ==================== @@ -32,12 +32,13 @@ Building from source (example was tested on Ubuntu 20.04 LTS) .. code-block:: bash #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 bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)" sudo -H pip install lit - git clone https://github.com/vgvassilev/clad.git clad - mkdir build_dir inst; cd build_dir - cmake ../clad -DClang_DIR=/usr/lib/llvm-11 -DLLVM_DIR=/usr/lib/llvm-11 -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``" - make && make install + 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) -------------------------------------------------------------------- @@ -48,26 +49,16 @@ Building from source (example was tested on macOS Catalina 10.15.7) brew install python python -m pip install lit git clone https://github.com/vgvassilev/clad.git clad - mkdir build_dir inst; cd build_dir - 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 -DCMAKE_INSTALL_PREFIX=../inst -DLLVM_EXTERNAL_LIT="``which lit``" + 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 - -Building from source LLVM, Clang and Clad (development environment) --------------------------------------------------------------------- + +Run the Clad tests: .. code-block:: bash - sudo -H pip install lit - git clone https://github.com/llvm/llvm-project.git src - cd src; git checkout llvmorg-13.0.0 - cd /tools - git clone https://github.com/vgvassilev/clad.git clad - cd ../../../ - mkdir obj inst - cd obj - cmake -S ../src/llvm -DLLVM_ENABLE_PROJECTS="clang" -DCMAKE_BUILD_TYPE="Debug" -DLLVM_TARGETS_TO_BUILD=host -DCMAKE_INSTALL_PREFIX=../inst - make && make install + make -j8 check-clad How to use Clad ================= diff --git a/docs/userDocs/source/user/UsingClad.rst b/docs/userDocs/source/user/UsingClad.rst index 5191934f6..6ca92397c 100644 --- a/docs/userDocs/source/user/UsingClad.rst +++ b/docs/userDocs/source/user/UsingClad.rst @@ -113,6 +113,14 @@ differentiation. The following examples demonstrate computation of higher-order std::cout << d_fn_3.execute(3) << "\n"; // prints 72.00 } +Clad also supports higher order differentiation of custom derivatives like `std::sin`. A usage example can be something like:: + + double mysin(double x) { return std::sin(x); } + int main() { + auto d_sin_3 = clad::differentiate<3>(mysin); + std::cout << d_sin_3.execute(3) << "\n"; // prints 0.989992 + } + .. note:: For derivative orders upto 3, clad has specially defined enums that can be used