Evalf command - Maple Help

MathematicalFunctions

 Evalf
 The Evalf command for the numerical evaluation of mathematical expressions, allowing for the use of different numerical methods in the case of Heun and Appell functions

 Calling Sequence Evalf(A, ) with(Evalf)

Parameters

 A - an algebraic expression or one that the map command can handle (relations, sets, lists, Arrays, etc.) allowmapping - (optional) for Appell functions, default = true, to allow or not the otherwise automatic mapping of the numerical evaluation of an Appell function into the evaluation of another Appell function when that seems convenient allowswapping - (optional) for Appell functions, default = true, to allow or not swapping parameters using symmetry properties of the function usede - (optional) synonyms: DE, de, for Appell and Heun functions, to indicate the exclusive use, or the exclusion (usede = false), of the method of numerically integrating the underlying differential equation useformulas - (optional) synonym: formulas, for Appell functions, to indicate the exclusive use, or the exclusion (useformulas = false), of a varied set of formulas that map the numerical evaluation problem into simpler numerical problems useseries - (optional) synonym: series, for Appell and Heun functions, to indicate the exclusive use, or the exclusion (useseries = false), of recurrence formulas to compute a series expansion around the origin when the evaluation point is within the circle of convergence usespecialvalues - (optional) synonym: specialvalues, for Appell functions, to indicate the exclusive use, or the exclusion (usespecialvalues = false), of special values (mapping the problem into simpler problems) to numerically evaluate the function usetaylor - (optional) synonyms: Taylor, taylor, for Appell and Heun functions, to indicate the exclusive use, or the exclusion (usetaylor = false), of a concatenated sequence of Taylor series expansions to numerically evaluate the function Z - (optional) for Heun functions, to use the Z approach to numerically evaluate the confluent HeunC function fdiff - (optional) for Heun functions, to use numerical differentiation to evaluate any of the 5 HeunPrime functions R = ... - (optional) for Appell and Heun functions, to indicate the maximum value of the radius used in each Taylor series when using the approach of a sequence of concatenated Taylor series expansions. remember - (optional) for Appell and Heun functions, default = false, to take advantage of previously cached intermediate results when computing the value of the function truncate = ... - (optional) to truncate the value returned to the indicated number of digits withaccuracy = ... - (optional) experimental, for Appell and Heun functions, to automatically increase the value of Digits in intermediate computations in order to achieve as many accurate digits as the value of Digits plot = ... - (optional) for Appell and Heun functions, to indicate the display of a plot showing the path and centers of the concatenated Taylor series expansions used to numerically evaluate the function zoom = ... - (optional) to zoom within the last plot for concatenated Taylor expansions shown quiet - (optional) for Appell and Heun functions, default = false, to display userinfo information for all the intermediate steps of the numerical evaluation of the function time - (optional) for Appell and Heun functions, default = true, to display the time consumed during the numerical evaluation of a function or expression

