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 d1 and set the new precision to 70 digits. Find pi using vpa. The result has 70 digits.

d1 = digits(70);
pi100 = vpa(pi)

pi100 = $$3.141592653589793238462643383279502884197169399375105820974944592307816$$

Note that vpa returns a symbolic output. 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(d1)

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 19.679741 seconds.

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

d1 = digits(8);
vpaInput = vpa(input);
tic
zeta(vpaInput);
toc

Elapsed time is 11.104991 seconds.

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

digits(d1)

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.

d1 = 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.

d2 = digits(20);
vpa(a)

ans = $$0.33333333333303016843$$

Restore the old value of digits for further calculations.

digits(d1)

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)

a = $$0.1$$

d1 = digits(10);
b = vpa(1/10)

b = $$0.1$$

digits(d1)

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

c = a - b

c = $$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)

b = $$0.09999999999999999991326382620116$$

c = a - b

c = $$0.000000000000000000086736173798840354720600815844403$$

Techniques Used to Convert Floating-Point Numbers to Symbolic Objects

Suppose you convert a double number to a symbolic object, and then apply the vpa function on that object. The result 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 $\pi =3.141592653589793...$ to a symbolic object.

r = sym(pi)

r = $$\pi$$

f = sym(pi,"f")

f = 
$$\frac{884279719003555}{281474976710656}$$

d = sym(pi,"d")

d = $$3.1415926535897931159979634685442$$

e = sym(pi,"e")

e = 
$$\pi -\frac{198\hspace{0.17em}\mathrm{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.

d1 = digits(4);
rvpa = vpa(r)

rvpa = $$3.142$$

fvpa = vpa(f)

fvpa = $$3.142$$

dvpa = vpa(d)

dvpa = $$3.142$$

evpa = vpa(e)

evpa = $$3.142-0.5515\hspace{0.17em}\mathrm{eps}$$

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

d2 = digits(40);
rvpa = vpa(r)

rvpa = $$3.141592653589793238462643383279502884197$$

fvpa = vpa(f)

fvpa = $$3.141592653589793115997963468544185161591$$

dvpa = vpa(d)

dvpa = $$3.1415926535897931159979634685442$$

evpa = vpa(e)

evpa = $$3.141592653589793238462643383279502884197-0.5515320334261838440111420612813370473538\hspace{0.17em}\mathrm{eps}$$

Restore the old value of digits for further calculations.

digits(d1)

Input Arguments

d — New accuracy setting

positive integer scalar

New accuracy setting, specified as a positive integer scalar. The setting specifies the number of significant decimal digits to be used for variable-precision calculations. d must be greater than 1 and less than $${10}^8+1$$. 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