diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..0f38f5bd --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,39 @@ + +name: Build Docs +on: + push: + branches: [ "master" ] + pull_request: + +jobs: + build-and-deploy-docs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Install Doxygen and some other things + shell: bash + run: sudo apt-get update && sudo apt-get install -y doxygen && sudo apt-get install -y graphviz + + - name: Set reusable strings + # Turn repeated input strings (such as the build output directory) into step outputs. These step outputs can be used throughout the workflow file. + id: strings + shell: bash + run: | + echo "build-output-dir=${{ github.workspace }}/build" >> "$GITHUB_OUTPUT" + + - name: Configure ADOL-C + run: + cmake -B ${{ steps.strings.outputs.build-output-dir }} -S ${{ github.workspace }} + + - name: build docs + run: + cmake --build ${{ steps.strings.outputs.build-output-dir }} --target doxygen + + + - name: Deploy + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ${{ steps.strings.outputs.build-output-dir }}/ADOL-C/doc/doxygen/html diff --git a/ADOL-C/doc/doxygen/CMakeLists.txt b/ADOL-C/doc/doxygen/CMakeLists.txt index c05715c6..87ca0d01 100644 --- a/ADOL-C/doc/doxygen/CMakeLists.txt +++ b/ADOL-C/doc/doxygen/CMakeLists.txt @@ -2,8 +2,10 @@ find_package(Doxygen) if(DOXYGEN_FOUND) - set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in) - set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) + # Absolute path to manual in the source tree: + set(PDF_SOURCE_PATH ${CMAKE_SOURCE_DIR}/ADOL-C/doc/adolc-manual.pdf) + set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxyfile.in) + set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/doxyfile) configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY) add_custom_target(doxygen diff --git a/ADOL-C/doc/doxygen/Mainpage.md b/ADOL-C/doc/doxygen/Mainpage.md deleted file mode 100644 index 0b93891f..00000000 --- a/ADOL-C/doc/doxygen/Mainpage.md +++ /dev/null @@ -1,63 +0,0 @@ -# ADOL-C: A Package for the Automatic Differentiation of Algorithms Written in C/C++ - -## Scope of the library - -ADOL-C is a library for automatic differentiation written in C++ -featuring e.g. - -- traceless-forward mode -- tape-based mode -- sparse Jacobians and sparse Hessians -- external differentiated functions -- optimal checkpointing -- adapted differentiation of fixed point iterations -- parallel differentiation of OpenMP-parallel loops -- Lie derivatives of scalar, vector and covector fields - - -## Documentation - - -### Class documentation - -The library contains a class documentation generated by using [doxygen]. -In order to generate it, it is required that the `doxygen` program -is available and found by CMake. After the project was configured using -CMake and if doxygen was found, the documentation can -be build by calling -```shell -make doxygen -``` -from within the build directory. The entry page of the documentation is located -in `ADOL-C/doc/doxygen/html/index.html` within the build directory. -For an overview of the contained features and submodules -you can e.g. refer to the [Topics](topics.html) section of the doxygen documentation. - - -### Manual - -A manual of ADOL-C is contained in the `ADOL-C/doc/` directory -and was also published as - -@todo Add reference to manual. - -### Examples - -@todo Describe where to find examples. - - - -## Using ADOL-C and licensing - -@todo How to incorporate ADOL-C in user code. -@todo How to cite ADOL-C -@todo Licence - - - -## Building ADOL-C - -### Dependencies -### Building the library - -[doxygen]: http://www.stack.nl/~dimitri/doxygen/ diff --git a/ADOL-C/doc/doxygen/differentiating_cpp_code.md b/ADOL-C/doc/doxygen/differentiating_cpp_code.md new file mode 100644 index 00000000..b7757d47 --- /dev/null +++ b/ADOL-C/doc/doxygen/differentiating_cpp_code.md @@ -0,0 +1,61 @@ +@page differentiating_cpp_code Differentiating C++ Code + +## Differentiating C++ Code + +ADOL-C utilizes C++'s operator overloading features to compute derivatives of programs. This operator overloading is applied via ADOL-C's main datatype `adouble`. Basic derivative evaluation can be done using tape-based or tape-less AD. + +The tape-based AD utilizes a tape to store intermediate values to be later used to compute, e.g., a gradient using reverse mode AD or many of the derivative drivers. In contrast, the tape-less `adouble` is only capable of forward-mode computations, but serves as a light-weight option, which can be much faster in some situations. + +--- + +## Tape-based AD + +To compute derivatives using tape-based AD, all necessary operations must be included in a [`trace_on`](@ref trace_on) – [`trace_off`](@ref trace_off) block. + +Inside this block, all operations involving `adouble` variables are traced onto the tape. + +> 💡 **Best practice**: allocate and free all `adouble` objects within the same [`trace_on`](@ref trace_on) – [`trace_off`](@ref trace_off) block. + +--- + +## Tape-less AD + +In comparison, for tape-less AD ... + +*(To be completed similarly)* + +--- + +## Troubleshooting + +### `adouble` variables outside [`trace_on`](@ref trace_on) – [`trace_off`](@ref trace_off) block + +It is possible (though not recommended) to have `adouble` variables outside the tracing block. To do so, you must explicitly create a tape using [`createNewTape`](@ref createNewTape) and select it using [`setCurrentTape`](@ref setCurrentTape) **before** allocating any `adouble` on this specific tape. + +> ⚠️ When working with multiple tapes, be careful during deallocation: +> `adouble` objects notify their associated tape via [`currentTape`](@ref currentTape) during destruction. If the wrong tape is selected, this may result in undefined behavior or errors. + +However, it is always safe to encapsulate logic like this: + +```cpp +const short tapeId = createNewTape(); +call_your_function(tapeId); +gradient(tapeId, ...); +``` + +with + +```cpp +void call_your_function(short tapeId) { + setCurrentTape(tapeId); + + // Allocate your data here + std::array data; + + trace_on(tapeId); + + // Computations involving `adouble` + + trace_off(); +} +``` diff --git a/ADOL-C/doc/doxygen/Doxyfile.in b/ADOL-C/doc/doxygen/doxyfile.in similarity index 99% rename from ADOL-C/doc/doxygen/Doxyfile.in rename to ADOL-C/doc/doxygen/doxyfile.in index 5a1f65fb..5c323ecc 100644 --- a/ADOL-C/doc/doxygen/Doxyfile.in +++ b/ADOL-C/doc/doxygen/doxyfile.in @@ -342,7 +342,7 @@ OPTIMIZE_OUTPUT_SLICE = NO # # Note see also the list of default file extension mappings. -EXTENSION_MAPPING = +EXTENSION_MAPPING = md=markdown # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable @@ -944,8 +944,10 @@ WARN_LOGFILE = # Note: If this tag is empty the current directory is searched. INPUT = @CMAKE_CURRENT_SOURCE_DIR@/../../include/adolc/ \ - @CMAKE_CURRENT_SOURCE_DIR@/Mainpage.md \ - @CMAKE_CURRENT_SOURCE_DIR@/Topics.md + @CMAKE_CURRENT_SOURCE_DIR@/mainpage.md \ + @CMAKE_CURRENT_SOURCE_DIR@/topics.md \ + @CMAKE_CURRENT_SOURCE_DIR@/drivers.md \ + @CMAKE_CURRENT_SOURCE_DIR@/differentiating_cpp_code.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -1160,7 +1162,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = Mainpage.md +USE_MDFILE_AS_MAINPAGE = mainpage.md #USE_MDFILE_AS_MAINPAGE = ../README.md # The Fortran standard specifies that for fixed formatted Fortran code all @@ -1410,7 +1412,7 @@ HTML_EXTRA_STYLESHEET = # files will be copied as-is; there are no commands or markers available. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_FILES = +HTML_EXTRA_FILES = @PDF_SOURCE_PATH@ # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output # should be rendered with a dark or light theme. @@ -2864,3 +2866,4 @@ MSCGEN_TOOL = # command). MSCFILE_DIRS = + diff --git a/ADOL-C/doc/doxygen/drivers.md b/ADOL-C/doc/doxygen/drivers.md new file mode 100644 index 00000000..c6dabe6c --- /dev/null +++ b/ADOL-C/doc/doxygen/drivers.md @@ -0,0 +1,3 @@ +@page drivers Drivers + +## Drivers \ No newline at end of file diff --git a/ADOL-C/doc/doxygen/mainpage.md b/ADOL-C/doc/doxygen/mainpage.md new file mode 100644 index 00000000..c42b497f --- /dev/null +++ b/ADOL-C/doc/doxygen/mainpage.md @@ -0,0 +1,58 @@ +# ADOL-C: A Package for the Automatic Differentiation of Algorithms Written in C/C++ + +@warning This documentation is experimental. We have not yet transferred the documentation to this place. + +See the [comprehensive manual](adolc-manual.pdf) + +## Scope of the library + +The C++ package ADOL-C described here facilitates the evaluation of +first and higher derivatives of vector functions that are defined +by computer programs written in C++. + +ADOL-C provides drivers to compute Jacobians, Hessians, univariate Taylor Coefficients or derivative tensors of arbitrary order. There are drivers for Jacobian-vector or Jacobian-matrix-products and vector-Jacobian or matrix-Jacobian products. Sparsity is also supported for first and second-order derivatives. For solution curves defined by ordinary differential equations, +special routines are provided that evaluate the Taylor coefficient vectors and their Jacobians with respect to the current state vector. +There are many more drivers like drivers for implicitly defined functions or drivers for fixed-point iterations. For a full list please refer to [this](@ref drivers) page + +## Documentation + + +### Class documentation + +The library contains a class documentation generated by using [doxygen]. +In order to generate it, it is required that the `doxygen` program +is available and found by CMake. After the project was configured using +CMake and if doxygen was found, the documentation can +be build by calling +```shell +make doxygen +``` +from within the build directory. The entry page of the documentation is located +in `ADOL-C/doc/doxygen/html/index.html` within the build directory. +For an overview of the contained features and submodules +you can e.g. refer to the [Topics](topics.html) section of the doxygen documentation. + + + + + +### Examples + +@todo Describe where to find examples. + + + +## Using ADOL-C and licensing + +@todo How to incorporate ADOL-C in user code. +@todo How to cite ADOL-C +@todo Licence + + + +## Building ADOL-C + +### Dependencies +### Building the library + +[doxygen]: http://www.stack.nl/~dimitri/doxygen/ \ No newline at end of file diff --git a/ADOL-C/doc/doxygen/tape_interface.dox b/ADOL-C/doc/doxygen/tape_interface.dox new file mode 100644 index 00000000..5a2a0ade --- /dev/null +++ b/ADOL-C/doc/doxygen/tape_interface.dox @@ -0,0 +1,10 @@ +/** + * \page tape_interface Tape Interface + * + * # Tape Interface + * + * This page documents all tape lifecycle functions from `tape_interface.h`. + * These are grouped in the \ref tape_group. + * + * \see \ref tape_group for full function documentation. + */ \ No newline at end of file diff --git a/ADOL-C/doc/doxygen/Topics.md b/ADOL-C/doc/doxygen/topics.md similarity index 99% rename from ADOL-C/doc/doxygen/Topics.md rename to ADOL-C/doc/doxygen/topics.md index 3e34111e..2f3f330d 100644 --- a/ADOL-C/doc/doxygen/Topics.md +++ b/ADOL-C/doc/doxygen/topics.md @@ -6,4 +6,3 @@ @defgroup TapeBackward Tape-based backward mode @brief Interfaces for tape-base backward mode AD - diff --git a/ADOL-C/include/adolc/tape_interface.h b/ADOL-C/include/adolc/tape_interface.h index 80e114c4..869183e4 100644 --- a/ADOL-C/include/adolc/tape_interface.h +++ b/ADOL-C/include/adolc/tape_interface.h @@ -9,6 +9,10 @@ #include #include +/// \defgroup tape_group Tape Interface +/// \brief Functions for controlling the AD tape lifecycle +/// \{ + /** * @brief Returns a thread-local vector that holds unique pointers to ValueTape * instances. @@ -18,6 +22,7 @@ * management. * * @return Reference to the thread-local vector of unique pointers to ValueTape. + * @ingroup tape_group */ inline std::vector> &tapeBuffer() { thread_local std::vector> tBuffer; @@ -317,4 +322,5 @@ ADOLC_API void setTapeInfoHessSparse(short tapeId, SparseHessInfos sHInfos) { } #endif +/// \} #endif // ADOLC_TAPE_INTERFACE_H \ No newline at end of file diff --git a/README.md b/README.md index 64690192..c174e0d5 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ [![Build Status](https://github.com/coin-or/ADOL-C/actions/workflows/ci.yml/badge.svg)](https://github.com/coin-or/ADOL-C/actions?query=branch%3Amaster) [![codecov](https://codecov.io/github/coin-or/ADOL-C/graph/badge.svg?token=4FSN87ZXCZ)](https://codecov.io/github/coin-or/ADOL-C) +[![Docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://coin-or.github.io/ADOL-C/) > [!WARNING] > We are in the process of modernizing ADOL-C. The master branch is unstable. Please use the latest release or help us by reporting bugs.