# `float`

Convert to a floating-point number

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.

## Syntax

```float(`object`)
float(`object`, `n`)
```

## Description

`float(object)` converts the object or numerical subexpressions of the object to floating-point numbers.

`float` converts numbers and numerical expressions such as `sqrt(sin(2))` or `sqrt(3) + sin(PI/17)*I` to real or complex floating-point numbers of type `DOM_FLOAT` or `DOM_COMPLEX`, respectively. If symbolic objects other than the special constants CATALAN, E, EULER, and PI are present, only numerical subexpressions are converted to floats. In particular, identifiers and indexed identifiers are returned unchanged by `float`. Cf. Example 1.

A `float` call is mapped recursively to the operands of an expression. When numbers (or constants such as PI) are found, they are converted to floating-point approximations. The number of significant decimal digits is given by the environment variable `DIGITS`; the default value is 10. The converted operands are combined by arithmetical operations or function calls according to the structure of the expression. E.g., a call such as `float(PI - 314/100)` may be regarded as a sequence of numerical operations:

``` t1 := float(PI); t2 := float(314/100); result := t1 - t2 ```
Consequently, float evaluation via `float` may be subject to error propagation. Cf. Example 2.

The second argument `n` in ```float(object, n)``` temporarily overwrites the current setting for `DIGITS`. See Example 3.

`float` is automatically mapped to the elements of sets and lists. However, it is not automatically mapped to the entries of arrays, hfarrays, tables, and operands of function calls. Use ```map(object, float)``` for a fast floating-point conversion of all entries of an array or a table. Use `mapcoeffs(p, float)` to convert the coefficients of a polynomial `p` of type `DOM_POLY`. To control the behavior of `float` on a function call, use a function environment providing a `"float"` slot. Cf. Example 4 and Example 5.

The preferences `Pref::floatFormat` and `Pref::trailingZeroes` can be used to modify the screen output of floating-point numbers.

Rational approximations of floating-point numbers may be computed by the function `numeric::rationalize`.

MuPAD® special functions such as `sin`, `exp`, `besselJ` etc. are implemented as function environments. Via overloading, the `"float"` attribute (slot) of a function environment `f`, say, is called for the float evaluation of symbolic calls `f(x1, x2, ...)` contained in an expression.

The user may extend the functionality of the system function `float` to his own functions. For this, the function `f` to be processed must be declared as a function environment via `funcenv`. A `"float"` attribute must be written, which is called by the system function `float` in the form `f::float(x1, x2, ...)` whenever a symbolic call `f(x1, x2, ...)` inside an expression is found. The arguments passed to `f::float` are not converted to floats, neither is the return value of the slot subject to any further float evaluation. Thus, the float conversion of symbolic functions calls of `f` is entirely determined by the slot routine. Cf. Example 5.

Also a domain `d`, say, written in the MuPAD language, can overload `float` to define the float evaluation of its elements. A slot `d::float` must be implemented. If an element `x`, say, of this domain is subject to a float evaluation, the slot is called in the form `d::float(x)`. As for function environments, neither `x` nor the return value of the slot are subject to any further float evaluation.

If a domain does not have a `"float"` slot, the system function `float` returns its elements unchanged.

Note that MuPAD floating-point numbers are restricted in size. On 32 bit architectures, an overflow/underflow occurs if numbers of absolute size larger/smaller than about are encountered. On 64 bit architectures, the limits are about .

See the documentation for `DIGITS` for further information.

## Environment Interactions

The function is sensitive to the environment variable `DIGITS` which determines the numerical working precision.

## Examples

### Example 1

We convert some numbers and numerical expressions to floats:

`float(17), float(PI/7 + I/4), float(4^(1/3) + sin(7))`
` `

`float` is sensitive to `DIGITS`:

```DIGITS := 20: float(17), float(PI/7 + I/4), float(4^(1/3) + sin(7))```
` `