Description

 • Evalf is both a command and a package of commands for the numerical evaluation of mathematical expressions and functions, numerical experimentation, and fast development of numerical algorithms, taking advantage of the advanced symbolic capabilities of the Maple computer algebra system. This kind of numerical/symbolic environment is increasingly relevant nowadays, when rather complicated mathematical expressions and advanced special functions, as for instance is the case of the Heun and Appell functions, appear more and more in the modeling of problems in science.
 • The Evalf package is also an excellent helper for understanding how numerical algorithms work, placing some of the typical numerical approaches used in the literature at the tip of your fingers, in a flexible and friendly manner.
 • As a command, Evalf allows, among other things, for the indication of different numerical methods to evaluate the mathematical functions involved in an algebraic expression. In this version, Evalf implements optional arguments only for the 10 Heun and 4 Appell functions. For anything else Evalf works the same as the standard evalf command.
 • The options implemented for numerical evaluation, generally speaking, are divided into four groups:
 – restrictive options;
 – numerical methods options;
 – management options;
 – information options;
 • The restrictive options
 – allowmapping: to allow or not mapping the given function into different perhaps simpler functions to compute its value.
 – allowswapping: to allow or not swapping parameters using symmetry properties of the function in order to map the given problem into one perhaps simpler.
 • The numerical methods options match the most common approaches used in the literature. I.e., most special functions can be evaluated via
 – usespecialvalues: special values in terms of simpler functions that occur for particular values of the given function's parameters.
 – useseries: a power series where the coefficients satisfy a recurrence, i.e. they can be computed in terms of the previous $n$ coefficients (the value of $n$ depends on the function) typically related to the value of the function and some of its derivatives at the origin, that are assumed to be computable. This approach works provided that the evaluation point $z$ is within the radius of convergence around the origin, which is equal to the absolute value of the singularity (closest to the origin) of the differential equation underlying the function.
 – useformulas: either infinite series closed-form formulas defining a function, typically having a restricted radius of convergence, or using mathematical formulas that map the problem outside the radius of convergence into problems that are within the radius of convergence of the defining infinite series.
 – usetaylor: a sequence of concatenated Taylor series expansions, i.e. evaluate the function at some regular point ${z}_{0}$, use a Taylor series around ${z}_{0}$ to compute the function at ${z}_{1}$ where ${z}_{1}$ is within the radius of convergence around ${z}_{0}$, repeat the process expanding around ${z}_{1}$ to compute the function at ${z}_{2}$ and so on until reaching the desired evaluation point ${z}_{\mathrm{final}}$. This method works provided that: 1) the evaluation point $z$ is not a singularity of the $n$th order differential equation underlying the function (see Evalf:-Singularities), and 2) the function, and the first $n-1$ of its derivatives can be computed at some ${z}_{0}$ using one of the other methods.
 – usede: numerically integrating the ODE with appropriate initial conditions, mathematically equal to the given function. This approach works provided that the conditions 1) and 2) mentioned for the usetaylor approach hold.
 – fdiff: valid only for the Heun Prime functions, using numerical differentiation (see fdiff) to evaluate these Heun prime functions performing only evaluation of the corresponding Heun (not prime) ones.
 – Z: special approach, only implemented for the HeunC function, based on a change of variables from $z$ to $Z$, attempting to map a problem where the evaluation point $z$ satisfies $2<\left|z\right|$ into a problem where $1\le \left|Z\right|$ $\le 2$.
 • The management options are
 – R: default value is 95/100, indicates how much of the radius of convergence is actually used when computing using a concatenated Taylor series expansions approach. This option is useful when the function diverges too rapidly as the radius of convergence is approached.
 – remember: default is false, to take advantage of intermediate steps cached when performing other numerical evaluations
 – truncate: default is false, to truncate (chop) the numerical value returned to the indicated number of digits.
 – withaccuracy: default is false, experimental, to automatically and repeatedly increase the value of Digits until achieving at least Digits accurate digits in the returned number.
 • The information options cover:
 – quiet: default is false, to display or not userinfo regarding intermediate steps, relevant when various methods are at work and interrelated;
 – plot: default is true, to visualize in a plot the path used when numerically evaluating with the concatenated Taylor series approach, useful to understand how the value got computed, or what the problems for a computation would be;
 – time: default is true, to display the time consumed during the numerical evaluation, useful to compare the performance of different numerical approaches
 • As usual, to perform a computation with $N$ digits, assign $N$ to the environment variable Digits. Additionally, by indexing Evalf with a positive integer $M$, for instance as in Evalf[50](....) you specify to Evalf that the internal computations only should be performed with $M$ digits, typically $\mathrm{Digits}, while the value returned will continue correspond to the original value of Digits. This is achieved by internally reassigning Digits with the value $M$ resulting in val, then apply evalf(SFloat(val), OriginalValueOfDigits) to the result. This mechanism is particularly useful to verify whether augmenting the value of Digits during internal intermediate steps increases the accuracy - up to the original value of Digits - of the value returned.

Examples

 Initialization: Load the package command and set the display of special functions in output to typeset mathematical notation (textbook notation):
 > $\mathrm{with}\left(\mathrm{MathematicalFunctions},\mathrm{Evalf}\right):\mathrm{Typesetting}:-\mathrm{EnableTypesetRule}\left(\mathrm{Typesetting}:-\mathrm{SpecialFunctionRules}\right):$

Consider the following confluent HeunC function

 >
 ${\mathrm{HC}}{≔}{\mathrm{HC}}{}\left({1}{,}{2}{,}{3}{,}{4}{,}{5}{,}{6}\right)$ (1)

