CppADCodeGen  2.4.3
A C++ Algorithmic Differentiation Package with Source Code Generation
mainpage.md
1 # CppADCodeGen
2 
3 CppADCodeGen performs **hybrid Automatic Differentiation** (AD), that is, uses
4 operator-overloading and produces source-code. Such source-code can be
5 statically compiled at runtime using an existing compiler and linked dynamically
6 or, alternatively, go through a JIT compilation using Clang/LLVM.
7 
8 The evaluation of differential information can be orders of magnitude faster
9 to compute using a compiled model than using a regular operator overloading
10 strategy.
11 
12 In addition to C source generation, CppADCodeGen can also produce
13  [Latex](http://www.latex-project.org/),
14  html+[MathML](http://www.w3.org/Math/), and
15  [dot](https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29)
16  source-code files for your algorithm.
17 Latex sources can be used to create PDF files for documentation purposes,
18 html+MathML can be used to display your algorithm in a web browser, and
19 dot files can be used to create images with a graph of your model
20 (see [graphviz](http://graphviz.org/)).
21 
22 CppADCodeGen can also be used to perform differentiation index reduction of
23 Differential Algebraic Equations (DAE) through Pantelides, Soares-Secchi, and Dummy
24 Derivatives methods.
25 
26 CppADCodeGen is built on top of the [CppAD](http://www.coin-or.org/CppAD)
27 library, which is a header only C++ AD library using operator overloading.
28 
29 ## License ##
30 
31 CppADCodeGen is available with both the **EPL** and **GPL** licenses
32 (suitable for both open-source and closed-source commercial projects).
33 See epl-v10.txt and gpl3.txt for a copy of the licenses.
34 
35 ## Requirements ##
36 
37 CppADCodeGen is a C++11 header only library, therefore there aren't many dependencies:
38 
39  - **CppAD** (2020),
40  - A **C++11** compiler (such as GCC and Clang),
41  - Clang/LLVM (only required for JIT compilation), and
42  - Eigen 3 (required when DAE differentiation index reduction is used).
43 
44 Runtime compilation and dynamic linking:
45  - Linux (it might be very easy to support other OSes but it is not implemented yet)
46 
47 ## Installing ##
48 
49 ### General installation ###
50 
51 Get the sources from GitHub:
52 ```
53  git clone https://github.com/joaoleal/CppADCodeGen.git CppADCodeGen
54 ```
55 Create a new folder to build the project:
56 ```
57  mkdir cppadcg-build
58 ```
59 Build the project (no compilation of C/C++ occurs, just generation of header files):
60 ```
61  cd cppadcg-build
62  cmake ../CppADCodeGen
63 ```
64 Either install the project in your system:
65 ```
66  make install
67 ```
68 or to some other folder:
69 ```
70  make DESTDIR=someotherfolder install
71 ```
72 
73 ### Debian/Ubuntu ###
74 
75 A debian installation package can be created at the root of the project.
76 Typically you can create the installer by just typing:
77 ```
78  dpkg-buildpackage
79 ```
80 It will create a debian package outside the project's folder.
81 
82 ## Using CppADCodeGen ##
83 
84 See the [wiki](https://github.com/joaoleal/CppADCodeGen/wiki).
85 
86 The folder example includes some simple use cases.
87 
88 ## Testing ##
89 
90 Get the sources from GitHub:
91 ```
92  git clone https://github.com/joaoleal/CppADCodeGen.git CppADCodeGen
93 ```
94 Create a new folder for the tests:
95 ```
96  cd make-build-debug
97  cmake ../CppADCodeGen
98 ```
99 Testing requires [google-test](https://github.com/google/googletest) (version 1.8.1).
100 Either install it in your system or configure CppADCodeGen to download the sources from GitHub by replacing the previous line with:
101 ```
102  cmake -DGOOGLETEST_GIT=ON ../CppADCodeGen
103 ```
104 
105 Then compile the tests:
106 ```
107  make build_tests
108 ```
109 
110 Run the complete set of tests:
111 ```
112  make test
113 ```
114 If [valgrind](https://valgrind.org/) is available in your system, CppADCodeGen will also perform memory checks which can
115 lead to a very lengthy test execution.
116 It is possible to disable memory validations by turning off the CMake option `USE_VALGRIND`.
117 For instance, by calling the following command before running the tests:
118  ```
119  cmake -DUSE_VALGRIND=OFF ../CppADCodeGen
120  ```
121 ---
122 
123 ## Repository Content
124 
125 |Directories | Description |
126 |------------|-----------------------------------------------------------------|
127 |bin | Helper shell and sed scripts used for CppAD development. |
128 |bug | Directory containing demonstration of known bugs (may be empty).|
129 |debian | Debian package creation files (Linux). |
130 |doc | Holds files for generation of developer documentation. |
131 |example | CppADCodegen example files are here. |
132 |include | The CppADCodeGen header files. |
133 |pkgconfig | pkg-config support files. |
134 |python | Pretty printers for GDB (debugging). |
135 |speed | Contains some benchmarks for CppADCodeGen. |
136 |test | Contains tests for CppADCodeGen. |
137 
138 
139 | Files | Description |
140 |---------------|--------------------------------------------------------------|
141 |AUTHORS | Statement of authorship and copyright. |
142 |CMakeLists.txt | CppADCodeGen CMake input file. |
143 |COPYING | Statement of user license to use software. |
144 |epl-v10.txt | A copy of the Eclipse Public License version 1. |
145 |gpl3.txt | A copy of the GNU General Public License version 3. |
146 |INSTALL | Points to this file. |