docs: Address review feedback on lazy reducer pitfall section

- Only force evaluation of the returned expression; intermediate lazy
  expressions are safe as long as they do not outlive the function
- Use auto for shifted/expVals/sumExp in the doc example and tests
- Remove misleading "Alternatively" sections (eval on intermediates is
  not required; evaluation_strategy::immediate does not fix the issue)
- Fix logSoftmax_eval test variant to drop unnecessary xt::eval wrappers

Author: ssam18

docs/source/pitfall.rst

@@ -92,32 +92,21 @@ is still an lvalue and thus captured by reference.
     that hold references to local variables. When the function returns, these local
     variables are destroyed, and the returned expression contains dangling references.
 
-    The fix is to use explicit container types to force evaluation:
+    The fix is to force evaluation of only the returned expression — intermediate
+    lazy expressions are safe as long as they do not outlive the function:
 
     .. code::
 
         template <typename T>
         xt::xtensor<T, 2> logSoftmax(const xt::xtensor<T, 2> &matrix)
         {
             xt::xtensor<T, 2> maxVals = xt::amax(matrix, {1}, xt::keep_dims);
-            xt::xtensor<T, 2> shifted = matrix - maxVals;
-            xt::xtensor<T, 2> expVals = xt::exp(shifted);
-            xt::xtensor<T, 2> sumExp = xt::sum(expVals, {1}, xt::keep_dims);
-            return shifted - xt::log(sumExp);
+            auto shifted = matrix - maxVals;
+            auto expVals = xt::exp(shifted);
+            auto sumExp = xt::sum(expVals, {1}, xt::keep_dims);
+            return xt::xtensor<T, 2>(shifted - xt::log(sumExp));
         }
 
-    Alternatively, you can use :cpp:func:`xt::eval` to force evaluation:
-
-    .. code::
-
-        auto shifted = xt::eval(matrix - maxVals);
-
-    Or use the immediate evaluation strategy for reducers:
-
-    .. code::
-
-        auto sumExp = xt::sum(expVals, {1}, xt::evaluation_strategy::immediate | xt::keep_dims);
-
 Random numbers not consistent
 -----------------------------
 

test/test_xmath.cpp

@@ -976,26 +976,26 @@ namespace xt
     TEST(xmath, issue_2871_intermediate_result_handling)
     {
         // This test verifies the correct pattern for using reducers with
-        // intermediate results. Using 'auto' with lazy expressions can lead
-        // to dangling references when the function returns.
+        // intermediate results. Returning a lazy expression from a function can lead
+        // to dangling references — only the returned expression must be evaluated.
 
-        // The CORRECT way: use explicit container types for intermediate results
+        // The CORRECT way: use auto for intermediates, force evaluation only at return
         auto logSoftmax_correct = [](const xt::xtensor<double, 2>& matrix)
         {
             xt::xtensor<double, 2> maxVals = xt::amax(matrix, {1}, xt::keep_dims);
-            xt::xtensor<double, 2> shifted = matrix - maxVals;
-            xt::xtensor<double, 2> expVals = xt::exp(shifted);
-            xt::xtensor<double, 2> sumExp = xt::sum(expVals, {1}, xt::keep_dims);
+            auto shifted = matrix - maxVals;
+            auto expVals = xt::exp(shifted);
+            auto sumExp = xt::sum(expVals, {1}, xt::keep_dims);
             return xt::xtensor<double, 2>(shifted - xt::log(sumExp));
         };
 
-        // Alternative CORRECT way: use xt::eval for intermediate results
+        // Alternative CORRECT way: use xt::eval on the reducer result
         auto logSoftmax_eval = [](const xt::xtensor<double, 2>& matrix)
         {
             auto maxVals = xt::eval(xt::amax(matrix, {1}, xt::keep_dims));
-            auto shifted = xt::eval(matrix - maxVals);
-            auto expVals = xt::eval(xt::exp(shifted));
-            auto sumExp = xt::eval(xt::sum(expVals, {1}, xt::keep_dims));
+            auto shifted = matrix - maxVals;
+            auto expVals = xt::exp(shifted);
+            auto sumExp = xt::sum(expVals, {1}, xt::keep_dims);
             return xt::xtensor<double, 2>(shifted - xt::log(sumExp));
         };