You can normally evaluate the function using evalf

 > $\mathrm{evalf}\left(\mathrm{HC}\right);$
 ${-0.009083056536}{-}{0.004476814952}{}{I}$ (2)

 > $\mathrm{Evalf}\left(\mathrm{HC}\right)$
 HeunCZ and HeunCZPrime at Z = .500000000000-.559016994375*I using a series expansion around Z = 0       HeunCZ and HeunCZPrime at Z = 1.06250000000-.559016994375*I using a series expansion around Z = .500000000000-.559016994375*I       HeunCZ and HeunCZPrime at Z = 1.16204916259-.149352378815*I using a series expansion around Z = 1.06250000000-.559016994375*I       HeunCZ at Z = 1.200000000 using a series expansion around Z = 1.16204916259-.149352378815*I
 ${\mathrm{CPU time elapsed during evaluation: .421 seconds}}$
 ${-0.009083056536}{-}{0.004476814952}{}{I}$ (3)

From this information we see that the Z approach (see the description) was used to first map the original problem at $z=6$ into a problem within the ring $1\le z$ $\le 2$, then a sequence of concatenated taylor series got used departing from the origin, working around the singularity at $z=1$, finally reaching $Z=1.200000000$ and from there getting the value at $z=6$.

In the case of the Heun or Appell functions, the singularities behind the corresponding differential equations, and hence restricting the radius of convergence of power series expansions, can be viewed using the Evalf:-Singularities command

 > $\mathrm{Evalf}:-\mathrm{Singularities}\left(\mathrm{HC}\right)$
 $\left[{0}{,}{1}\right]$ (4)

The same computation can be performed using two other methods: a direct use of concatenated Taylor series expansions, without the Z mapping, and also the numerical integration of the ODE underlying HC

 > $\mathrm{Evalf}\left(\mathrm{HC},\mathrm{usetaylor}\right)$
 HeunC and HeunCPrime at z = .500000000000+.559016994375*I using a series expansion around z = 0    HeunC and HeunCPrime at z = 1.06250000000+.559016994375*I using a series expansion around z = .500000000000+.559016994375*I    HeunC and HeunCPrime at z = 1.48169682661+.511556103224*I using a series expansion around z = 1.06250000000+.559016994375*I    HeunC and HeunCPrime at z = 2.00534123501+.452269799770*I using a series expansion around z = 1.48169682661+.511556103224*I    HeunC and HeunCPrime at z = 2.82688343621+.359255915807*I using a series expansion around z = 2.00534123501+.452269799770*I    HeunC and HeunCPrime at z = 4.15256327699+.202160606573*I using a series expansion around z = 2.82688343621+.359255915807*I    HeunC at z = 6. using a series expansion around z = 4.15256327699+.202160606573*I
 ${\mathrm{CPU time elapsed during evaluation: .422 seconds}}$
 ${-0.009083056535}{-}{0.004476814952}{}{I}$ (5)
 > $\mathrm{Evalf}\left(\mathrm{HC},\mathrm{usede}\right)$
 C using dsolve/numeric approach for 1 <= abs(z). -> computing initial conditions for C and CPrime at z = .1    HeunC at z = .1 using a series expansion around z = 0    HeunCPrime at z = .1 using a series expansion around z = 0 -> computing an extra step at z = 1.+.2*I
 ${\mathrm{CPU time elapsed during evaluation: 1.014 seconds}}$
 ${-0.009083056540}{-}{0.004476814953}{}{I}$ (6)

