From b936754c1ad38f8d09dc34bcf1e512ea16f1e795 Mon Sep 17 00:00:00 2001
From: mzhelyez <maksym.zhelyeznyakov@planopsim.com>
Date: Wed, 27 Aug 2025 05:27:54 +0200
Subject: [PATCH] added docs and renamed ET macro

---
 doc/differentiation/autodiff_reverse.qbk      | 19 +++++++++++++++++--
 .../math/differentiation/autodiff_reverse.hpp |  6 +++---
 .../reverse_mode_autodiff_erf_overloads.hpp   |  2 +-
 .../reverse_mode_autodiff_stl_expressions.hpp |  2 +-
 4 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/doc/differentiation/autodiff_reverse.qbk b/doc/differentiation/autodiff_reverse.qbk
index 329bafcef..8f4ac736d 100644
--- a/doc/differentiation/autodiff_reverse.qbk
+++ b/doc/differentiation/autodiff_reverse.qbk
@@ -8,8 +8,13 @@
 [template autodiff_graph[name] '''<inlinemediaobject><imageobject><imagedata fileref="../graphs/autodiff/'''[name]'''"></imagedata></imageobject></inlinemediaobject>''']
 [h1:synopsis Synopsis]
 
+    /* enable or disable expression templates at compile time */
+    #ifndef BOOST_MATH_REVERSE_MODE_ET_OFF
+    #define BOOST_MATH_REVERSE_MODE_ET_ON
+    #endif
+
     #include <boost/math/differentiation/autodiff_reverse.hpp>
-    
+
     namespace boost {
     namespace math {
     namespace differentiation {
@@ -572,7 +577,17 @@ When in doubt, its always preferrable to compute higher order derivatives with:
   auto g4 = grad_nd<4>(f, &x,&y,&z)
 
 [h2:expression-templates-and-auto Expression Templates and auto]
-Reverse mode autodiff is expression template based. This means that some care has to be taken into considerations when writing code that uses this library. For example consider the code below:
+Reverse mode autodiff is expression template based by default. If you'd like to disable expression templates (for debugging, benchmarking, or simplify integration with other systems), you must define the following macro at compile time:
+
+    #define BOOST_MATH_REVERSE_MODE_ET_OFF
+
+or pass it to the compiler via flag
+
+    g++ -DBOOST_MATH_REVERSE_MODE_ET_OFF
+
+The expression templated version of this code doesn't currently interact nicely with the Boost.Math special function implementations, and will throw compile time errors. Disabling expression templates will often fix this, however various special functions are implemented in a way that breaks the automatic differentiation chain for certain values. Complete special function support may be added in the future.
+
+Furthermore, some care also has to be taken when writing code with expression templated types. For example consider the code below:
 
     rvar<double, 1> x = 1.0;
     rvar<double, 1> y = 2.0;
diff --git a/include/boost/math/differentiation/autodiff_reverse.hpp b/include/boost/math/differentiation/autodiff_reverse.hpp
index dc7b43521..a47aa43cf 100644
--- a/include/boost/math/differentiation/autodiff_reverse.hpp
+++ b/include/boost/math/differentiation/autodiff_reverse.hpp
@@ -7,11 +7,11 @@
 
 #include <boost/math/constants/constants.hpp>
 
-#ifndef BOOST_MATH_ET_OFF
-#define BOOST_MATH_ET_ON
+#ifndef BOOST_MATH_REVERSE_MODE_ET_OFF
+#define BOOST_MATH_REVERSE_MODE_ET_ON
 #endif
 
-#ifdef BOOST_MATH_ET_ON
+#ifdef BOOST_MATH_REVERSE_MODE_ET_ON
 #include <boost/math/differentiation/detail/reverse_mode_autodiff_basic_ops_et.hpp>
 #include <boost/math/differentiation/detail/reverse_mode_autodiff_stl_et.hpp>
 #else
diff --git a/include/boost/math/differentiation/detail/reverse_mode_autodiff_erf_overloads.hpp b/include/boost/math/differentiation/detail/reverse_mode_autodiff_erf_overloads.hpp
index 37aa26f7b..7f7fd9ce8 100644
--- a/include/boost/math/differentiation/detail/reverse_mode_autodiff_erf_overloads.hpp
+++ b/include/boost/math/differentiation/detail/reverse_mode_autodiff_erf_overloads.hpp
@@ -8,7 +8,7 @@
 #include <boost/math/constants/constants.hpp>
 #include <boost/math/differentiation/detail/reverse_mode_autodiff_expression_template_base.hpp>
 
-#ifdef BOOST_MATH_ET_ON
+#ifdef BOOST_MATH_REVERSE_MODE_ET_ON
 #include <boost/math/differentiation/detail/reverse_mode_autodiff_stl_et.hpp>
 #else
 #include <boost/math/differentiation/detail/reverse_mode_autodiff_stl_no_et.hpp>
diff --git a/include/boost/math/differentiation/detail/reverse_mode_autodiff_stl_expressions.hpp b/include/boost/math/differentiation/detail/reverse_mode_autodiff_stl_expressions.hpp
index 0acc2e6b0..72d7fe453 100644
--- a/include/boost/math/differentiation/detail/reverse_mode_autodiff_stl_expressions.hpp
+++ b/include/boost/math/differentiation/detail/reverse_mode_autodiff_stl_expressions.hpp
@@ -6,7 +6,7 @@
 #define REVERSE_MODE_AUTODIFF_STL_OVERLOADS
 /* stl support : expressions */
 
-#ifdef BOOST_MATH_ET_ON
+#ifdef BOOST_MATH_REVERSE_MODE_ET_ON
 #include <boost/math/differentiation/detail/reverse_mode_autodiff_basic_ops_et.hpp>
 #else
 #include <boost/math/differentiation/detail/reverse_mode_autodiff_basic_ops_no_et.hpp>