MathematicalFunctions - Maple Programming Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Mathematics : Special Functions : MathematicalFunctions : Evalf : MathematicalFunctions/Evalf/command

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

Parameters

Description

Examples

Compatibility

Calling Sequence

Evalf(A, <options>)

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 z0, use a Taylor series around z0 to compute the function at z1 where z1 is within the radius of convergence around z0, repeat the process expanding around z1 to compute the function at z2 and so on until reaching the desired evaluation point zfinal. This method works provided that: 1) the evaluation point z is not a singularity of the nth order differential equation underlying the function (see Evalf:-Singularities), and 2) the function, and the first n1 of its derivatives can be computed at some z0 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<z into a problem where 1Z 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 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.

Examples

  

Initialization: Load the package command and set the display of special functions in output to typeset mathematical notation (textbook notation):

withMathematicalFunctions&comma;Evalf&colon;Typesetting:-EnableTypesetRuleTypesetting:-SpecialFunctionRules&colon;

Consider the following confluent HeunC function

HC  HeunC1&comma; 2&comma; 3&comma; 4&comma; 5&comma; 6&semi;

HCHC1&comma;2&comma;3&comma;4&comma;5&comma;6

(1)

You can normally evaluate the function using evalf

evalfHC&semi;

−0.0090830565360.004476814952I

(2)

But how was this evaluation performed? To start with, using Evalf, instead of a black box approach, you have access to information describing the approach used:

EvalfHC

      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

CPU time elapsed during evaluation: .421 seconds

−0.0090830565360.004476814952I

(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 1z 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

Evalf:-SingularitiesHC

0&comma;1

(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

EvalfHC&comma;usetaylor

   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

CPU time elapsed during evaluation: .422 seconds

−0.0090830565350.004476814952I

(5)

EvalfHC&comma;usede

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

CPU time elapsed during evaluation: 1.014 seconds

−0.0090830565400.004476814953I

(6)

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

EvalfHC&comma;withaccuracy

      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

CPU time elapsed during evaluation: 1.467 seconds

−0.0090830565350.004476814952I

(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

EvalfHC&comma;15&comma;truncate=5&comma;time&comma;quiet

CPU time elapsed during evaluation: .484 seconds

−0.00908310.0044768I

(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

F1  %AppellF14.0&comma; 2.0&comma; .3&comma; 2.3&comma; 1.12&comma; 1.1&semi;

F1%AppellF14.0&comma;2.0&comma;0.3&comma;2.3&comma;1.12&comma;1.1

(9)

F1 &equals; valueconvertF1&comma; rational&semi;

%AppellF14.0&comma;2.0&comma;0.3&comma;2.3&comma;1.12&comma;1.1=10000F122,4;2310;15

(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:

evalf

5325.710910=5325.710910

(11)

Compute now showing the strategy used

Evalf

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

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

Evalf&comma;usespecialvalues=false

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

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

CPU time elapsed during evaluation: 0. seconds

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:

Evalf&comma;usespecialvalues=false&comma;allowmapping=false

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

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 z1z11<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

Evalf&comma;usetaylor&comma;time&comma;plot&comma;quiet

CPU time elapsed during evaluation: .46e-1 seconds

5325.710910+1.10−13I=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

Evalf50&comma;usetaylor&comma;R&equals;12&comma;time&comma;plot&comma;zoom=1&comma;12&comma;quiet

CPU time elapsed during evaluation: .312 seconds

5325.710910+1.41024082110−52I=5325.710910

(16)

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

Evalf:-Zoom1.1&comma;115

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

F1  %AppellF11&sol;2&comma; 5&comma; 2&sol;3&comma; 2&comma; 2&comma; 30

F1%AppellF112&comma;5&comma;23&comma;2&comma;2&comma;30

(17)

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

EvalfF1

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

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

CPU time elapsed during evaluation: 1.794 seconds

0.0019747683040.2571152807I

(18)

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

EvalfF1&comma;usede&comma;time&comma;quiet&comma;50

CPU time elapsed during evaluation: 5.023 seconds

0.0019747682010.2571152807I

(19)

Compatibility

• 

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

• 

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

See Also

Add

Appell

AppellF1

AppellF2

AppellF3

AppellF4

Evalb

evalf

Evalf package

GenerateRecurrence

Heun

HeunB

HeunC

HeunD

HeunG

HeunT

hypergeom

MathematicalFunctions

MeijerG

PairwiseSummation

QuadrantNumbers

Singularities

Zoom