The discrepancy in the last two digits of the real and imaginary parts can be resolved using the (experimental) withaccuracy option

 > $\mathrm{Evalf}\left(\mathrm{HC},\mathrm{withaccuracy}\right)$
 HeunCZ and HeunCZPrime at Z = .500000000000-.559016994375*I using a series expansion around Z = 0       HeunCZ and HeunCZPrime at Z = 1.06250000000-.559016994375*I using a series expansion around Z = .500000000000-.559016994375*I       HeunCZ and HeunCZPrime at Z = 1.16204916259-.149352378815*I using a series expansion around Z = 1.06250000000-.559016994375*I       HeunCZ at Z = 1.200000000 using a series expansion around Z = 1.16204916259-.149352378815*I             HeunCZ and HeunCZPrime at Z = .50000000000000000-.55901699437494740*I using a series expansion around Z = 0             HeunCZ and HeunCZPrime at Z = 1.0625000000000000-.55901699437494740*I using a series expansion around Z = .50000000000000000-.55901699437494740*I             HeunCZ and HeunCZPrime at Z = 1.1620491625867589-.14935237881501522*I using a series expansion around Z = 1.0625000000000000-.55901699437494740*I             HeunCZ at Z = 1.200000000 using a series expansion around Z = 1.1620491625867589-.14935237881501522*I -> Testing accuracy of 10 digits for HeunCZ at Z = 1.200000000 around Z = 1.162049163-.1493523788*I and Z = 1.200000000 using Digits = 15          HeunCZ at Z = 1.16204916259-.149352378815*I using a series expansion around Z = 1.06250000000-.559016994375*I             HeunCZ at Z = 1.06250000000-.559016994375*I using a series expansion around Z = .500000000000-.559016994375*I                   HeunCZ and HeunCZPrime at Z = .499999999999973874825-.559016994374970791168*I using a series expansion around Z = 0                   HeunCZ at Z = .500000000000-.559016994375*I using a series expansion around Z = .499999999999973874825-.559016994374970791168*I                   HeunCZ and HeunCZPrime at Z = .272727272727272727250-.408180805829884514696*I using a series expansion around Z = 0                   HeunCZ and HeunCZPrime at Z = .449885452775968702046-.541443395498165954360*I using a series expansion around Z = .272727272727272727250-.408180805829884514696*I                   HeunCZPrime at Z = .500000000000-.559016994375*I using a series expansion around Z = .449885452775968702046-.541443395498165954360*I             HeunCZPrime at Z = 1.06250000000-.559016994375*I using a series expansion around Z = .500000000000-.559016994375*I          HeunCZPrime at Z = 1.16204916259-.149352378815*I using a series expansion around Z = 1.06250000000-.559016994375*I <- Reached required accuracy of 10 digits for HeunCZ using Digits = 15
 ${\mathrm{CPU time elapsed during evaluation: 1.467 seconds}}$
 ${-0.009083056535}{-}{0.004476814952}{}{I}$ (7)

This result also shows that the value achieved by default, at the beginning, with evalf and Digits = 10 has the last digit of the real part inaccurate, it should be 5, not 6, and it also indicates that to achieve this more accurate result it suffices to perform the intermediate computations at Digits = 15.

Note that when computing withaccuracy, the intermediate computations were performed at Digits = 15 but the value returned has the number of decimals expected when computing at Digits = 10. With Evalf you can handle these two things independently. For example: compute this same result performing all intermediate computations with Digits = 15 but truncate (chop) the result as if the computation was performed with Digits = 5, show the time taken by the computation and do not display any other information

 > $\mathrm{Evalf}\left(\mathrm{HC},15,\mathrm{truncate}=5,\mathrm{time},\mathrm{quiet}\right)$
 ${\mathrm{CPU time elapsed during evaluation: .484 seconds}}$
 ${-0.0090831}{-}{0.0044768}{}{I}$ (8)

Evalf can evaluate expressions in general, not just single function calls. Any optional arguments apply when Heun or Appell functions are present in the expression. Consider for instance one of the special values of AppellF1, a case where the function can be represented by a 2F1 hypergeometric function

 >
 ${\mathrm{F1}}{≔}{\mathrm{%AppellF1}}{}\left({4.0}{,}{2.0}{,}{0.3}{,}{2.3}{,}{1.12}{,}{1.1}\right)$ (9)
 >
 ${\mathrm{%AppellF1}}{}\left({4.0}{,}{2.0}{,}{0.3}{,}{2.3}{,}{1.12}{,}{1.1}\right){=}{10000}{}{}_{{2}}{F}_{{1}}{}\left({2}{,}{4}{;}\frac{{23}}{{10}}{;}{-}\frac{{1}}{{5}}\right)$ (10)

The left-hand side is AppellF1 in inert form, to avoid the automatic representation in terms of 2F1 functions, while the right-hand side involves only a hypergeometric 2F1 function:

 > $\mathrm{evalf}\left(\right)$
 ${5325.710910}{=}{5325.710910}$ (11)

