@c ITEMS IN THIS FILE ARE IN NEED OF EXPANSION, CLARIFICATION, AND EXAMPLES

@menu
* Functions and Variables for Floating Point::  
@end menu

@node Functions and Variables for Floating Point,  , Floating Point, Floating Point
@section Functions and Variables for Floating Point

@c FOLLOWING FUNCTIONS IN bffac.mac ARE NOT DESCRIBED IN .texi FILES: !!!
@c obfac, azetb, vonschtoonk, divrlst, obzeta, bfhzeta, bfpsi0 !!!
@c DON'T KNOW WHICH ONES ARE INTENDED FOR GENERAL USE !!!

@c FOLLOWING FUNCTIONS IN bffac.mac ARE DESCRIBED IN Number.texi: !!!
@c burn, bzeta, bfzeta !!!

@c FOLLOWING FUNCTIONS IN bffac.mac ARE DESCRIBED HERE: !!!
@c bfpsi, bffac, cbffac !!!

@deffn {Function} bffac (@var{expr}, @var{n})
Bigfloat version of the factorial (shifted gamma)
function.  The second argument is how many digits to retain and return,
it's a good idea to request a couple of extra.

@opencatbox
@category{Gamma and factorial functions} @category{Numerical evaluation}
@closecatbox
@end deffn

@defvr {Option variable} algepsilon
Default value: 10^8

@c WHAT IS algepsilon, EXACTLY ??? describe ("algsys") IS NOT VERY INFORMATIVE !!!
@code{algepsilon} is used by @code{algsys}.

@opencatbox
@category{Algebraic equations}
@closecatbox

@end defvr

@deffn {Function} bfloat (@var{expr})
Converts all numbers and functions of numbers in @var{expr} to bigfloat numbers.
The number of significant digits in the resulting bigfloats is specified by the global variable @code{fpprec}.

When @code{float2bf} is @code{false} a warning message is printed when
a floating point number is converted into a bigfloat number (since
this may lead to loss of precision).

@opencatbox
@category{Numerical evaluation}
@closecatbox
@end deffn

@deffn {Function} bfloatp (@var{expr})
Returns @code{true} if @var{expr} is a bigfloat number, otherwise @code{false}.

@opencatbox
@category{Numerical evaluation} @category{Predicate functions}
@closecatbox

@end deffn

@deffn {Function} bfpsi (@var{n}, @var{z}, @var{fpprec})
@deffnx {Function} bfpsi0 (@var{z}, @var{fpprec})
@code{bfpsi} is the polygamma function of real argument @var{z} and integer order @var{n}.
@code{bfpsi0} is the digamma function. 
@code{bfpsi0 (@var{z}, @var{fpprec})} is equivalent to @code{bfpsi (0, @var{z}, @var{fpprec})}.

These functions return bigfloat values.
@var{fpprec} is the bigfloat precision of the return value.

