Added examples for complex number and updated documentation.

Author: MaxSagebaum

README.md

@@ -21,8 +21,8 @@ There is a newsletter available at [codi-info@uni-kl.de](https://lists.uni-kl.de
 
 CoDiPack is a header only library.
 The only file the user needs to include is `codi.hpp`.
-The only other requirement is a C++11 compliant compiler
-where one usually needs to specify '-std=c++11' in compiler arguments.
+The only other requirement is a C++17 compliant compiler
+where one usually needs to specify '-std=c++17' in compiler arguments. For a C++11 compilant version of CoDiPack use th 2.* release.
 CoDiPack is tested with gcc, clang, and the Intel compiler.
 
 The file `codi.hpp` defines several datatypes. The most important ones are:
@@ -83,6 +83,12 @@ Therefore we recomend to force inlining of CoDiPack with the option
 -DCODI_UseForcedInlines 
 ~~~~
 
+### Complex numbers
+
+If your compiler has problems with the specialization of `std::complex` for CoDiPack types, try `-DCODI_SpecializeStdComplex=0` to disable this behaviour.
+Without the specialization, complex types can be defined by using `codi::ActiveComplex<CoDiType>`, e.g. `codi::ActiveComplex<codi::RealReverse>`.
+
+
 ## Hello World Example
 
 A very small and simple example for the usage of the RealForward type is the following code:
@@ -106,11 +112,11 @@ A very small and simple example for the usage of the RealForward type is the fol
 
 It is compiled with
 ~~~~{.txt}
-  g++  -I<path to codi>/include -std=c++11 -g -o forward forward.cpp
+  g++  -I<path to codi>/include -std=c++17 -g -o forward forward.cpp
 ~~~~
 for the gcc compiler or with
 ~~~~{.txt}
-  icpc  -I<path to codi>/include -std=c++11 -g -o forward forward.cpp
+  icpc  -I<path to codi>/include -std=c++17 -g -o forward forward.cpp
 ~~~~
 for the Intel compiler.
 

documentation/CoDiLayout.xml

@@ -45,6 +45,7 @@
       <tab type="user" title="Example 25 - Tape writers" url="@ref Example_25_Tape_Writers"/>
       <tab type="user" title="Example 26 - Jacobian tape readers" url="@ref Example_26_Jacobian_Tape_Readers"/>
       <tab type="user" title="Example 27 - Primal tape readers" url="@ref Example_27_Primal_Tape_Readers"/>
+      <tab type="user" title="Example 28 - Complex numbers" url="@ref Example_28_Complex_numbers"/>
     </tab>
     <tab type="user" title="Papers" url="@ref Papers"/>
     <tab type="user" title="Taping strategies" url="@ref TapingStrategy"/>

documentation/examples/Example_28_Complex_numbers.cpp

@@ -0,0 +1,47 @@
+//! [Example 28 - Complex numbers]
+#include <iostream>
+#include <codi.hpp>
+
+//! [Function implementations]
+template<typename Type>
+Type func(Type const& v) {
+  Type t = v + v.real();
+  return 2 * v * t;
+}
+//! [Function implementations]
+
+int main(int nargs, char** args) {
+  using Real = codi::RealReverse;
+  using Tape = typename Real::Tape;
+
+  Tape& tape = Real::getTape();
+
+  std::complex<Real> x = 10.0;
+  Real w = 5.0;
+
+  tape.setActive();
+
+  codi::RealTraits::registerInput(w);
+  codi::RealTraits::registerInput(x); // Use general registration function for complex numbers.
+
+  // Use complex numbers as usual.
+  std::complex<Real> y = func(x);
+  y *= w;
+
+  codi::RealTraits::registerOutput(y);  // Use general registration function for complex numbers.
+
+  tape.setPassive();
+
+  // Cast to Real* is still possible.
+  Real* x_p = reinterpret_cast<Real*>(&x);
+  Real* y_p = reinterpret_cast<Real*>(&y);
+  for(int i = 0; i < 2; i += 1) {
+    tape.clearAdjoints();
+    y_p[i].setGradient(1.0);
+    tape.evaluate();
+    std::cout << "Gradient of dy[" << i << "]/dw: " << w.getGradient() << std::endl;
+    std::cout << "Gradient of dy[" << i << "]/dx[0]: " << x_p[0].getGradient() << std::endl;
+    std::cout << "Gradient of dy[" << i << "]/dx[1]: " << x_p[1].getGradient() << std::endl;
+  }
+}
+//! [Example 28 - Complex numbers]

documentation/examples/Example_28_Complex_numbers.md

@@ -0,0 +1,17 @@
+Example 28 - Complex numbers {#Example_28_Complex_numbers}
+=======
+
+**Goal:** Demonstrate the use of std::complex with CoDiPack.
+
+**Prerequisite:** \ref Tutorial_02_Reverse_mode_AD
+
+**Function:**
+\snippet examples/Example_28_Complex_numbers.cpp Function implementations
+
+**Full code:**
+\snippet examples/Example_28_Complex_numbers.cpp Example 28 - Complex numbers
+
+**Additional information:**
+std::complex is automatically specialized for CoDiPack types. With some compilers this can lead to problems.
+Use the option `-DCODI_SpecializeStdComplex=0` to disable this behaviour.
+Without the specialization, complex types can be defined by using `codi::ActiveComplex<CoDiType>`, e.g. `codi::ActiveComplex<codi::RealReverse>`.

documentation/user/Tutorials.md

@@ -47,6 +47,7 @@ or pointers to other features.
 | \subpage Example_25_Tape_Writers "" | Writing tapes to disk and other tape writers.|
 | \subpage Example_26_Jacobian_Tape_Readers "" | Reading Jacobian tapes from disk. |
 | \subpage Example_27_Primal_Tape_Readers "" | Rading primal value tapes from disk. |
+| \subpage Example_28_Complex_numbers "" | How to use complex numbers in CoDiPack. |
 
 The graph shows how the tutorials and examples are connected. Usually it is better to understand first the prerequisites
 of a tutorial/example before reading the actual example.

documentation/user/TutorialsGraph.dot

@@ -74,6 +74,8 @@ digraph Tutorials {
 
   E27 [label="E27 - Primal tape readers"];
 
+  E28 [label="E28 - Complex numbers"];
+
   // Edges (sorted)
   E02:e -> E08:w;
   E02:e -> E09:w;
@@ -99,6 +101,7 @@ digraph Tutorials {
   T02:e -> E22:w;
   T02:e -> E23:w;
   T02:e -> E25:w;
+  T02:e -> E28:w;
   T02:e -> T03:w;
   T02:e -> T04:w;
   T02:e -> T05:w;