Debian Codegraph @

include/deal.II/differentiation/sd/symengine_math.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_math_h
16 #define dealii_differentiation_sd_symengine_math_h
17
18 #include <deal.II/base/config.h>
19
20 #ifdef DEAL_II_WITH_SYMENGINE
21
22 # include <deal.II/differentiation/sd/symengine_number_types.h>
23
24 # include <type_traits>
25
26 DEAL_II_NAMESPACE_OPEN
27
28 namespace Differentiation
29 {
30 namespace SD
31 {
32 // Mathematical functions:
33 //
34 // It is necessary that all computed inputs to SymEngine functions are
35 // of type SymEngine::RCP<SymEngine::Basic>. So we instead simply offer a
36 // unified interface to Expression types and with other permutations of
37 // numbers we convert between them.
38 //
39 // For a full list of functions that we (ultimately) expect to support, see
40 // http://www.cplusplus.com/reference/cmath/. Those that are currently
41 // supported are extracted from symengine/{functions,pow}.h;
42 // symengine/type_codes.inc.
43
44
45 /**
46 * @name Power functions
47 */
48 /** @{ */
49
50 /**
51 * Return a symbolic number that represents a @p base value raised to the power of
52 * an @p exponent.
53 *
54 * Mimics the function <code> std::%pow(base,exponent) </code> using the
55 * standard math library.
56 */
57 Expression
58 pow(const Expression &base, const Expression &exponent);
59
60 /**
61 * Return a symbolic number that represents a @p base value raised to the power of
62 * an @p exponent.
63 *
64 * Mimics the function <code> std::%pow(base,exponent) </code> using the
65 * standard math library.
66 *
67 * This variant is used when the @p exponent is not a Expression.
68 */
69 template <
70 typename NumberType,
71 typename = std::enable_if_t<!std::is_same_v<NumberType, Expression>>>
72 Expression
73 pow(const Expression &base, const NumberType &exponent)
74 {
75 // Call other implementation
76 return pow(base, Expression(exponent));
77 }
78
79 /**
80 * Return a symbolic number that represents a @p base value raised to the power of
81 * an @p exponent.
82 *
83 * Mimics the function <code> std::%pow(base,exponent) </code> using the
84 * standard math library.
85 *
86 * This variant is used when the @p base is not a Expression.
87 */
88 template <
89 typename NumberType,
90 typename = std::enable_if_t<!std::is_same_v<NumberType, Expression>>>
91 Expression
92 pow(const NumberType &base, const Expression &exponent)
93 {
94 // Call other implementation
95 return pow(Expression(base), exponent);
96 }
97
98 /**
99 * Return a symbolic number that represents the square root of some value @p x.
100 *
101 * Mimics the function <code> std::%sqrt(x) </code> using the standard math
102 * library.
103 */
104 Expression
105 sqrt(const Expression &x);
106
107 /**
108 * Return a symbolic number that represents the cubic root of some value @p x.
109 *
110 * Mimics the function <code> std::%cbrt(x) </code> using the standard math
111 * library.
112 */
113 Expression
114 cbrt(const Expression &x);
115
116 /**
117 * Return a symbolic number that represents the Euler constant
118 * $e \approx 2.71828$ raised to the given @p exponent.
119 *
120 * Mimics the function <code> std::%exp(exponent) </code> using the standard
121 * math library.
122 */
123 Expression
124 exp(const Expression &exponent);
125
126 /**
127 * Return a symbolic number that represents the natural logarithm of a value @p x.
128 *
129 * Mimics the function <code> std::%log(x) </code> using the standard math
130 * library.
131 */
132 Expression
133 log(const Expression &x);
134
135 /**
136 * Return a symbolic number that represents the logarithm of a value @p x taken with
137 * respect to a @p base number.
138 *
139 * Mimics the function <code> std::%log(x,base) </code> using the standard
140 * math library.
141 */
142 Expression
143 log(const Expression &x, const Expression &base);
144
145 /**
146 * Return a symbolic number that represents the logarithm of a value @p x taken with
147 * respect to a @p base number.
148 *
149 * Mimics the function <code> std::%log(x,base) </code> using the standard
150 * math library.
151 *
152 * This variant is used when the @p base is not a Expression.
153 */
154 template <
155 typename NumberType,
156 typename = std::enable_if_t<!std::is_same_v<NumberType, Expression>>>
157 Expression
158 log(const Expression &x, const NumberType &base)
159 {
160 // Call other implementation
161 return log(x, Expression(base));
162 }
163
164 /**
165 * Return a symbolic number that represents the logarithm of a value @p x taken with
166 * respect to a @p base number.
167 *
168 * Mimics the function <code> std::%log(x,base) </code> using the standard
169 * math library.
170 *
171 * This variant is used when the @p value is not a Expression.
172 */
173 template <
174 typename NumberType,
175 typename = std::enable_if_t<!std::is_same_v<NumberType, Expression>>>
176 Expression
177 log(const NumberType &x, const Expression &base)
178 {
179 // Call other implementation
180 return log(Expression(x), base);
181 }
182
183 /**
184 * Return a symbolic number that represents the base 10 logarithm of a value @p x.
185 *
186 * Mimics the function <code> std::%log10(x) </code> using the standard math
187 * library.
188 */
189 Expression
190 log10(const Expression &x);
191
192 /** @} */
193
194 /**
195 * @name Trigonometric functions
196 */
197 /** @{ */
198
199 /**
200 * Return a symbolic number that represents the sine function with the
201 * given argument @p x.
202 *
203 * Mimics the function <code> std::%sin(x) </code> using the standard math
204 * library.
205 */
206 Expression
207 sin(const Expression &x);
208
209 /**
210 * Return a symbolic number that represents the cosine function with the
211 * given argument @p x.
212 *
213 * Mimics the function <code> std::%cos(x) </code> using the standard math
214 * library.
215 */
216 Expression
217 cos(const Expression &x);
218
219 /**
220 * Return a symbolic number that represents the tangent function with the
221 * given argument @p x.
222 *
223 * Mimics the function <code> std::%tan(x) </code> using the standard math
224 * library.
225 */
226 Expression
227 tan(const Expression &x);
228
229 /**
230 * Return a symbolic number that represents the cosecant function with the
231 * given argument @p x.
232 *
233 * Mimics the function <code> 1.0/std::%sin(x) </code> using the standard
234 * math library.
235 */
236 Expression
237 csc(const Expression &x);
238
239 /**
240 * Return a symbolic number that represents the secant function with the
241 * given argument @p x.
242 *
243 * Mimics the function <code> 1.0/std::%cos(x) </code> using the standard
244 * math library.
245 */
246 Expression
247 sec(const Expression &x);
248
249 /**
250 * Return a symbolic number that represents the cotangent function with the
251 * given argument @p x.
252 *
253 * Mimics the function <code> 1.0/std::%tan(x) </code> using the standard
254 * math library.
255 */
256 Expression
257 cot(const Expression &x);
258
259 /**
260 * Return a symbolic number that represents the inverse sine function with
261 * the
262 * given argument @p x.
263 *
264 * Mimics the function <code> std::%asin(x) </code> using the standard math
265 * library.
266 */
267 Expression
268 asin(const Expression &x);
269
270 /**
271 * Return a symbolic number that represents the inverse cosine function
272 * with the
273 * given argument @p x.
274 *
275 * Mimics the function <code> std::%acos(x) </code> using the standard math
276 * library.
277 */
278 Expression
279 acos(const Expression &x);
280
281 /**
282 * Return a symbolic number that represents the inverse tangent function
283 * with the
284 * given argument @p x.
285 *
286 * Mimics the function <code> std::%atan(x) </code> using the standard math
287 * library.
288 */
289 Expression
290 atan(const Expression &x);
291
292 /**
293 * Return a symbolic number that represents the inverse tangent function
294 * with the
295 * given arguments @p x and @p y.
296 *
297 * Mimics the function <code> std::%atan2(y,x) </code> using the standard
298 * math library.
299 */
300 Expression
301 atan2(const Expression &y, const Expression &x);
302
303 /**
304 * Return a symbolic number that represents the inverse tangent function
305 * with the
306 * given arguments @p x and @p y.
307 *
308 * Mimics the function <code> std::%atan2(y,x) </code> using the standard
309 * math library.
310 *
311 * This variant is used when the numerator @p y is not a Expression.
312 */
313 template <
314 typename NumberType,
315 typename = std::enable_if_t<!std::is_same_v<NumberType, Expression>>>
316 Expression
317 atan2(const NumberType &y, const Expression &x)
318 {
319 // Call other implementation
320 return atan2(Expression(y), x);
321 }
322
323 /**
324 * Return a symbolic number that represents the inverse tangent function
325 * with the
326 * given arguments @p x and @p y.
327 *
328 * Mimics the function <code> std::%atan2(y,x) </code> using the standard
329 * math library.
330 *
331 * This variant is used when the denominator @p x is not a Expression.
332 */
333 template <
334 typename NumberType,
335 typename = std::enable_if_t<!std::is_same_v<NumberType, Expression>>>
336 Expression
337 atan2(const Expression &y, const NumberType &x)
338 {
339 // Call other implementation
340 return atan2(y, Expression(x));
341 }
342
343 /**
344 * Return a symbolic number that represents the inverse cosecant function
345 * with the
346 * given argument @p x.
347 *
348 * Mimics the function <code> 1.0/std::%asin(x) </code> using the standard
349 * math library.
350 */
351 Expression
352 acsc(const Expression &x);
353
354 /**
355 * Return a symbolic number that represents the inverse secant function
356 * with the
357 * given argument @p x.
358 *
359 * Mimics the function <code> 1.0/std::%acos(x) </code> using the standard
360 * math library.
361 */
362 Expression
363 asec(const Expression &x);
364
365 /**
366 * Return a symbolic number that represents the inverse cotangent function
367 * with the
368 * given argument @p x.
369 *
370 * Mimics the function <code> 1.0/std::%atan(x) </code> using the standard
371 * math library.
372 */
373 Expression
374 acot(const Expression &x);
375
376 /** @} */
377
378 /**
379 * @name Hyperbolic trigonometric functions
380 */
381 /** @{ */
382
383 /**
384 * Return a symbolic number that represents the hyperbolic sine function
385 * with the
386 * given argument @p x.
387 *
388 * Mimics the function <code> std::%sinh(x) </code> using the standard math
389 * library.
390 */
391 Expression
392 sinh(const Expression &x);
393
394 /**
395 * Return a symbolic number that represents the hyperbolic cosine function
396 * with the
397 * given argument @p x.
398 *
399 * Mimics the function <code> std::%cosh(x) </code> using the standard math
400 * library.
401 */
402 Expression
403 cosh(const Expression &x);
404
405 /**
406 * Return a symbolic number that represents the hyperbolic tangent function
407 * with the
408 * given argument @p x.
409 *
410 * Mimics the function <code> std::%tanh(x) </code> using the standard math
411 * library.
412 */
413 Expression
414 tanh(const Expression &x);
415
416 /**
417 * Return a symbolic number that represents the hyperbolic cosecant
418 * function with the
419 * given argument @p x.
420 *
421 * Mimics the function <code> 1.0/std::%sinh(x) </code> using the standard
422 * math library.
423 */
424 Expression
425 csch(const Expression &x);
426
427 /**
428 * Return a symbolic number that represents the hyperbolic secant function
429 * with the
430 * given argument @p x.
431 *
432 * Mimics the function <code> 1.0/std::%cosh(x) </code> using the standard
433 * math library.
434 */
435 Expression
436 sech(const Expression &x);
437
438 /**
439 * Return a symbolic number that represents the hyperbolic cotangent
440 * function with the
441 * given argument @p x.
442 *
443 * Mimics the function <code> 1.0/std::%tanh(x) </code> using the standard
444 * math library.
445 */
446 Expression
447 coth(const Expression &x);
448
449 /**
450 * Return a symbolic number that represents the inverse hyperbolic sine
451 * function with the
452 * given argument @p x.
453 *
454 * Mimics the function <code> std::%asinh(x) </code> using the standard math
455 * library.
456 */
457 Expression
458 asinh(const Expression &x);
459
460 /**
461 * Return a symbolic number that represents the inverse hyperbolic cosine
462 * function with the
463 * given argument @p x.
464 *
465 * Mimics the function <code> std::%acosh(x) </code> using the standard math
466 * library.
467 */
468 Expression
469 acosh(const Expression &x);
470
471 /**
472 * Return a symbolic number that represents the inverse hyperbolic tangent
473 * function with the
474 * given argument @p x.
475 *
476 * Mimics the function <code> std::%atanh(x) </code> using the standard math
477 * library.
478 */
479 Expression
480 atanh(const Expression &x);
481
482 /**
483 * Return a symbolic number that represents the inverse hyperbolic cosecant
484 * function with the
485 * given argument @p x.
486 *
487 * Mimics the function <code> 1.0/std::%asin(x) </code> using the standard
488 * math library.
489 */
490 Expression
491 acsch(const Expression &x);
492
493 /**
494 * Return a symbolic number that represents the inverse hyperbolic secant
495 * function with the
496 * given argument @p x.
497 *
498 * Mimics the function <code> 1.0/std::%acos(x) </code> using the standard
499 * math library.
500 */
501 Expression
502 asech(const Expression &x);
503
504 /**
505 * Return a symbolic number that represents the inverse hyperbolic
506 * cotangent function with the
507 * given argument @p x.
508 *
509 * Mimics the function <code> 1.0/std::%atan(x) </code> using the standard
510 * math library.
511 */
512 Expression
513 acoth(const Expression &x);
514
515 /** @} */
516
517 /**
518 * @name Other functions
519 */
520 /** @{ */
521
522 /**
523 * Return a symbolic number that represents the absolute value of value @p x.
524 *
525 * Mimics the function <code> std::%abs(x) </code> using the standard math
526 * library.
527 */
528 Expression
529 abs(const Expression &x);
530
531
532 /**
533 * Return a symbolic number that represents the absolute value of value @p x.
534 *
535 * Mimics the function <code> std::%fabs(x) </code> using the standard math
536 * library.
537 */
538 Expression
539 fabs(const Expression &x);
540
541
542 /**
543 * Return a symbolic number that represents the sign of value @p x.
544 *
545 * Although there is no such function in the standard library, it mimics
546 * the function <code> boost::sign(x) </code> using the
547 * boost math library.
548 */
549 Expression
550 sign(const Expression &x);
551
552
553 /**
554 * Return a symbolic number that represents the @p value of the first
555 * argument that takes the @p sign of the second argument.
556 *
557 * Mimics the function <code> std::%copysign(value, sign) </code> using
558 * the standard math library.
559 */
560 Expression
561 copysign(const Expression &value, const Expression &sign);
562
563
564 /**
565 * Return a symbolic number that represents the floor of value @p x.
566 *
567 * Mimics the function <code> std::%floor(x) </code> using the standard math
568 * library.
569 */
570 Expression
571 floor(const Expression &x);
572
573
574 /**
575 * Return a symbolic number that represents the ceiling of value @p x.
576 *
577 * Mimics the function <code> std::%ceil(x) </code> using the standard math
578 * library.
579 */
580 Expression
581 ceil(const Expression &x);
582
583 /**
584 * Return a symbolic number that represents the maximum of two
585 * values @p a and @p b.
586 *
587 * Mimics the function <code> std::%max(a,b) </code> using the standard math
588 * library.
589 */
590 Expression
591 max(const Expression &a, const Expression &b);
592
593 /**
594 * Return a symbolic number that represents the maximum of two
595 * values @p a and @p b.
596 *
597 * Mimics the function <code> std::%max(a,b) </code> using the standard math
598 * library.
599 *
600 * This variant is used when @p b is not a Expression.
601 */
602 template <
603 typename NumberType,
604 typename = std::enable_if_t<!std::is_same_v<NumberType, Expression>>>
605 Expression
606 max(const Expression &a, const NumberType &b)
607 {
608 // Call other implementation
609 return max(a, Expression(b));
610 }
611
612 /**
613 * Return a symbolic number that represents the maximum of two
614 * values @p a and @p b.
615 *
616 * Mimics the function <code> std::%max(a,b) </code> using the standard math
617 * library.
618 *
619 * This variant is used when @p a is not a Expression.
620 */
621 template <
622 typename NumberType,
623 typename = std::enable_if_t<!std::is_same_v<NumberType, Expression>>>
624 Expression
625 max(const NumberType &a, const Expression &b)
626 {
627 // Call other implementation
628 return max(Expression(a), b);
629 }
630
631 /**
632 * Return a symbolic number that represents the minimum of two
633 * values @p a and @p b.
634 *
635 * Mimics the function <code> std::%min(a,b) </code> using the standard math
636 * library.
637 */
638 Expression
639 min(const Expression &a, const Expression &b);
640
641 /**
642 * Return a symbolic number that represents the minimum of two
643 * values @p a and @p b.
644 *
645 * Mimics the function <code> std::%min(a,b) </code> using the standard math
646 * library.
647 *
648 * This variant is used when @p b is not a Expression.
649 */
650 template <
651 typename NumberType,
652 typename = std::enable_if_t<!std::is_same_v<NumberType, Expression>>>
653 Expression
654 min(const Expression &a, const NumberType &b)
655 {
656 // Call other implementation
657 return min(a, Expression(b));
658 }
659
660 /**
661 * Return a symbolic number that represents the minimum of two
662 * values @p a and @p b.
663 *
664 * Mimics the function <code> std::%min(a,b) </code> using the standard math
665 * library.
666 *
667 * This variant is used when @p a is not a Expression.
668 */
669 template <
670 typename NumberType,
671 typename = std::enable_if_t<!std::is_same_v<NumberType, Expression>>>
672 Expression
673 min(const NumberType &a, const Expression &b)
674 {
675 // Call other implementation
676 return min(Expression(a), b);
677 }
678
679 /**
680 * Return a symbolic number that represents error function with the
681 * given argument @p x.
682 *
683 * Mimics the function <code> std::%erf(x) </code> using the standard math
684 * library.
685 */
686 Expression
687 erf(const Expression &x);
688
689 /**
690 * Return a symbolic number that represents complimentary error function
691 * with the given argument @p x.
692 *
693 * Mimics the function <code> std::%erfc(x) </code> using the standard math
694 * library.
695 */
696 Expression
697 erfc(const Expression &x);
698
699 /** @} */
700
701 } // namespace SD
702 } // namespace Differentiation
703
704 DEAL_II_NAMESPACE_CLOSE
705
706
707 # ifndef DOXYGEN
708
709 // Import math operations into standard namespace.
710 // This gives us the ability to use them within the Tensor class.
711 namespace std
712 {
713 /**
714 * Expose SymEngine wrapper math functions
715 */
716
717 # define DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(func) \
718 using dealii::Differentiation::SD::func;
719
720 # define DEAL_II_EXPOSE_SYMENGINE_BINARY_MATH_FUNCTION(func) \
721 using dealii::Differentiation::SD::func;
722
723 DEAL_II_EXPOSE_SYMENGINE_BINARY_MATH_FUNCTION(pow)
724 DEAL_II_EXPOSE_SYMENGINE_BINARY_MATH_FUNCTION(max)
725 DEAL_II_EXPOSE_SYMENGINE_BINARY_MATH_FUNCTION(min)
726 DEAL_II_EXPOSE_SYMENGINE_BINARY_MATH_FUNCTION(copysign)
727
728 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(exp)
729 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(log10)
730 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(sqrt)
731 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(cbrt)
732 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(erf)
733 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(erfc)
734 // Note: Both unary and binary versions
735 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(log)
736
737 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(abs)
738 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(fabs)
739 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(sign)
740 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(floor)
741 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(ceil)
742
743 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(sin)
744 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(cos)
745 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(tan)
746 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(csc)
747 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(sec)
748 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(cot)
749
750 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(asin)
751 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(acos)
752 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(atan)
753 DEAL_II_EXPOSE_SYMENGINE_BINARY_MATH_FUNCTION(atan2)
754 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(acsc)
755 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(asec)
756 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(acot)
757
758 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(sinh)
759 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(cosh)
760 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(tanh)
761 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(csch)
762 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(sech)
763 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(coth)
764
765 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(asinh)
766 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(acosh)
767 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(atanh)
768 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(acsch)
769 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(asech)
770 DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION(acoth)
771
772 # undef DEAL_II_EXPOSE_SYMENGINE_BINARY_MATH_FUNCTION
773 # undef DEAL_II_EXPOSE_SYMENGINE_UNARY_MATH_FUNCTION
774
775 } // namespace std
776
777 # endif // DOXYGEN
778
779 #else
780
781 // Make sure the scripts that create the C++20 module input files have
782 // something to latch on if the preprocessor #ifdef above would
783 // otherwise lead to an empty content of the file.
784 DEAL_II_NAMESPACE_OPEN
785 DEAL_II_NAMESPACE_CLOSE
786
787 #endif // DEAL_II_WITH_SYMENGINE
788
789 #endif