Compute now showing the strategy used

 > $\mathrm{Evalf}\left(\right)$
 -> Numerical evaluation of AppellF1(4.0, 2.0, .3, 2.3, 1.12, 1.1)    -> AppellF1, checking singular cases    -> AppellF1, trying special values Hypergeometric: case: c = b1 + b2    <- special values of AppellF1 successful
 ${\mathrm{CPU time elapsed during evaluation: .16e-1 seconds}}$
 ${5325.710910}{=}{5325.710910}$ (12)

So the special value of hypergeometric form was identified and used. Compute this equation without using the special values information of AppellF1

 > $\mathrm{Evalf}\left(,\mathrm{usespecialvalues}=\mathrm{false}\right)$
 -> Numerical evaluation of AppellF1(4.0, 2.0, .3, 2.3, 1.12, 1.1)    -> AppellF1, checking singular cases    -> AppellF1, trying formulas       case AKF page 36, after (13), maps into AppellF3 with abs(z2/(z2-1)) < 1          case: abs(z1) > 1, abs(z2) > 1 and 1.1 <= abs(z1) < abs(z2); swapping parameters and z1 <-> z2          -> Numerical evaluation of AppellF3(-1.7, 2.0, .3, 4.0, 2.3, 11.00000000, 1.12)             -> AppellF3, checking singular cases             -> AppellF3, trying special values             -> AppellF3, trying formulas
 ${\mathrm{CPU time elapsed during evaluation: 0. seconds}}$
 case AKF page 35, (9), maps into AppellF2 with abs(1 - z1/z2) < 1          case: abs(z1) < 1, abs(z2) > 1; swapping parameters and z1 <-> z2          -> Numerical evaluation of AppellF2(2.3, 4.0, .3, 2.3, 2.3, 1.12, -.18181818e-1)             -> AppellF2, checking singular cases             -> AppellF2, trying special values Hypergeometric: case: c1 = a, c2 = a and z1 <> 1 and z2 <> 1             <- special values of AppellF2 successful
 ${\mathrm{CPU time elapsed during evaluation: 0. seconds}}$
 ${\mathrm{CPU time elapsed during evaluation: .31e-1 seconds}}$
 ${5325.710904}{=}{5325.710910}$ (13)

In the information above we see that first a mapping into AppellF3 was attempted, it did not succeed, then a mapping into AppellF2 was attempted and that resulted in the correct value.

Compute the same problem without mapping into other functions:

 > $\mathrm{Evalf}\left(,\mathrm{usespecialvalues}=\mathrm{false},\mathrm{allowmapping}=\mathrm{false}\right)$
 -> Numerical evaluation of AppellF1(4.0, 2.0, .3, 2.3, 1.12, 1.1)    -> AppellF1, checking singular cases    -> AppellF1, trying formulas       case z1 <> 0 and z1 <> 1 and abs(z1/(z1-1)) < 1; swapping parameters and recursing          case AKF page 30, (5.5), abs(z1) > 1, abs(z2) > 1, and abs((z2-z1)/(z2-1)) <= 1; using identity mapping into F*AppellF1(..., z1, (z2-z1)/(z2-1))             -> Numerical evaluation of AppellF1(-1.7, 0., 2.0, 2.3, 1.1, .1666666667)                -> AppellF1, checking singular cases                -> AppellF1, trying special values                <- special values of AppellF1 successful
 ${\mathrm{CPU time elapsed during evaluation: 0. seconds}}$
 ${5325.710909}{=}{5325.710910}$ (14)

We see now that there was still another formula that could be used, it is a transformation of Euler-type mapping AppellF1 into an equivalent form of AppellF1 that has the advantage of having as evaluation point $\left|\frac{\mathrm{z1}}{\mathrm{z1}-1}\right|<1$ so after swapping parameters the function got evaluated again as expected. The same problem using a sequence of concatenated Taylor expansions, avoid displaying extra information, just the time consumed and a plot showing the path used and expansion points

 > $\mathrm{Evalf}\left(,\mathrm{usetaylor},\mathrm{time},\mathrm{plot},\mathrm{quiet}\right)$
 ${\mathrm{CPU time elapsed during evaluation: .46e-1 seconds}}$
 ${5325.710910}{+}{1.}{}{{10}}^{{-13}}{}{I}{=}{5325.710910}$ (15)

