Debian Codegraph @

include/deal.II/differentiation/sd/symengine_scalar_operations.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2019 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_differentiation_sd_symengine_scalar_operations_h
16 #define dealii_differentiation_sd_symengine_scalar_operations_h
17
18 #include <deal.II/base/config.h>
19
20 #ifdef DEAL_II_WITH_SYMENGINE
21
22 # include <deal.II/base/numbers.h>
23
24 # include <deal.II/differentiation/sd/symengine_number_types.h>
25 # include <deal.II/differentiation/sd/symengine_types.h>
26
27 # include <symengine/basic.h>
28 # include <symengine/symengine_rcp.h>
29
30 # include <algorithm>
31 # include <type_traits>
32 # include <utility>
33 # include <vector>
34
35 DEAL_II_NAMESPACE_OPEN
36
37 namespace Differentiation
38 {
39 namespace SD
40 {
41 /**
42 * @name Symbolic variable creation
43 */
44 /** @{ */
45
46 /**
47 * Return an Expression representing a scalar symbolic variable
48 * with the identifier specified by @p symbol.
49 *
50 * For example, if the @p symbol is the string `"x"` then the scalar
51 * symbolic variable that is returned represents the scalar $x$.
52 *
53 * @param[in] symbol An identifier (or name) for the returned symbolic
54 * variable.
55 * @return A scalar symbolic variable with the name @p symbol.
56 *
57 * @warning It is up to the user to ensure that there is no ambiguity in the
58 * symbols used within a section of code.
59 */
60 Expression
61 make_symbol(const std::string &symbol);
62
63 /**
64 * Return an Expression representing a scalar symbolic function
65 * with the identifier specified by @p symbol. The function's symbolic
66 * dependencies are specified by the input @p arguments.
67 *
68 * For example, if the @p symbol is the string `"f"`, and the
69 * arguments to the function that is generated are the
70 * symbolic variable `x` and the symbolic expression `y+z`, then the
71 * generic symbolic function that is returned represents $f(x, y+z)$.
72 *
73 * @param[in] symbol An identifier (or name) for the returned symbolic
74 * function.
75 * @param[in] arguments A vector of input arguments to the returned
76 * symbolic function.
77 * @return A generic symbolic function with the identifier @p symbolic and
78 * the number of input arguments equal to the length of @p arguments.
79 *
80 * @warning It is up to the user to ensure that there is no ambiguity in the
81 * symbols used within a section of code.
82 */
83 Expression
84 make_symbolic_function(const std::string &symbol,
85 const types::symbol_vector &arguments);
86
87 /**
88 * Return an Expression representing a scalar symbolic function
89 * with the identifier specified by @p symbol. The function's symbolic
90 * dependencies are specified by the keys to the input @p arguments map;
91 * the values stored in the map are ignored.
92 *
93 * For example, if the @p symbol is the string `"f"`, and the
94 * arguments to the function that is generated are the
95 * symbolic variable `x` and the symbolic expression `y+z`, then the
96 * generic symbolic function that is returned represents $f(x, y+z)$.
97 *
98 * @param[in] symbol An identifier (or name) for the returned symbolic
99 * function.
100 * @param[in] arguments A map of input arguments to the returned
101 * symbolic function.
102 * @return A generic symbolic function with the identifier @p symbolic and
103 * the number of input arguments equal to the length of @p arguments.
104 *
105 * @warning It is up to the user to ensure that there is no ambiguity in the
106 * symbols used within a section of code.
107 */
108 Expression
109 make_symbolic_function(const std::string &symbol,
110 const types::substitution_map &arguments);
111
112 /** @} */
113
114 /**
115 * @name Symbolic differentiation
116 */
117 /** @{ */
118
119 /**
120 * Return the symbolic result of computing the partial derivative of the
121 * scalar @p f with respect to the scalar @p x.
122 * In most use cases the function or variable @p f would be called the
123 * dependent variable, and @p x the independent variable.
124 *
125 * @param[in] f A scalar symbolic function or (dependent) expression.
126 * @param[in] x A scalar symbolic (independent) variable.
127 * @return The symbolic function or expression representing the result
128 * $\frac{\partial f}{\partial x}$.
129 */
130 Expression
131 differentiate(const Expression &f, const Expression &x);
132
133 /** @} */
134
135 /**
136 * @name Symbol map creation and manipulation
137 */
138 /** @{ */
139
140 namespace internal
141 {
142 /**
143 * Return whether or not an @p entry is a valid symbol that
144 * we can expect to perform substitution on.
145 */
146 bool
147 is_valid_substitution_symbol(const SymEngine::Basic &entry);
148
149 /**
150 * A convenience function to set the @p value associated with
151 * the @p symbol in the @p substitution_map.
152 *
153 * Using this function ensures that the @p symbol is one that is
154 * valid specifically for the purpose of symbolic substitution.
155 * It must therefore represent a symbol or symbolic derivative,
156 * otherwise an error will be thrown.
157 */
158 void
159 set_value_in_symbol_map(
160 types::substitution_map &substitution_map,
161 const SymEngine::RCP<const SymEngine::Basic> &symbol,
162 const SymEngine::RCP<const SymEngine::Basic> &value);
163 } // namespace internal
164
165 /**
166 * Return a symbolic map that has a single entry with the key given by
167 * the @p symbol.
168 * It is expected that all entries to be added to the symbolic map are
169 * valid symbols or symbolic expressions.
170 *
171 * @tparam ignore_invalid_symbols See the
172 * `add_to_symbol_map(types::substitution_map &, const Expression &)`
173 * function for a detailed discussion on the role of this
174 * template argument.
175 *
176 * @tparam SymbolicType Any symbolic type that is understood by the
177 * add_to_symbol_map() functions. This includes individual
178 * Expression, std::vector<Expression>, as well as
179 * Tensors and SymmetricTensors of Expressions.
180 * @tparam ValueType A type that corresponds to the @p value that the
181 * @p symbol is to represent. This @p ValueType is somewhat
182 * arbitrary as it is only used to create default-constructed
183 * values as entries in the map.
184 */
185 template <bool ignore_invalid_symbols = false,
186 typename ValueType = double,
187 typename SymbolicType>
188 types::substitution_map
189 make_symbol_map(const SymbolicType &symbol);
190
191 /**
192 * Return a symbolic map that has the entry keys given by @p symbol and all
193 * @p other_symbols.
194 * It is expected that all entries to be added to the symbolic map are
195 * valid symbols or symbolic expressions.
196 *
197 * With this function it is possible to construct a symbolic map from
198 * different types. An example may be as follows:
199 *
200 * @code
201 * const types::substitution_map symbol_map
202 * = make_symbol_map(
203 * Expression(...),
204 * Tensor<1,dim,Expression>(...),
205 * SymmetricTensor<2,dim,Expression>(...));
206 * @endcode
207 *
208 * @tparam ignore_invalid_symbols See the
209 * `add_to_symbol_map(types::substitution_map &, const Expression &)`
210 * function for a detailed discussion on the role of this
211 * template argument.
212 *
213 * @tparam SymbolicType Any symbolic type that is understood by the
214 * add_to_symbol_map() functions. This includes individual
215 * Expression, std::vector<Expression>, as well as
216 * Tensors and SymmetricTensors of Expressions.
217 * @tparam ValueType A type that corresponds to the @p value that the
218 * @p symbol is to represent. This @p ValueType is somewhat
219 * arbitrary as it is only used to create default-constructed
220 * values as entries in the map.
221 * @tparam Args A type associated with the parameter pack that contains
222 * any number of other @p SymbolicTypes. All types held by the
223 * parameter pack share the same restriction as the @p SymbolicType
224 * documented above.
225 */
226 template <bool ignore_invalid_symbols = false,
227 typename ValueType = double,
228 typename SymbolicType,
229 typename... Args>
230 types::substitution_map
231 make_symbol_map(const SymbolicType &symbol, const Args &...other_symbols);
232
233 /**
234 * A convenience function for adding an empty entry, with the key value
235 * given by @p symbol, to the symbolic map @p symbol_map.
236 *
237 * This function is guaranteed to create an ordering that is identical
238 * to the typical add_to_substitution_map() call that is used when
239 * constructing a map to perform symbol substitution.
240 * It exists primarily to create an initial map that can be used in the
241 * optimize() call to a BatchOptimizer, specifically if the values that
242 * are to be substituted into the map are not known at the time that the
243 * symbols used to construct symbolic expressions are defined.
244 * This helps one conform to the requirement that the arguments sent into
245 * lambda and LLVM JIT compiled functions (created by optimizing symbolic
246 * expressions) (i) be the same, and (ii) have a constant ordering.
247 *
248 * @tparam ignore_invalid_symbols A template parameter that enforces whether
249 * or not the @p symbol has to be a valid one or not. In the
250 * overwhelming majority of cases, the default value of
251 * <tt>false</tt> should be selected, with the result that an
252 * exception will be thrown if the input @p symbolic is, in fact,
253 * not a symbolic value or expression.
254 * An exceptional case is, for example, when performing symbolic
255 * assembly on a finite element level. When extracting the symbolic
256 * equivalent of the shape function gradients using FEExtractors,
257 * the returned tensor will have some <em>a priori</em> determined
258 * zero-valued components. These trivial components are not valid
259 * symbols (as they are not symbolic expressions), and we would
260 * typically wish to guard against their (erroneous) inclusion. In
261 * this scenario, for convenience, one could set
262 * @p ignore_invalid_symbols to <tt>true</tt> and these zero-valued
263 * entries would be skipped over and ignored.
264 *
265 * @note In this function, the @p ValueType is somewhat arbitrary as
266 * it is only used to create default-constructed values as entries in
267 * the map.
268 */
269 template <bool ignore_invalid_symbols = false, typename ValueType = double>
270 void
271 add_to_symbol_map(types::substitution_map &symbol_map,
272 const Expression &symbol);
273
274 /**
275 * A convenience function for adding an empty entry, with the key value
276 * given by @p symbol, to the symbolic map @p symbol_map.
277 *
278 * For more context which this function is used, see the other
279 * `add_to_symbol_map(types::substitution_map &, const Expression &)`
280 * function.
281 *
282 * @tparam ignore_invalid_symbols See the other
283 * `add_to_symbol_map(types::substitution_map &, const Expression &)`
284 * function for a detailed discussion on the role of this
285 * template argument.
286 *
287 * @tparam SymbolicType A type that represents a symbolic variable.
288 * The Differentiation::SD::Expression class is often suitable for
289 * this purpose, although if the @p ValueType is not supported
290 * by this class then a user-defined @p SymbolicType should be
291 * used.
292 * @tparam ValueType A type that corresponds to the @p value that the
293 * @p symbol is to represent. This @p ValueType is somewhat
294 * arbitrary as it is only used to create default-constructed
295 * values as entries in the map.
296 * @tparam T An arbitrary type resulting from the application of
297 * the SFINAE idiom to selectively specialize this class.
298 * The required condition is fulfilled when the @p SymbolicType
299 * can be explicitly converted to a
300 * `const SymEngine::RCP<const SymEngine::Basic> &`.
301 */
302 template <bool ignore_invalid_symbols = false,
303 typename ValueType = double,
304 typename SymbolicType,
305 typename T = std::enable_if_t<
306 !std::is_base_of_v<Expression, SymbolicType> &&
307 dealii::internal::is_explicitly_convertible<
308 SymbolicType,
309 const SymEngine::RCP<const SymEngine::Basic> &>::value>>
310 void
311 add_to_symbol_map(types::substitution_map &symbol_map,
312 const SymbolicType &symbol);
313
314 /**
315 * A convenience function for adding empty entries, with the key values
316 * equal to the entries in @p symbols, to the symbolic map @p symbol_map.
317 * It is expected that all entries in the input vector @p symbols be
318 * of @p SymbolicType, compatible with the other add_to_symbol_map()
319 * functions.
320 *
321 * For more context which this function is used, see the other
322 * `add_to_symbol_map(types::substitution_map &, const Expression &)`
323 * function.
324 *
325 * @tparam ignore_invalid_symbols See the other
326 * `add_to_symbol_map(types::substitution_map &, const Expression &)`
327 * function for a detailed discussion on the role of this
328 * template argument.
329 *
330 * @tparam SymbolicType Any symbolic type that is understood by the
331 * add_to_symbol_map() functions. This includes an individual
332 * Expression, as well as Tensors and SymmetricTensors of
333 * Expressions.
334 * @tparam ValueType A type that corresponds to the @p value that the
335 * @p symbol is to represent. This @p ValueType is somewhat
336 * arbitrary as it is only used to create default-constructed
337 * values as entries in the map.
338 */
339 template <bool ignore_invalid_symbols = false,
340 typename ValueType = double,
341 typename SymbolicType>
342 void
343 add_to_symbol_map(types::substitution_map &symbol_map,
344 const std::vector<SymbolicType> &symbols);
345
346 /**
347 * A convenience function for adding empty entries, with the key values
348 * equal to the key entries in @p other_symbols, to the symbolic
349 * map @p symbol_map.
350 *
351 * For more context which this function is used, see the other
352 * `add_to_symbol_map(types::substitution_map &, const Expression &)`
353 * function.
354 *
355 * @tparam ignore_invalid_symbols See the other
356 * `add_to_symbol_map(types::substitution_map &, const Expression &)`
357 * function for a detailed discussion on the role of this
358 * template argument.
359 *
360 * @tparam ValueType A type that corresponds to the @p value that the
361 * @p symbol is to represent. This @p ValueType is somewhat
362 * arbitrary as it is only used to create default-constructed
363 * values as entries in the map.
364 */
365 template <bool ignore_invalid_symbols = false, typename ValueType = double>
366 void
367 add_to_symbol_map(types::substitution_map &symbol_map,
368 const types::substitution_map &other_symbols);
369
370 /**
371 * A convenience function for adding empty entries, with the key values
372 * equal to the entries in @p symbol plus @p other_symbols, to the symbolic
373 * map @p symbol_map.
374 * It is expected that all entries in @p symbol and @p other_symbols be
375 * of a @p SymbolicType, compatible with the other add_to_symbol_map()
376 * functions.
377 *
378 * For more context which this function is used, see the other
379 * `add_to_symbol_map(types::substitution_map &, const Expression &)`
380 * function.
381 *
382 * With this function it is possible to add entries from different types
383 * to a symbolic map. An example may be as follows:
384 *
385 * @code
386 * types::substitution_map symbol_map = ...;
387 * add_to_symbol_map(
388 * symbol_map,
389 * Expression(...),
390 * Tensor<1,dim,Expression>(...),
391 * SymmetricTensor<2,dim,Expression>(...));
392 * @endcode
393 *
394 * @tparam ignore_invalid_symbols See the other
395 * `add_to_symbol_map(types::substitution_map &, const Expression &)`
396 * function for a detailed discussion on the role of this
397 * template argument.
398 *
399 * @tparam SymbolicType Any symbolic type that is understood by the
400 * add_to_symbol_map() functions. This includes individual
401 * Expression, std::vector<Expression>, as well as
402 * Tensors and SymmetricTensors of Expressions.
403 * @tparam ValueType A type that corresponds to the @p value that the
404 * @p symbol is to represent. This @p ValueType is somewhat
405 * arbitrary as it is only used to create default-constructed
406 * values as entries in the map.
407 * @tparam Args A type associated with the parameter pack that contains
408 * any number of other @p SymbolicTypes. All types held by the
409 * parameter pack share the same restriction as the @p SymbolicType
410 * documented above.
411 */
412 template <bool ignore_invalid_symbols = false,
413 typename ValueType = double,
414 typename SymbolicType,
415 typename... Args>
416 void
417 add_to_symbol_map(types::substitution_map &symbol_map,
418 const SymbolicType &symbol,
419 const Args &...other_symbols);
420
421 /**
422 * Find the entry for @p symbol in the @p substitution_map and set its
423 * corresponding @p value.
424 *
425 * This function may be used to safely transform an existing or null
426 * symbolic map (one with uninitialized entries) into one that can be used
427 * to conduct symbolic substitution operations (i.e., a substitution map).
428 */
429 void
430 set_value_in_symbol_map(types::substitution_map &substitution_map,
431 const Expression &symbol,
432 const Expression &value);
433
434 /**
435 * Find the entry for @p symbol in the @p substitution_map and set its
436 * corresponding @p value.
437 *
438 * This function may be used to safely transform an existing or null
439 * symbolic map (one with uninitialized entries) into one that can be used
440 * to conduct symbolic substitution operations (i.e., a substitution map).
441 *
442 * @tparam SymbolicType A type that represents a symbolic variable.
443 * The Differentiation::SD::Expression class is often suitable for
444 * this purpose, although if the @p ValueType is not supported
445 * by this class then a user-defined @p SymbolicType should be
446 * used.
447 * @tparam ValueType A type that corresponds to the @p value that the
448 * @p symbol is to represent. Although it is typically
449 * arithmetic in nature, it may also represent another symbolic
450 * expression type or be a special type that a user-defined
451 * @p ExpressionType can be constructed from.
452 * @tparam T An arbitrary type resulting from the application of
453 * the SFINAE idiom to selectively specialize this class.
454 * The required condition is fulfilled when the @p SymbolicType
455 * can be explicitly converted to a
456 * `const SymEngine::RCP<const SymEngine::Basic> &`, and it is
457 * possible to construct an @p SymbolicType directly from the
458 * @p ValueType.
459 */
460 template <typename SymbolicType,
461 typename ValueType,
462 typename T = std::enable_if_t<
463 dealii::internal::is_explicitly_convertible<
464 SymbolicType,
465 const SymEngine::RCP<const SymEngine::Basic> &>::value &&
466 std::is_constructible_v<SymbolicType, ValueType>>>
467 void
468 set_value_in_symbol_map(types::substitution_map &substitution_map,
469 const SymbolicType &symbol,
470 const ValueType &value);
471
472 /**
473 * Find the entries for @p symbols in the @p substitution_map and set their
474 * corresponding @p values.
475 *
476 * This function may be used to safely transform an existing or null
477 * symbolic map (one with uninitialized entries) into one that can be used
478 * to conduct symbolic substitution operations (i.e., a substitution map).
479 *
480 * @tparam SymbolicType A type that represents a symbolic variable.
481 * The Differentiation::SD::Expression class is often suitable for
482 * this purpose, although if the @p ValueType is not supported
483 * by this class then a user-defined @p SymbolicType should be
484 * used.
485 * @tparam ValueType A type that corresponds to the @p value that the
486 * @p symbol is to represent. Although it is typically
487 * arithmetic in nature, it may also represent another symbolic
488 * expression type or be a special type that a user-defined
489 * @p SymbolicType can be constructed from.
490 */
491 template <typename SymbolicType, typename ValueType>
492 void
493 set_value_in_symbol_map(types::substitution_map &substitution_map,
494 const std::vector<SymbolicType> &symbols,
495 const std::vector<ValueType> &values);
496
497 /**
498 * Find the entry for @p symbols in the @p substitution_map and set their
499 * corresponding @p values. The modified symbol will have the key given by
500 * the first element of @p symbol_value and the value given by its second
501 * element.
502 *
503 * This function may be used to safely transform an existing or null
504 * symbolic map (one with uninitialized entries) into one that can be used
505 * to conduct symbolic substitution operations (i.e., a substitution map).
506 *
507 * @tparam SymbolicType A type that represents a symbolic variable.
508 * The Differentiation::SD::Expression class is often suitable for
509 * this purpose, although if the @p ValueType is not supported
510 * by this class then a user-defined @p SymbolicType should be
511 * used.
512 * @tparam ValueType A type that corresponds to the @p value that the
513 * @p symbol is to represent. Although it is typically
514 * arithmetic in nature, it may also represent another symbolic
515 * expression type or be a special type that a user-defined
516 * @p SymbolicType can be constructed from.
517 */
518 template <typename SymbolicType, typename ValueType>
519 void
520 set_value_in_symbol_map(
521 types::substitution_map &substitution_map,
522 const std::pair<SymbolicType, ValueType> &symbol_value);
523
524 /**
525 * Find the entries for @p symbols in the @p substitution_map and set their
526 * corresponding @p values, followed by the same operation for the
527 * @p other_symbol_values.
528 *
529 * This function may be used to safely transform an existing or null
530 * symbolic map (one with uninitialized entries) into one that can be used
531 * to conduct symbolic substitution operations (i.e., a substitution map).
532 *
533 * @tparam SymbolicType A type that represents a symbolic variable.
534 * The Differentiation::SD::Expression class is often suitable for
535 * this purpose, although if the @p ValueType is not supported
536 * by this class then a user-defined @p SymbolicType should be
537 * used.
538 * @tparam ValueType A type that corresponds to the @p value that the
539 * @p symbol is to represent. Although it is typically
540 * arithmetic in nature, it may also represent another symbolic
541 * expression type or be a special type that a user-defined
542 * @p SymbolicType can be constructed from.
543 * @tparam Args A type associated with the parameter pack that contains
544 * any number of other pairs of @p SymbolicTypes and @p ValueTypes.
545 * All types held by the parameter pack share the same restriction
546 * as the @p SymbolicType and @p ValueType documented above.
547 */
548 template <typename SymbolicType, typename ValueType, typename... Args>
549 void
550 set_value_in_symbol_map(
551 types::substitution_map &substitution_map,
552 const std::pair<SymbolicType, ValueType> &symbol_value,
553 const Args &...other_symbol_values);
554
555 /**
556 * Find the entries for @p symbols in the @p substitution_map and set their
557 * corresponding @p values. The modified symbol will have the key given by
558 * the first element of each paired entry in the @p symbol_values vector
559 * and the value given by its respective second element.
560 *
561 * This function may be used to safely transform an existing or null
562 * symbolic map (one with uninitialized entries) into one that can be used
563 * to conduct symbolic substitution operations (i.e., a substitution map).
564 *
565 * @tparam SymbolicType A type that represents a symbolic variable.
566 * The Differentiation::SD::Expression class is often suitable for
567 * this purpose, although if the @p ValueType is not supported
568 * by this class then a user-defined @p SymbolicType should be
569 * used.
570 * @tparam ValueType A type that corresponds to the @p value that the
571 * @p symbol is to represent. Although it is typically
572 * arithmetic in nature, it may also represent another symbolic
573 * expression type or be a special type that a user-defined
574 * @p SymbolicType can be constructed from.
575 */
576 template <typename SymbolicType, typename ValueType>
577 void
578 set_value_in_symbol_map(
579 types::substitution_map &substitution_map,
580 const std::vector<std::pair<SymbolicType, ValueType>> &symbol_values);
581
582 /**
583 * Find the entries for @p symbols in the @p substitution_map and set their
584 * corresponding @p values. The modified symbol will have the key given by
585 * the each element the @p symbol_values map and the value given by its
586 * respective mapped element.
587 *
588 * This function may be used to safely transform an existing or null
589 * symbolic map (one with uninitialized entries) into one that can be used
590 * to conduct symbolic substitution operations (i.e., a substitution map).
591 */
592 void
593 set_value_in_symbol_map(types::substitution_map &substitution_map,
594 const types::substitution_map &symbol_values);
595
596 /** @} */
597
598 /**
599 * @name Symbol substitution map creation
600 */
601 /** @{ */
602
603 /**
604 * Return a substitution map that has the entry key given by @p symbol
605 * and the value given by @p value. It is expected that the key entry
606 * be valid symbol or symbolic expression.
607 *
608 * The values that map to a @p symbol would typically be of an arithmetic
609 * type. However, in some instances is may be useful to map a symbolic type
610 * to another symbolic type (i.e. perform partial substitution). In such
611 * a situation the resolve_explicit_dependencies() function may be useful
612 * to simplify the final substitution map by resolving all explicit
613 * interdependencies between entries in the substitution map.
614 */
615 types::substitution_map
616 make_substitution_map(const Expression &symbol, const Expression &value);
617
618 /**
619 * Return a substitution map that has the entry key given by @p symbol
620 * and the value given by @p value. It is expected that the key entry
621 * be valid symbol or symbolic expression.
622 *
623 * The values that map to a @p symbol would typically be of a @p ValueType
624 * (i.e., an arithmetic type).
625 * However, in some instances is may be useful to map a symbolic type
626 * to another symbolic type (i.e. perform partial substitution). In such
627 * a situation the resolve_explicit_dependencies() function may be useful
628 * to simplify the final substitution map by resolving all explicit
629 * interdependencies between entries in the substitution map.
630 *
631 * @tparam ExpressionType A type that represents a symbolic expression.
632 * The Differentiation::SD::Expression class is often suitable for
633 * this purpose, although if the @p ValueType is not supported
634 * by this class then a user-defined @p ExpressionType should be
635 * used.
636 * @tparam ValueType A type that corresponds to the @p value that the
637 * @p symbol is to represent. Although it is typically
638 * arithmetic in nature, it may also represent another symbolic
639 * expression type or be a special type that a user-defined
640 * @p ExpressionType can be constructed from.
641 * @tparam T An arbitrary type resulting from the application of
642 * the SFINAE idiom to selectively specialize this class.
643 * The required condition is fulfilled when the @p ExpressionType
644 * can be explicitly converted to a
645 * `const SymEngine::RCP<const SymEngine::Basic> &`, and it is
646 * possible to construct an @p ExpressionType directly from the
647 * @p ValueType.
648 */
649 template <typename ExpressionType,
650 typename ValueType,
651 typename T = std::enable_if_t<
652 dealii::internal::is_explicitly_convertible<
653 ExpressionType,
654 const SymEngine::RCP<const SymEngine::Basic> &>::value &&
655 std::is_constructible_v<ExpressionType, ValueType>>>
656 types::substitution_map
657 make_substitution_map(const ExpressionType &symbol, const ValueType &value);
658
659 /**
660 * Return a substitution map that has the entry keys given by @p symbols
661 * and the values given by @p values. It is expected that all key entries
662 * be valid symbols or symbolic expressions.
663 *
664 * It is possible to map symbolic types to other symbolic types
665 * using this function. For more details on this, see the other
666 * `make_substitution_map(const Expression &, const ValueType &)`
667 * function.
668 *
669 * @tparam ExpressionType A type that represents a symbolic expression.
670 * The Differentiation::SD::Expression class is often suitable for
671 * this purpose, although if the @p ValueType is not supported
672 * by this class then a user-defined @p ExpressionType should be
673 * used.
674 * @tparam ValueType A type that corresponds to the @p value that the
675 * @p symbol is to represent. Although it is typically
676 * arithmetic in nature, it may also represent another symbolic
677 * expression type or be a special type that a user-defined
678 * @p ExpressionType can be constructed from.
679 */
680 template <typename ExpressionType, typename ValueType>
681 types::substitution_map
682 make_substitution_map(const std::vector<ExpressionType> &symbols,
683 const std::vector<ValueType> &values);
684
685 /**
686 * Return a substitution map that has the key given by the first entry in
687 * @p symbol_value, and the value of its second entry. It is expected that
688 * the key entry be a valid symbol or symbolic expression.
689 *
690 * It is possible to map symbolic types to other symbolic types
691 * using this function. For more details on this, see the other
692 * `make_substitution_map(const Expression &, const ValueType &)`
693 * function.
694 *
695 * @tparam ExpressionType A type that represents a symbolic expression.
696 * The Differentiation::SD::Expression class is often suitable for
697 * this purpose, although if the @p ValueType is not supported
698 * by this class then a user-defined @p ExpressionType should be
699 * used.
700 * @tparam ValueType A type that corresponds to the @p value that the
701 * @p symbol is to represent. Although it is typically
702 * arithmetic in nature, it may also represent another symbolic
703 * expression type or be a special type that a user-defined
704 * @p ExpressionType can be constructed from.
705 */
706 template <typename ExpressionType, typename ValueType>
707 types::substitution_map
708 make_substitution_map(
709 const std::pair<ExpressionType, ValueType> &symbol_value);
710
711 /**
712 * Return a substitution map that has the keys given by the first entry of
713 * each element of @p symbol_values, and the values given its second entry.
714 * It is expected that all key entries be valid symbols or symbolic
715 * expressions.
716 *
717 * It is possible to map symbolic types to other symbolic types
718 * using this function. For more details on this, see the other
719 * `make_substitution_map(const Expression &, const ValueType &)`
720 * function.
721 *
722 * @tparam ExpressionType A type that represents a symbolic expression.
723 * The Differentiation::SD::Expression class is often suitable for
724 * this purpose, although if the @p ValueType is not supported
725 * by this class then a user-defined @p ExpressionType should be
726 * used.
727 * @tparam ValueType A type that corresponds to the @p value that the
728 * @p symbol is to represent. Although it is typically
729 * arithmetic in nature, it may also represent another symbolic
730 * expression type or be a special type that a user-defined
731 * @p ExpressionType can be constructed from.
732 */
733 template <typename ExpressionType, typename ValueType>
734 types::substitution_map
735 make_substitution_map(
736 const std::vector<std::pair<ExpressionType, ValueType>> &symbol_values);
737
738 /**
739 * Return a substitution map that has the key given by the first entry in
740 * @p symbol_value, and the value of its second entry, followed by the
741 * addition of the @p other_symbol_values. It is expected that all key
742 * entries be valid symbols or symbolic expressions.
743 *
744 * With this function it is possible to construct a symbolic substitution
745 * map from different types, so long as there exists a
746 * add_to_substitution_map() function with the signature corresponding to
747 * the pair types. An example may be as follows:
748 *
749 * @code
750 * const types::substitution_map substitution_map
751 * = make_substitution_map(
752 * std::make_pair(Expression(...), 3),
753 * std::make_pair(Tensor<1,dim,Expression>(...),
754 * Tensor<1,dim,float>(...)),
755 * std::make_pair(SymmetricTensor<2,dim,Expression>(...),
756 * SymmetricTensor<2,dim,double>(...)));
757 * @endcode
758 *
759 * It is possible to map symbolic types to other symbolic types
760 * using this function. For more details on this, see the other
761 * `make_substitution_map(const Expression &, const ValueType &)`
762 * function.
763 *
764 * @tparam ExpressionType Any symbolic expression type that is understood
765 * by the make_substitution_map() functions. This includes
766 * individual Expression, as well as Tensors and SymmetricTensors
767 * of Expressions.
768 * @tparam ValueType A type that corresponds to the @p value that the
769 * @p symbol is to represent. Although it is typically
770 * arithmetic in nature, it may also represent another symbolic
771 * expression type or be a special type that a user-defined
772 * @p ExpressionType can be constructed from.
773 * @tparam Args A type associated with the parameter pack that contains
774 * any number of other @p ExpressionTypes. All types held by the
775 * parameter pack share the same restriction as the
776 * @p ExpressionType documented above.
777 */
778 template <typename ExpressionType, typename ValueType, typename... Args>
779 types::substitution_map
780 make_substitution_map(
781 const std::pair<ExpressionType, ValueType> &symbol_value,
782 const Args &...other_symbol_values);
783
784 /** @} */
785
786 /**
787 * @name Symbol substitution map enlargement
788 */
789 /** @{ */
790
791 namespace internal
792 {
793 /**
794 * A convenience function to add an entry to the @p substitution_map.
795 * The new entry will have the key given by @p symbol with its paired
796 * @p value. Such maps are required to perform substitution of symbolic
797 * expressions, where all entries given as keys in the map are substituted
798 * by their value counterparts.
799 *
800 * There are cases where it is convenient to simply ignore the fact that
801 * we may be trying to add invalid symbols. For example, one may wish to
802 * add a tensor where only some entries are symbols and the others are
803 * zero'd. In this case we ensure that the user knows what they're doing
804 * by forcing them to override this safety mechanism with a template
805 * parameter. These types of functions are typically called in a manner
806 * indicating that the user knows exactly what they're passing into it.
807 *
808 * @tparam ignore_invalid_symbols A template parameter that enforces whether
809 * or not the @p symbol has to be a valid one or not. In the
810 * overwhelming majority of cases, the default value of
811 * <tt>false</tt> should be selected, with the result that an
812 * exception will be thrown if the input @p symbolic is, in fact,
813 * not a symbolic value or expression.
814 */
815 template <bool ignore_invalid_symbols = false>
816 void
817 add_to_substitution_map(
818 types::substitution_map &substitution_map,
819 const SymEngine::RCP<const SymEngine::Basic> &symbol,
820 const SymEngine::RCP<const SymEngine::Basic> &value);
821 } // namespace internal
822
823 /**
824 * A convenience function to add an entry to the @p substitution_map.
825 * The new entry will have the key given by @p symbol with its paired
826 * @p value. Such maps are required to perform substitution of symbolic
827 * expressions, with key entries being exchanges with their pair values.
828 *
829 * This function is guaranteed to create an ordering that is identical
830 * to the typical add_to_symbol_map() call that may be used when initially
831 * configuring a BatchOptimizer.
832 * This helps one conform to the requirement that the arguments sent into
833 * lambda and LLVM JIT compiled functions (created by optimizing symbolic
834 * expressions) (i) be the same, and (ii) have a constant ordering.
835 *
836 * @tparam ignore_invalid_symbols A template parameter that enforces whether
837 * or not the @p symbol has to be a valid one or not. In the
838 * overwhelming majority of cases, the default value of
839 * <tt>false</tt> should be selected, with the result that an
840 * exception will be thrown if the input @p symbolic is, in fact,
841 * not a symbolic value or expression.
842 * An exceptional case is, for example, when performing symbolic
843 * assembly on a finite element level. When extracting the symbolic
844 * equivalent of the shape function gradients using FEExtractors,
845 * the returned tensor will have some <em>a priori</em> determined
846 * zero-valued components. These trivial components are not valid
847 * symbols (as they are not symbolic expressions), and we would
848 * typically wish to guard against their (erroneous) inclusion. In
849 * this scenario, for convenience, one could set
850 * @p ignore_invalid_symbols to <tt>true</tt> and these zero-valued
851 * entries would be skipped over and ignored.
852 */
853 template <bool ignore_invalid_symbols = false>
854 void
855 add_to_substitution_map(types::substitution_map &substitution_map,
856 const Expression &symbol,
857 const Expression &value);
858
859 /**
860 * A convenience function to add an entry to the @p substitution_map.
861 * The new entry will have the key given by @p symbol with its paired
862 * @p value.
863 *
864 * The @p ExpressionType will be used to convert the @p value to a
865 * compatible SymEngine number type.
866 * It is therefore required that the @p ExpressionType
867 * 1. can be constructed from a @p ValueType, and that
868 * 2. it is convertible to a `const SymEngine::RCP<const SymEngine::Basic>
869 * &`.
870 *
871 * For more context which this function is used, see the other
872 * `add_to_substitution_map(types::substitution_map &, const Expression &,
873 * const Expression &)` function.
874 *
875 * @tparam ignore_invalid_symbols See the other
876 * `add_to_substitution_map(types::substitution_map &, const Expression &,
877 * const Expression &)` function for a detailed discussion on the role of
878 * this template argument.
879 *
880 * @tparam ExpressionType A type that represents a symbolic expression.
881 * The Differentiation::SD::Expression class is often suitable for
882 * this purpose, although if the @p ValueType is not supported
883 * by this class then a user-defined @p ExpressionType should be
884 * used.
885 * @tparam ValueType A type that corresponds to the @p value that the
886 * @p symbol is to represent. Although it is typically
887 * arithmetic in nature, it may also represent another symbolic
888 * expression type or be a special type that a user-defined
889 * @p ExpressionType can be constructed from.
890 */
891 template <bool ignore_invalid_symbols = false,
892 typename ExpressionType,
893 typename ValueType,
894 typename = std::enable_if_t<
895 dealii::internal::is_explicitly_convertible<
896 ExpressionType,
897 const SymEngine::RCP<const SymEngine::Basic> &>::value &&
898 std::is_constructible_v<ExpressionType, ValueType>>>
899 void
900 add_to_substitution_map(types::substitution_map &substitution_map,
901 const ExpressionType &symbol,
902 const ValueType &value);
903
904 /**
905 * A convenience function for adding multiple entries to the
906 * @p substitution_map. The new entries will have the keys given in the
907 * @p symbols vector, each of which will be paired index-wise with its
908 * corresponding element in the @p values vector.
909 *
910 * The class represented by the @p ExpressionType template parameter will
911 * be used to convert the p value to a compatible SymEngine number type.
912 * It is therefore required that the @p ExpressionType
913 * 1. can be constructed from a @p ValueType, and that
914 * 2. it is convertible to a `const SymEngine::RCP<const SymEngine::Basic>
915 * &`.
916 *
917 * For more context which this function is used, see the other
918 * `add_to_substitution_map(types::substitution_map &, const Expression &,
919 * const Expression &)` function.
920 *
921 * @tparam ignore_invalid_symbols See the other
922 * `add_to_substitution_map(types::substitution_map &, const Expression &,
923 * const Expression &)` function for a detailed discussion on the role of
924 * this template argument.
925 *
926 * @tparam ExpressionType A type that represents a symbolic expression.
927 * The Differentiation::SD::Expression class is often suitable for
928 * this purpose, although if the @p ValueType is not supported
929 * by this class then a user-defined @p ExpressionType should be
930 * used.
931 * @tparam ValueType A type that corresponds to the @p value that the
932 * @p symbol is to represent. Although it is typically
933 * arithmetic in nature, it may also represent another symbolic
934 * expression type or be a special type that a user-defined
935 * @p ExpressionType can be constructed from.
936 */
937 template <bool ignore_invalid_symbols = false,
938 typename ExpressionType,
939 typename ValueType,
940 typename = std::enable_if_t<
941 dealii::internal::is_explicitly_convertible<
942 ExpressionType,
943 const SymEngine::RCP<const SymEngine::Basic> &>::value &&
944 std::is_constructible_v<ExpressionType, ValueType>>>
945 void
946 add_to_substitution_map(types::substitution_map &substitution_map,
947 const std::vector<ExpressionType> &symbols,
948 const std::vector<ValueType> &values);
949
950 /**
951 * A convenience function for adding multiple entries to the
952 * @p substitution_map. The new entries will have the keys given in the
953 * @p symbols vector, each of which will be paired index-wise with its
954 * corresponding element in the @p values vector. It is expected that there
955 * are no duplicate entries between the two maps.
956 *
957 * For more context which this function is used, see the other
958 * `add_to_substitution_map(types::substitution_map &, const Expression &,
959 * const Expression &)` function.
960 *
961 * @tparam ignore_invalid_symbols See the other
962 * `add_to_substitution_map(types::substitution_map &, const Expression &,
963 * const Expression &)` function for a detailed discussion on the role of
964 * this template argument.
965 */
966 template <bool ignore_invalid_symbols = false>
967 void
968 add_to_substitution_map(types::substitution_map &substitution_map,
969 const types::substitution_map &symbol_values);
970
971 /**
972 * A convenience function to add an entry to the @p substitution_map.
973 * The new entry will have the key given by the first element of
974 * @p symbol_value and the value given by its second element.
975 * It is expected that the key entry be a valid symbol or symbolic
976 * expression, and that the paired @p symbol_value elements are compatible
977 * with the other add_to_substitution_map() functions.
978 *
979 * The @p ExpressionType and its associated @p ValueType need not be scalar
980 * types. So, for example, this function could be used to add tensor-valued
981 * data to the map in the following way:
982 *
983 * @code
984 * types::substitution_map substitution_map = ...;
985 * add_to_substitution_map(
986 * substitution_map,
987 * std::make_pair(Tensor<1,dim,Expression>(...),
988 * Tensor<1,dim,double>(...))
989 * );
990 * @endcode
991 *
992 * For more context which this function is used, see the other
993 * `add_to_substitution_map(types::substitution_map &, const Expression &,
994 * const Expression &)` function.
995 *
996 * @tparam ignore_invalid_symbols See the other
997 * `add_to_substitution_map(types::substitution_map &, const Expression &,
998 * const Expression &)` function for a detailed discussion on the role of
999 * this template argument.
1000 *
1001 * @tparam ExpressionType Any symbolic expression type that is understood
1002 * by the add_to_substitution_map() functions. This includes
1003 * individual Expression, as well as Tensors and SymmetricTensors
1004 * of Expressions.
1005 * @tparam ValueType A type that corresponds to the @p value that the
1006 * @p symbol is to represent. Although it is typically
1007 * arithmetic in nature, it may also represent another symbolic
1008 * expression type or be a special type that a user-defined
1009 * @p ExpressionType can be constructed from.
1010 */
1011 template <bool ignore_invalid_symbols = false,
1012 typename ExpressionType,
1013 typename ValueType>
1014 void
1015 add_to_substitution_map(
1016 types::substitution_map &substitution_map,
1017 const std::pair<ExpressionType, ValueType> &symbol_value);
1018
1019 /**
1020 * A convenience function for adding multiple entries to the
1021 * @p substitution_map. The new entries will have the keys given by first
1022 * entry of each element of @p symbol_values, and the values given its
1023 * second entry. It is expected that the key entry be a valid symbols or
1024 * symbolic expressions, and that the paired @p symbol_value elements are
1025 * compatible with the other add_to_substitution_map() functions.
1026 *
1027 * The @p ExpressionType and its associated @p ValueType need not be scalar
1028 * types. So, for example, this function could be used to add tensor-valued
1029 * data to the map in the following way:
1030 *
1031 * @code
1032 * types::substitution_map substitution_map = ...;
1033 * using vector_entry_t = std::vector<std::pair<
1034 * Tensor<1,dim,Expression>, Tensor<1,dim,double>
1035 * >>;
1036 * add_to_substitution_map(
1037 * substitution_map,
1038 * vector_entry_t{
1039 * {Tensor<1,dim,Expression>(...), Tensor<1,dim,double>(...)},
1040 * {Tensor<1,dim,Expression>(...), Tensor<1,dim,double>(...)}
1041 * });
1042 * @endcode
1043 *
1044 * For more context which this function is used, see the other
1045 * `add_to_substitution_map(types::substitution_map &, const Expression &,
1046 * const Expression &)` function.
1047 *
1048 * @tparam ignore_invalid_symbols See the other
1049 * `add_to_substitution_map(types::substitution_map &, const Expression &,
1050 * const Expression &)` function for a detailed discussion on the role of
1051 * this template argument.
1052 *
1053 * @tparam ExpressionType Any symbolic expression type that is understood
1054 * by the add_to_substitution_map() functions. This includes
1055 * individual Expression, as well as Tensors and SymmetricTensors
1056 * of Expressions.
1057 * @tparam ValueType A type that corresponds to the @p value that the
1058 * @p symbol is to represent. Although it is typically
1059 * arithmetic in nature, it may also represent another symbolic
1060 * expression type or be a special type that a user-defined
1061 * @p ExpressionType can be constructed from.
1062 */
1063 template <bool ignore_invalid_symbols = false,
1064 typename ExpressionType,
1065 typename ValueType>
1066 void
1067 add_to_substitution_map(
1068 types::substitution_map &substitution_map,
1069 const std::vector<std::pair<ExpressionType, ValueType>> &symbol_values);
1070
1071 /**
1072 * A convenience function for adding multiple entries to the
1073 * @p substitution_map. The new entries will have the keys given by first
1074 * entry of each element of @p symbol_values, and the values given its
1075 * second entry, along with the addition of the @p other_symbol_values.
1076 * It is expected that the key entry be a valid symbols or symbolic
1077 * expressions, and that the paired @p symbol_value elements are compatible
1078 * with the other add_to_substitution_map() functions.
1079 *
1080 * With this function it is possible to construct a symbolic substitution
1081 * map from different types, so long as there exists a
1082 * add_to_substitution_map() function with the signature corresponding to
1083 * the pair types. An example may be as follows:
1084 *
1085 * @code
1086 * types::substitution_map substitution_map = ...;
1087 * add_to_substitution_map(
1088 * substitution_map,
1089 * std::make_pair(Expression(...), 3),
1090 * std::make_pair(Tensor<1,dim,Expression>(...),
1091 * Tensor<1,dim,float>(...)),
1092 * std::make_pair(SymmetricTensor<2,dim,Expression>(...),
1093 * SymmetricTensor<2,dim,double>(...)));
1094 * @endcode
1095 *
1096 * It is possible to map symbolic types to other symbolic types
1097 * using this function. For more details on this, see the other
1098 * `make_substitution_map(const Expression &, const ValueType &)`
1099 * function.
1100 *
1101 * @tparam ExpressionType Any symbolic expression type that is understood
1102 * by the add_to_substitution_map() functions. This includes
1103 * individual Expression, as well as Tensors and SymmetricTensors
1104 * of Expressions.
1105 * @tparam ValueType A type that corresponds to the @p value that the
1106 * @p symbol is to represent. Although it is typically
1107 * arithmetic in nature, it may also represent another symbolic
1108 * expression type or be a special type that a user-defined
1109 * @p ExpressionType can be constructed from.
1110 * @tparam Args A type associated with the parameter pack that contains
1111 * any number of other @p ExpressionTypes. All types held by the
1112 * parameter pack share the same restriction as the
1113 * @p ExpressionType documented above.
1114 */
1115 template <bool ignore_invalid_symbols = false,
1116 typename ExpressionType,
1117 typename ValueType,
1118 typename... Args>
1119 void
1120 add_to_substitution_map(
1121 types::substitution_map &substitution_map,
1122 const std::pair<ExpressionType, ValueType> &symbol_value,
1123 const Args &...other_symbol_values);
1124
1125 /**
1126 * Concatenate two symbolic maps, merging a second map @p substitution_map_in
1127 * in-place into the initial and resultant map @p substitution_map_out. The map
1128 * @p substitution_map_out need not initially be empty.
1129 *
1130 * @note Duplicate symbols (keys) in the maps are permitted, so long as their
1131 * values are equal. If this is not the case then an error will be thrown.
1132 */
1133 void
1134 merge_substitution_maps(types::substitution_map &substitution_map_out,
1135 const types::substitution_map &substitution_map_in);
1136
1137 /**
1138 * Concatenate multiple symbolic maps, merging the maps @p substitution_map_in
1139 * and @p other_substitution_maps_in, a collection of other maps,
1140 * in-place into the resultant map @p substitution_map_out. The map
1141 * @p substitution_map_out need not initially be empty.
1142 *
1143 * @note Duplicate symbols (keys) in the maps are permitted, so long as their
1144 * values are equal. If this is not the case then an error will be thrown.
1145 */
1146 template <typename... Args>
1147 void
1148 merge_substitution_maps(types::substitution_map &substitution_map_out,
1149 const types::substitution_map &substitution_map_in,
1150 const Args &...other_substitution_maps_in);
1151
1152 /**
1153 * Concatenate multiple symbolic maps, merging the maps @p substitution_map_in
1154 * and @p other_substitution_maps_in and returning the result.
1155 *
1156 * @note Duplicate symbols (keys) in the maps are permitted, so long as their
1157 * values are equal. If this is not the case then an error will be thrown.
1158 */
1159 template <typename... Args>
1160 types::substitution_map
1161 merge_substitution_maps(const types::substitution_map &substitution_map_in,
1162 const Args &...other_substitution_maps_in);
1163
1164 /** @} */
1165
1166 /**
1167 * @name Symbol substitution and evaluation
1168 */
1169 /** @{ */
1170
1171 /**
1172 * Return a substitution map that has any explicit interdependencies between
1173 * the entries of the input @p substitution_map resolved.
1174 *
1175 * The @p force_cyclic_dependency_resolution flag exists to ensure, if
1176 * desired, that no cyclic dependencies can exist in the returned map.
1177 * If a cyclic dependency exists in the input substitution map,
1178 * @p substitution_map, then with this flag set to <tt>true</tt> the
1179 * dependency cycle is broken by a dictionary-ordered substitution.
1180 * For example, if the substitution map contains two entries
1181 * <tt>map["a"] -> "b"</tt> and <tt>map["b"] -> "a"</tt>, then the result
1182 * of calling this function would be a map with the elements
1183 * <tt>map["a"] -> "a"</tt> and <tt>map["b"] -> "a"</tt>.
1184 *
1185 * If one symbol is an explicit function of another, and it is desired that
1186 * all their values are completely resolved, then it may be necessary to
1187 * perform substitution a number of times before the result is finalized.
1188 * This function performs substitution sweeps for a set of symbolic
1189 * variables until all explicit relationships between the symbols in the map
1190 * have been resolved. Whether each entry returns a symbolic or real value
1191 * depends on the nature of the values stored in the substitution map. If
1192 * the values associated with a key are also symbolic then the returned
1193 * result may still be symbolic in nature. The terminal result of using the
1194 * input substitution map, @p symbol_values, is then guaranteed to be
1195 * rendered by a single substitution of the returned dependency-resolved
1196 * map.
1197 *
1198 * Example:
1199 * If <tt>map["a"] -> 1</tt> and
1200 * <tt>map["b"] -> "a"+ 2</tt>, then the function $f(a,b(a)) = a+b$
1201 * will be evaluated and the result $f\vert_{a=1,b=a+2} = 3+a$ is determined
1202 * upon the completion of the first sweep. A second sweep is therefore
1203 * necessary to resolve the final symbol, and the returned value is
1204 * ultimately $f = [3+a]_{a=1} = 4$. By resolving the explicit relationships
1205 * between all symbols in the map, we determine that <tt>map["a"] -> 1</tt>
1206 * and <tt>map["b"] -> 1 + 2 = 3</tt> and thus, using only one substitution,
1207 * that $f = a+b = 1 + 3 = 4$.
1208 */
1209 types::substitution_map
1210 resolve_explicit_dependencies(
1211 const types::substitution_map &substitution_map,
1212 const bool force_cyclic_dependency_resolution = false);
1213
1214 /**
1215 * Return a substitution map that has any explicit interdependencies between
1216 * the entries of the map generated by the paired elements in the
1217 * @p symbol_values vector resolved.
1218 * The @p force_cyclic_dependency_resolution exists to ensure, if desired,
1219 * that no cyclic dependencies can exist in the returned map.
1220 *
1221 * This function performs substitution sweeps for a set of symbolic
1222 * variables until all explicit relationships between the symbols in the map
1223 * have been resolved. Whether each entry returns a symbolic or real value
1224 * depends on the chosen ValueType and the values represented therein. If
1225 * the ValueType is another Expression, and they contain symbols then
1226 * the returned result may still be symbolic in nature.
1227 *
1228 * For an example of what this function does, see the documentation for the
1229 * other
1230 * `resolve_explicit_dependencies(const types::substitution_map &)`
1231 * function.
1232 *
1233 * @tparam ExpressionType A type that represents a symbolic expression.
1234 * The Differentiation::SD::Expression class is often suitable for
1235 * this purpose, although if the @p ValueType is not supported
1236 * by this class then a user-defined @p ExpressionType should be
1237 * used.
1238 * @tparam ValueType A type that corresponds to the @p value that the
1239 * @p symbol is to represent. Although it is typically
1240 * arithmetic in nature, it may also represent another symbolic
1241 * expression type or be a special type that a user-defined
1242 * @p ExpressionType can be constructed from.
1243 */
1244 template <typename ExpressionType, typename ValueType>
1245 types::substitution_map
1246 resolve_explicit_dependencies(
1247 const std::vector<std::pair<ExpressionType, ValueType>> &symbol_values,
1248 const bool force_cyclic_dependency_resolution = false);
1249
1250 /**
1251 * Perform a single substitution sweep of a set of symbols into the given
1252 * symbolic expression.
1253 * The symbols in the @p expression that correspond to the entry keys
1254 * of the @p substitution_map are substituted with the map entry's associated
1255 * value.
1256 * This substitution function may be used to give a set of symbolic
1257 * variables either a numeric interpretation or some symbolic definition.
1258 *
1259 * @note It is not required that all symbolic expressions be fully resolved
1260 * when using this function. In other words, partial substitutions are
1261 * valid.
1262 *
1263 * @note This function call is typically expensive, as by default it performs a
1264 * dictionary substitution for the symbols in the symbolic expression.
1265 * Should the numerical value of some symbolic expression be desired, then
1266 * this performance deficit may be mitigated through the use of the
1267 * BatchOptimizer class.
1268 * Situation dependent, the overhead of using a typical dictionary based
1269 * substitution may be on par with that of a substitution performed
1270 * using a BatchOptimizer. This is because there is an overhead to setting
1271 * up the optimizer, so this should be taken into consideration if
1272 * substitution is to occur for the given symbolic
1273 * expression only a few times.
1274 *
1275 * @note If the symbols stored in the map are explicitly dependent on one another,
1276 * then the returned result depends on the order in which the map is
1277 * traversed. It is recommended to first resolve all interdependencies in
1278 * the map using the resolve_explicit_dependencies() function.
1279 *
1280 * Examples:
1281 * <ol>
1282 * <li>If <tt>map["a"] == 1</tt> and <tt>map["b"] == "a" + 2</tt>, then
1283 * the function $f(a,b(a)) := a+b$ will be evaluated and the result
1284 * $f\vert_{a=1,b=a+2} = 3+a$ is returned. This return is because the
1285 * symbol "a" is substituted throughout the function first, and only
1286 * then is the symbol "b(a)" substituted, by which time its explicit
1287 * dependency on "a" cannot be resolved.</li>
1288 *
1289 * <li>If <tt>map["a"] == "b"+2</tt> and <tt>map["b"] == 1</tt>, then
1290 * the function $f(a(b),b): = a+b$ will be evaluated and the result
1291 * $f\vert_{a=b+2, b} = [b+2+b]_{b=1} = 4$ is returned. This is because
1292 * the explicitly dependent symbol "a(b)" is substituted first followed
1293 * by the symbol "b".</li>
1294 * </ol>
1295 */
1296 Expression
1297 substitute(const Expression &expression,
1298 const types::substitution_map &substitution_map);
1299
1300 /**
1301 * Perform a substitution of the @p symbol into the given
1302 * @p expression. All matches are assigned
1303 * the corresponding @p value.
1304 * This substitution function may be used to give a set of symbolic
1305 * variables either a numeric interpretation or some symbolic definition.
1306 *
1307 * For more information regarding the performance of symbolic substitution,
1308 * see the other
1309 * `substitute(const Expression &, const types::substitution_map &)`
1310 * function.
1311 *
1312 * @note It is not required that all symbolic expressions be fully resolved
1313 * when using this function. In other words, partial substitutions are
1314 * valid.
1315 *
1316 * @tparam ValueType A type that corresponds to the @p value that the
1317 * @p symbol is to represent. Although it is typically
1318 * arithmetic in nature, it may also represent another symbolic
1319 * expression type.
1320 */
1321 template <typename ValueType>
1322 Expression
1323 substitute(const Expression &expression,
1324 const Expression &symbol,
1325 const ValueType &value);
1326
1327 /**
1328 * Perform a single substitution sweep of a set of symbols into the given
1329 * symbolic expression.
1330 * The symbols in the @p expression that correspond to a matching entry key
1331 * of the @p symbol_values vector entry are substituted by the entry's associated
1332 * value.
1333 * This substitution function may be used to give a set of symbolic
1334 * variables either a numeric interpretation or some symbolic definition.
1335 *
1336 * For more information regarding the performance of symbolic substitution,
1337 * see the other
1338 * `substitute(const Expression &, const types::substitution_map &)`
1339 * function.
1340 *
1341 * @note It is not required that all symbolic expressions be fully resolved
1342 * when using this function. In other words, partial substitutions are
1343 * valid.
1344 *
1345 * @tparam ExpressionType A type that represents a symbolic expression.
1346 * The Differentiation::SD::Expression class is often suitable for
1347 * this purpose, but this may also represent Tensors and
1348 * SymmetricTensors of Expressions.
1349 * @tparam Args Any symbolic type and value combination that is understood
1350 * by the make_substitution_map() functions. This includes
1351 * arguments involving individual Expressions,
1352 * std::vector<Expression>, as well as Tensors and SymmetricTensors
1353 * of Expressions.
1354 */
1355 template <typename ExpressionType, typename... Args>
1356 ExpressionType
1357 substitute(const ExpressionType &expression, const Args &...symbol_values);
1358
1359 /**
1360 * Perform a single substitution sweep of a set of symbols into the given
1361 * symbolic function, and immediately evaluate the result.
1362 * The symbols in the @p expression that correspond to the entry keys
1363 * of the @p substitution_map are substituted with the map entry's associated
1364 * value.
1365 * This substitution function is used to give a set of symbolic variables
1366 * a numeric interpretation, with the returned result being of the type
1367 * specified by the @p ValueType template argument.
1368 *
1369 * For more information regarding the performance of symbolic substitution,
1370 * and the outcome of evaluation using a substitution map with cyclic
1371 * dependencies, see the
1372 * `substitute(const Expression &, const types::substitution_map &)`
1373 * function.
1374 *
1375 * @note It is required that all symbols in the @p expression be
1376 * successfully resolved by the @p substitution_map.
1377 * If only partial substitution is performed, then an error is thrown.
1378 *
1379 * @tparam ValueType A type that corresponds to the @p value that the
1380 * @p symbol is to represent. In the context of this particular
1381 * function, this template parameter is typically arithmetic in
1382 * nature.
1383 */
1384 template <typename ValueType>
1385 ValueType
1386 substitute_and_evaluate(const Expression &expression,
1387 const types::substitution_map &substitution_map);
1388
1389 /**
1390 * Perform a single substitution sweep of a set of symbols into the given
1391 * symbolic function, and immediately evaluate the result.
1392 * The symbols in the @p expression that correspond to the entry keys
1393 * of the @p substitution_map are substituted with the map entry's associated
1394 * value.
1395 * This substitution function is used to give a set of symbolic variables
1396 * a numeric interpretation with the returned result being of the type
1397 * specified by the @p ValueType template argument.
1398 *
1399 * For more information regarding the performance of symbolic substitution,
1400 * and the outcome of evaluation using a substitution map with cyclic
1401 * dependencies, see the
1402 * `substitute(const Expression &, const types::substitution_map &)`
1403 * function.
1404 *
1405 * @note It is required that all symbols in the @p expression be
1406 * successfully resolved by the substitution map that is generated with the
1407 * input collection of @p symbol_values.
1408 * If only partial substitution is performed, then an error is thrown.
1409 *
1410 * @tparam ValueType A type that corresponds to the @p value that the
1411 * @p symbol is to represent. In the context of this particular
1412 * function, this template parameter is typically arithmetic in
1413 * nature.
1414 * @tparam Args Any symbolic type and value combination that is understood
1415 * by the make_substitution_map() functions. This includes
1416 * arguments involving individual Expressions,
1417 * std::vector<Expression>, as well as Tensors and SymmetricTensors
1418 * of Expressions.
1419 */
1420 template <typename ValueType, typename... Args>
1421 ValueType
1422 substitute_and_evaluate(const Expression &expression,
1423 const Args &...symbol_values);
1424
1425 /** @} */
1426
1427 } // namespace SD
1428 } // namespace Differentiation
1429
1430
1431 /* -------------------- inline and template functions ------------------ */
1432
1433
1434 # ifndef DOXYGEN
1435
1436
1437 namespace Differentiation
1438 {
1439 namespace SD
1440 {
1441 /* ---------------- Symbol map creation and manipulation --------------*/
1442
1443
1444 template <bool ignore_invalid_symbols,
1445 typename ValueType,
1446 typename SymbolicType>
1447 types::substitution_map
1448 make_symbol_map(const SymbolicType &symbol)
1449 {
1450 types::substitution_map symbol_map;
1451 add_to_symbol_map<ignore_invalid_symbols, ValueType>(symbol_map, symbol);
1452 return symbol_map;
1453 }
1454
1455
1456 template <bool ignore_invalid_symbols,
1457 typename ValueType,
1458 typename SymbolicType,
1459 typename... Args>
1460 types::substitution_map
1461 make_symbol_map(const SymbolicType &symbol, const Args &...other_symbols)
1462 {
1463 types::substitution_map symbol_map;
1464 add_to_symbol_map<ignore_invalid_symbols, ValueType>(symbol_map,
1465 symbol,
1466 other_symbols...);
1467 return symbol_map;
1468 }
1469
1470
1471 template <bool ignore_invalid_symbols, typename ValueType>
1472 void
1473 add_to_symbol_map(types::substitution_map &symbol_map,
1474 const Expression &symbol)
1475 {
1476 // Call the above function
1477 add_to_substitution_map<ignore_invalid_symbols>(
1478 symbol_map,
1479 symbol,
1480 dealii::internal::NumberType<ValueType>::value(0.0));
1481 }
1482
1483
1484 template <bool ignore_invalid_symbols,
1485 typename ValueType,
1486 typename SymbolicType,
1487 typename>
1488 void
1489 add_to_symbol_map(types::substitution_map &symbol_map,
1490 const SymbolicType &symbol)
1491 {
1492 // Call the above function
1493 using SE_RCP_Basic = const SymEngine::RCP<const SymEngine::Basic> &;
1494 add_to_substitution_map<ignore_invalid_symbols>(
1495 symbol_map,
1496 static_cast<SE_RCP_Basic>(symbol),
1497 dealii::internal::NumberType<ValueType>::value(0.0));
1498 }
1499
1500
1501 template <bool ignore_invalid_symbols,
1502 typename ValueType,
1503 typename SymbolicType>
1504 void
1505 add_to_symbol_map(types::substitution_map &symbol_map,
1506 const std::vector<SymbolicType> &symbols)
1507 {
1508 for (const auto &symbol : symbols)
1509 add_to_symbol_map<ignore_invalid_symbols, ValueType>(symbol_map,
1510 symbol);
1511 }
1512
1513
1514 template <bool ignore_invalid_symbols, typename ValueType>
1515 void
1516 add_to_symbol_map(types::substitution_map &symbol_map,
1517 const types::substitution_map &other_symbols)
1518 {
1519 // We should be cautious as to whether or not the user has
1520 // hand-made the other_symbols map to be "merged" in.
1521 // So instead of blindly merging using the merge_substitution_maps()
1522 // function, we do it by hand and check for invalid symbols
1523 // if required.
1524 for (types::substitution_map::const_iterator it = other_symbols.begin();
1525 it != other_symbols.end();
1526 ++it)
1527 {
1528 Assert(symbol_map.find(it->first) == symbol_map.end(),
1529 ExcMessage("Entry already exists in symbol map"));
1530 add_to_symbol_map<ignore_invalid_symbols, ValueType>(
1531 symbol_map, Expression(it->first));
1532 }
1533 }
1534
1535
1536 template <bool ignore_invalid_symbols,
1537 typename ValueType,
1538 typename SymbolicType,
1539 typename... Args>
1540 void
1541 add_to_symbol_map(types::substitution_map &symbol_map,
1542 const SymbolicType &symbol,
1543 const Args &...other_symbols)
1544 {
1545 add_to_symbol_map<ignore_invalid_symbols, ValueType>(symbol_map, symbol);
1546 add_to_symbol_map<ignore_invalid_symbols, ValueType>(symbol_map,
1547 other_symbols...);
1548 }
1549
1550
1551 template <typename SymbolicType, typename ValueType, typename>
1552 void
1553 set_value_in_symbol_map(types::substitution_map &substitution_map,
1554 const SymbolicType &symbol,
1555 const ValueType &value)
1556 {
1557 // Call the above function
1558 using SE_RCP_Basic = const SymEngine::RCP<const SymEngine::Basic> &;
1559 internal::set_value_in_symbol_map(substitution_map,
1560 static_cast<SE_RCP_Basic>(symbol),
1561 static_cast<SE_RCP_Basic>(
1562 SymbolicType(value)));
1563 }
1564
1565
1566 template <typename SymbolicType, typename ValueType>
1567 void
1568 set_value_in_symbol_map(types::substitution_map &substitution_map,
1569 const std::vector<SymbolicType> &symbols,
1570 const std::vector<ValueType> &values)
1571 {
1572 Assert(symbols.size() == values.size(),
1573 ExcDimensionMismatch(symbols.size(), values.size()));
1574
1575 typename std::vector<SymbolicType>::const_iterator it_symb =
1576 symbols.begin();
1577 typename std::vector<ValueType>::const_iterator it_val = values.begin();
1578 for (; it_symb != symbols.end(); ++it_symb, ++it_val)
1579 {
1580 Assert(it_val != values.end(), ExcInternalError());
1581 set_value_in_symbol_map(substitution_map, *it_symb, *it_val);
1582 }
1583 }
1584
1585
1586 template <typename SymbolicType, typename ValueType>
1587 void
1588 set_value_in_symbol_map(
1589 types::substitution_map &substitution_map,
1590 const std::pair<SymbolicType, ValueType> &symbol_value)
1591 {
1592 set_value_in_symbol_map(substitution_map,
1593 symbol_value.first,
1594 symbol_value.second);
1595 }
1596
1597
1598 template <typename SymbolicType, typename ValueType, typename... Args>
1599 void
1600 set_value_in_symbol_map(
1601 types::substitution_map &substitution_map,
1602 const std::pair<SymbolicType, ValueType> &symbol_value,
1603 const Args &...other_symbol_values)
1604 {
1605 set_value_in_symbol_map(substitution_map, symbol_value);
1606 set_value_in_symbol_map(substitution_map, other_symbol_values...);
1607 }
1608
1609
1610 template <typename SymbolicType, typename ValueType>
1611 void
1612 set_value_in_symbol_map(
1613 types::substitution_map &substitution_map,
1614 const std::vector<std::pair<SymbolicType, ValueType>> &symbol_values)
1615 {
1616 // Call the above function
1617 for (const auto &entry : symbol_values)
1618 set_value_in_symbol_map(substitution_map, entry.first, entry.second);
1619 }
1620
1621
1622 /* ------------------ Symbol substitution map creation ----------------*/
1623
1624
1625 template <typename ExpressionType, typename ValueType, typename>
1626 types::substitution_map
1627 make_substitution_map(const ExpressionType &symbol, const ValueType &value)
1628 {
1629 types::substitution_map substitution_map;
1630 add_to_substitution_map(substitution_map, symbol, value);
1631 return substitution_map;
1632 }
1633
1634
1635 template <typename ExpressionType, typename ValueType>
1636 types::substitution_map
1637 make_substitution_map(const std::vector<ExpressionType> &symbols,
1638 const std::vector<ValueType> &values)
1639 {
1640 types::substitution_map substitution_map;
1641 add_to_substitution_map(substitution_map, symbols, values);
1642 return substitution_map;
1643 }
1644
1645
1646 template <typename ExpressionType, typename ValueType>
1647 types::substitution_map
1648 make_substitution_map(
1649 const std::pair<ExpressionType, ValueType> &symbol_value)
1650 {
1651 types::substitution_map substitution_map;
1652 add_to_substitution_map(substitution_map, symbol_value);
1653 return substitution_map;
1654 }
1655
1656
1657 template <typename ExpressionType, typename ValueType>
1658 types::substitution_map
1659 make_substitution_map(
1660 const std::vector<std::pair<ExpressionType, ValueType>> &symbol_values)
1661 {
1662 types::substitution_map substitution_map;
1663 add_to_substitution_map(substitution_map, symbol_values);
1664 return substitution_map;
1665 }
1666
1667
1668 template <typename ExpressionType, typename ValueType, typename... Args>
1669 types::substitution_map
1670 make_substitution_map(
1671 const std::pair<ExpressionType, ValueType> &symbol_value,
1672 const Args &...other_symbol_values)
1673 {
1674 types::substitution_map substitution_map;
1675 add_to_substitution_map(substitution_map,
1676 symbol_value,
1677 other_symbol_values...);
1678 return substitution_map;
1679 }
1680
1681
1682 /* ---------------- Symbolic substitution map enlargement --------------*/
1683
1684 namespace internal
1685 {
1686 /**
1687 * There are cases where it is convenient to simply ignore
1688 * the fact that we may be trying to add invalid symbols.
1689 * For example, one may wish to add a tensor where only
1690 * some entries are symbols and the others are zero'd.
1691 * In this case we ensure that the user knows what they're
1692 * doing by forcing them to override this safety mechanism
1693 * with a template parameter. These types of functions are
1694 * typically called in a manner indicating that the user
1695 * knows exactly what they're passing into it.
1696 */
1697 template <bool ignore_invalid_symbols>
1698 void
1699 add_to_substitution_map(
1700 types::substitution_map &substitution_map,
1701 const SymEngine::RCP<const SymEngine::Basic> &symbol,
1702 const SymEngine::RCP<const SymEngine::Basic> &value)
1703 {
1704 if (ignore_invalid_symbols == false)
1705 {
1706 Assert(
1707 internal::is_valid_substitution_symbol(*symbol),
1708 ExcMessage(
1709 "Substitution with a number that does not represent a symbol or symbolic derivative"));
1710 Assert(substitution_map.find(symbol) == substitution_map.end(),
1711 ExcMessage("This symbol is already in the map."));
1712 substitution_map[Expression(symbol)] = Expression(value);
1713 }
1714 else
1715 {
1716 if (internal::is_valid_substitution_symbol(*symbol))
1717 {
1718 Assert(substitution_map.find(symbol) == substitution_map.end(),
1719 ExcMessage("This symbol is already in the map."));
1720 substitution_map[Expression(symbol)] = Expression(value);
1721 }
1722 }
1723 }
1724
1725 } // namespace internal
1726
1727
1728 template <bool ignore_invalid_symbols>
1729 void
1730 add_to_substitution_map(types::substitution_map &substitution_map,
1731 const Expression &symbol,
1732 const Expression &value)
1733 {
1734 internal::add_to_substitution_map<ignore_invalid_symbols>(
1735 substitution_map, symbol.get_RCP(), value.get_RCP());
1736 }
1737
1738
1739 template <bool ignore_invalid_symbols,
1740 typename ExpressionType,
1741 typename ValueType,
1742 typename>
1743 void
1744 add_to_substitution_map(types::substitution_map &substitution_map,
1745 const ExpressionType &symbol,
1746 const ValueType &value)
1747 {
1748 using SE_RCP_Basic = const SymEngine::RCP<const SymEngine::Basic> &;
1749 internal::add_to_substitution_map<ignore_invalid_symbols>(
1750 substitution_map,
1751 static_cast<SE_RCP_Basic>(symbol),
1752 static_cast<SE_RCP_Basic>(ExpressionType(value)));
1753 }
1754
1755
1756 template <bool ignore_invalid_symbols,
1757 typename ExpressionType,
1758 typename ValueType,
1759 typename>
1760 void
1761 add_to_substitution_map(types::substitution_map &substitution_map,
1762 const std::vector<ExpressionType> &symbols,
1763 const std::vector<ValueType> &values)
1764 {
1765 Assert(symbols.size() == values.size(),
1766 ExcMessage(
1767 "Vector of symbols and values must be of equal length."));
1768
1769 typename types::symbol_vector::const_iterator it_s = symbols.begin();
1770 typename std::vector<ValueType>::const_iterator it_v = values.begin();
1771 using SE_RCP_Basic = const SymEngine::RCP<const SymEngine::Basic> &;
1772 for (; it_s != symbols.end(); ++it_s, ++it_v)
1773 {
1774 Assert(it_v != values.end(), ExcInternalError());
1775 internal::add_to_substitution_map<ignore_invalid_symbols>(
1776 substitution_map,
1777 static_cast<SE_RCP_Basic>(*it_s),
1778 static_cast<SE_RCP_Basic>(ExpressionType(*it_v)));
1779 }
1780 }
1781
1782
1783 template <bool ignore_invalid_symbols,
1784 typename ExpressionType,
1785 typename ValueType>
1786 void
1787 add_to_substitution_map(
1788 types::substitution_map &substitution_map,
1789 const std::pair<ExpressionType, ValueType> &symbol_value)
1790 {
1791 add_to_substitution_map<ignore_invalid_symbols>(substitution_map,
1792 symbol_value.first,
1793 symbol_value.second);
1794 }
1795
1796
1797 template <bool ignore_invalid_symbols,
1798 typename ExpressionType,
1799 typename ValueType>
1800 void
1801 add_to_substitution_map(
1802 types::substitution_map &substitution_map,
1803 const std::vector<std::pair<ExpressionType, ValueType>> &symbol_values)
1804 {
1805 for (const auto &entry : symbol_values)
1806 {
1807 add_to_substitution_map<ignore_invalid_symbols>(substitution_map,
1808 entry);
1809 }
1810 }
1811
1812
1813 template <bool ignore_invalid_symbols>
1814 void
1815 add_to_substitution_map(types::substitution_map &substitution_map,
1816 const types::substitution_map &symbol_values)
1817 {
1818 for (const auto &entry : symbol_values)
1819 {
1820 const SymEngine::RCP<const SymEngine::Basic> &symbol = entry.first;
1821 const SymEngine::RCP<const SymEngine::Basic> &value = entry.second;
1822 internal::add_to_substitution_map<ignore_invalid_symbols>(
1823 substitution_map, symbol, value);
1824 }
1825 }
1826
1827
1828 template <bool ignore_invalid_symbols,
1829 typename ExpressionType,
1830 typename ValueType,
1831 typename... Args>
1832 void
1833 add_to_substitution_map(
1834 types::substitution_map &substitution_map,
1835 const std::pair<ExpressionType, ValueType> &symbol_value,
1836 const Args &...other_symbol_values)
1837 {
1838 add_to_substitution_map<ignore_invalid_symbols>(substitution_map,
1839 symbol_value);
1840 add_to_substitution_map<ignore_invalid_symbols>(substitution_map,
1841 other_symbol_values...);
1842 }
1843
1844
1845 template <typename... Args>
1846 types::substitution_map
1847 merge_substitution_maps(
1848 const types::substitution_map &substitution_map_in_1,
1849 const Args &...other_substitution_maps_in)
1850 {
1851 types::substitution_map substitution_map_out = substitution_map_in_1;
1852 merge_substitution_maps(substitution_map_out,
1853 other_substitution_maps_in...);
1854 return substitution_map_out;
1855 }
1856
1857
1858 template <typename... Args>
1859 void
1860 merge_substitution_maps(
1861 types::substitution_map &substitution_map_out,
1862 const types::substitution_map &substitution_map_in_1,
1863 const Args &...other_substitution_maps_in)
1864 {
1865 merge_substitution_maps(substitution_map_out, substitution_map_in_1);
1866 merge_substitution_maps(substitution_map_out,
1867 other_substitution_maps_in...);
1868 }
1869
1870
1871 /* ---------------- Symbol substitution and evaluation --------------*/
1872
1873
1874 template <typename ExpressionType, typename ValueType>
1875 types::substitution_map
1876 resolve_explicit_dependencies(
1877 const std::vector<std::pair<ExpressionType, ValueType>> &symbol_values,
1878 const bool force_cyclic_dependency_resolution)
1879 {
1880 return resolve_explicit_dependencies(make_substitution_map(symbol_values),
1881 force_cyclic_dependency_resolution);
1882 }
1883
1884
1885 template <typename ValueType>
1886 Expression
1887 substitute(const Expression &expression,
1888 const Expression &symbol,
1889 const ValueType &value)
1890 {
1891 return expression.substitute(symbol, value);
1892 }
1893
1894
1895 template <typename ExpressionType, typename... Args>
1896 ExpressionType
1897 substitute(const ExpressionType &expression, const Args &...symbol_values)
1898 {
1899 // Call other function
1900 return substitute(expression, make_substitution_map(symbol_values...));
1901 }
1902
1903
1904 template <typename ValueType>
1905 ValueType
1906 substitute_and_evaluate(const Expression &expression,
1907 const types::substitution_map &substitution_map)
1908 {
1909 return expression.substitute_and_evaluate<ValueType>(substitution_map);
1910 }
1911
1912
1913 template <typename ValueType, typename... Args>
1914 ValueType
1915 substitute_and_evaluate(const Expression &expression,
1916 const Args &...symbol_values)
1917 {
1918 // Call other function
1919 return substitute_and_evaluate<ValueType>(
1920 expression, make_substitution_map(symbol_values...));
1921 }
1922
1923 } // namespace SD
1924 } // namespace Differentiation
1925
1926
1927 # endif // DOXYGEN
1928
1929 DEAL_II_NAMESPACE_CLOSE
1930
1931 #else
1932
1933 // Make sure the scripts that create the C++20 module input files have
1934 // something to latch on if the preprocessor #ifdef above would
1935 // otherwise lead to an empty content of the file.
1936 DEAL_II_NAMESPACE_OPEN
1937 DEAL_II_NAMESPACE_CLOSE
1938
1939 #endif // DEAL_II_WITH_SYMENGINE
1940
1941 #endif