Debian Codegraph @

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

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2020 - 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_optimizer_h
16 #define dealii_differentiation_sd_symengine_optimizer_h
17
18 #include <deal.II/base/config.h>
19
20 #ifdef DEAL_II_WITH_SYMENGINE
21
22 // Low level
23 # include <symengine/basic.h>
24 # include <symengine/dict.h>
25 # include <symengine/symengine_exception.h>
26 # include <symengine/symengine_rcp.h>
27
28 // Optimization
29 # include <symengine/lambda_double.h>
30 # include <symengine/visitor.h>
31 # ifdef HAVE_SYMENGINE_LLVM
32 # include <symengine/llvm_double.h>
33 # endif
34
35 # include <deal.II/base/exceptions.h>
36 # include <deal.II/base/utilities.h>
37
38 # include <deal.II/differentiation/sd/symengine_number_types.h>
39 # include <deal.II/differentiation/sd/symengine_number_visitor_internal.h>
40 # include <deal.II/differentiation/sd/symengine_scalar_operations.h>
41 # include <deal.II/differentiation/sd/symengine_tensor_operations.h>
42 # include <deal.II/differentiation/sd/symengine_utilities.h>
43
44 # include <boost/serialization/split_member.hpp>
45 # include <boost/type_traits.hpp>
46
47 # include <algorithm>
48 # include <map>
49 # include <memory>
50 # include <type_traits>
51 # include <utility>
52 # include <vector>
53
54
55 DEAL_II_NAMESPACE_OPEN
56
57
58 namespace Differentiation
59 {
60 namespace SD
61 {
62 /**
63 * @addtogroup Exceptions
64 * @{
65 */
66
67 /**
68 * An exception to indicate that the SymEngine library has not been built
69 * against the LLVM compiler.
70 */
71 DeclExceptionMsg(ExcSymEngineLLVMNotAvailable,
72 "SymEngine has not been built with LLVM support.");
73
74 /**
75 * An exception to indicate that SymEngine's LLVM optimizer doesn't work
76 * with the desired return type.
77 */
78 DeclExceptionMsg(ExcSymEngineLLVMReturnTypeNotSupported,
79 "The SymEngine LLVM optimizer does not (yet) support the "
80 "selected return type.");
81
82 /** @} */
83
84
85 // Forward declarations
86 template <typename ReturnType>
87 class BatchOptimizer;
88
89
90 /**
91 * An enumeration to distinguish between different optimization methods
92 * that can be used by SymEngine to more rapidly evaluate complex
93 * symbolic expressions.
94 */
95 enum class OptimizerType
96 {
97 /**
98 * Use dictionary substitution. This is SymEngine's default method.
99 */
100 dictionary,
101 /**
102 * Convert the symbolic expression into a collection of
103 * `std::function`s.
104 */
105 lambda,
106 /**
107 * Use the LLVM JIT compiler to compile the expression into an
108 * aggressively optimized, stand-alone function.
109 */
110 llvm
111 };
112
113
114 /**
115 * Output operator that outputs the selected optimizer type.
116 */
117 template <typename StreamType>
118 inline StreamType &
119 operator<<(StreamType &s, OptimizerType o)
120 {
121 if (o == OptimizerType::dictionary)
122 s << "dictionary";
123 else if (o == OptimizerType::lambda)
124 s << "lambda";
125 else if (o == OptimizerType::llvm)
126 s << "llvm";
127 else
128 {
129 Assert(false, ExcMessage("Unknown optimization method."));
130 }
131
132 return s;
133 }
134
135
136 /**
137 * An enumeration to specify which special techniques, over and above
138 * those used with the chosen OptimizerType, to be applied to the
139 * set of expressions that are to be optimized.
140 */
141 enum class OptimizationFlags : unsigned char
142 {
143 /**
144 * No additional optimization.
145 */
146 optimize_default = 0,
147 /**
148 * Apply common subexpresson elimination.
149 */
150 optimize_cse = 0x0001,
151 /**
152 * Employ aggressive optimizations when compiling with the LLVM JIT
153 * compiler.
154 */
155 optimize_aggressive = 0x0002,
156 /**
157 * Apply all possible optimizations.
158 */
159 optimize_all = optimize_cse | optimize_aggressive
160 };
161
162
163 /**
164 * A global operator that returns an object in which all bits are
165 * individually set in the following way:
166 * If the corresponding bit in either the first or second argument are set,
167 * then the output bit it set. Otherwise the output bit remains unset.
168 * This `or` type operation is performed for each bit composing the input
169 * arguments (and output) in an individual manner.
170 */
171 // This operator exists since if it did not then the result of the bit-or
172 // <tt>operator |</tt> would be an integer which would in turn trigger a
173 // compiler warning when we tried to assign it to an object of type
174 // OptimizationFlags.
175 inline OptimizationFlags
176 operator|(const OptimizationFlags f1, const OptimizationFlags f2)
177 {
178 return static_cast<OptimizationFlags>(static_cast<unsigned int>(f1) |
179 static_cast<unsigned int>(f2));
180 }
181
182
183 /**
184 * Global operator that sets the bits from the second argument also in the
185 * first one.
186 */
187 inline OptimizationFlags &
188 operator|=(OptimizationFlags &f1, const OptimizationFlags f2)
189 {
190 f1 = f1 | f2;
191 return f1;
192 }
193
194
195 /**
196 * A global operator that returns an object in which all bits are
197 * individually set in the following way:
198 * If the corresponding bit in both the first or second argument are set,
199 * then the output bit it set. Otherwise the output bit remains unset.
200 * This `and` type operation is performed for each bit composing the input
201 * arguments (and output) in an individual manner.
202 */
203 // This operator exists since if it did not then the result of the bit-or
204 // <tt>operator |</tt> would be an integer which would in turn trigger a
205 // compiler warning when we tried to assign it to an object of type
206 // OptimizationFlags.
207 inline OptimizationFlags
208 operator&(const OptimizationFlags f1, const OptimizationFlags f2)
209 {
210 return static_cast<OptimizationFlags>(static_cast<unsigned int>(f1) &
211 static_cast<unsigned int>(f2));
212 }
213
214
215 /**
216 * Global operator which clears all the bits in the first argument if they
217 * are not also set in the second argument.
218 */
219 inline OptimizationFlags &
220 operator&=(OptimizationFlags &f1, const OptimizationFlags f2)
221 {
222 f1 = f1 & f2;
223 return f1;
224 }
225
226
227 namespace internal
228 {
229 /**
230 * A utility function that checks whether or not CSE
231 * has been selected as an optimization flag.
232 */
233 inline bool
234 use_symbolic_CSE(const enum OptimizationFlags &flags)
235 {
236 return static_cast<int>(flags & OptimizationFlags::optimize_cse);
237 }
238
239 /**
240 * A utility function that returns the optimization level
241 * that is to be employed when the LLVM optimizer is invoked.
242 */
243 inline int
244 get_LLVM_optimization_level(const enum OptimizationFlags &flags)
245 {
246 // With the LLVM compiler there exists the opportunity to tune
247 // the level of optimizations performed during compilation.
248 // By default SymEngine sets this at "opt_level=2", which one
249 // presumes targets -O2. Here we are a bit more specific about
250 // want we want it to do:
251 // - Normal compilation: -02 (default settings)
252 // - Aggressive mode: -03 (the whole lot!)
253 // In theory we could also target
254 // - Debug mode: -O0 (no optimizations)
255 // but this doesn't make much sense since SymEngine is a
256 // tested external library.
257 const bool use_agg_opt =
258 static_cast<int>(flags & OptimizationFlags::optimize_aggressive);
259 const int opt_level = (use_agg_opt ? 3 : 2);
260 return opt_level;
261 }
262 } // namespace internal
263
264
265 /**
266 * Output operator that outputs optimization flags as a set of or'd
267 * text values.
268 */
269 template <typename StreamType>
270 inline StreamType &
271 operator<<(StreamType &s, OptimizationFlags o)
272 {
273 s << " OptimizationFlags|";
274 if (static_cast<unsigned int>(o & OptimizationFlags::optimize_cse))
275 s << "cse|";
276
277 // LLVM optimization level
278 s << "-O" + std::to_string(internal::get_LLVM_optimization_level(o)) +
279 "|";
280
281 return s;
282 }
283
284
285 namespace internal
286 {
287 /**
288 * A wrapper for dictionary based optimization.
289 *
290 * @tparam ReturnType The number type that is returned as a result
291 * of operations performed by the optimizer.
292 * Floating point and complex numbers are currently supported.
293 * @tparam T An arbitrary type resulting from the application of
294 * the SFINAE idiom to selectively specialize this class.
295 */
296 template <typename ReturnType, typename T = void>
297 struct DictionaryOptimizer;
298
299
300 /**
301 * A wrapper for SymEngine's "lambda" optimizer.
302 *
303 * @tparam ReturnType The number type that is returned as a result
304 * of operations performed by the optimizer.
305 * Floating point and complex numbers are currently supported.
306 * @tparam T An arbitrary type resulting from the application of
307 * the SFINAE idiom to selectively specialize this class.
308 */
309 template <typename ReturnType, typename T = void>
310 struct LambdaOptimizer;
311
312
313 # ifdef HAVE_SYMENGINE_LLVM
314 /**
315 * A wrapper for SymEngine's LLVM JIT optimizer.
316 *
317 * @tparam ReturnType The number type that is returned as a result
318 * of operations performed by the optimizer.
319 * Floating point and complex numbers are currently supported.
320 * @tparam T An arbitrary type resulting from the application of
321 * the SFINAE idiom to selectively specialize this class.
322 */
323 template <typename ReturnType, typename T = void>
324 struct LLVMOptimizer;
325 # endif // HAVE_SYMENGINE_LLVM
326
327
328 /**
329 * A wrapper class for all supported Optimizer types and
330 * @p ReturnTypes. It aims to deal with the case when the
331 * @p ReturnType and native return type of the @p Optimizer
332 * are not the same.
333 *
334 * @tparam ReturnType The number type that is returned as a result
335 * of operations performed by the optimizer.
336 * Floating point and complex numbers are currently supported.
337 * @tparam Optimizer An internal class that implements a wrapper to a
338 * SymEngine optimizer. Currently, the target classes are the
339 * DictionaryOptimizer, the LambdaOptimizer and the LLVMOptimizer.
340 * @tparam T An arbitrary type resulting from the application of
341 * the SFINAE idiom to selectively specialize this class.
342 */
343 template <typename ReturnType, typename Optimizer, typename T = void>
344 struct OptimizerHelper;
345
346
347 # ifndef DOXYGEN
348
349
350 /* ----------- Specializations for the Optimizers ----------- */
351
352
353 // A helper struct to type trait detection for the optimizers that
354 // will be defined next.
355 template <typename ReturnType_, typename T = void>
356 struct SupportedOptimizerTypeTraits
357 {
358 static const bool is_supported = false;
359
360 using ReturnType = void;
361 };
362
363
364
365 // Specialization for arithmetic types
366 template <typename ReturnType_>
367 struct SupportedOptimizerTypeTraits<
368 ReturnType_,
369 std::enable_if_t<std::is_arithmetic_v<ReturnType_>>>
370 {
371 static const bool is_supported = true;
372
373 using ReturnType =
374 std::conditional_t<std::is_same_v<ReturnType_, float>, float, double>;
375 };
376
377
378
379 // Specialization for complex arithmetic types
380 template <typename ReturnType_>
381 struct SupportedOptimizerTypeTraits<
382 ReturnType_,
383 std::enable_if_t<
384 boost::is_complex<ReturnType_>::value &&
385 std::is_arithmetic_v<typename ReturnType_::value_type>>>
386 {
387 static const bool is_supported = true;
388
389 using ReturnType =
390 std::conditional_t<std::is_same_v<ReturnType_, std::complex<float>>,
391 std::complex<float>,
392 std::complex<double>>;
393 };
394
395
396
397 template <typename ReturnType_>
398 struct DictionaryOptimizer<ReturnType_,
399 std::enable_if_t<SupportedOptimizerTypeTraits<
400 ReturnType_>::is_supported>>
401 {
402 using ReturnType =
403 typename SupportedOptimizerTypeTraits<ReturnType_>::ReturnType;
404 using OptimizerType =
405 internal::DictionarySubstitutionVisitor<ReturnType, SD::Expression>;
406
407
408 /**
409 * Initialize an instance of an optimizer.
410 *
411 * @param optimizer The optimizer to be initialized.
412 * @param independent_symbols A vector of symbols that represent independent variables.
413 * @param dependent_functions A vector of expressions that represent dependent variables.
414 * @param optimization_flags A set of flags that indicate the types of optimization to be performed.
415 */
416 static void
417 initialize(OptimizerType &optimizer,
418 const SymEngine::vec_basic &independent_symbols,
419 const SymEngine::vec_basic &dependent_functions,
420 const enum OptimizationFlags &optimization_flags)
421 {
422 const bool use_symbolic_cse = use_symbolic_CSE(optimization_flags);
423 optimizer.init(independent_symbols,
424 dependent_functions,
425 use_symbolic_cse);
426 }
427
428
429
430 /**
431 * Write the data of the @p optimizer to a stream for the purpose
432 * of serialization.
433 */
434 template <class Archive>
435 static void
436 save(Archive &archive,
437 const unsigned int version,
438 OptimizerType &optimizer)
439 {
440 optimizer.save(archive, version);
441 }
442
443
444
445 /**
446 * Read the data for the @p optimizer from a stream for the purpose
447 * of serialization.
448 */
449 template <class Archive>
450 static void
451 load(Archive &archive,
452 const unsigned int version,
453 OptimizerType &optimizer,
454 const SymEngine::vec_basic & /*independent_symbols*/,
455 const SymEngine::vec_basic & /*dependent_functions*/,
456 const enum OptimizationFlags & /*optimization_flags*/)
457 {
458 optimizer.load(archive, version);
459 }
460
461
462
463 /**
464 * Print some information on state of the internal data
465 * structures stored in the @p optimizer.
466 *
467 * @tparam Stream The type for the output stream.
468 * @param stream The output stream to print to.
469 * @param optimizer The instance of the optimizer from which to retrieve
470 * information to print to the stream.
471 * @param print_independent_symbols A flag to indicate if the independent
472 * variables should be outputted to the @p stream.
473 * @param print_dependent_functions A flag to indicate if the dependent
474 * expressions should be outputted to the @p stream.
475 * @param print_cse_reductions A flag to indicate whether or not all
476 * common subexpressions should be printed to the @p stream.
477 */
478 template <typename Stream>
479 static void
480 print(Stream &stream,
481 const OptimizerType &optimizer,
482 const bool print_independent_symbols = false,
483 const bool print_dependent_functions = false,
484 const bool print_cse_reductions = true)
485 {
486 optimizer.print(stream,
487 print_independent_symbols,
488 print_dependent_functions,
489 print_cse_reductions);
490 }
491 };
492
493
494
495 template <typename ReturnType_>
496 struct LambdaOptimizer<ReturnType_,
497 std::enable_if_t<SupportedOptimizerTypeTraits<
498 ReturnType_>::is_supported>>
499 {
500 using ReturnType =
501 std::conditional_t<!boost::is_complex<ReturnType_>::value,
502 double,
503 std::complex<double>>;
504 using OptimizerType =
505 std::conditional_t<!boost::is_complex<ReturnType_>::value,
506 SymEngine::LambdaRealDoubleVisitor,
507 SymEngine::LambdaComplexDoubleVisitor>;
508
509
510 /**
511 * Initialize an instance of an optimizer.
512 *
513 * @param optimizer The optimizer to be initialized.
514 * @param independent_symbols A vector of symbols that represent independent variables.
515 * @param dependent_functions A vector of expressions that represent dependent variables.
516 * @param optimization_flags A set of flags that indicate the types of optimization to be performed.
517 */
518 static void
519 initialize(OptimizerType &optimizer,
520 const SymEngine::vec_basic &independent_symbols,
521 const SymEngine::vec_basic &dependent_functions,
522 const enum OptimizationFlags &optimization_flags)
523 {
524 const bool use_symbolic_cse = use_symbolic_CSE(optimization_flags);
525 optimizer.init(independent_symbols,
526 dependent_functions,
527 use_symbolic_cse);
528 }
529
530
531
532 /**
533 * Write the data of the @p optimizer to a stream for the purpose
534 * of serialization.
535 */
536 template <class Archive>
537 static void
538 save(Archive & /*archive*/,
539 const unsigned int /*version*/,
540 OptimizerType & /*optimizer*/)
541 {}
542
543
544 /**
545 * Read the data for the @p optimizer from a stream for the purpose
546 * of serialization.
547 */
548 template <class Archive>
549 static void
550 load(Archive & /*archive*/,
551 const unsigned int /*version*/,
552 OptimizerType &optimizer,
553 const SymEngine::vec_basic &independent_symbols,
554 const SymEngine::vec_basic &dependent_functions,
555 const enum OptimizationFlags &optimization_flags)
556 {
557 initialize(optimizer,
558 independent_symbols,
559 dependent_functions,
560 optimization_flags);
561 }
562
563
564
565 /**
566 * Print some information on state of the internal data
567 * structures stored in the @p optimizer.
568 *
569 * @tparam Stream The type for the output stream.
570 * @param stream The output stream to print to.
571 * @param optimizer The instance of the optimizer from which to retrieve
572 * information to print to the stream.
573 * @param print_independent_symbols A flag to indicate if the independent
574 * variables should be outputted to the @p stream.
575 * @param print_dependent_functions A flag to indicate if the dependent
576 * expressions should be outputted to the @p stream.
577 * @param print_cse_reductions A flag to indicate whether or not all
578 * common subexpressions should be printed to the @p stream.
579 */
580 template <typename StreamType>
581 static void
582 print(StreamType & /*stream*/,
583 const OptimizerType & /*optimizer*/,
584 const bool /*print_independent_symbols*/ = false,
585 const bool /*print_dependent_functions*/ = false,
586 const bool /*print_cse_reductions*/ = true)
587 {
588 // No built-in print function
589 }
590 };
591
592
593
594 # ifdef HAVE_SYMENGINE_LLVM
595 template <typename ReturnType_>
596 struct LLVMOptimizer<ReturnType_,
597 std::enable_if_t<std::is_arithmetic_v<ReturnType_>>>
598 {
599 using ReturnType =
600 std::conditional_t<std::is_same_v<ReturnType_, float>, float, double>;
601 using OptimizerType =
602 std::conditional_t<std::is_same_v<ReturnType_, float>,
603 SymEngine::LLVMFloatVisitor,
604 SymEngine::LLVMDoubleVisitor>;
605
606 /**
607 * A flag to indicate if the ReturnType is supported by a
608 * SymEngine LLVM wrapper.
609 */
610 static const bool supported_by_LLVM = true;
611
612
613 /**
614 * Initialize an instance of an optimizer.
615 *
616 * @param optimizer The optimizer to be initialized.
617 * @param independent_symbols A vector of symbols that represent independent variables.
618 * @param dependent_functions A vector of expressions that represent dependent variables.
619 * @param optimization_flags A set of flags that indicate the types of optimization to be performed.
620 */
621 static void
622 initialize(OptimizerType &optimizer,
623 const SymEngine::vec_basic &independent_symbols,
624 const SymEngine::vec_basic &dependent_functions,
625 const enum OptimizationFlags &optimization_flags)
626 {
627 const int opt_level = get_LLVM_optimization_level(optimization_flags);
628 const bool use_symbolic_cse = use_symbolic_CSE(optimization_flags);
629 optimizer.init(independent_symbols,
630 dependent_functions,
631 use_symbolic_cse,
632 opt_level);
633 }
634
635
636
637 /**
638 * Write the data of the @p optimizer to a stream for the purpose
639 * of serialization.
640 */
641 template <class Archive>
642 static void
643 save(Archive &archive,
644 const unsigned int /*version*/,
645 OptimizerType &optimizer)
646 {
647 const std::string llvm_compiled_function = optimizer.dumps();
648 archive &llvm_compiled_function;
649 }
650
651
652
653 /**
654 * Read the data for the @p optimizer from a stream for the purpose
655 * of serialization.
656 */
657 template <class Archive>
658 static void
659 load(Archive &archive,
660 const unsigned int /*version*/,
661 OptimizerType &optimizer,
662 const SymEngine::vec_basic & /*independent_symbols*/,
663 const SymEngine::vec_basic & /*dependent_functions*/,
664 const enum OptimizationFlags & /*optimization_flags*/)
665 {
666 std::string llvm_compiled_function;
667 archive &llvm_compiled_function;
668 optimizer.loads(llvm_compiled_function);
669 }
670
671
672
673 /**
674 * Print some information on state of the internal data
675 * structures stored in the @p optimizer.
676 *
677 * @tparam Stream The type for the output stream.
678 * @param stream The output stream to print to.
679 * @param optimizer The instance of the optimizer from which to retrieve
680 * information to print to the stream.
681 * @param print_independent_symbols A flag to indicate if the independent
682 * variables should be outputted to the @p stream.
683 * @param print_dependent_functions A flag to indicate if the dependent
684 * expressions should be outputted to the @p stream.
685 * @param print_cse_reductions A flag to indicate whether or not all
686 * common subexpressions should be printed to the @p stream.
687 */
688 template <typename StreamType>
689 static void
690 print(StreamType & /*stream*/,
691 const OptimizerType & /*optimizer*/,
692 const bool /*print_independent_symbols*/ = false,
693 const bool /*print_dependent_functions*/ = false,
694 const bool /*print_cse_reductions*/ = true)
695 {
696 // No built-in print function
697 }
698 };
699
700
701 // There is no LLVM optimizer built with complex number support.
702 // So we fall back to the LambdaDouble case as a type (required
703 // at compile time), but offer no implementation. We expect that
704 // the calling class does not create this type: This can be done by
705 // checking the `supported_by_LLVM` flag.
706 template <typename ReturnType_>
707 struct LLVMOptimizer<
708 ReturnType_,
709 std::enable_if_t<
710 boost::is_complex<ReturnType_>::value &&
711 std::is_arithmetic_v<typename ReturnType_::value_type>>>
712 {
713 // Since there is no working implementation, these are dummy types
714 // that help with templating in the calling function.
715 using ReturnType = typename LambdaOptimizer<ReturnType_>::ReturnType;
716 using OptimizerType =
717 typename LambdaOptimizer<ReturnType_>::OptimizerType;
718
719 /**
720 * A flag to indicate if the ReturnType is supported by a
721 * SymEngine LLVM wrapper.
722 */
723 static const bool supported_by_LLVM = false;
724
725
726 /**
727 * Initialize an instance of an optimizer.
728 *
729 * @param optimizer The optimizer to be initialized.
730 * @param independent_symbols A vector of symbols that represent independent variables.
731 * @param dependent_functions A vector of expressions that represent dependent variables.
732 * @param optimization_flags A set of flags that indicate the types of optimization to be performed.
733 */
734 static void
735 initialize(OptimizerType & /*optimizer*/,
736 const SymEngine::vec_basic & /*independent_symbols*/,
737 const SymEngine::vec_basic & /*dependent_functions*/,
738 const enum OptimizationFlags & /*optimization_flags*/)
739 {
740 AssertThrow(false, ExcNotImplemented());
741 }
742
743
744
745 /**
746 * Write the data of the @p optimizer to a stream for the purpose
747 * of serialization.
748 */
749 template <class Archive>
750 static void
751 save(Archive & /*archive*/,
752 const unsigned int /*version*/,
753 OptimizerType & /*optimizer*/)
754 {
755 AssertThrow(false, ExcNotImplemented());
756 }
757
758
759
760 /**
761 * Read the data for the @p optimizer from a stream for the purpose
762 * of serialization.
763 */
764 template <class Archive>
765 static void
766 load(Archive & /*archive*/,
767 const unsigned int /*version*/,
768 OptimizerType & /*optimizer*/,
769 const SymEngine::vec_basic & /*independent_symbols*/,
770 const SymEngine::vec_basic & /*dependent_functions*/,
771 const enum OptimizationFlags & /*optimization_flags*/)
772 {
773 AssertThrow(false, ExcNotImplemented());
774 }
775
776
777
778 /**
779 * Print some information on state of the internal data
780 * structures stored in the @p optimizer.
781 *
782 * @tparam Stream The type for the output stream.
783 * @param stream The output stream to print to.
784 * @param optimizer The instance of the optimizer from which to retrieve
785 * information to print to the stream.
786 * @param print_independent_symbols A flag to indicate if the independent
787 * variables should be outputted to the @p stream.
788 * @param print_dependent_functions A flag to indicate if the dependent
789 * expressions should be outputted to the @p stream.
790 * @param print_cse_reductions A flag to indicate whether or not all
791 * common subexpressions should be printed to the @p stream.
792 */
793 template <typename StreamType>
794 static void
795 print(StreamType & /*stream*/,
796 const OptimizerType & /*optimizer*/,
797 const bool /*print_independent_symbols*/ = false,
798 const bool /*print_dependent_functions*/ = false,
799 const bool /*print_cse_reductions*/ = true)
800 {
801 AssertThrow(false, ExcNotImplemented());
802 }
803 };
804 # endif // HAVE_SYMENGINE_LLVM
805
806
807 /* ----------- Specializations for OptimizerHelper ----------- */
808
809
810 template <typename ReturnType, typename Optimizer>
811 struct OptimizerHelper<
812 ReturnType,
813 Optimizer,
814 std::enable_if_t<
815 std::is_same_v<ReturnType, typename Optimizer::ReturnType>>>
816 {
817 /**
818 * Initialize an instance of an optimizer.
819 *
820 * @param optimizer The optimizer to be initialized.
821 * @param independent_symbols A vector of symbols that represent independent variables.
822 * @param dependent_functions A vector of expressions that represent dependent variables.
823 * @param optimization_flags A set of flags that indicate the types of optimization to be performed.
824 */
825 static void
826 initialize(typename Optimizer::OptimizerType *optimizer,
827 const SymEngine::vec_basic &independent_symbols,
828 const SymEngine::vec_basic &dependent_functions,
829 const enum OptimizationFlags &optimization_flags)
830 {
831 Assert(optimizer, ExcNotInitialized());
832
833 // Some optimizers don't have the same interface for
834 // initialization, we filter them out through the specializations
835 // of the Optimizer class
836 Optimizer::initialize(*optimizer,
837 independent_symbols,
838 dependent_functions,
839 optimization_flags);
840 }
841
842
843
844 /**
845 * Perform value substitution, evaluating the pre-registered dependent
846 * functions with some values associated with all independent symbols.
847 *
848 * @param optimizer The optimizer on which to perform value substitution
849 * for all independent symbols. The values are substituted into the
850 * optimized form of the dependent variables that were registered with
851 * this class instance.
852 * @param output_values The evaluated numerical outcome of the
853 * substitution.
854 * @param substitution_values The values with which to associate each
855 * individual independent symbol.
856 */
857 static void
858 substitute(typename Optimizer::OptimizerType *optimizer,
859 std::vector<ReturnType> &output_values,
860 const std::vector<ReturnType> &substitution_values)
861 {
862 Assert(optimizer, ExcNotInitialized());
863 optimizer->call(output_values.data(), substitution_values.data());
864 }
865
866
867
868 /**
869 * Write the data of the @p optimizer to a stream for the purpose
870 * of serialization.
871 */
872 template <class Archive>
873 static void
874 save(Archive &archive,
875 const unsigned int version,
876 typename Optimizer::OptimizerType *optimizer)
877 {
878 Assert(optimizer, ExcNotInitialized());
879
880 // Some optimizers don't have the same interface for
881 // serialization, we filter them out through the specializations
882 // of the Optimizer class
883 Optimizer::save(archive, version, *optimizer);
884 }
885
886
887
888 /**
889 * Read the data for the @p optimizer from a stream for the purpose
890 * of serialization.
891 */
892 template <class Archive>
893 static void
894 load(Archive &archive,
895 const unsigned int version,
896 typename Optimizer::OptimizerType *optimizer,
897 const SymEngine::vec_basic &independent_symbols,
898 const SymEngine::vec_basic &dependent_functions,
899 const enum OptimizationFlags &optimization_flags)
900 {
901 Assert(optimizer, ExcNotInitialized());
902
903 // Some optimizers don't have the same interface for
904 // serialization, we filter them out through the specializations
905 // of the Optimizer class
906 Optimizer::load(archive,
907 version,
908 *optimizer,
909 independent_symbols,
910 dependent_functions,
911 optimization_flags);
912 }
913
914
915
916 /**
917 * Print some information on state of the internal data
918 * structures stored in the @p optimizer.
919 *
920 * @tparam Stream The type for the output stream.
921 * @param stream The output stream to print to.
922 * @param optimizer A pointer to the instance of the optimizer from
923 * which to retrieve information to print to the stream.
924 * @param print_independent_symbols A flag to indicate if the independent
925 * variables should be outputted to the @p stream.
926 * @param print_dependent_functions A flag to indicate if the dependent
927 * expressions should be outputted to the @p stream.
928 * @param print_cse_reductions A flag to indicate whether or not all
929 * common subexpressions should be printed to the @p stream.
930 */
931 template <typename Stream>
932 static void
933 print(Stream &stream,
934 typename Optimizer::OptimizerType *optimizer,
935 const bool print_independent_symbols = false,
936 const bool print_dependent_functions = false,
937 const bool print_cse_reductions = true)
938 {
939 Assert(optimizer, ExcNotInitialized());
940
941 // Some optimizers don't have a print function, so
942 // we filter them out through the specializations of
943 // the Optimizer class
944 Optimizer::print(stream,
945 *optimizer,
946 print_independent_symbols,
947 print_dependent_functions,
948 print_cse_reductions);
949 }
950 };
951
952 template <typename ReturnType, typename Optimizer>
953 struct OptimizerHelper<
954 ReturnType,
955 Optimizer,
956 std::enable_if_t<
957 !std::is_same_v<ReturnType, typename Optimizer::ReturnType>>>
958 {
959 /**
960 * Initialize an instance of an optimizer.
961 *
962 * @param optimizer The optimizer to be initialized.
963 * @param independent_symbols A vector of symbols that represent independent variables.
964 * @param dependent_functions A vector of expressions that represent dependent variables.
965 * @param optimization_flags A set of flags that indicate the types of optimization to be performed.
966 */
967 static void
968 initialize(typename Optimizer::OptimizerType *optimizer,
969 const SymEngine::vec_basic &independent_symbols,
970 const SymEngine::vec_basic &dependent_functions,
971 const enum OptimizationFlags &optimization_flags)
972 {
973 Assert(optimizer, ExcNotInitialized());
974
975 const bool use_symbolic_cse = use_symbolic_CSE(optimization_flags);
976 optimizer->init(independent_symbols,
977 dependent_functions,
978 use_symbolic_cse);
979 }
980
981
982
983 /**
984 * Perform value substitution, evaluating the pre-registered dependent
985 * functions with some values associated with all independent symbols.
986 *
987 * @param optimizer The optimizer on which to perform value substitution
988 * for all independent symbols. The values are substituted into the
989 * optimized form of the dependent variables that were registered with
990 * this class instance.
991 * @param output_values The evaluated numerical outcome of the
992 * substitution.
993 * @param substitution_values The values with which to associate each
994 * individual independent symbol.
995 */
996 static void
997 substitute(typename Optimizer::OptimizerType *optimizer,
998 std::vector<ReturnType> &output_values,
999 const std::vector<ReturnType> &substitution_values)
1000 {
1001 Assert(optimizer, ExcNotInitialized());
1002
1003 // Intermediate values to accommodate the difference in
1004 // value types.
1005 std::vector<typename Optimizer::ReturnType> int_outputs(
1006 output_values.size());
1007 std::vector<typename Optimizer::ReturnType> int_inputs(
1008 substitution_values.size());
1009
1010 std::copy(substitution_values.begin(),
1011 substitution_values.end(),
1012 int_inputs.begin());
1013 optimizer->call(int_outputs.data(), int_inputs.data());
1014 std::copy(int_outputs.begin(),
1015 int_outputs.end(),
1016 output_values.begin());
1017 }
1018
1019
1020
1021 /**
1022 * Write the data of the @p optimizer to a stream for the purpose
1023 * of serialization.
1024 */
1025 template <class Archive>
1026 static void
1027 save(Archive &archive,
1028 const unsigned int version,
1029 typename Optimizer::OptimizerType *optimizer)
1030 {
1031 Assert(optimizer, ExcNotInitialized());
1032 Optimizer::save(archive, version, *optimizer);
1033 }
1034
1035
1036
1037 /**
1038 * Read the data for the @p optimizer from a stream for the purpose
1039 * of serialization.
1040 */
1041 template <class Archive>
1042 static void
1043 load(Archive &archive,
1044 const unsigned int version,
1045 typename Optimizer::OptimizerType *optimizer,
1046 const SymEngine::vec_basic &independent_symbols,
1047 const SymEngine::vec_basic &dependent_functions,
1048 const enum OptimizationFlags &optimization_flags)
1049 {
1050 Assert(optimizer, ExcNotInitialized());
1051
1052 // Some optimizers don't have the same interface for
1053 // serialization, we filter them out through the specializations
1054 // of the Optimizer class
1055 Optimizer::load(archive,
1056 version,
1057 *optimizer,
1058 independent_symbols,
1059 dependent_functions,
1060 optimization_flags);
1061 }
1062
1063
1064
1065 /**
1066 * Print some information on state of the internal data
1067 * structures stored in the @p optimizer.
1068 *
1069 * @tparam Stream The type for the output stream.
1070 * @param stream The output stream to print to.
1071 * @param optimizer A pointer to the instance of the optimizer from
1072 * which to retrieve information to print to the stream.
1073 * @param print_independent_symbols A flag to indicate if the independent
1074 * variables should be outputted to the @p stream.
1075 * @param print_dependent_functions A flag to indicate if the dependent
1076 * expressions should be outputted to the @p stream.
1077 * @param print_cse_reductions A flag to indicate whether or not all
1078 * common subexpressions should be printed to the @p stream.
1079 */
1080 template <typename Stream>
1081 static void
1082 print(Stream &stream,
1083 typename Optimizer::OptimizerType *optimizer,
1084 const bool print_cse_reductions = true,
1085 const bool print_independent_symbols = false,
1086 const bool print_dependent_functions = false)
1087 {
1088 Assert(optimizer, ExcNotInitialized());
1089
1090 optimizer->print(stream,
1091 print_independent_symbols,
1092 print_dependent_functions,
1093 print_cse_reductions);
1094 }
1095 };
1096
1097 # endif // DOXYGEN
1098
1099
1100 /* -------------------- Utility functions ---------------------- */
1101
1102
1103 /**
1104 * A convenience function that returns the numeric equivalent of
1105 * an input @p symbol_tensor, computed through the @p optimizer.
1106 *
1107 * @tparam NumberType The number type that is returned as a result
1108 * of operations performed by the optimizer.
1109 * @tparam rank The rank of the output tensor.
1110 * @tparam dim The dimension of the output tensor.
1111 * @tparam TensorType The type of tensor to be evaluated and returned
1112 * (i.e. Tensor or SymmetricTensor).
1113 * @param[in] symbol_tensor The symbolic tensor that is to be evaluated.
1114 * @param[in] cached_evaluation A vector that stores the numerical
1115 * values of all dependent variables referenced by the
1116 * @p optimizer. This vector is, most typically, first attained
1117 * by a call to the BatchOptimizer::evaluate() variant that
1118 * takes no arguments.
1119 * @param[in] optimizer The optimizer that can evaluate the input
1120 * @p symbol_tensor.
1121 * @return TensorType<rank, dim, NumberType> The numeric result that the
1122 * input @p symbol_tensor evaluates to.
1123 */
1124 template <typename NumberType,
1125 int rank,
1126 int dim,
1127 template <int, int, typename>
1128 class TensorType>
1129 TensorType<rank, dim, NumberType>
1130 tensor_evaluate_optimized(
1131 const TensorType<rank, dim, Expression> &symbol_tensor,
1132 const std::vector<NumberType> &cached_evaluation,
1133 const BatchOptimizer<NumberType> &optimizer)
1134 {
1135 TensorType<rank, dim, NumberType> out;
1136 for (unsigned int i = 0; i < out.n_independent_components; ++i)
1137 {
1138 const TableIndices<rank> indices(
1139 out.unrolled_to_component_indices(i));
1140 out[indices] =
1141 optimizer.extract(symbol_tensor[indices], cached_evaluation);
1142 }
1143 return out;
1144 }
1145
1146
1147 /**
1148 * A convenience function that returns the numeric equivalent of
1149 * an input @p symbol_tensor, computed through the @p optimizer.
1150 * This is a specialization for rank-4 symmetric tensors.
1151 *
1152 * @tparam NumberType The number type that is returned as a result
1153 * of operations performed by the optimizer.
1154 * @tparam rank The rank of the output tensor.
1155 * @tparam dim The dimension of the output tensor.
1156 * @tparam TensorType The type of tensor to be evaluated and returned
1157 * (i.e. Tensor or SymmetricTensor).
1158 * @param[in] symbol_tensor The symbolic tensor that is to be evaluated.
1159 * @param[in] cached_evaluation A vector that stores the numerical
1160 * values of all dependent variables referenced by the
1161 * @p optimizer. This vector is, most typically, first attained
1162 * by a call to the BatchOptimizer::evaluate() variant that
1163 * takes no arguments.
1164 * @param[in] optimizer The optimizer that can evaluate the input
1165 * @p symbol_tensor.
1166 * @return TensorType<rank, dim, NumberType> The numeric result that the
1167 * input @p symbol_tensor evaluates to.
1168 */
1169 template <typename NumberType, int dim>
1170 SymmetricTensor<4, dim, NumberType>
1171 tensor_evaluate_optimized(
1172 const SymmetricTensor<4, dim, Expression> &symbol_tensor,
1173 const std::vector<NumberType> &cached_evaluation,
1174 const BatchOptimizer<NumberType> &optimizer)
1175 {
1176 SymmetricTensor<4, dim, NumberType> out;
1177 for (unsigned int i = 0;
1178 i < SymmetricTensor<2, dim>::n_independent_components;
1179 ++i)
1180 for (unsigned int j = 0;
1181 j < SymmetricTensor<2, dim>::n_independent_components;
1182 ++j)
1183 {
1184 const TableIndices<4> indices =
1185 make_rank_4_tensor_indices<dim>(i, j);
1186 out[indices] =
1187 optimizer.extract(symbol_tensor[indices], cached_evaluation);
1188 }
1189 return out;
1190 }
1191
1192
1193 /**
1194 * A helper function to register a single @p function with the
1195 * @p optimizer.
1196 *
1197 * @tparam NumberType The number type that is returned as a result
1198 * of operations performed by the optimizer.
1199 * @tparam T A compatible type that may be used to represent a single
1200 * dependent variable. This includes scalar Expressions, Tensors
1201 * of Expressions and SymmetricTensors of Expressions.
1202 * @param optimizer The instance of the BatchOptimizer to register the
1203 * @p function with.
1204 * @param function A symbolic expression (scalar or tensor) that
1205 * represents a dependent variable.
1206 *
1207 * @note This is the end-point for all recursive template functions
1208 * with the same name.
1209 */
1210 template <typename NumberType, typename T>
1211 void
1212 register_functions(BatchOptimizer<NumberType> &optimizer,
1213 const T &function)
1214 {
1215 optimizer.register_function(function);
1216 }
1217
1218
1219 /**
1220 * A helper function to register a vector of @p functions with the
1221 * @p optimizer.
1222 *
1223 * @tparam NumberType The number type that is returned as a result
1224 * of operations performed by the optimizer.
1225 * @tparam T A compatible type that may be used to represent a single
1226 * dependent variable. This includes scalar Expressions, Tensors
1227 * of Expressions and SymmetricTensors of Expressions.
1228 * @param optimizer The instance of the BatchOptimizer to register the
1229 * @p function with.
1230 * @param functions A vector of symbolic expressions (scalar or tensor)
1231 * that each represent a dependent variable.
1232 *
1233 * @note This is the end-point for all recursive template functions
1234 * with the same name.
1235 */
1236 template <typename NumberType, typename T>
1237 void
1238 register_functions(BatchOptimizer<NumberType> &optimizer,
1239 const std::vector<T> &functions)
1240 {
1241 for (const auto &function : functions)
1242 register_functions(optimizer, function);
1243 }
1244
1245
1246 /**
1247 * A helper function to register the symbolic dependent variables
1248 * collectively given by @p function and @p other_functions with the
1249 * @p optimizer.
1250 *
1251 * @tparam NumberType The number type that is returned as a result
1252 * of operations performed by the optimizer.
1253 * @tparam T A compatible type that may be used to represent a single
1254 * dependent variable. This includes scalar Expressions, Tensors
1255 * of Expressions and SymmetricTensors of Expressions.
1256 * @tparam Args The parameter pack that collects all other types of
1257 * dependent variables to be registered.
1258 * @param optimizer The instance of the BatchOptimizer to register the
1259 * @p function with.
1260 * @param function A valid symbolic expression (or collection of symbolic
1261 * expression) that represents one (or more) dependent variable.
1262 * @param other_functions One or more other valid symbolic expression(s)
1263 * that represent dependent variable(s).
1264 */
1265 template <typename NumberType, typename T, typename... Args>
1266 void
1267 register_functions(BatchOptimizer<NumberType> &optimizer,
1268 const T &function,
1269 const Args &...other_functions)
1270 {
1271 register_functions(optimizer, function);
1272 register_functions(optimizer, other_functions...);
1273 }
1274
1275
1276 /**
1277 * A utility function that unrolls the input @p symbol_tensor into
1278 * a vector of Expressions.
1279 *
1280 * @tparam rank The rank of the input tensor.
1281 * @tparam dim The dimension of the input tensor.
1282 * @tparam TensorType The type of tensor to be evaluated and returned
1283 * (i.e. Tensor or SymmetricTensor).
1284 * @param symbol_tensor
1285 * @return A vector of Expressions, with a consistent ordering.
1286 */
1287 template <int rank,
1288 int dim,
1289 template <int, int, typename>
1290 class TensorType>
1291 types::symbol_vector
1292 unroll_to_expression_vector(
1293 const TensorType<rank, dim, Expression> &symbol_tensor)
1294 {
1295 SD::types::symbol_vector out;
1296 out.reserve(symbol_tensor.n_independent_components);
1297 for (unsigned int i = 0; i < symbol_tensor.n_independent_components;
1298 ++i)
1299 {
1300 const TableIndices<rank> indices(
1301 symbol_tensor.unrolled_to_component_indices(i));
1302 out.push_back(symbol_tensor[indices].get_RCP());
1303 }
1304 return out;
1305 }
1306
1307
1308 /**
1309 * A utility function that unrolls the input @p symbol_tensor into
1310 * a vector of Expressions.
1311 * This is a specialization for rank-4 symmetric tensors.
1312 *
1313 * @tparam dim The dimension of the input tensor.
1314 * @param symbol_tensor
1315 * @return A vector of Expressions, with a consistent ordering.
1316 */
1317 template <int dim>
1318 types::symbol_vector
1319 unroll_to_expression_vector(
1320 const SymmetricTensor<4, dim, Expression> &symbol_tensor)
1321 {
1322 SD::types::symbol_vector out;
1323 out.reserve(symbol_tensor.n_independent_components);
1324 for (unsigned int i = 0;
1325 i < SymmetricTensor<2, dim>::n_independent_components;
1326 ++i)
1327 for (unsigned int j = 0;
1328 j < SymmetricTensor<2, dim>::n_independent_components;
1329 ++j)
1330 {
1331 const TableIndices<4> indices =
1332 make_rank_4_tensor_indices<dim>(i, j);
1333 out.push_back(symbol_tensor[indices].get_RCP());
1334 }
1335 return out;
1336 }
1337
1338 } // namespace internal
1339
1340
1341
1342 /**
1343 * A class that facilitates the optimization of symbol expressions.
1344 *
1345 * This expression will be optimized by this class; that is to say that
1346 * the code path taken to substitute the set of (independent) symbols
1347 * into a collection of (dependent) symbolic functions will be optimized
1348 * using a chosen approach.
1349 *
1350 * This snippet of pseudo-code describes the general usage of this class:
1351 * @code
1352 *
1353 * // Define some independent variables
1354 * const Expression x("x");
1355 * const Expression y("y");
1356 * ...
1357 *
1358 * // Compute some symbolic expressions that are dependent on the
1359 * // independent variables. These could be, for example, scalar
1360 * // expressions or tensors of expressions.
1361 * const auto f = calculate_f(x, y, ...);
1362 * const auto g = calculate_g(x, y, ...);
1363 * ...
1364 *
1365 * // Now create a optimizer to evaluate the dependent functions.
1366 * // The numerical result will be of type double, and a "lambda" optimizer,
1367 * // which employs common subexpression elimination, will be used.
1368 * using ReturnType = double;
1369 * BatchOptimizer<ReturnType> optimizer (OptimizerType::lambda,
1370 * OptimizationFlags::optimize_cse);
1371 *
1372 * // Register symbols that represent independent variables...
1373 * optimizer.register_symbols(x, y, ...);
1374 * // ... and symbolic expressions that represent dependent functions.
1375 * optimizer.register_functions(f, g, ...);
1376 *
1377 * // Now we determine an equivalent code path that will evaluate
1378 * // all of the dependent functions at once, but with less computational
1379 * // cost than when evaluating the symbolic expression directly.
1380 * optimizer.optimize(); // Note: This is an expensive call.
1381 *
1382 * // Next we pass the optimizer the numeric values that we wish the
1383 * // independent variables to represent.
1384 * const auto substitution_map
1385 * = make_substitution_map({x, ...}, {y, ...}, ...);
1386 * // When making this next call, the call path used to (numerically)
1387 * // evaluate the dependent functions is quicker than dictionary
1388 * // substitution.
1389 * optimizer.substitute(substitution_map);
1390 *
1391 * // Finally, we can get the numeric equivalent of the dependent functions
1392 * // from the optimizer.
1393 * const auto result_f = optimizer.evaluate(f);
1394 * const auto result_g = optimizer.evaluate(g);
1395 * @endcode
1396 *
1397 * Since the call to optimize() may be quite costly, there are a few "best
1398 * practices" that can be adopted in order to mitigate this cost as much
1399 * as possible:
1400 * 1. Reuse a single instance of the class as much as possible.
1401 * The most obvious way that this can be achieved would be to place an
1402 * instance of this class in a centralized location where it can
1403 * potentially be used by multiple calling functions and objects, if
1404 * contextually possible.
1405 * 2. Another form of reuse would entail generalizing the dependent
1406 * functions/expressions to be evaluated by the optimizer as much as
1407 * possible. For example, material coefficients need not necessarily be
1408 * hard-coded, and one generalized statement of a constitutive law could
1409 * then be broadly used in other material subdomains governed by the
1410 * same class of constitutive law, but with different constitutive
1411 * parameters. The same principle applies if using symbolic expressions
1412 * to describe boundary conditions, systems of linear equations, etc.
1413 * 3. When possible, consider using serialization to save and load the state
1414 * of an optimizer that has already "optimized", i.e. it has been placed
1415 * in a state where it is ready to evaluate expressions.
1416 * With the exception of "lambda" optimization, all other forms of
1417 * optimization permit checkpointing, meaning that the optimization could
1418 * be done up front before executing the main body of code.
1419 * It could also be used to duplicate an optimizer in an efficient
1420 * manner, should multiple instances of the same optimizer be required.
1421 *
1422 * @tparam ReturnType The number type that is to be returned after
1423 * value substitution and evaluation. Floating point and complex numbers
1424 * are currently supported.
1425 *
1426 * @warning This class is not thread-safe.
1427 *
1428 * @warning The LLVM optimizer does not yet support complex numbers. If this
1429 * incompatible combination of @p ReturnType and optimization method are
1430 * selected, then an error will be thrown at run time.
1431 */
1432 template <typename ReturnType>
1433 class BatchOptimizer
1434 {
1435 public:
1436 /**
1437 * Default constructor.
1438 *
1439 * By default, dictionary substitution will be selected when this
1440 * constructor is called. In order to select a specific optimization
1441 * approach, a call to set_optimization_method() is necessary.
1442 */
1443 BatchOptimizer();
1444
1445 /**
1446 * Constructor.
1447 *
1448 * @param[in] optimization_method The optimization method that is to be
1449 * employed.
1450 * @param[in] optimization_flags The optimization flags that indicate
1451 * which expression manipulation mechanisms are to be employed.
1452 *
1453 * @note As the optimization method is fixed, a further call to
1454 * set_optimization_method() is not necessary and will result in an
1455 * error being thrown.
1456 *
1457 * @note In the case that the @p optimization_method is not implemented for the
1458 * required @p ReturnType, or the desired feature is not active,
1459 * then an error will be thrown. Currently the LLVM optimization method
1460 * is not compatible with complex numbers.
1461 */
1462 BatchOptimizer(const enum OptimizerType &optimization_method,
1463 const enum OptimizationFlags &optimization_flags =
1464 OptimizationFlags::optimize_all);
1465
1466 /**
1467 * Copy constructor.
1468 *
1469 * @note The optimized data and results from previous substitutions
1470 * executed by the @p other optimizer instance are not copied over.
1471 * It is therefore necessary to re-optimize the data stored in
1472 * this class, and it is possible to do so with a different optimization
1473 * scheme.
1474 */
1475 BatchOptimizer(const BatchOptimizer &other);
1476
1477 /**
1478 * Move constructor.
1479 */
1480 BatchOptimizer(BatchOptimizer &&) noexcept = default;
1481
1482 /**
1483 * Destructor.
1484 */
1485 ~BatchOptimizer() = default;
1486
1487 /**
1488 * Duplicate the data stored in an @p other BatchOptimizer instance.
1489 *
1490 * @note The optimized data and results from previous substitutions
1491 * executed by the @p other optimizer instance are not copied over.
1492 * It is therefore necessary to call optimize() before it is possible to
1493 * substitute() values and evaluate() data. One may, however, still
1494 * extract() values using @p this optimizer instance if those results are
1495 * stored elsewhere.
1496 */
1497 void
1498 copy_from(const BatchOptimizer &other);
1499
1500 /**
1501 * Print some information on state of the internal data
1502 * structures stored in the class.
1503 *
1504 * @tparam Stream The type for the output stream.
1505 * @param stream The output stream to print to.
1506 * @param print_cse A flag to indicate whether or not all common
1507 * subexpressions should be printed to the @p stream.
1508 */
1509 template <typename Stream>
1510 void
1511 print(Stream &stream, const bool print_cse = false) const;
1512
1513 /**
1514 * Write the data of this object from a stream for the purpose
1515 * of serialization using the [BOOST serialization
1516 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
1517 *
1518 * This effectively saves the value stored into the @p archive with the
1519 * given @p version number into this object.
1520 */
1521 template <class Archive>
1522 void
1523 save(Archive &archive, const unsigned int version) const;
1524
1525 /**
1526 * Read the data of this object from a stream for the purpose
1527 * of serialization using the [BOOST serialization
1528 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
1529 *
1530 * This effectively loads the value stored out of the
1531 * @p archive with the given @p version number into this object.
1532 * In doing so, the previous contents of this object are thrown away.
1533 *
1534 * @note When deserializing a symbolic expression, it is imperative that
1535 * you first create or deserialize all of the symbolic variables used in
1536 * the serialized expression.
1537 */
1538 template <class Archive>
1539 void
1540 load(Archive &archive, const unsigned int version);
1541
1542 # ifdef DOXYGEN
1543 /**
1544 * Write and read the data of this object from a stream for the purpose
1545 * of serialization using the [BOOST serialization
1546 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
1547 *
1548 * This effectively saves or loads the value stored into/out of the
1549 * @p archive with the given @p version number into this object.
1550 * If deserializing data, then the previous contents of this object
1551 * are thrown away.
1552 *
1553 * @note When deserializing a batch optimizer, it is imperative that
1554 * you first create or deserialize all of the symbolic variables and
1555 * symbolic functions used in the optimizer.
1556 *
1557 * @note Complete serialization is not possible when the "lambda"
1558 * optimization method is invoked. Although the registered symbols
1559 * and dependent function expressions are stored, the optimization
1560 * is itself not stored. It might, therefore, take some time for the
1561 * deserialization when "lambda" optimization is used as the optimization
1562 * step will be (automatically) performed once more.
1563 */
1564 template <class Archive>
1565 void
1566 serialize(Archive &archive, const unsigned int version);
1567 # else
1568 // This macro defines the serialize() method that is compatible with
1569 // the templated save() and load() method that have been implemented.
1570 BOOST_SERIALIZATION_SPLIT_MEMBER()
1571 # endif
1572
1573 /**
1574 * @name Independent variables
1575 */
1576 /** @{ */
1577
1578 /**
1579 * Register a collection of symbols that represents an independent
1580 * variable. These symbols are stored as the <tt>key</tt> to
1581 * the @p substitution_map.
1582 */
1583 void
1584 register_symbols(const types::substitution_map &substitution_map);
1585
1586 /**
1587 * Register a collection of symbols that represents an independent
1588 * variable. These symbols are stored as the <tt>key</tt> to
1589 * the @p substitution_map.
1590 */
1591 void
1592 register_symbols(const SymEngine::map_basic_basic &substitution_map);
1593
1594 /**
1595 * Register a collection of symbols that represents independent variables.
1596 *
1597 * @warning When using this function is no mechanism to check that the ordering
1598 * of the later used @p substitution_values vector or map matches the internal
1599 * ordering of the registered symbols. This function is therefore
1600 * typically used in conjunction with the substitute() function that takes
1601 * in a vector of values. With this pair of functions to the class
1602 * interface, the management of symbol ordering is maintained by the user.
1603 */
1604 void
1605 register_symbols(const types::symbol_vector &symbols);
1606
1607 /**
1608 * Register a collection of symbols that represents independent variables.
1609 *
1610 * @warning When using this function is no mechanism to check that the ordering
1611 * of the later used @p substitution_values vector or map matches the internal
1612 * ordering of the registered symbols. This function is therefore
1613 * typically used in conjunction with the substitute() function that takes
1614 * in a vector of values. With this pair of functions to the class
1615 * interface, the management of symbol ordering is maintained by the user.
1616 */
1617 void
1618 register_symbols(const SymEngine::vec_basic &symbols);
1619
1620 /**
1621 * Return a vector of symbols that have been registered as independent
1622 * variables.
1623 */
1624 types::symbol_vector
1625 get_independent_symbols() const;
1626
1627 /**
1628 * The number of independent variables that this optimizer will recognize.
1629 * This is equal to the number of unique symbols passed to this class
1630 * instance through the register_symbols() function.
1631 */
1632 std::size_t
1633 n_independent_variables() const;
1634
1635 /** @} */
1636
1637 /**
1638 * @name Dependent variables
1639 */
1640 /** @{ */
1641
1642 /**
1643 * Register a scalar symbolic expression that represents a dependent
1644 * variable.
1645 */
1646 void
1647 register_function(const Expression &function);
1648
1649 /**
1650 * Register a tensor of symbolic expressions that represents a dependent
1651 * variable.
1652 */
1653 template <int rank, int dim>
1654 void
1655 register_function(const Tensor<rank, dim, Expression> &function_tensor);
1656
1657 /**
1658 * Register a symmetric tensor of symbolic expressions that represents a
1659 * dependent variable.
1660 */
1661 template <int rank, int dim>
1662 void
1663 register_function(
1664 const SymmetricTensor<rank, dim, Expression> &function_tensor);
1665
1666 /**
1667 * Register a collection of symbolic expressions that represent dependent
1668 * variables.
1669 */
1670 void
1671 register_functions(const types::symbol_vector &functions);
1672
1673 /**
1674 * Register a collection of symbolic expressions that represent multiple
1675 * dependent variables.
1676 */
1677 void
1678 register_functions(const SymEngine::vec_basic &functions);
1679
1680 /**
1681 * Register a collection of symbolic expressions that represent multiple
1682 * dependent variables.
1683 *
1684 * @tparam T A compatible type that may be used to represent a single dependent
1685 * variable. This includes scalar Expressions, Tensors of
1686 * Expressions and SymmetricTensors of Expressions.
1687 * @param functions A vector of symbolic dependent variables.
1688 */
1689 template <typename T>
1690 void
1691 register_functions(const std::vector<T> &functions);
1692
1693 /**
1694 * Register a collection of symbolic expressions that represent dependent
1695 * variables.
1696 *
1697 * @tparam T A compatible type that may be used to represent a single dependent
1698 * variable. This includes scalar Expressions, Tensors of
1699 * Expressions, SymmetricTensors of Expressions, and `std::vector`s
1700 * of Expressions.
1701 * @tparam Args A variadic template that represents a collection of any compatible
1702 * symbolic dependent variable types.
1703 * @param functions One or more symbolic dependent variables.
1704 * @param other_functions An arbitrary collection of symbolic dependent variables.
1705 */
1706 template <typename T, typename... Args>
1707 void
1708 register_functions(const T &functions, const Args &...other_functions);
1709
1710 /**
1711 * Return a vector of expressions that have been registered as dependent
1712 * variables.
1713 */
1714 const types::symbol_vector &
1715 get_dependent_functions() const;
1716
1717 /**
1718 * The number of dependent symbolic expressions that this optimizer
1719 * will optimize. This is equal to the number of unique symbolic
1720 * functions / expressions passed to this class instance through the
1721 * register_functions() method.
1722 */
1723 std::size_t
1724 n_dependent_variables() const;
1725
1726 /** @} */
1727
1728 /**
1729 * @name Optimization
1730 */
1731 /** @{ */
1732
1733 /**
1734 * Select the @p optimization_method for the batch optimizer to
1735 * employ, in conjunction with the @p optimization_flags.
1736 *
1737 * It is required that the this class instance is not yet optimized, i.e.
1738 * that the optimize() method has not yet been called.
1739 *
1740 * @note In the case that the @p method is not implemented for the
1741 * required @p ReturnType, or the desired feature is not active,
1742 * then a safe default will be selected.
1743 */
1744 void
1745 set_optimization_method(const enum OptimizerType &optimization_method,
1746 const enum OptimizationFlags &optimization_flags =
1747 OptimizationFlags::optimize_all);
1748
1749 /**
1750 * Return the optimization method that has been
1751 * selected for use.
1752 */
1753 enum OptimizerType
1754 optimization_method() const;
1755
1756 /**
1757 * Return the optimization flags that have been
1758 * selected for use.
1759 */
1760 enum OptimizationFlags
1761 optimization_flags() const;
1762
1763 /**
1764 * State whether the internal selection of optimization
1765 * methods and flags will render an optimizer that uses
1766 * common subexpression elimination (CSE).
1767 */
1768 bool
1769 use_symbolic_CSE() const;
1770
1771 /**
1772 * Perform the optimization of all registered dependent functions using
1773 * the registered symbols.
1774 *
1775 * @note This function, which should only be called once per instance of this
1776 * class, finalizes the set of accepted independent symbols and dependent
1777 * functions that are recognized and used by the optimizer.
1778 *
1779 * @note This may be a time-consuming process, but if the class instance is
1780 * retained throughout the course of a simulation (and both the
1781 * independent and dependent variables that are associated with the class
1782 * instance remain unchanged) then it need only be performed once.
1783 * Serialization also offers the opportunity to reuse the already computed
1784 * optimized evaluation call path.
1785 */
1786 void
1787 optimize();
1788
1789 /**
1790 * Returns a flag which indicates whether the optimize()
1791 * function has been called and the class is finalized.
1792 */
1793 bool
1794 optimized() const;
1795
1796 /** @} */
1797
1798 /**
1799 * @name Symbol substitution
1800 */
1801 /** @{ */
1802
1803 /**
1804 * Perform batch substitution of all of the registered symbols
1805 * into the registered functions. The result is cached and can
1806 * be extracted by calls to evaluate().
1807 *
1808 * @note Calling substitute() again with a new
1809 * @p substitution_map overwrites any previously computed
1810 * results.
1811 */
1812 void
1813 substitute(const types::substitution_map &substitution_map) const;
1814
1815 /**
1816 * Perform batch substitution of all of the registered symbols
1817 * into the registered functions. The result is cached and can
1818 * be extracted by calls to evaluate().
1819 *
1820 * @note Calling substitute() again with a new
1821 * @p substitution_map overwrites any previously computed
1822 * results.
1823 */
1824 void
1825 substitute(const SymEngine::map_basic_basic &substitution_map) const;
1826
1827 /**
1828 * Perform batch substitution of all of the registered symbols
1829 * into the registered functions. The result is cached and can
1830 * be extracted by calls to evaluate().
1831 * It is expected that there is a 1-1 correspondence between each
1832 * of the @p symbols and @p values.
1833 *
1834 * @note Calling substitute() again with a new set of
1835 * @p values overwrites any previously computed results.
1836 */
1837 void
1838 substitute(const types::symbol_vector &symbols,
1839 const std::vector<ReturnType> &values) const;
1840
1841 /**
1842 * Perform batch substitution of all of the registered symbols
1843 * into the registered functions. The result is cached and can
1844 * be extracted by calls to evaluate().
1845 * It is expected that there is a 1-1 correspondence between each
1846 * of the @p symbols and @p values.
1847 *
1848 * @note Calling substitute() again with a new set of
1849 * @p values overwrites any previously computed results.
1850 */
1851 void
1852 substitute(const SymEngine::vec_basic &symbols,
1853 const std::vector<ReturnType> &values) const;
1854
1855 /**
1856 * Returns a flag to indicate whether the substitute()
1857 * function has been called and if there are meaningful
1858 * values that will be returned upon evaluation.
1859 */
1860 bool
1861 values_substituted() const;
1862
1863 /** @} */
1864
1865 /**
1866 * @name Evaluation / data extraction
1867 */
1868 /** @{ */
1869
1870 /**
1871 * Returns the result of a value substitution into the optimized
1872 * counterpart of all dependent functions. This function fetches all of
1873 * those cached values. If these results are stored elsewhere, and you
1874 * want to use this optimizer to extract components of the cached results
1875 * then you can make use of the extract() functions listed below.
1876 *
1877 * These values were computed by substituting a @p substitution_values map
1878 * during substitute() call.
1879 *
1880 * @note In contrast to the other variants of this function, the order of
1881 * the returned entries is an internal implementation detail, and cannot
1882 * be guaranteed under all conditions. The entries in the returned vector
1883 * are, in general, identical to the order in which the dependent
1884 * expressions are originally registered. However, when registering
1885 * tensors and symmetric tensors of expressions, these are "unrolled"
1886 * and their components are individually registered. If it is necessary to
1887 * control the order in which results appear in the returned vector, then
1888 * the register_function() method that takes a Tensor or a SymmetricTensor
1889 * as an argument should be avoided. Instead, the individual entries of
1890 * these types of data should be registered one by one.
1891 */
1892 const std::vector<ReturnType> &
1893 evaluate() const;
1894
1895 /**
1896 * Returns the result of a value substitution into the optimized
1897 * counterpart of @p func. This function fetches that one cached value.
1898 *
1899 * This value was computed by substituting a @p substitution_values map
1900 * during substitute() call.
1901 */
1902 ReturnType
1903 evaluate(const Expression &func) const;
1904
1905 /**
1906 * Returns the result of a value substitution into the optimized
1907 * counterpart of @p funcs. This function fetches that subset of cached
1908 * values.
1909 *
1910 * This value was computed by substituting a @p substitution_values map
1911 * during substitute() call.
1912 */
1913 std::vector<ReturnType>
1914 evaluate(const std::vector<Expression> &funcs) const;
1915
1916 /**
1917 * Returns the result of a tensor value substitution into the optimized
1918 * counterpart of @p funcs. This function fetches those cached tensor
1919 * components.
1920 *
1921 * This value was computed by substituting a @p substitution_values map
1922 * during substitute() call.
1923 */
1924 template <int rank, int dim>
1925 Tensor<rank, dim, ReturnType>
1926 evaluate(const Tensor<rank, dim, Expression> &funcs) const;
1927
1928
1929 /**
1930 * Returns the result of a tensor value substitution into the optimized
1931 * counterpart of @p funcs. This function fetches those cached symmetric
1932 * tensor components.
1933 *
1934 * This value was computed by substituting a @p substitution_values map
1935 * during substitute() call.
1936 */
1937 template <int rank, int dim>
1938 SymmetricTensor<rank, dim, ReturnType>
1939 evaluate(const SymmetricTensor<rank, dim, Expression> &funcs) const;
1940
1941
1942 /**
1943 * Returns the result of a value substitution into the optimized
1944 * counterpart of @p func. This function fetches that one value
1945 * stored in the @p cached_evaluation vector. This vector is, most
1946 * typically, first attained by a call to the evaluate() variant that
1947 * takes no arguments.
1948 */
1949 ReturnType
1950 extract(const Expression &func,
1951 const std::vector<ReturnType> &cached_evaluation) const;
1952
1953
1954 /**
1955 * Returns the result of a value substitution into the optimized
1956 * counterpart of @p funcs. This function fetches that subset of
1957 * values stored in the @p cached_evaluation vector. This vector is, most
1958 * typically, first attained by a call to the evaluate() variant that
1959 * takes no arguments.
1960 */
1961 std::vector<ReturnType>
1962 extract(const std::vector<Expression> &funcs,
1963 const std::vector<ReturnType> &cached_evaluation) const;
1964
1965
1966 /**
1967 * Returns the result of a tensor value substitution into the optimized
1968 * counterpart of @p funcs. This function fetches those tensor components
1969 * stored in the @p cached_evaluation vector. This vector is, most
1970 * typically, first attained by a call to the evaluate() variant that
1971 * takes no arguments.
1972 */
1973 template <int rank, int dim>
1974 Tensor<rank, dim, ReturnType>
1975 extract(const Tensor<rank, dim, Expression> &funcs,
1976 const std::vector<ReturnType> &cached_evaluation) const;
1977
1978
1979 /**
1980 * Returns the result of a tensor value substitution into the optimized
1981 * counterpart of @p funcs. This function fetches those symmetric
1982 * tensor components stored in the @p cached_evaluation vector. This vector
1983 * is, most typically, first attained by a call to the evaluate() variant
1984 * that takes no arguments.
1985 */
1986 template <int rank, int dim>
1987 SymmetricTensor<rank, dim, ReturnType>
1988 extract(const SymmetricTensor<rank, dim, Expression> &funcs,
1989 const std::vector<ReturnType> &cached_evaluation) const;
1990
1991 /** @} */
1992
1993 private:
1994 /**
1995 * The optimization methods that is to be employed.
1996 */
1997 enum OptimizerType method;
1998
1999 /**
2000 * The optimization flags that indicate which expression manipulation
2001 * mechanisms are to be employed.
2002 */
2003 enum OptimizationFlags flags;
2004
2005 /**
2006 * A map that represents the symbols that form the set of independent
2007 * variables upon which optimized symbolic expressions are to be based.
2008 *
2009 * @note As the ordering of the input symbols is fixed at the time at
2010 * which optimization is performed, we store all of the entries in
2011 * a map to ensure that both we and the user never mistakenly
2012 * swap the order of two or more symbols during evaluation.
2013 */
2014 types::substitution_map independent_variables_symbols;
2015
2016 /**
2017 * A set of symbolic expressions to be optimized. It is required that
2018 * the symbols on which these dependent functions are based are
2019 * registered in the @p independent_variables_symbols map.
2020 */
2021 types::symbol_vector dependent_variables_functions;
2022
2023 /**
2024 * A check to see if a function is exactly equal to one of the logical
2025 * results of a differentiation operation.
2026 */
2027 bool
2028 is_valid_nonunique_dependent_variable(
2029 const SD::Expression &function) const;
2030
2031 /**
2032 * A check to see if a function is exactly equal to one of the logical
2033 * results of a differentiation operation.
2034 */
2035 bool
2036 is_valid_nonunique_dependent_variable(
2037 const SymEngine::RCP<const SymEngine::Basic> &function) const;
2038
2039 /**
2040 * The output of substituting symbolic values with floating point
2041 * values through the use of the @p optimizer.
2042 *
2043 * @p It is necessary to use this intermediate storage mechanism
2044 * to store the result of a substitution sweep as some optimizers
2045 * work on all symbolic expressions in a single batch. In this way
2046 * they can employ methods such as common subexpression elimination
2047 * to minimize the number of terms evaluated across all symbolic
2048 * functions.
2049 *
2050 * This variable is marked as mutable. This facilitates the substitution
2051 * functionality being used in logically constant `get_*` functions.
2052 */
2053 mutable std::vector<ReturnType> dependent_variables_output;
2054
2055 /**
2056 * A map type used to indicate which dependent variable is associated
2057 * with which entry in the output vector.
2058 *
2059 * @note We use a custom comparator here because otherwise we can't use
2060 * std::map::find; it is sensitive to the some data from the
2061 * underlying SymEngine::Basic other than the value that it represents.
2062 */
2063 using map_dependent_expression_to_vector_entry_t =
2064 std::map<SD::Expression,
2065 std::size_t,
2066 SD::types::internal::ExpressionKeyLess>;
2067
2068 /**
2069 * A map indicating which dependent variable is associated with which
2070 * entry in the output vector.
2071 */
2072 mutable map_dependent_expression_to_vector_entry_t map_dep_expr_vec_entry;
2073
2074 /**
2075 * A pointer to an instance of an optimizer that will be used to
2076 * reformulate the substitution of symbolic expressions in a
2077 * manner that is more efficient than plain dictionary-based
2078 * approach.
2079 */
2080 mutable std::unique_ptr<SymEngine::Visitor> optimizer;
2081
2082 /**
2083 * A flag to record whether or not substitution has taken place and
2084 * values can now be extracted.
2085 *
2086 * @note This variable is marked as mutable. This facilitates the
2087 * substitution functionality being used in logically constant
2088 * `get_*` functions.
2089 */
2090 mutable bool ready_for_value_extraction;
2091
2092 /**
2093 * A flag to record whether or not this class instance has been serialized
2094 * in the past.
2095 */
2096 mutable bool has_been_serialized;
2097
2098 /**
2099 * Register a single symbol that represents a dependent variable.
2100 */
2101 void
2102 register_scalar_function(const SD::Expression &function);
2103
2104 /**
2105 * Register a collection of symbols that represent dependent
2106 * variables.
2107 */
2108 void
2109 register_vector_functions(const types::symbol_vector &functions);
2110
2111 /**
2112 * Create an instance of the selected optimizer.
2113 */
2114 void
2115 create_optimizer(std::unique_ptr<SymEngine::Visitor> &optimizer);
2116
2117 /**
2118 * Perform batch substitution of all of the registered symbols
2119 * into the registered functions. The result is cached and can
2120 * be extracted by calls to evaluate().
2121 *
2122 * @note Calling substitute() again with a new set of
2123 * @p substitution_values overwrites any previously computed
2124 * results.
2125 *
2126 * @warning When using this function there is no mechanism to check that
2127 * the ordering of the @p substitution_values vector matches the internal
2128 * ordering of the registered symbols. This function is therefore
2129 * typically used in conjunction with the register_symbols() function that
2130 * takes in a vector of symbols. With this pair of functions to the class
2131 * interface, the management of symbol ordering is maintained by the user.
2132 */
2133 void
2134 substitute(const std::vector<ReturnType> &substitution_values) const;
2135 };
2136
2137
2138
2139 /* -------------------- inline and template functions ------------------ */
2140
2141
2142 # ifndef DOXYGEN
2143
2144
2145 template <typename ReturnType>
2146 template <typename Stream>
2147 void
2148 BatchOptimizer<ReturnType>::print(Stream &stream,
2149 const bool /*print_cse*/) const
2150 {
2151 // Settings
2152 stream << "Method? " << optimization_method() << '\n';
2153 stream << "Flags: " << optimization_flags() << '\n';
2154 stream << "Optimized? " << (optimized() ? "Yes" : "No") << '\n';
2155 stream << "Values substituted? " << values_substituted() << "\n\n";
2156
2157 // Independent variables
2158 stream << "Symbols (" << n_independent_variables()
2159 << " independent variables):" << '\n';
2160 int cntr = 0;
2161 for (SD::types::substitution_map::const_iterator it =
2162 independent_variables_symbols.begin();
2163 it != independent_variables_symbols.end();
2164 ++it, ++cntr)
2165 {
2166 stream << cntr << ": " << it->first << '\n';
2167 }
2168 stream << '\n' << std::flush;
2169
2170 // Dependent functions
2171 stream << "Functions (" << n_dependent_variables()
2172 << " dependent variables):" << '\n';
2173 cntr = 0;
2174 for (typename SD::types::symbol_vector::const_iterator it =
2175 dependent_variables_functions.begin();
2176 it != dependent_variables_functions.end();
2177 ++it, ++cntr)
2178 {
2179 stream << cntr << ": " << (*it) << '\n';
2180 }
2181 stream << '\n' << std::flush;
2182
2183 // Common subexpression
2184 if (optimized() == true && use_symbolic_CSE() == true)
2185 {
2186 Assert(optimizer, ExcNotInitialized());
2187 const bool print_cse_reductions = true;
2188 const bool print_independent_symbols = false;
2189 const bool print_dependent_functions = false;
2190
2191 if (optimization_method() == OptimizerType::dictionary)
2192 {
2193 Assert(dynamic_cast<typename internal::DictionaryOptimizer<
2194 ReturnType>::OptimizerType *>(optimizer.get()),
2195 ExcMessage("Cannot cast optimizer to Dictionary type."));
2196
2197 internal::OptimizerHelper<
2198 ReturnType,
2199 internal::DictionaryOptimizer<ReturnType>>::
2200 print(stream,
2201 dynamic_cast<typename internal::DictionaryOptimizer<
2202 ReturnType>::OptimizerType *>(optimizer.get()),
2203 print_independent_symbols,
2204 print_dependent_functions,
2205 print_cse_reductions);
2206
2207 stream << '\n' << std::flush;
2208 }
2209 else if (optimization_method() == OptimizerType::lambda)
2210 {
2211 Assert(dynamic_cast<typename internal::LambdaOptimizer<
2212 ReturnType>::OptimizerType *>(optimizer.get()),
2213 ExcMessage("Cannot cast optimizer to Lambda type."));
2214
2215 internal::OptimizerHelper<ReturnType,
2216 internal::LambdaOptimizer<ReturnType>>::
2217 print(stream,
2218 dynamic_cast<typename internal::LambdaOptimizer<
2219 ReturnType>::OptimizerType *>(optimizer.get()),
2220 print_independent_symbols,
2221 print_dependent_functions,
2222 print_cse_reductions);
2223 }
2224 # ifdef HAVE_SYMENGINE_LLVM
2225 else if (optimization_method() == OptimizerType::llvm)
2226 {
2227 Assert(dynamic_cast<typename internal::LLVMOptimizer<
2228 ReturnType>::OptimizerType *>(optimizer.get()),
2229 ExcMessage("Cannot cast optimizer to LLVM type."));
2230
2231 internal::OptimizerHelper<ReturnType,
2232 internal::LLVMOptimizer<ReturnType>>::
2233 print(stream,
2234 dynamic_cast<typename internal::LLVMOptimizer<
2235 ReturnType>::OptimizerType *>(optimizer.get()),
2236 print_independent_symbols,
2237 print_dependent_functions,
2238 print_cse_reductions);
2239 }
2240 # endif // HAVE_SYMENGINE_LLVM
2241 else
2242 {
2243 AssertThrow(false, ExcMessage("Unknown optimizer type."));
2244 }
2245 }
2246
2247 if (values_substituted())
2248 {
2249 stream << "Evaluated functions:" << '\n';
2250 stream << std::flush;
2251 cntr = 0;
2252 for (typename std::vector<ReturnType>::const_iterator it =
2253 dependent_variables_output.begin();
2254 it != dependent_variables_output.end();
2255 ++it, ++cntr)
2256 {
2257 stream << cntr << ": " << (*it) << '\n';
2258 }
2259 stream << '\n' << std::flush;
2260 }
2261 }
2262
2263
2264
2265 template <typename ReturnType>
2266 template <class Archive>
2267 void
2268 BatchOptimizer<ReturnType>::save(Archive &ar,
2269 const unsigned int version) const
2270 {
2271 // Serialize enum classes...
2272 {
2273 const auto m =
2274 static_cast<std::underlying_type_t<OptimizerType>>(method);
2275 ar &m;
2276 }
2277 {
2278 const auto f =
2279 static_cast<std::underlying_type_t<OptimizationFlags>>(flags);
2280 ar &f;
2281 }
2282
2283 // Important: Independent variables must always be
2284 // serialized before the dependent variables.
2285 ar &independent_variables_symbols;
2286 ar &dependent_variables_functions;
2287
2288 ar &dependent_variables_output;
2289 ar &map_dep_expr_vec_entry;
2290 ar &ready_for_value_extraction;
2291
2292 // Mark that we've saved this class at some point.
2293 has_been_serialized = true;
2294 ar &has_been_serialized;
2295
2296 // When we serialize the optimizer itself, we have to (unfortunately)
2297 // provide it with sufficient information to rebuild itself from scratch.
2298 // This is because only two of the three optimization classes support
2299 // real serialization (i.e. have save/load capability).
2300 const SD::types::symbol_vector symbol_vec =
2301 Utilities::extract_symbols(independent_variables_symbols);
2302 if (typename internal::DictionaryOptimizer<ReturnType>::OptimizerType
2303 *opt = dynamic_cast<typename internal::DictionaryOptimizer<
2304 ReturnType>::OptimizerType *>(optimizer.get()))
2305 {
2306 Assert(optimization_method() == OptimizerType::dictionary,
2307 ExcInternalError());
2308 internal::OptimizerHelper<
2309 ReturnType,
2310 internal::DictionaryOptimizer<ReturnType>>::save(ar, version, opt);
2311 }
2312 else if (typename internal::LambdaOptimizer<ReturnType>::OptimizerType
2313 *opt = dynamic_cast<typename internal::LambdaOptimizer<
2314 ReturnType>::OptimizerType *>(optimizer.get()))
2315 {
2316 Assert(optimization_method() == OptimizerType::lambda,
2317 ExcInternalError());
2318 internal::OptimizerHelper<
2319 ReturnType,
2320 internal::LambdaOptimizer<ReturnType>>::save(ar, version, opt);
2321 }
2322 # ifdef HAVE_SYMENGINE_LLVM
2323 else if (typename internal::LLVMOptimizer<ReturnType>::OptimizerType
2324 *opt = dynamic_cast<typename internal::LLVMOptimizer<
2325 ReturnType>::OptimizerType *>(optimizer.get()))
2326 {
2327 Assert(optimization_method() == OptimizerType::llvm,
2328 ExcInternalError());
2329 internal::OptimizerHelper<
2330 ReturnType,
2331 internal::LLVMOptimizer<ReturnType>>::save(ar, version, opt);
2332 }
2333 # endif
2334 else
2335 {
2336 AssertThrow(false, ExcMessage("Unknown optimizer type."));
2337 }
2338 }
2339
2340
2341
2342 template <typename ReturnType>
2343 template <class Archive>
2344 void
2345 BatchOptimizer<ReturnType>::load(Archive &ar, const unsigned int version)
2346 {
2347 Assert(independent_variables_symbols.empty(), ExcInternalError());
2348 Assert(dependent_variables_functions.empty(), ExcInternalError());
2349 Assert(dependent_variables_output.empty(), ExcInternalError());
2350 Assert(map_dep_expr_vec_entry.empty(), ExcInternalError());
2351 Assert(ready_for_value_extraction == false, ExcInternalError());
2352
2353 // Deserialize enum classes...
2354 {
2355 std::underlying_type_t<OptimizerType> m;
2356 ar &m;
2357 method = static_cast<OptimizerType>(m);
2358 }
2359 {
2360 std::underlying_type_t<OptimizationFlags> f;
2361 ar &f;
2362 flags = static_cast<OptimizationFlags>(f);
2363 }
2364
2365 // Important: Independent variables must always be
2366 // deserialized before the dependent variables.
2367 ar &independent_variables_symbols;
2368 ar &dependent_variables_functions;
2369
2370 ar &dependent_variables_output;
2371 ar &map_dep_expr_vec_entry;
2372 ar &ready_for_value_extraction;
2373
2374 ar &has_been_serialized;
2375
2376 // If we're reading in data, then create the optimizer
2377 // and then deserialize it.
2378 Assert(!optimizer, ExcInternalError());
2379
2380 // Create and configure the optimizer
2381 create_optimizer(optimizer);
2382 Assert(optimizer, ExcNotInitialized());
2383
2384 // When we deserialize the optimizer itself, we have to (unfortunately)
2385 // provide it with sufficient information to rebuild itself from scratch.
2386 // This is because only two of the three optimization classes support
2387 // real serialization (i.e. have save/load capability).
2388 const SD::types::symbol_vector symbol_vec =
2389 Utilities::extract_symbols(independent_variables_symbols);
2390 if (typename internal::DictionaryOptimizer<ReturnType>::OptimizerType
2391 *opt = dynamic_cast<typename internal::DictionaryOptimizer<
2392 ReturnType>::OptimizerType *>(optimizer.get()))
2393 {
2394 Assert(optimization_method() == OptimizerType::dictionary,
2395 ExcInternalError());
2396 internal::OptimizerHelper<ReturnType,
2397 internal::DictionaryOptimizer<ReturnType>>::
2398 load(ar,
2399 version,
2400 opt,
2401 Utilities::convert_expression_vector_to_basic_vector(
2402 symbol_vec),
2403 Utilities::convert_expression_vector_to_basic_vector(
2404 dependent_variables_functions),
2405 optimization_flags());
2406 }
2407 else if (typename internal::LambdaOptimizer<ReturnType>::OptimizerType
2408 *opt = dynamic_cast<typename internal::LambdaOptimizer<
2409 ReturnType>::OptimizerType *>(optimizer.get()))
2410 {
2411 Assert(optimization_method() == OptimizerType::lambda,
2412 ExcInternalError());
2413 internal::OptimizerHelper<ReturnType,
2414 internal::LambdaOptimizer<ReturnType>>::
2415 load(ar,
2416 version,
2417 opt,
2418 Utilities::convert_expression_vector_to_basic_vector(
2419 symbol_vec),
2420 Utilities::convert_expression_vector_to_basic_vector(
2421 dependent_variables_functions),
2422 optimization_flags());
2423 }
2424 # ifdef HAVE_SYMENGINE_LLVM
2425 else if (typename internal::LLVMOptimizer<ReturnType>::OptimizerType
2426 *opt = dynamic_cast<typename internal::LLVMOptimizer<
2427 ReturnType>::OptimizerType *>(optimizer.get()))
2428 {
2429 Assert(optimization_method() == OptimizerType::llvm,
2430 ExcInternalError());
2431 internal::OptimizerHelper<ReturnType,
2432 internal::LLVMOptimizer<ReturnType>>::
2433 load(ar,
2434 version,
2435 opt,
2436 Utilities::convert_expression_vector_to_basic_vector(
2437 symbol_vec),
2438 Utilities::convert_expression_vector_to_basic_vector(
2439 dependent_variables_functions),
2440 optimization_flags());
2441 }
2442 # endif
2443 else
2444 {
2445 AssertThrow(false, ExcMessage("Unknown optimizer type."));
2446 }
2447 }
2448
2449
2450
2451 template <typename ReturnType>
2452 template <int rank, int dim>
2453 void
2454 BatchOptimizer<ReturnType>::register_function(
2455 const Tensor<rank, dim, Expression> &function_tensor)
2456 {
2457 Assert(optimized() == false,
2458 ExcMessage(
2459 "Cannot register functions once the optimizer is finalised."));
2460
2461 register_vector_functions(
2462 internal::unroll_to_expression_vector(function_tensor));
2463 }
2464
2465
2466
2467 template <typename ReturnType>
2468 template <int rank, int dim>
2469 void
2470 BatchOptimizer<ReturnType>::register_function(
2471 const SymmetricTensor<rank, dim, Expression> &function_tensor)
2472 {
2473 Assert(optimized() == false,
2474 ExcMessage(
2475 "Cannot register functions once the optimizer is finalised."));
2476
2477 register_vector_functions(
2478 internal::unroll_to_expression_vector(function_tensor));
2479 }
2480
2481
2482
2483 template <typename ReturnType>
2484 template <typename T, typename... Args>
2485 void
2486 BatchOptimizer<ReturnType>::register_functions(
2487 const T &functions,
2488 const Args &...other_functions)
2489 {
2490 internal::register_functions(*this, functions);
2491 internal::register_functions(*this, other_functions...);
2492 }
2493
2494
2495
2496 template <typename ReturnType>
2497 template <typename T>
2498 void
2499 BatchOptimizer<ReturnType>::register_functions(
2500 const std::vector<T> &functions)
2501 {
2502 internal::register_functions(*this, functions);
2503 }
2504
2505
2506
2507 template <typename ReturnType>
2508 template <int rank, int dim>
2509 Tensor<rank, dim, ReturnType>
2510 BatchOptimizer<ReturnType>::extract(
2511 const Tensor<rank, dim, Expression> &funcs,
2512 const std::vector<ReturnType> &cached_evaluation) const
2513 {
2514 return internal::tensor_evaluate_optimized(funcs,
2515 cached_evaluation,
2516 *this);
2517 }
2518
2519
2520
2521 template <typename ReturnType>
2522 template <int rank, int dim>
2523 Tensor<rank, dim, ReturnType>
2524 BatchOptimizer<ReturnType>::evaluate(
2525 const Tensor<rank, dim, Expression> &funcs) const
2526 {
2527 Assert(
2528 values_substituted() == true,
2529 ExcMessage(
2530 "The optimizer is not configured to perform evaluation. "
2531 "This action can only performed after substitute() has been called."));
2532
2533 return extract(funcs, dependent_variables_output);
2534 }
2535
2536
2537
2538 template <typename ReturnType>
2539 template <int rank, int dim>
2540 SymmetricTensor<rank, dim, ReturnType>
2541 BatchOptimizer<ReturnType>::extract(
2542 const SymmetricTensor<rank, dim, Expression> &funcs,
2543 const std::vector<ReturnType> &cached_evaluation) const
2544 {
2545 return internal::tensor_evaluate_optimized(funcs,
2546 cached_evaluation,
2547 *this);
2548 }
2549
2550
2551
2552 template <typename ReturnType>
2553 template <int rank, int dim>
2554 SymmetricTensor<rank, dim, ReturnType>
2555 BatchOptimizer<ReturnType>::evaluate(
2556 const SymmetricTensor<rank, dim, Expression> &funcs) const
2557 {
2558 Assert(
2559 values_substituted() == true,
2560 ExcMessage(
2561 "The optimizer is not configured to perform evaluation. "
2562 "This action can only performed after substitute() has been called."));
2563
2564 return extract(funcs, dependent_variables_output);
2565 }
2566
2567 # endif // DOXYGEN
2568
2569 } // namespace SD
2570 } // namespace Differentiation
2571
2572
2573 DEAL_II_NAMESPACE_CLOSE
2574
2575 #else
2576
2577 // Make sure the scripts that create the C++20 module input files have
2578 // something to latch on if the preprocessor #ifdef above would
2579 // otherwise lead to an empty content of the file.
2580 DEAL_II_NAMESPACE_OPEN
2581 DEAL_II_NAMESPACE_CLOSE
2582
2583 #endif // DEAL_II_WITH_SYMENGINE
2584
2585 #endif