From 7aceecd2706833c12f194bd2332ee9595f76a415 Mon Sep 17 00:00:00 2001 From: Jean-Paul Pelteret Date: Tue, 22 Jan 2019 16:19:15 +0100 Subject: [PATCH] Improve documentation to AD helpers header. --- .../deal.II/differentiation/ad/ad_helpers.h | 55 +++++++++++++++++-- 1 file changed, 49 insertions(+), 6 deletions(-) diff --git a/include/deal.II/differentiation/ad/ad_helpers.h b/include/deal.II/differentiation/ad/ad_helpers.h index c8bd16a31b..ac716dfd94 100644 --- a/include/deal.II/differentiation/ad/ad_helpers.h +++ b/include/deal.II/differentiation/ad/ad_helpers.h @@ -482,12 +482,33 @@ namespace Differentiation * Return a flag that, when true, indicates that the * retaping of the dependent function is necessary for a reliable * computation to be performed on a tape with the given @p tape_index. - * This may be necessary a sign comparison within branched operations + * This may be necessary if a sign comparison within branched operations * yields different results to those computed at the original tape * evaluation point. * + * This issue, known as "branch switching", can be clarified by means of + * a trivial example: + * @code + * ADNumberType func (ADNumberType x, ADNumberType y, ADNumberType z) + * { + * if (x < y) + * return y; + * else + * return x*z; + * } + * @endcode + * During taping, the conditional statement may be either true or + * false, and the result (with its sensitivities) returned by + * this function. For some other evaluation of the tape (i.e. for some + * different + * inputs @p x and @p y, the other branch of the conditional check may be + * chosen. The result of following this code path has not been recorded on + * the tape, and therefore cannot be evaluated. In such a case, it is + * therefore necessary to re-record the tape at the new evaluation point + * in order to resolve the new code branch. + * * For the output of this function to be meaningful, it must be called - * after the activate_recorded_tape() is called and the new evaluation + * after activate_recorded_tape() is called and the new evaluation * point for the tape (i.e. values of the independent variables) have * been set and subsequently used (i.e. in the determination of the values * or derivatives of the dependent variables). @@ -499,12 +520,34 @@ namespace Differentiation /** * Return a flag that, when true, indicates that the * retaping of the dependent function is necessary for a reliable - * computation to be performed on the avtive tape. This may be necessary a - * sign comparison within branched operations yields different results to - * those computed at the original tape evaluation point. + * computation to be performed on the active tape. + * This may be necessary if a sign comparison within branched operations + * yields different results to those computed at the original tape + * evaluation point. + * + * This issue, known as "branch switching", can be clarified by means of + * a trivial example: + * @code + * ADNumberType func (ADNumberType x, ADNumberType y, ADNumberType z) + * { + * if (x < y) + * return y; + * else + * return x*z; + * } + * @endcode + * During taping, the conditional statement may be either true or + * false, and the result (with its sensitivities) returned by + * this function. For some other evaluation of the tape (i.e. for some + * different + * inputs @p x and @p y, the other branch of the conditional check may be + * chosen. The result of following this code path has not been recorded on + * the tape, and therefore cannot be evaluated. In such a case, it is + * therefore necessary to re-record the tape at the new evaluation point + * in order to resolve the new code branch. * * For the output of this function to be meaningful, it must be called - * after the activate_recorded_tape() is called and the new evaluation + * after activate_recorded_tape() is called and the new evaluation * point for the tape (i.e. values of the independent variables) have * been set and subsequently used (i.e. in the determination of the values * or derivatives of the dependent variables). -- 2.39.5