From: Jean-Paul Pelteret Date: Sat, 25 Aug 2018 09:25:52 +0000 (+0200) Subject: Enhancements to AD drivers header X-Git-Tag: v9.1.0-rc1~779^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F7118%2Fhead;p=dealii.git Enhancements to AD drivers header - Spelling / grammar corrections - Move special numbers into their own namespace - Rename some functions - Reorder some function arguments --- diff --git a/include/deal.II/differentiation/ad/ad_drivers.h b/include/deal.II/differentiation/ad/ad_drivers.h index 25bc4fcbed..d5711c6ebd 100644 --- a/include/deal.II/differentiation/ad/ad_drivers.h +++ b/include/deal.II/differentiation/ad/ad_drivers.h @@ -99,7 +99,7 @@ namespace Differentiation { /** * Typedef for tape indices. ADOL-C uses short integers, so - * we restrict outselves to similar types. + * we restrict ourselves to similar types. */ using tape_index = unsigned short; @@ -107,7 +107,14 @@ namespace Differentiation * Typedef for tape buffer sizes. */ using tape_buffer_sizes = unsigned int; + } // namespace types + /** + * A collection of special numbers used within the context of + * auto-differentiable numbers. + */ + namespace numbers + { /** * A tape index that is unusable and can be used to invalidate recording * operations. @@ -133,7 +140,7 @@ namespace Differentiation static const types::tape_index max_tape_index = std::numeric_limits::max(); #endif // DEAL_II_WITH_ADOLC - } // namespace types + } // namespace numbers /** * A driver class for taped auto-differentiable numbers. @@ -173,8 +180,8 @@ namespace Differentiation * tape buffer. */ static void - enable_taping(const types::tape_index tape_index, - const bool keep_independent_values); + start_taping(const types::tape_index tape_index, + const bool keep_independent_values); /** * Enable the recording mode for a given tape, using the run-time @@ -190,12 +197,12 @@ namespace Differentiation * @param[in] tbufsize ADOL-C Taylor buffer size */ static void - enable_taping(const types::tape_index tape_index, - const bool keep_independent_values, - const types::tape_buffer_sizes obufsize, - const types::tape_buffer_sizes lbufsize, - const types::tape_buffer_sizes vbufsize, - const types::tape_buffer_sizes tbufsize); + start_taping(const types::tape_index tape_index, + const bool keep_independent_values, + const types::tape_buffer_sizes obufsize, + const types::tape_buffer_sizes lbufsize, + const types::tape_buffer_sizes vbufsize, + const types::tape_buffer_sizes tbufsize); /** * Disable the recording mode for a given tape. @@ -206,19 +213,19 @@ namespace Differentiation * should be written to file or kept in memory. */ static void - disable_taping(const types::tape_index active_tape_index, - const bool write_tapes_to_file); + stop_taping(const types::tape_index active_tape_index, + const bool write_tapes_to_file); /** - * Prints the statistics regarding the usage of the tapes. + * Print the statistics regarding the usage of the tapes. * - * @param[in] stream The output stream to which the values are to be - * written. * @param[in] tape_index The index of the tape to get the statistics of. + * @param[out] stream The output stream to which the values are to be + * written. */ static void - print_tape_stats(std::ostream & stream, - const types::tape_index tape_index); + print_tape_stats(const types::tape_index tape_index, + std::ostream & stream); //@} @@ -249,7 +256,7 @@ namespace Differentiation * dependent function is recorded. * @param[in] independent_variables The scalar values of the independent * variables whose sensitivities were tracked. - * @param[out] gradient The scalar values of the dependent function's + * @param[out] gradient The values of the dependent function's * gradients. It is expected that this vector be of the * correct size (with length * n_independent_variables). @@ -267,7 +274,7 @@ namespace Differentiation * dependent function is recorded. * @param[in] independent_variables The scalar values of the independent * variables whose sensitivities were tracked. - * @param[out] hessian The scalar values of the dependent function's + * @param[out] hessian The values of the dependent function's * Hessian. It is expected that this matrix be of the correct * size (with dimensions * n_independent_variables$\times$n_independent_variables). @@ -292,7 +299,7 @@ namespace Differentiation * @param[in] n_dependent_variables The number of dependent variables. * @param[in] independent_variables The scalar values of the independent * variables whose sensitivities were tracked. - * @param[out] values The scalar values of the dependent functions. + * @param[out] values The component values of the dependent functions. * It is expected that this vector be of the correct size * (with length n_dependent_variables). */ @@ -315,7 +322,7 @@ namespace Differentiation * @param[in] n_dependent_variables The number of dependent variables. * @param[in] independent_variables The scalar values of the independent * variables whose sensitivities were tracked. - * @param[out] jacobian The scalar values of the dependent functions' + * @param[out] jacobian The component values of the dependent functions' * Jacobian. It is expected that this matrix be of the correct * size (with dimensions * n_dependent_variables$\times$n_independent_variables). @@ -406,7 +413,7 @@ namespace Differentiation * sensitivities were tracked. * @param[in] dependent_variables The (single) dependent variable whose * gradients are to be extracted. - * @param[out] gradient The scalar values of the dependent function's + * @param[out] gradient The values of the dependent function's * gradients. It is expected that this vector be of the * correct size (with length * n_independent_variables). @@ -424,7 +431,7 @@ namespace Differentiation * sensitivities were tracked. * @param[in] dependent_variables The (single) dependent variable whose * Hessians are to be extracted. - * @param[out] hessian The scalar values of the dependent function's + * @param[out] hessian The values of the dependent function's * Hessian. It is expected that this matrix be of the correct * size (with dimensions * n_independent_variables$\times$n_independent_variables). @@ -446,7 +453,7 @@ namespace Differentiation * * @param[in] dependent_variables The dependent variables whose Hessians * are to be extracted. - * @param[out] values The scalar values of the dependent functions. + * @param[out] values The component values of the dependent functions. * It is expected that this vector be of the correct size * (with length n_dependent_variables). */ @@ -466,7 +473,7 @@ namespace Differentiation * sensitivities were tracked. * @param[in] dependent_variables The dependent variables whose Jacobian * are to be extracted. - * @param[out] jacobian The scalar values of the dependent functions' + * @param[out] jacobian The component values of the dependent functions' * Jacobian. It is expected that this matrix be of the correct * size (with dimensions * n_dependent_variables$\times$n_independent_variables). @@ -498,7 +505,7 @@ namespace Differentiation template void - TapedDrivers::enable_taping( + TapedDrivers::start_taping( const types::tape_index, const bool) { @@ -508,7 +515,7 @@ namespace Differentiation template void - TapedDrivers::enable_taping( + TapedDrivers::start_taping( const types::tape_index, const bool, const types::tape_buffer_sizes, @@ -522,7 +529,7 @@ namespace Differentiation template void - TapedDrivers::disable_taping( + TapedDrivers::stop_taping( const types::tape_index, const bool) { @@ -533,8 +540,8 @@ namespace Differentiation template void TapedDrivers::print_tape_stats( - std::ostream &, - const types::tape_index) + const types::tape_index, + std::ostream &) { AssertThrow(false, ExcRequiresADNumberSpecialization()); } @@ -618,19 +625,19 @@ namespace Differentiation // === Taping === static void - enable_taping(const types::tape_index tape_index, - const bool keep_independent_values) + start_taping(const types::tape_index tape_index, + const bool keep_independent_values) { trace_on(tape_index, keep_independent_values); } static void - enable_taping(const types::tape_index tape_index, - const bool keep_independent_values, - const types::tape_buffer_sizes obufsize, - const types::tape_buffer_sizes lbufsize, - const types::tape_buffer_sizes vbufsize, - const types::tape_buffer_sizes tbufsize) + start_taping(const types::tape_index tape_index, + const bool keep_independent_values, + const types::tape_buffer_sizes obufsize, + const types::tape_buffer_sizes lbufsize, + const types::tape_buffer_sizes vbufsize, + const types::tape_buffer_sizes tbufsize) { trace_on(tape_index, keep_independent_values, @@ -641,8 +648,8 @@ namespace Differentiation } static void - disable_taping(const types::tape_index active_tape_index, - const bool write_tapes_to_file) + stop_taping(const types::tape_index active_tape_index, + const bool write_tapes_to_file) { if (write_tapes_to_file) trace_off(active_tape_index); // Slow @@ -651,7 +658,7 @@ namespace Differentiation } static void - print_tape_stats(std::ostream &stream, const types::tape_index tape_index) + print_tape_stats(const types::tape_index tape_index, std::ostream &stream) { // See ADOL-C manual section 2.1 // and adolc/taping.h @@ -832,30 +839,30 @@ namespace Differentiation // === Taping === static void - enable_taping(const types::tape_index, const bool) + start_taping(const types::tape_index, const bool) { AssertThrow(false, ExcRequiresAdolC()); } static void - enable_taping(const types::tape_index, - const bool, - const types::tape_buffer_sizes, - const types::tape_buffer_sizes, - const types::tape_buffer_sizes, - const types::tape_buffer_sizes) + start_taping(const types::tape_index, + const bool, + const types::tape_buffer_sizes, + const types::tape_buffer_sizes, + const types::tape_buffer_sizes, + const types::tape_buffer_sizes) { AssertThrow(false, ExcRequiresAdolC()); } static void - disable_taping(const types::tape_index, const bool) + stop_taping(const types::tape_index, const bool) { AssertThrow(false, ExcRequiresAdolC()); } static void - print_tape_stats(std::ostream &, const types::tape_index) + print_tape_stats(const types::tape_index, std::ostream &) { AssertThrow(false, ExcRequiresAdolC()); } @@ -914,7 +921,7 @@ namespace Differentiation * Specialization for ADOL-C taped numbers. It is expected that the * scalar return type for this class is a float. * - * Note: ADOL-C only has drivers for doubles, and so floats are + * @note ADOL-C only has drivers for doubles, and so floats are * not intrinsically supported. This wrapper struct works around * the issue when necessary. */ @@ -930,26 +937,26 @@ namespace Differentiation // === Taping === static void - enable_taping(const types::tape_index tape_index, - const bool keep_independent_values) + start_taping(const types::tape_index tape_index, + const bool keep_independent_values) { // ADOL-C only supports 'double', not 'float', so we can forward to // the 'double' implementation of this function - TapedDrivers::enable_taping( + TapedDrivers::start_taping( tape_index, keep_independent_values); } static void - enable_taping(const types::tape_index tape_index, - const bool keep_independent_values, - const types::tape_buffer_sizes obufsize, - const types::tape_buffer_sizes lbufsize, - const types::tape_buffer_sizes vbufsize, - const types::tape_buffer_sizes tbufsize) + start_taping(const types::tape_index tape_index, + const bool keep_independent_values, + const types::tape_buffer_sizes obufsize, + const types::tape_buffer_sizes lbufsize, + const types::tape_buffer_sizes vbufsize, + const types::tape_buffer_sizes tbufsize) { // ADOL-C only supports 'double', not 'float', so we can forward to // the 'double' implementation of this function - TapedDrivers::enable_taping( + TapedDrivers::start_taping( tape_index, keep_independent_values, obufsize, @@ -959,22 +966,22 @@ namespace Differentiation } static void - disable_taping(const types::tape_index active_tape_index, - const bool write_tapes_to_file) + stop_taping(const types::tape_index active_tape_index, + const bool write_tapes_to_file) { // ADOL-C only supports 'double', not 'float', so we can forward to // the 'double' implementation of this function - TapedDrivers::disable_taping(active_tape_index, - write_tapes_to_file); + TapedDrivers::stop_taping(active_tape_index, + write_tapes_to_file); } static void - print_tape_stats(std::ostream &stream, const types::tape_index tape_index) + print_tape_stats(const types::tape_index tape_index, std::ostream &stream) { // ADOL-C only supports 'double', not 'float', so we can forward to // the 'double' implementation of this function - TapedDrivers::print_tape_stats(stream, - tape_index); + TapedDrivers::print_tape_stats(tape_index, + stream); } // === Scalar drivers === @@ -1141,12 +1148,11 @@ namespace Differentiation * reverse-mode AD. */ template - static - typename std::enable_if::type_code == - NumberTypes::sacado_rad || - ADNumberTraits::type_code == - NumberTypes::sacado_rad_dfad)>::type - reverse_mode_dependent_variable_activation(ADNumberType &) + typename std::enable_if::type_code == + NumberTypes::sacado_rad || + ADNumberTraits::type_code == + NumberTypes::sacado_rad_dfad)>::type + reverse_mode_dependent_variable_activation(ADNumberType &) {} # ifdef DEAL_II_TRILINOS_WITH_SACADO @@ -1161,10 +1167,10 @@ namespace Differentiation * to. This function broadcasts this information. */ template - static typename std::enable_if::type_code == - NumberTypes::sacado_rad || - ADNumberTraits::type_code == - NumberTypes::sacado_rad_dfad>::type + typename std::enable_if::type_code == + NumberTypes::sacado_rad || + ADNumberTraits::type_code == + NumberTypes::sacado_rad_dfad>::type reverse_mode_dependent_variable_activation( ADNumberType &dependent_variable) { @@ -1187,10 +1193,9 @@ namespace Differentiation * auto-differentiable numbers. */ template - static - typename std::enable_if::type_code == - NumberTypes::adolc_tapeless)>::type - configure_tapeless_mode(const unsigned int) + typename std::enable_if::type_code == + NumberTypes::adolc_tapeless)>::type + configure_tapeless_mode(const unsigned int) {} @@ -1205,8 +1210,8 @@ namespace Differentiation * If not then it throws an error. */ template - static typename std::enable_if::type_code == - NumberTypes::adolc_tapeless>::type + typename std::enable_if::type_code == + NumberTypes::adolc_tapeless>::type configure_tapeless_mode(const unsigned int n_directional_derivatives) { # ifdef DEAL_II_ADOLC_WITH_TAPELESS_REFCOUNTING @@ -1266,8 +1271,8 @@ namespace Differentiation # else // DEAL_II_WITH_ADOLC template - static typename std::enable_if::type_code == - NumberTypes::adolc_tapeless>::type + typename std::enable_if::type_code == + NumberTypes::adolc_tapeless>::type configure_tapeless_mode(const unsigned int n_directional_derivatives) { AssertThrow(false, ExcRequiresAdolC());