The Math Libraries |
3
|
 |
Some information can also be obtained from the man page Intro(3).
This chapter has the following organization:
Standard Math Library
The libm math library contains the functions required by the various standards to which the Solaris operating system conforms. This library is bundled with the Solaris operating system in two forms: libm.a, the static version, and libm.so, the shared version.
| 1
On Solaris systems, this function is provided in the C library libc.
|
Note that the functions gamma_r and lgamma_r are reentrant versions of gamma and lgamma.
Additional Math Libraries
Sun Math Library
The library libsunmath is part of the libraries supplied with all Sun language products. The library libsunmath contains a set of functions that were incorporated in previous versions of libm from Sun.
Optimized Libraries
Optimized versions of some of the routines in libm are provided in the library libmopt. On SPARC and Intel systems, optimized versions of some of the support routines in libc are provided in the library libcopt. Finally, on SPARC and PowerPC systems, alternate forms of some libc support routines are provided in libcx.
The routines contained in libmopt replace corresponding routines in libm. The libmopt versions are generally noticeably faster. Note that unlike the libm versions, which can be configured to provide any of ANSI/POSIX, SVID, X/Open, or IEEE-style treatment of exceptional cases, the libmopt routines only support IEEE-style handling of these cases. (See Appendix F, "Standards Compliance.") To see which libm routines have counterparts in libmopt, use the nm command to search for all global symbols defined in libmopt.a.
Both libmopt and libcopt may be linked with a program by specifying the
-xlibmopt flag at link time. Note that the SunOS 5.x C compiler, however, does not accept the -xlibmopt flag. To use both libmopt and libcopt with the Solaris 2.x C compiler, link with both -lmopt and -lcopt.-nocx flag is used, but the C compiler does not automatically link with libcx. To use libcx with C programs, link with -lcx. (Note: A shared version of libcx, called libcx.so.1, is also provided. This version can be preloaded at run time by setting the environment variable LD_PRELOAD to the full path name of the libcx.so.1 file.) Vector Math Library (SPARC only)
On SPARC systems running the Solaris 2.x operating environment, the library libmvec provides routines that evaluate common mathematical functions for an entire vector of arguments.
Note that libmvec_mt.a provides parallel versions of the vector functions that rely on multiprocessor parallelization. To use libmvec_mt.a, you must have an Sun WorkShop license and link with
-xparallel.
Single, Double, and Long Double Precision
Most numerical functions are available in single, double, and long-double precision. Examples of calling different precision versions from different languages are shown in Table 3-4.
In C, names of single-precision functions are formed by appending f to the double-precision name, and names of quadruple-precision functions are formed by adding l. Because FORTRAN calling conventions differ, libsunmath provides r_..., d_..., and q_... versions for single, double, and quadruple precision functions, respectively. FORTRAN intrinsic functions can be called by the generic name for all three precisions.
Note - The Intel version of FORTRAN supports real and double precision only; it does not support REAL*16. The Intel version of C, however, supports long double.
IEEE Support Functions
This section describes the IEEE recommended functions, the functions that supply useful values, ieee_flags, ieee_retrospective, and standard_arithmetic and nonstandard_arithmetic. Refer to Chapter 4, "Exceptions and Exception Handling," for more information on the functions ieee_flags and ieee_handler.
ieee_functions(3m) and ieee_sun(3m)
The functions described by ieee_functions(3m) and ieee_sun(3m) provide capabilities either required by the IEEE standard or recommended in its appendix. These are implemented as efficient bit mask operations.
|
IEEE Function |
Single Precision |
Double Precision |
Quadruple Precision |
|
signbit(x) |
i=ir_signbit(x) |
i=id_signbit(x) |
i=iq_signbit(x) |
Note - You must declare d_function as double precision and q_function as REAL*16 in the FORTRAN program that uses them.
ieee_values(3m)
IEEE values like infinity, NaN, maximum and minimum positive floating-point numbers are provided by the functions described by the ieee_values(3m) man page. Table 3-9, Table 3-10, Table 3-11, and Table 3-12 show the decimal values and hexadecimal IEEE representations of the values provided by ieee_values(3m) functions.
IEEE Values: Double Extended Precision (Intel)
Table 3-12
ieee_flags(3m)
ieee_flags (3m) is the recommended interface to:
i = ieee_flags(action, mode, in, out);
The ASCII strings that are the possible values for the parameters are shown in Table 3-13:
The ieee_flags(3m) man page describes the parameters in complete detail.
or round towards -.
The IEEE default rounding direction is round towards nearest. This means that when the mathematical result of an operation lies halfway between two representable numbers, the one nearest to the mathematical result is delivered as the result. If the mathematical result lies halfway between the two representable numbers, then round to nearest mode specifies round to the nearest even number (final bit is zero.)
are shown in Table 3-14.
When mode is ``precision'', the specified action applies to the current rounding precision. On Intel, the possible rounding precisions are: single, double, and extended. The default rounding precision is extended; in this mode, arithmetic operations that deliver a result to a floating point register round their result to the full 64-bit precision of the extended double register format. When the rounding precision is single or double, arithmetic operations that deliver a result to a floating point register round their result to 24 or 53 significant bits, respectively. Although most programs produce results that are at least as accurate, if not more so, when extended rounding precision is used, some programs that require strict adherence to the semantics of IEEE arithmetic will not work correctly in extended rounding precision mode and must be run with the rounding precision set to single or double as appropriate.
ieee_retrospective(3m)
The libsunmath function ieee_retrospective prints
information about unrequited exceptions and nonstandard IEEE modes. It
reports:
ieee_retrospective prints information about exception flags that are raised, and exceptions for which a trap is enabled. These two distinct, if related, pieces of information should not be confused. If an exception flag is raised, then that exception occurred at some point during program execution. If a trap is enabled for an exception, then the exception may not have actually occurred (but if it had, a SIGFPE signal would have been delivered). The ieee_retrospective message is meant to alert you about exceptions that may need to be investigated (if the exception flag is raised), or to remind you that exceptions may have been handled by a signal handler (if the exception's trap is enabled.) Chapter 4, "Exceptions and Exception Handling," discusses exceptions, signals, and traps, and shows how to investigate the cause of a raised exception.
ieee_retrospective can be called anytime, but it is usually
called before exit points. Programs compiled with f77 call
ieee_retrospective on exit by default.
The following example shows four of the six ieee_retrospective warning messages:
A warning message appears only if trapping is enabled or an exception was raised.
character*8 out
i = ieee_flags('clearall', '', '', out)
call ieee_handler('clear', 'all', 0)
call standard_arithmetic()
|
Another way to avoid seeing ieee_retrospective messages is simply to redirect stderr to a file. Of course, this method should not be used if the program sends output other than ieee_retrospective messages to stderr.
Note - Clearing outstanding exceptions without investigating their cause is not recommended.
subroutine ieee_retrospective return end |
nonstandard_arithmetic(3m)
As discussed in Chapter 2, "IEEE Arithmetic," IEEE arithmetic handles underflowed results using gradual underflow. On some SPARC systems, gradual underflow is often implemented partly with software emulation of the arithmetic. If many calculations underflow, this may cause performance degradation.
To obtain some information about whether this is a case in a specific program,
you can use ieee_retrospective or ieee_flags to determine
if underflow exceptions occur, and check the amount of system time used by the program. If a program spends an unusually large amount of time in the operating system, and raises underflow exceptions, gradual underflow may be the cause. In this case, using non-IEEE arithmetic may speed up program execution.
Implementation Features of libm and libsunmath
This section describes implementation features of libm and libsunmath:
, and trigonometric functions scaled in .
Both the table-driven and polynomial/rational approximation algorithms for the common elementary functions in libm and the common single precision elementary functions in libsunmath deliver results that are accurate to within one unit in the last place (ulp). On SPARC and PowerPC, the common quadruple precision elementary functions in libsunmath deliver results that are accurate to within one ulp, except for the expm1l and log1pl functions, which deliver results accurate to within two ulps. These error bounds have been obtained by direct analysis of the algorithms. Users may also test the accuracy of these routines using BeEF, the Berkeley Elementary Function test programs, developed by Z. Alex Liu and available from netlib in the ucbtest package.
/4,/4] are usually computed by reducing the argument to the indicated range by subtracting integral multiples of /2. Because
is not a machine-representable number, it must be approximated. The error in the final computed trigonometric function depends on the rounding errors in argument reduction (with an approximate as well as the rounding), and approximation errors in computing the trigonometric function of the reduced argument. Even for fairly small arguments, the relative error in the final result may be dominated by the argument reduction error, while even for fairly large arguments, the error due to argument reduction may be no worse than the other errors. There is widespread misapprehension that trigonometric functions of all large arguments are inherently inaccurate, and all small arguments relatively accurate. This is based on the simple observation that large enough machine-representable numbers are separated by a distance greater than
. There is no inherent boundary at which computed trigonometric function values suddenly become bad, nor are the inaccurate function values useless. Provided that the argument reduction is done consistently, the fact that the argument reduction is performed with an approximation to
is practically undetectable, because all essential identities and relationships are as well preserved for large arguments as for small. libm and libsunmath trigonometric functions use an "infinitely" precise
for argument reduction. The value 2/ is computed to 916 hexadecimal digits and stored in a lookup table to use during argument reduction. The group of functions sinpi, cospi, tanpi (see Table 3-2 on page 34), scales the input argument by
to avoid inaccuracies introduced by range reduction.
Data Conversion Routines
In libm and libsunmath, there is a flexible data conversion routine, convert_external, used to convert binary floating-point data between IEEE and non-IEEE formats. Random Number Facilities
There are two facilities for generating uniform pseudo-random numbers, addrans(3m) and lcrans(3m). addrans is a table-driven additive random number generator, and lcrans is a linear congruential random number generator.
That is, these are the upper and lower bounds over which the data is uniformly distributed. These bounds cannot be altered.
libc Support Functions
This section describes the base conversion feature for libc support (applicable only to the Solaris operating environment). Base Conversion
Base conversion is used by I/O routines, like printf and scanf in C, and read, write, and print in FORTRAN. For these functions you need conversions between numbers representations in bases 2 and 10:
Base conversion is not too difficult for integer formats but gets more complicated when floating point is involved; as with other floating-point operations, rounding errors occur.
For instance, on conversion from internal floating point to an external decimal representation, the mathematical problem to be solved in default rounding mode is as follows:
In the case of printf %f or FORTRAN F format with n digits after the decimal point:
i × 2**e - J × 10**E 
0.5 × 10**E
J 10**n - 1
Correct rounding is required by the IEEE Standard 754. The standard requires correct rounding for typical numbers whose magnitudes range from 10 -44 to 10+44, but permits slightly incorrect rounding for larger exponents--the Sun table-driven algorithm for rounding is accurate through the entire range. (See section 5.6 of IEEE Standard 754.)
See Appendix G, "References," on page 237, for references on base conversion. Particularly good references are Coonen's thesis and Sterbenz's book.