@c psi0(1) = -%gamma IS AN INTERESTING PROPERTY BUT IN THE ABSENCE OF ANY OTHER
@c DISCUSSION OF THE PROPERTIES OF THIS FUNCTION, THIS STATEMENT SEEMS OUT OF PLACE.
@c Note @code{-bfpsi0 (1, fpprec)} provides @code{%gamma} (Euler's constant) as a bigfloat.

@opencatbox
@category{Gamma and factorial functions} @category{Numerical evaluation}
@closecatbox
@end deffn

@defvr {Option variable} bftorat
Default value: @code{false}

@code{bftorat} controls the conversion of bfloats to
rational numbers. 
When @code{bftorat} is @code{false},
@code{ratepsilon} will be used to
control the conversion (this results in relatively small rational
numbers).
When @code{bftorat} is @code{true},
the rational number generated will
accurately represent the bfloat.

@opencatbox
@category{Numerical evaluation}
@closecatbox

@end defvr

@defvr {Option variable} bftrunc
Default value: @code{true}

@code{bftrunc} causes trailing zeroes in non-zero bigfloat
numbers not to be displayed.  Thus, if @code{bftrunc} is @code{false}, @code{bfloat (1)}
displays as @code{1.000000000000000B0}. Otherwise, this is displayed as
@code{1.0B0}.

@opencatbox
@category{Numerical evaluation}
@closecatbox

@end defvr

@deffn {Function} cbffac (@var{z}, @var{fpprec})
Complex bigfloat factorial.

@code{load ("bffac")} loads this function.

@opencatbox
@category{Gamma and factorial functions} @category{Complex variables} @category{Numerical evaluation}
@closecatbox
@end deffn

@deffn {Function} float (@var{expr})
Converts integers, rational numbers and bigfloats in @var{expr}
to floating point numbers.  It is also an @code{evflag}, @code{float} causes
non-integral rational numbers and bigfloat numbers to be converted to
floating point.

@opencatbox
@category{Numerical evaluation} @category{Evaluation flags}
@closecatbox
@end deffn

@defvr {Option variable} float2bf
Default value: @code{false}
 
When @code{float2bf} is @code{false}, a warning message is printed when
a floating point number is converted into a bigfloat number (since
this may lead to loss of precision).

@opencatbox
@category{Numerical evaluation}
@closecatbox

@end defvr

@deffn {Function} floatnump (@var{expr})
Returns @code{true} if @var{expr} is a floating point number, otherwise @code{false}.

@opencatbox
@category{Numerical evaluation} @category{Predicate functions}
@closecatbox

@end deffn

@defvr {Option variable} fpprec
Default value: 16

@code{fpprec} is the number of significant digits for arithmetic on bigfloat numbers.
@code{fpprec} does not affect computations on ordinary floating point numbers.

See also @code{bfloat} and @code{fpprintprec}.

@opencatbox
@category{Numerical evaluation}
@closecatbox

@end defvr

@defvr {Option variable} fpprintprec
Default value: 0

@code{fpprintprec} is the number of digits to print when printing an ordinary float or bigfloat number.

For ordinary floating point numbers,
when @code{fpprintprec} has a value between 2 and 16 (inclusive),
the number of digits printed is equal to @code{fpprintprec}.
Otherwise, @code{fpprintprec} is 0, or greater than 16,
and the number of digits printed is 16.

For bigfloat numbers,
when @code{fpprintprec} has a value between 2 and @code{fpprec} (inclusive),
the number of digits printed is equal to @code{fpprintprec}.
Otherwise, @code{fpprintprec} is 0, or greater than @code{fpprec},
and the number of digits printed is equal to @code{fpprec}.

@code{fpprintprec} cannot be 1.

@opencatbox
@category{Numerical evaluation} @category{Display flags and variables}
@closecatbox

@end defvr

@c -----------------------------------------------------------------------------
@defvr {Option variable} numer_pbranch
Default value: @code{false}

The option variable @code{numer_pbranch} controls the numerical evaluation of 
the power of a negative integer, rational, or floating point number. When
@code{numer_pbranch} is @code{true} and the exponent is a floating point number
or the option variable @code{numer} is @code{true} too, Maxima evaluates
the numerical result using the principal branch. Otherwise a simplified, but not
an evaluated result is returned.

Examples:

@c ===beg===
@c (-2)^0.75;
@c (-2)^0.75,numer_pbranch:true;
@c (-2)^(3/4);
@c (-2)^(3/4),numer;
@c (-2)^(3/4),numer,numer_pbranch:true;
@c ===end===
@example
(%i1) (-2)^0.75;
(%o1) (-2)^0.75

(%i2) (-2)^0.75,numer_pbranch:true;
(%o2) 1.189207115002721*%i-1.189207115002721

(%i3) (-2)^(3/4);
(%o3) (-1)^(3/4)*2^(3/4)

(%i4) (-2)^(3/4),numer;
(%o4) 1.681792830507429*(-1)^0.75

(%i5) (-2)^(3/4),numer,numer_pbranch:true;
(%o5) 1.189207115002721*%i-1.189207115002721
@end example

@opencatbox
@category{Numerical evaluation}
@closecatbox
@end defvr