digits

Change variable precision used

Syntax

digits(d)

d1 = digits

d1 = digits(d)

Description

digits(d) sets the precision of symbolic computations involving variable-precision arithmetic, such as vpa, to d significant decimal digits. The default is 32 digits.

d1 = digits returns the current precision used by vpa.

d1 = digits(d) sets the new precision d and returns the old precision in d1.

Examples

Increase Precision of Results

By default, MATLAB^® uses 16 digits of precision. For higher precision, use vpa. The default precision for vpa is 32 digits. Increase precision beyond 32 digits by using digits.

Find pi using vpa, which uses the default 32 digits of precision. Confirm that the current precision is 32 by using digits.

pi32 = vpa(pi)

pi32 =
3.1415926535897932384626433832795

currentPrecision = digits

currentPrecision =
    32

Save the current value of digits in digitsOld and set the new precision to 100 digits. Find pi using vpa. The result has 100 digits.

digitsOld = digits(100);
pi100 = vpa(pi)

pi100 =
3.1415926535897932384626433832795028841971693993751058209...
74944592307816406286208998628034825342117068

Note

vpa output is symbolic. To use symbolic output with a MATLAB function that does not accept symbolic values, convert symbolic values to double precision by using double.

Lastly, restore the old value of digits for further calculations.

digits(digitsOld)

For more information, see Increase Precision of Numeric Calculations.

Increase Speed by Decreasing Precision

Increase the speed of MATLAB calculations by using vpa with a lower precision. Set the lower precision by using digits.

First, find the time taken to perform an operation on a large input.

input = 1:0.01:500;
tic
zeta(input);
toc

Elapsed time is 48.968983 seconds.

Now, repeat the operation with a lower precision by using vpa. Lower the precision to 10 digits by using digits. Then, use vpa to reduce the precision of input and perform the same operation. The time taken decreases significantly.

digitsOld = digits(10);
vpaInput = vpa(input);
tic
zeta(vpaInput);
toc

Elapsed time is 31.450342 seconds.

Note

vpa output is symbolic. To use symbolic output with a MATLAB function that does not accept symbolic values, convert symbolic values to double precision by using double.

Lastly, restore the old value of digits for further calculations.

digits(digitsOld)

For more information, see Increase Speed by Reducing Precision.

Guard Digits

The number of digits that you specify using the vpa function or the digits function is the guaranteed number of digits. Internally, the toolbox can use a few more digits than you specify. These additional digits are called guard digits. For example, set the number of digits to 4, and then display the floating-point approximation of 1/3 using four digits:

old = digits(4);
a = vpa(1/3)

a =
0.3333

Now, display a using 20 digits. The result shows that the toolbox internally used more than four digits when computing a. The last digits in the following result are incorrect because of the round-off error:

digits(20)
vpa(a)
digits(old)

ans =
0.33333333333303016843

Hidden Round-Off Errors

Hidden round-off errors can cause unexpected results. For example, compute the number 1/10 with the default 32-digit accuracy and with 10-digit accuracy:

a = vpa(1/10)
old = digits(10);
b = vpa(1/10)
digits(old)

a =
0.1
 
b =
0.1

Now, compute the difference a - b. The result is not 0:

a - b

ans =
0.000000000000000000086736173798840354720600815844403

The difference a - b is not equal to zero because the toolbox internally boosts the 10-digit number b = 0.1 to 32-digit accuracy. This process implies round-off errors. The toolbox actually computes the difference a - b as follows:

b = vpa(b)
a - b

b =
0.09999999999999999991326382620116
 
ans =
0.000000000000000000086736173798840354720600815844403

Techniques Used to Convert Floating-Point Numbers to Symbolic Objects

Suppose you convert a double number to a symbolic object, and then perform VPA operations on that object. The results can depend on the conversion technique that you used to convert a floating-point number to a symbolic object. The sym function lets you choose the conversion technique by specifying the optional second argument, which can be 'r', 'f', 'd', or 'e'. The default is 'r'. For example, convert the constant π = 3.141592653589793... to a symbolic object:

r = sym(pi)
f = sym(pi,'f')
d = sym(pi,'d')
e = sym(pi,'e')

r =
pi
 
f =
884279719003555/281474976710656
 
d =
3.1415926535897931159979634685442
 
e =
pi - (198*eps)/359

Although the toolbox displays these numbers differently on the screen, they are rational approximations of pi. Use vpa to convert these rational approximations of pi back to floating-point values.

Set the number of digits to 4. Three of the four approximations give the same result.

digits(4)
vpa(r)
vpa(f)
vpa(d)
vpa(e)

ans =
3.142
 
ans =
3.142
 
ans =
3.142
 
ans =
3.142 - 0.5515*eps

Now, set the number of digits to 40. The differences between the symbolic approximations of pi become more visible.

digits(40)
vpa(r)
vpa(f)
vpa(d)
vpa(e)

ans =
3.141592653589793238462643383279502884197
 
ans =
3.141592653589793115997963468544185161591
 
ans =
3.1415926535897931159979634685442
 
ans =
3.141592653589793238462643383279502884197 -...
0.5515320334261838440111420612813370473538*eps

Input Arguments

d — New accuracy setting

number | symbolic number

New accuracy setting, specified as a number or symbolic number. The setting specifies the number of significant decimal digits to be used for variable-precision calculations. If the value d is not an integer, digits rounds it to the nearest integer.

Output Arguments

d1 — Current accuracy setting

double-precision number

Current accuracy setting, returned as a double-precision number. The setting specifies the number of significant decimal digits currently used for variable-precision calculations.

Version History

Introduced before R2006a