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}<M$, 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.

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}\&comma;\mathrm{Evalf}\right)\&colon;\mathrm{Typesetting}:-\mathrm{EnableTypesetRule}\left(\mathrm{Typesetting}:-\mathrm{SpecialFunctionRules}\right)\&colon;$

$\mathrm{HC} ≔ \mathrm{HeunC}\left(1\&comma; 2\&comma; 3\&comma; 4\&comma; 5\&comma; 6\right)\&semi;$

$\mathrm{HC}≔\mathrm{HC}\left(1\&comma;2\&comma;3\&comma;4\&comma;5\&comma;6\right)$

$\mathrm{evalf}\left(\mathrm{HC}\right)\&semi;$

$\mathrm{-0.009083056536}-0.004476814952\mathrm{I}$

$\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}$

$\mathrm{-0.009083056536}-0.004476814952\mathrm{I}$

$\mathrm{Evalf}:-\mathrm{Singularities}\left(\mathrm{HC}\right)$

$\left[0\&comma;1\right]$

$\mathrm{Evalf}\left(\mathrm{HC}\&comma;\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}$

$\mathrm{-0.009083056535}-0.004476814952\mathrm{I}$

$\mathrm{Evalf}\left(\mathrm{HC}\&comma;\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}$

$\mathrm{-0.009083056540}-0.004476814953\mathrm{I}$

$\mathrm{Evalf}\left(\mathrm{HC}\&comma;\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}$

$\mathrm{-0.009083056535}-0.004476814952\mathrm{I}$

$\mathrm{Evalf}\left(\mathrm{HC}\&comma;15\&comma;\mathrm{truncate}=5\&comma;\mathrm{time}\&comma;\mathrm{quiet}\right)$

$\mathrm{CPU\; time\; elapsed\; during\; evaluation:\; .484\; seconds}$

$\mathrm{-0.0090831}-0.0044768\mathrm{I}$

$\mathrm{F1} ≔ \mathrm{\%AppellF1}\left(4.0\&comma; 2.0\&comma; .3\&comma; 2.3\&comma; 1.12\&comma; 1.1\right)\&semi;$

$\mathrm{F1}≔F_1\left(4.0\&comma;2.0\&comma;0.3\&comma;2.3\&comma;1.12\&comma;1.1\right)$

$\mathrm{F1} \&equals; \mathrm{value}\left(\mathrm{convert}\left(\mathrm{F1}\&comma; \mathrm{rational}\right)\right)\&semi;$

$F_1\left(4.0\&comma;2.0\&comma;0.3\&comma;2.3\&comma;1.12\&comma;1.1\right)=10000{}_{2}F_1\left(2,4;\frac{23}{10};-\frac{1}{5}\right)$

$\mathrm{evalf}\left(\right)$

$5325.710910=5325.710910$

$\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$

$\mathrm{Evalf}\left(\&comma;\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$

$\mathrm{Evalf}\left(\&comma;\mathrm{usespecialvalues}=\mathrm{false}\&comma;\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$

$\mathrm{Evalf}\left(\&comma;\mathrm{usetaylor}\&comma;\mathrm{time}\&comma;\mathrm{plot}\&comma;\mathrm{quiet}\right)$

$\mathrm{CPU\; time\; elapsed\; during\; evaluation:\; .46e-1\; seconds}$

$5325.710910+1.{10}^{\mathrm{-13}}\mathrm{I}=5325.710910$

$\mathrm{Evalf}\left[50\right]\left(\&comma;\mathrm{usetaylor}\&comma;R\&equals;\frac{1}{2}\&comma;\mathrm{time}\&comma;\mathrm{plot}\&comma;\mathrm{zoom}=\left[1\&comma;\frac{1}{2}\right]\&comma;\mathrm{quiet}\right)$

$\mathrm{CPU\; time\; elapsed\; during\; evaluation:\; .312\; seconds}$

$5325.710910+1.410240821{10}^{\mathrm{-52}}\mathrm{I}=5325.710910$

$\mathrm{Evalf}:-\mathrm{Zoom}\left(\left[1.1\&comma;\frac{1}{15}\right]\right)$

$\mathrm{F1} ≔ \mathrm{\%AppellF1}\left(1\&sol;2\&comma; 5\&comma; 2\&sol;3\&comma; 2\&comma; 2\&comma; 30\right)$

$\mathrm{F1}≔F_1\left(\frac{1}{2}\&comma;5\&comma;\frac{2}{3}\&comma;2\&comma;2\&comma;30\right)$

$\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\mathrm{I}$

$\mathrm{Evalf}\left(\mathrm{F1}\&comma;\mathrm{usede}\&comma;\mathrm{time}\&comma;\mathrm{quiet}\&comma;50\right)$

$\mathrm{CPU\; time\; elapsed\; during\; evaluation:\; 5.023\; seconds}$

$0.001974768201-0.2571152807\mathrm{I}$

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

For more information on Maple 2017 changes, see Updates in Maple 2017.