Symbolic objects such as identifiers are returned unchanged:

`DIGITS := 10: float(2*x + sin(3))`
` `

### Example 2

We illustrate error propagation in numerical computations. The following rational number approximates `exp(2)` to 17 decimal digits:

`r := 738905609893065023/100000000000000000:`

The following `float` call converts `exp(2)` and `r` to floating-point approximations. The approximation errors propagate and are amplified in the following numerical expression:

`DIGITS := 10: float(10^20*(r - exp(2)))`
` `

None of the digits in this result is correct! To obtain a better result, use the second argument in `float` to increase the number of digits for this particular function call:

`float(10^20*(r - exp(2)), 20)`
` `

For further calculations, free the variable `r`:

`delete r:`

### Example 3

The second argument in `float` lets you temporarily overwrite the current setting for the number of significant decimal digits. For example, compute the following expression with 10 and 30 significant decimal digits. To display floating-point numbers with the number of digits that MuPAD used to compute them, set the value of `Pref::outputDigits` to `InternalPrecision`:

`Pref::outputDigits(InternalPrecision):`

Compute the following expression with the default value of ```DIGITS = 10```:

```x := 10^8: float(sqrt(x^2 + 1) - x)```
` `

Compute the same expression with 30 significant decimal digits:

`float(sqrt(x^2 + 1) - x, 30)`
` `

After evaluating `float`, MuPAD restores the value of `DIGITS`:

`DIGITS`
` `

For further calculations, restore the output precision and free the variable `x`:

```Pref::outputDigits(UseDigits): delete x```

### Example 4

`float` is mapped to the elements of sets and lists:

`float([PI, 1/7, [1/4, 2], {sin(1), 7/2}])`
` `

For tables and arrays, the function `map` must be used to forward `float` to the entries:

```T := table("a" = 4/3, 3 = PI): float(T), map(T, float)```
` `
```A := array(1..2, [1/7, PI]): float(A), map(A, float)```
` `

Matrix domains overload the function `float`. In contrast to arrays, `float` works directly on a matrix:

`float(matrix(A))`
` `

Use `mapcoeffs` to apply `float` to the coefficients of a polynomial generated by `poly`:

`p := poly(9/4*x^2 + PI, [x]): float(p), mapcoeffs(p, float)`
` `
`delete A, T, p:`

### Example 5

We demonstrate overloading of `float` by a function environment. The following function `Sin` is to represent the sine function. In contrast to the `sin` function in MuPAD, `Sin` measures its argument in degrees rather than in radians (i.e., `Sin(x)` = `sin(PI/180*x)`). The only functionality of `Sin` is to produce floating point values if the argument is a real float. For all other kinds of arguments, a symbolic function call is to be returned:

```Sin := proc(x) begin if domtype(x) = DOM_FLOAT then return(Sin::float(x)); else return(procname(args())) end_if; end_proc:```

The function is turned into a function environment via `funcenv`:

`Sin := funcenv(Sin):`

Finally, the `"float"` attribute is implemented. If the argument can be converted to a real floating-point number, a floating-point result is produced. In all other cases, a symbolic call of `Sin` is returned:

```Sin::float := proc(x) begin x := float(x): if domtype(x) = DOM_FLOAT then return(float(sin(PI/180*x))); else return(Sin(x)) end_if; end_proc:```

Now, float evaluation of arbitrary expressions involving `Sin` is possible:

`Sin(x), Sin(x + 0.3), Sin(120)`
` `
`Sin(120.0), float(Sin(120)), float(Sin(x + 120))`
` `
`float(sqrt(2) + Sin(120 + sqrt(3)))`
` `
`delete Sin:`

## Parameters

 `object` Any MuPAD object `n` An integer greater than 1

## Return Values

Floating point number of type `DOM_FLOAT` or `DOM_COMPLEX`, or the input object with exact numbers replaced by floating-point numbers.

`object`