Documentation for autodiff.

Author: MaxSagebaum

docs/cpp2/metafunctions.md

@@ -367,6 +367,36 @@ main: () = {
 
 ### For computational and functional types
 
+#### `autodiff`
+
+A `autodiff` type is extended so that derivatives can be computed. The metafunction adds for each function and member function a differentiated version. **This is a proof of concept implementation. Expect it to break.**
+A simple hello diff example is:
+```
+ad: @autodiff type = {
+    func: (x: double) -> (r: double) = {
+        r = x * x;
+    }
+}
+
+main: (args) = {
+    x := 3.0;
+    x_d := 1.0;
+
+    r := ad::func_d(x, x_d);
+
+    std::cout << "Derivative of 'x*x' at (x)$ is (r.r_d)$" << std::endl;
+}
+```
+
+The `@autodiff` metafunction mostly supports the forward mode of algorithmic differentiation. The reverse mode is only partly implemented and not yet well tested.
+See [Supported autodiff features](../notes/autodiff_status.md) for a list of supported language features.
+
+Options can be given by text template arguments, e.g. `@autodiff<"reverse">` enables the reverse mode.
+| Option | Description |
+| `"reverse"` | Reverse mode algorithmic differentiation. Default suffix `_b`. |
+| `"order=<n>"` | Higher order derivatives. `<n>` can be arbitrary. See `regression-tests/pure2-autodiff-higher-order.cpp2` for examples. |
+| `"suffix=<s>"` | Change the forward mode suffix. Can be used to apply autodiff multiple times. E.g. `@autodiff @autodiff<"suffix=_d2">`. |
+| `"rws_suffix=<s>"` | Change the reverse mode suffix. |
 
 #### `regex`
 

docs/notes/autodiff_status.md

@@ -0,0 +1,34 @@
+# Supported algorithmic differentiation (autodiff) features
+
+The listings might be incomplete. If something is missing, it is not supported. Algorithmic differentiation is applied via the [`autodiff` metafunction](../cpp2/metafunctions.md#autodiff). Maybe the planned features are added in 2026. Do not wait for them. The autodif feature is a proof of concept implementation.
+
+** Reverse mode algorithmic differentiation is very experimental. Expect it to break. **
+
+## Currently supported or planned features
+
+| Description | Status forward | Status reverse |
+| --- | --- | --- |
+| Type definitions (structures) | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| Member values | <span style="color:green">Supported</span> | <span style="color:gray">Planned</span> |
+| Member functions | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| Function arguments | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| Function return arguments | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| Addition and multiplication | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| Prefix addition and subtraction | <span style="color:green">Supported</span> | <span style="color:gray">Planned</span> |
+| Static member function calls | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| Member function calls | <span style="color:green">Supported</span> | <span style="color:gray">Planned</span> |
+| Function calls | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| Math functions (sin, cos, exp, sqrt) | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| If else | <span style="color:green">Supported</span> | <span style="color:gray">Planned</span> |
+| Return statement | <span style="color:green">Supported</span> | <span style="color:gray">Planned</span> |
+| Intermediate variables | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| Passive variables | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| While loop | <span style="color:green">Supported</span> | <span style="color:gray">Planned</span> |
+| Do while loop | <span style="color:green">Supported</span> | <span style="color:gray">Planned</span> |
+| For loop | <span style="color:green">Supported</span> | <span style="color:green">Supported</span> |
+| Template arguments |  <span style="color:gray">Planned</span> |  <span style="color:gray">Planned</span> |
+| Lambda functions |  <span style="color:gray">Planned</span> |  <span style="color:gray">Planned</span> |
+
+
+
+

regression-tests/test-results/pure2-autodiff.cpp2.output

@@ -1439,5 +1439,6 @@ ad_test_2:/* @autodiff<"order=2"> @print */ type =
         return;
     }
 }
- ok (all Cpp2, passes safety checks)
+
+pure2-autodiff.cpp2(195,1): error: while applying @autodiff - AD: Warning reverse mode differentiation is very experimental.