From: Jean-Paul Pelteret Date: Fri, 10 May 2019 23:16:13 +0000 (+0200) Subject: Improve function documentation and add some extra template parameters X-Git-Tag: v9.1.0-rc1~68^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F8008%2Fhead;p=dealii.git Improve function documentation and add some extra template parameters --- diff --git a/include/deal.II/differentiation/sd/symengine_scalar_operations.h b/include/deal.II/differentiation/sd/symengine_scalar_operations.h index 86cc7518d0..ab8029fa39 100644 --- a/include/deal.II/differentiation/sd/symengine_scalar_operations.h +++ b/include/deal.II/differentiation/sd/symengine_scalar_operations.h @@ -164,22 +164,32 @@ namespace Differentiation } // namespace internal /** - * Return a symbolic map that has the entry key given by @p symbol. - * It is expected that all entries be valid symbols or symbolic expressions. + * Return a symbolic map that has a single entry with the key given by + * the @p symbol. + * It is expected that all entries to be added to the symbolic map are + * valid symbols or symbolic expressions. + * + * @tparam ignore_invalid_symbols See the + * @ref add_to_symbol_map(types::substitution_map &,const + * Expression &) function for a detailed discussion on the role of this + * template argument. * * @tparam SymbolicType Any symbolic type that is understood by the * add_to_symbol_map() functions. This includes individual * Expression, std::vector, as well as * Tensors and SymmetricTensors of Expressions. */ - template + template types::substitution_map make_symbol_map(const SymbolicType &symbol); /** * Return a symbolic map that has the entry keys given by @p symbol and all - * @p other_symbols. It is expected that all entries be valid symbols or - * symbolic expressions. + * @p other_symbols. + * It is expected that all entries to be added to the symbolic map are + * valid symbols or symbolic expressions. * * With this function it is possible to construct a symbolic map from * different types. An example may be as follows: @@ -192,18 +202,30 @@ namespace Differentiation * SymmetricTensor<2,dim,Expression>(...)); * @endcode * + * @tparam ignore_invalid_symbols See the + * @ref add_to_symbol_map(types::substitution_map &,const + * Expression &) function for a detailed discussion on the role of this + * template argument. + * * @tparam SymbolicType Any symbolic type that is understood by the * add_to_symbol_map() functions. This includes individual * Expression, std::vector, as well as * Tensors and SymmetricTensors of Expressions. + * @tparam Args A type associated with the parameter pack that contains + * any number of other @p SymbolicTypes. All types held by the + * parameter pack share the same restriction as the @p SymbolicType + * documented above. */ - template + template types::substitution_map make_symbol_map(const SymbolicType &symbol, const Args &... other_symbols); /** - * A convenience function for an adding empty entry, with the key value - * given by @p symbol, to the symbolic map @p substitution_map. + * A convenience function for adding an empty entry, with the key value + * given by @p symbol, to the symbolic map @p symbol_map. * * This function is guaranteed to create an ordering that is identical * to the typical add_to_substitution_map() call that is used when @@ -234,7 +256,8 @@ namespace Differentiation * entries would be skipped over and ignored. * * @note In this function, the @p ValueType is somewhat arbitrary as - * it is only used to create dummy values. + * it is only used to create default-constructed values as entries in + * the map. */ template void @@ -242,8 +265,8 @@ namespace Differentiation const Expression & symbol); /** - * A convenience function for an adding empty entry, with the key value - * given by @p symbol, to the symbolic map @p substitution_map. + * A convenience function for adding an empty entry, with the key value + * given by @p symbol, to the symbolic map @p symbol_map. * * For more context which this function is used, see the other * @ref add_to_symbol_map(types::substitution_map &,const @@ -254,13 +277,25 @@ namespace Differentiation * Expression &) function for a detailed discussion on the role of this * template argument. * - * @note In this function, the @p ValueType is somewhat arbitrary as - * it is only used to create dummy values. + * @tparam SymbolicType A type that represents a symbolic variable. + * The Differentiation::SD::Expression class is often suitable for + * this purpose, although if the @p ValueType is not supported + * by this class then a user-defined @p SymbolicType should be + * used. + * @tparam ValueType A type that corresponds to the @p value that the + * @p symbol is to represent. This @p ValueType is somewhat + * arbitrary as it is only used to create default-constructed + * values as entries in the map. + * @tparam T An arbitrary type resulting from the application of + * the SFINAE idiom to selectively specialize this class. + * The required condition is fulfilled when the @p SymbolicType + * can be explicitly converted to a + * `const SymEngine::RCP &`. */ template ::value && dealii::internal::is_explicitly_convertible< SymbolicType, @@ -284,8 +319,15 @@ namespace Differentiation * @ref add_to_symbol_map(types::substitution_map &,const * Expression &) function for a detailed discussion on the role of this * template argument. + * + * @tparam SymbolicType Any symbolic type that is understood by the + * add_to_symbol_map() functions. This includes an individual + * Expression, as well as Tensors and SymmetricTensors of + * Expressions. */ - template + template void add_to_symbol_map(types::substitution_map & symbol_map, const std::vector &symbols); @@ -304,7 +346,7 @@ namespace Differentiation * Expression &) function for a detailed discussion on the role of this * template argument. */ - template + template void add_to_symbol_map(types::substitution_map & symbol_map, const types::substitution_map &other_symbols); @@ -337,8 +379,18 @@ namespace Differentiation * @ref add_to_symbol_map(types::substitution_map &,const * Expression &) function for a detailed discussion on the role of this * template argument. + * + * @tparam SymbolicType Any symbolic type that is understood by the + * add_to_symbol_map() functions. This includes individual + * Expression, std::vector, as well as + * Tensors and SymmetricTensors of Expressions. + * @tparam Args A type associated with the parameter pack that contains + * any number of other @p SymbolicTypes. All types held by the + * parameter pack share the same restriction as the @p SymbolicType + * documented above. */ template void @@ -347,7 +399,7 @@ namespace Differentiation const Args &... other_symbols); /** - * Find the input @p symbol in the @p substitution_map and set its + * Find the entry for @p symbol in the @p substitution_map and set its * corresponding @p value. * * This function may be used to safely transform an existing or null @@ -360,16 +412,34 @@ namespace Differentiation const Expression & value); /** - * Find the input @p symbol in the @p substitution_map and set its + * Find the entry for @p symbol in the @p substitution_map and set its * corresponding @p value. * * This function may be used to safely transform an existing or null * symbolic map (one with uninitialized entries) into one that can be used * to conduct symbolic substitution operations (i.e., a substitution map). + * + * @tparam SymbolicType A type that represents a symbolic variable. + * The Differentiation::SD::Expression class is often suitable for + * this purpose, although if the @p ValueType is not supported + * by this class then a user-defined @p SymbolicType should be + * used. + * @tparam ValueType A type that corresponds to the @p value that the + * @p symbol is to represent. Although it is typically + * arithmetic in nature, it may also represent another symbolic + * expression type or be a special type that a user-defined + * @p ExpressionType can be constructed from. + * @tparam T An arbitrary type resulting from the application of + * the SFINAE idiom to selectively specialize this class. + * The required condition is fulfilled when the @p SymbolicType + * can be explicitly converted to a + * `const SymEngine::RCP &`, and it is + * possible to construct an @p SymbolicType directly from the + * @p ValueType. */ - template &>::value && @@ -380,47 +450,82 @@ namespace Differentiation const ValueType & value); /** - * Find the input @p symbols in the @p substitution_map and set their + * Find the entries for @p symbols in the @p substitution_map and set their * corresponding @p values. * * This function may be used to safely transform an existing or null * symbolic map (one with uninitialized entries) into one that can be used * to conduct symbolic substitution operations (i.e., a substitution map). + * + * @tparam SymbolicType A type that represents a symbolic variable. + * The Differentiation::SD::Expression class is often suitable for + * this purpose, although if the @p ValueType is not supported + * by this class then a user-defined @p SymbolicType should be + * used. + * @tparam ValueType A type that corresponds to the @p value that the + * @p symbol is to represent. Although it is typically + * arithmetic in nature, it may also represent another symbolic + * expression type or be a special type that a user-defined + * @p SymbolicType can be constructed from. */ - template + template void set_value_in_symbol_map(types::substitution_map & substitution_map, const std::vector &symbols, const std::vector & values); /** - * Find the input @p symbols in the @p substitution_map and set their + * Find the entry for @p symbols in the @p substitution_map and set their * corresponding @p values. The modified symbol will have the key given by - * the first element of @p symbol_value and the value given by its second + * the first element of @p symbol_value and the value given by its second * element. * * This function may be used to safely transform an existing or null * symbolic map (one with uninitialized entries) into one that can be used * to conduct symbolic substitution operations (i.e., a substitution map). + * + * @tparam SymbolicType A type that represents a symbolic variable. + * The Differentiation::SD::Expression class is often suitable for + * this purpose, although if the @p ValueType is not supported + * by this class then a user-defined @p SymbolicType should be + * used. + * @tparam ValueType A type that corresponds to the @p value that the + * @p symbol is to represent. Although it is typically + * arithmetic in nature, it may also represent another symbolic + * expression type or be a special type that a user-defined + * @p SymbolicType can be constructed from. */ - template + template void set_value_in_symbol_map( types::substitution_map & substitution_map, const std::pair &symbol_value); /** - * Find the input @p symbols in the @p substitution_map and set their + * Find the entries for @p symbols in the @p substitution_map and set their * corresponding @p values, followed by the same operation for the * @p other_symbol_values. * * This function may be used to safely transform an existing or null * symbolic map (one with uninitialized entries) into one that can be used * to conduct symbolic substitution operations (i.e., a substitution map). + * + * @tparam SymbolicType A type that represents a symbolic variable. + * The Differentiation::SD::Expression class is often suitable for + * this purpose, although if the @p ValueType is not supported + * by this class then a user-defined @p SymbolicType should be + * used. + * @tparam ValueType A type that corresponds to the @p value that the + * @p symbol is to represent. Although it is typically + * arithmetic in nature, it may also represent another symbolic + * expression type or be a special type that a user-defined + * @p SymbolicType can be constructed from. + * @tparam Args A type associated with the parameter pack that contains + * any number of other pairs of @p SymbolicTypes and @p ValueTypes. + * All types held by the parameter pack share the same restriction + * as the @p SymbolicType and @p ValueType documented above. */ - template + template void set_value_in_symbol_map( types::substitution_map & substitution_map, @@ -428,7 +533,7 @@ namespace Differentiation const Args &... other_symbol_values); /** - * Find the input @p symbols in the @p substitution_map and set their + * Find the entries for @p symbols in the @p substitution_map and set their * corresponding @p values. The modified symbol will have the key given by * the first element of each paired entry in the @p symbol_values vector * and the value given by its respective second element. @@ -436,6 +541,17 @@ namespace Differentiation * This function may be used to safely transform an existing or null * symbolic map (one with uninitialized entries) into one that can be used * to conduct symbolic substitution operations (i.e., a substitution map). + * + * @tparam SymbolicType A type that represents a symbolic variable. + * The Differentiation::SD::Expression class is often suitable for + * this purpose, although if the @p ValueType is not supported + * by this class then a user-defined @p SymbolicType should be + * used. + * @tparam ValueType A type that corresponds to the @p value that the + * @p symbol is to represent. Although it is typically + * arithmetic in nature, it may also represent another symbolic + * expression type or be a special type that a user-defined + * @p SymbolicType can be constructed from. */ template void @@ -444,7 +560,7 @@ namespace Differentiation const std::vector> &symbol_values); /** - * Find the input @p symbols in the @p substitution_map and set their + * Find the entries for @p symbols in the @p substitution_map and set their * corresponding @p values. The modified symbol will have the key given by * the each element the @p symbol_values map and the value given by its * respective mapped element. @@ -996,22 +1112,29 @@ namespace Differentiation /* ---------------- Symbol map creation and manipulation --------------*/ - template + template types::substitution_map make_symbol_map(const SymbolicType &symbol) { types::substitution_map symbol_map; - add_to_symbol_map(symbol_map, symbol); + add_to_symbol_map(symbol_map, symbol); return symbol_map; } - template + template types::substitution_map make_symbol_map(const SymbolicType &symbol, const Args &... other_symbols) { types::substitution_map symbol_map; - add_to_symbol_map(symbol_map, symbol, other_symbols...); + add_to_symbol_map(symbol_map, + symbol, + other_symbols...); return symbol_map; } @@ -1030,8 +1153,8 @@ namespace Differentiation template void add_to_symbol_map(types::substitution_map &symbol_map, @@ -1046,17 +1169,20 @@ namespace Differentiation } - template + template void add_to_symbol_map(types::substitution_map & symbol_map, const std::vector &symbols) { for (const auto &symbol : symbols) - add_to_symbol_map(symbol_map, symbol); + add_to_symbol_map(symbol_map, + symbol); } - template + template void add_to_symbol_map(types::substitution_map & symbol_map, const types::substitution_map &other_symbols) @@ -1072,13 +1198,14 @@ namespace Differentiation { Assert(symbol_map.find(it->first) == symbol_map.end(), ExcMessage("Entry already exists in symbol map")); - add_to_symbol_map(symbol_map, - Expression(it->first)); + add_to_symbol_map( + symbol_map, Expression(it->first)); } } template void @@ -1086,8 +1213,9 @@ namespace Differentiation const SymbolicType & symbol, const Args &... other_symbols) { - add_to_symbol_map(symbol_map, symbol); - add_to_symbol_map(symbol_map, other_symbols...); + add_to_symbol_map(symbol_map, symbol); + add_to_symbol_map(symbol_map, + other_symbols...); } diff --git a/include/deal.II/differentiation/sd/symengine_tensor_operations.h b/include/deal.II/differentiation/sd/symengine_tensor_operations.h index ee781d4ae3..a572f950a0 100644 --- a/include/deal.II/differentiation/sd/symengine_tensor_operations.h +++ b/include/deal.II/differentiation/sd/symengine_tensor_operations.h @@ -385,16 +385,24 @@ namespace Differentiation * Expression &) function for a detailed discussion on the role of this * template argument. * - * @note In this function, the @p ValueType is somewhat arbitrary as - * it is only used to create dummy values. + * @tparam SymbolicType A type that represents a symbolic variable. + * The Differentiation::SD::Expression class is often suitable for + * this purpose, although if the @p ValueType is not supported + * by this class then a user-defined @p SymbolicType should be + * used. + * @tparam ValueType A type that corresponds to the @p value that the + * @p symbol is to represent. This @p ValueType is somewhat + * arbitrary as it is only used to create default-constructed + * values as entries in the map. */ template + typename ValueType = double, + int rank, + int dim, + typename SymbolicType> void - add_to_symbol_map(types::substitution_map & symbol_map, - const Tensor &symbol_tensor); + add_to_symbol_map(types::substitution_map & symbol_map, + const Tensor &symbol_tensor); /** * A convenience function for adding empty entries, with the key values @@ -410,17 +418,25 @@ namespace Differentiation * Expression &) function for a detailed discussion on the role of this * template argument. * - * @note In this function, the @p ValueType is somewhat arbitrary as - * it is only used to create dummy values. + * @tparam SymbolicType A type that represents a symbolic variable. + * The Differentiation::SD::Expression class is often suitable for + * this purpose, although if the @p ValueType is not supported + * by this class then a user-defined @p SymbolicType should be + * used. + * @tparam ValueType A type that corresponds to the @p value that the + * @p symbol is to represent. This @p ValueType is somewhat + * arbitrary as it is only used to create default-constructed + * values as entries in the map. */ template + typename ValueType = double, + int rank, + int dim, + typename SymbolicType> void add_to_symbol_map( - types::substitution_map & symbol_map, - const SymmetricTensor &symbol_tensor); + types::substitution_map & symbol_map, + const SymmetricTensor &symbol_tensor); /** * Find the input @p symbols in the @p substitution_map and set the entries @@ -430,12 +446,24 @@ namespace Differentiation * This function may be used to safely transform an existing or null * symbolic map (one with uninitialized entries) into one that can be used * to conduct symbolic substitution operations (i.e., a substitution map). + * + * @tparam SymbolicType A type that represents a symbolic variable. + * The Differentiation::SD::Expression class is often suitable for + * this purpose, although if the @p ValueType is not supported + * by this class then a user-defined @p SymbolicType should be + * used. + * @tparam ValueType A type that corresponds to the @p value that the + * @p symbol is to represent. Although it is typically + * arithmetic in nature, it may also represent another symbolic + * expression type or be a special type that a user-defined + * @p ExpressionType can be constructed from. */ - template + template void - set_value_in_symbol_map(types::substitution_map &substitution_map, - const Tensor &symbol_tensor, - const Tensor & value_tensor); + set_value_in_symbol_map( + types::substitution_map & substitution_map, + const Tensor &symbol_tensor, + const Tensor & value_tensor); /** * Find the input @p symbols in the @p substitution_map and set the entries @@ -445,13 +473,24 @@ namespace Differentiation * This function may be used to safely transform an existing or null * symbolic map (one with uninitialized entries) into one that can be used * to conduct symbolic substitution operations (i.e., a substitution map). + * + * @tparam SymbolicType A type that represents a symbolic variable. + * The Differentiation::SD::Expression class is often suitable for + * this purpose, although if the @p ValueType is not supported + * by this class then a user-defined @p SymbolicType should be + * used. + * @tparam ValueType A type that corresponds to the @p value that the + * @p symbol is to represent. Although it is typically + * arithmetic in nature, it may also represent another symbolic + * expression type or be a special type that a user-defined + * @p ExpressionType can be constructed from. */ - template + template void set_value_in_symbol_map( - types::substitution_map & substitution_map, - const SymmetricTensor &symbol_tensor, - const SymmetricTensor & value_tensor); + types::substitution_map & substitution_map, + const SymmetricTensor &symbol_tensor, + const SymmetricTensor & value_tensor); //@} @@ -943,15 +982,16 @@ namespace Differentiation namespace internal { - template class TensorType> void - tensor_set_value_in_symbol_map( - types::substitution_map & substitution_map, - const TensorType &symbol_tensor, - const TensorType & value_tensor) + set_tensor_value_in_symbol_map( + types::substitution_map & substitution_map, + const TensorType &symbol_tensor, + const TensorType & value_tensor) { TensorType out; for (unsigned int i = 0; i < out.n_independent_components; ++i) @@ -965,12 +1005,12 @@ namespace Differentiation } - template + template void - tensor_set_value_in_symbol_map( - types::substitution_map & substitution_map, - const SymmetricTensor<4, dim, Expression> &symbol_tensor, - const SymmetricTensor<4, dim, ValueType> & value_tensor) + set_tensor_value_in_symbol_map( + types::substitution_map & substitution_map, + const SymmetricTensor<4, dim, SymbolicType> &symbol_tensor, + const SymmetricTensor<4, dim, ValueType> & value_tensor) { SymmetricTensor<4, dim, Expression> out; for (unsigned int i = 0; @@ -991,12 +1031,13 @@ namespace Differentiation template + typename ValueType, + int rank, + int dim, + typename SymbolicType> void - add_to_symbol_map(types::substitution_map & symbol_map, - const Tensor &symbol_tensor) + add_to_symbol_map(types::substitution_map & symbol_map, + const Tensor &symbol_tensor) { // Call the above function add_to_substitution_map( @@ -1005,13 +1046,14 @@ namespace Differentiation template + typename ValueType, + int rank, + int dim, + typename SymbolicType> void add_to_symbol_map( - types::substitution_map & symbol_map, - const SymmetricTensor &symbol_tensor) + types::substitution_map & symbol_map, + const SymmetricTensor &symbol_tensor) { // Call the above function add_to_substitution_map( @@ -1019,26 +1061,27 @@ namespace Differentiation } - template + template void - set_value_in_symbol_map(types::substitution_map &substitution_map, - const Tensor &symbol_tensor, - const Tensor & value_tensor) + set_value_in_symbol_map( + types::substitution_map & substitution_map, + const Tensor &symbol_tensor, + const Tensor & value_tensor) { - internal::tensor_set_value_in_symbol_map(substitution_map, + internal::set_tensor_value_in_symbol_map(substitution_map, symbol_tensor, value_tensor); } - template + template void set_value_in_symbol_map( - types::substitution_map & substitution_map, - const SymmetricTensor &symbol_tensor, - const SymmetricTensor & value_tensor) + types::substitution_map & substitution_map, + const SymmetricTensor &symbol_tensor, + const SymmetricTensor & value_tensor) { - internal::tensor_set_value_in_symbol_map(substitution_map, + internal::set_tensor_value_in_symbol_map(substitution_map, symbol_tensor, value_tensor); } diff --git a/source/differentiation/sd/symengine_scalar_operations.cc b/source/differentiation/sd/symengine_scalar_operations.cc index ae0bfb7c92..9ac872b12f 100644 --- a/source/differentiation/sd/symengine_scalar_operations.cc +++ b/source/differentiation/sd/symengine_scalar_operations.cc @@ -133,8 +133,7 @@ namespace Differentiation ExcMessage( "Substitution with a number that does not represent a symbol or symbolic derivative")); - types::substitution_map::iterator it_sym = - substitution_map.find(Expression(symbol)); + auto it_sym = substitution_map.find(Expression(symbol)); Assert(it_sym != substitution_map.end(), ExcMessage("Did not find this symbol in the map."));