In this Taylor approach, each expansion around a point is used to reach up to 95/100 of the radius of convergence before starting another expansion. Reduce that to 1/2, compute internally at Digits = 50 (but return as if computing with Digits = 10) and zoom the plot around $z=1$ extending 1/2 to either side of $z=1$

 > $\mathrm{Evalf}\left[50\right]\left(,\mathrm{usetaylor},R=\frac{1}{2},\mathrm{time},\mathrm{plot},\mathrm{zoom}=\left[1,\frac{1}{2}\right],\mathrm{quiet}\right)$
 ${\mathrm{CPU time elapsed during evaluation: .312 seconds}}$
 ${5325.710910}{+}{1.410240821}{}{{10}}^{{-52}}{}{I}{=}{5325.710910}$ (16)

Use the Evalf:-Zoom command to zoom closer to the point $z=1.1$

 > $\mathrm{Evalf}:-\mathrm{Zoom}\left(\left[1.1,\frac{1}{15}\right]\right)$

Consider finally an Appell problem where the evaluation point is on the branch cut of the function and there is a singularity in between that point and the origin

 >
 ${\mathrm{F1}}{≔}{\mathrm{%AppellF1}}{}\left(\frac{{1}}{{2}}{,}{5}{,}\frac{{2}}{{3}}{,}{2}{,}{2}{,}{30}\right)$ (17)

As the information below shows, this function is evaluated by mapping the AppellF1 function into AppellF3:

 > $\mathrm{Evalf}\left(\mathrm{F1}\right)$
 case: abs(z1) > 1, abs(z2) > 1 and 1.1 <= abs(z1) < abs(z2); swapping parameters and z1 <-> z2 -> Numerical evaluation of AppellF1(.5000000000, .6666666667, 5., 2., 30., 2.)    -> AppellF1, checking singular cases    -> AppellF1, trying special values    -> AppellF1, trying formulas       case AKF page 36, after (13), maps into AppellF3 with abs(z2/(z2-1)) < 1          case: abs(z1) > 1, abs(z2) > 1 and 1.1 <= abs(z1) < abs(z2); swapping parameters and z1 <-> z2          -> Numerical evaluation of AppellF3(.5000000000, 1.500000000, .6666666667, 5., 2., 30., 2.000000000)             -> AppellF3, checking singular cases             -> AppellF3, trying special values             -> AppellF3, trying formulas
 ${\mathrm{CPU time elapsed during evaluation: 0. seconds}}$
 -> AppellF1, trying the numerical integration of the related ODE       -> computing initial conditions: all of AppellF1, AppellF1' and AppellF1'' at z2 = .6412500000-.4750000000*I          -> Numerical evaluation of AppellF1(.5000000000, .6666666667, 5., 2., 30., .6412500000-.4750000000*I)             -> AppellF1, checking singular cases             -> AppellF1, trying special values             -> AppellF1, trying series based on recurrence          -> Numerical evaluation of AppellF1(1.5000000000, .6666666667, 6., 3., 30., .6412500000-.4750000000*I)             -> AppellF1, checking singular cases             -> AppellF1, trying special values             -> AppellF1, trying series based on recurrence          -> Numerical evaluation of AppellF1(2.5000000000, .6666666667, 7., 4., 30., .6412500000-.4750000000*I)             -> AppellF1, checking singular cases             -> AppellF1, trying special values             -> AppellF1, trying series based on recurrence
 ${\mathrm{CPU time elapsed during evaluation: 1.794 seconds}}$
 ${0.001974768304}{-}{0.2571152807}{}{I}$ (18)

It can also be computed by numerically integrating the corresponding differential equation, requesting the internal use of a higher value of Digits = 50

 > $\mathrm{Evalf}\left(\mathrm{F1},\mathrm{usede},\mathrm{time},\mathrm{quiet},50\right)$
 ${\mathrm{CPU time elapsed during evaluation: 5.023 seconds}}$
 ${0.001974768201}{-}{0.2571152807}{}{I}$ (19)

Compatibility

 • The MathematicalFunctions[Evalf] command was introduced in Maple 2017.