MPFI 1.0
This manual documents how to install and use the Multiple Precision
Floating-Point Interval Library
MPFR/MPFI Copying Conditions
This library is free; this means that everyone is free to use it and
free to redistribute it on a free basis. The library is not in the public
domain; it is copyrighted and there are restrictions on its distribution, but
these restrictions are designed to permit everything that a good cooperating
citizen would want to do. What is not allowed is to try to prevent others
from further sharing any version of this library that they might get from
you.
Specifically, we want to make sure that you have the right to give away copies
of the library, that you receive source code or else can get it if you want
it, that you can change this library or use pieces of it in new free programs,
and that you know you can do these things.
To make sure that everyone has such rights, we have to forbid you to deprive
anyone else of these rights. For example, if you distribute copies of the
MPFR/MPFI library, you must give the recipients all the rights that you have. You
must make sure that they, too, receive or can get the source code. And you
must tell them their rights.
Also, for our own protection, we must make certain that everyone finds out
that there is no warranty for the MPFR/MPFI library. If it is modified by
someone else and passed on, we want their recipients to know that what they
have is not what we distributed, so that any problems introduced by others
will not reflect on our reputation.
The precise conditions of the license for the MPFR/MPFI library are found in the
Lesser General Public License that accompany the source code.
See the file COPYING.LIB in the main MPFR directory.
1. Introduction to MPFI
MPFI is intended to be a portable library written in C
for arbitrary precision interval arithmetic
with intervals represented using MPFR
reliable floating-point numbers. It is based on the GNU MP
library and on the MPFR library and is part of the latter.
The purpose of an arbitrary precision interval
arithmetic is on the one hand to get guaranteed
results, thanks to interval computation, and on the other
hand to obtain accurate results, thanks to multiple
precision arithmetic. The MPFI library is built upon
MPFR in order to benefit from the correct roundings
provided by MPFR.
Further advantages of using MPFR are its portability
and compliance with the IEEE 754 standard for floating-point
arithmetic.
This version of MPFR/MPFI is released under the GNU Lesser General Public
License.
It is permitted to link MPFR/MPFI to non-free programs, as long as when
distributing them the MPFR/MPFI source code and a means to re-link with a
modified MPFR/MPFI is provided.
2. Installing MPFI
To build MPFI, you first have to install MPFR (version 2.0 or above)
on your computer.
You need a C compiler, preferably GCC, but any reasonable compiler should
work. And you need a standard Unix `make' program, plus some other
standard Unix utility programs.
Here are the steps needed to install the MPFI library on Unix systems:
-
Edit the file `Makefile' and set the various variables:
set `CC' to your C compiler, `COPT' to the optimization
options for the compiler, `C_EXTRA_FLAGS'
to some other useful options (`-static' may reveal useful)
and `AR', `LD' to the proper utilities.
Also set `GMP_INCLUDE' to the directory containing
the GNU MP header files and `GMP_LIB' to the GNU MP library
directory. Similarly, set `MPFR_INCLUDE' to the directory containing
the MPFR header files and `MPFR_LIB' to the directory
containing the MPFR library files.
-
`make all'
This will compile MPFI, and create a library archive file `libmpfi.a'
in the working directory.
-
`make tests'
This will make some random tests in order to check
whether MPFI was built correctly.
If you get error messages from the test program, please
report this to `Nathalie.Revol@ens-lyon.fr, Fabrice.Rouillier@loria.fr'. (See section 3. Reporting Bugs, for
information on what to include in useful bug reports.)
There are some other useful make targets:
-
`mpfi.dvi' or `dvi'
Create a DVI version of the manual, in `mpfi.dvi'.
-
`mpfi.info' or `info'
Create an info version of the manual, in `mpfi.info'.
-
`clean'
Delete all object files and archive files, but not the configuration files.
2.1 Known Build Problems
The installation procedure and MPFI itself have been tested
only on Solaris 2.6 and 2.8 and some Linux distributions.
Since it has not been intensively tested,
you may discover that
MPFI suffers from all bugs of the underlying libraries, plus many many more.
Please report any problem to `Nathalie.Revol@ens-lyon.fr, Fabrice.Rouillier@loria.fr'.
See section 3. Reporting Bugs.
3. Reporting Bugs
If you think you have found a bug in the MPFI library, please investigate it
and report it. We have made this library available to you, and it is not to ask
too much from you, to ask you to report the bugs that you find.
There are a few things you should think about when you put your bug report
together.
You have to send us a test case that makes it possible for us to reproduce the
bug. Include instructions on how to run the test case.
You also have to explain what is wrong; if you get a crash, or if the results
printed are incorrect and in that case, in what way.
Please include compiler version information
in your bug report. This can be extracted using `cc -V' on some machines or,
if you're using gcc, `gcc -v'. Also, include the output from `uname
-a'.
If your bug report is good, we will do our best to help you to get a corrected
version of the library; if the bug report is poor, we won't do anything about
it (except kidding you for sending poor bug reports).
Send your bug report to: `Nathalie.Revol@ens-lyon.fr, Fabrice.Rouillier@loria.fr'.
If you think something in this manual is unclear, or downright incorrect, or if
the language needs to be improved, please send a note to the same address.
4. MPFI Basics
All declarations needed to use MPFI are collected in the include file
`mpfi.h'. The declarations useful for inputs and outputs are to be found
in `mpfi_io.h'. It is designed to work with both C and C++ compilers.
You should include these files in any program using the MPFI library:
| | #include "mpfi.h"
#include "mpfi_io.h"
|
4.1 Nomenclature and Types
An interval is a connected set of real numbers, it is represented
in MPFI by its endpoints which are MPFR floating-point numbers.
The C data type for these objects is mpfi_t. An interval can
have finite or infinite endpoints and its meaning is straightforward.
It can also have one (or both) NaN endpoint(s): this indicates that
an invalid operation has been performed and that the resulting interval
has no mathematical meaning. An empty interval has its left endpoint larger
than its right endpoint. The handling of empty intervals is not performed
by MPFI and relies on the user.
Some functions on intervals return a floating-point value: among such
functions are mpfi_get_left that returns the left endpoint of
an interval and mpfi_diam_abs that gets the width of the
input interval.
A Floating point number or Float for short, is an arbitrary precision
mantissa with a limited precision exponent. The C data type for such objects
is mpfr_t.
The Precision is the number of bits used to represent the mantissa
of a floating-point number;
the corresponding C data type is mp_prec_t.
4.2 Function Classes
There is only one class of functions in the MPFI library:
-
Functions for interval arithmetic based on floating-point numbers,
with names beginning with
mpfi_. The associated type is mpfi_t. There are around 150
functions in this class.
4.3 MPFI Variable Conventions
As a general rule, all MPFI functions expect output arguments before input
arguments. This notation is based on an analogy with the assignment operator.
MPFI allows you to use the same variable for both input and output in the same
expression. For example, the function for the exponential,
mpfi_exp, can be used like this: mpfi_exp (x, x).
This
computes the set of exponentials of every real belonging to x
and puts the result back in x.
Before you can assign an MPFI variable, you need to initialize it by calling
one of the special initialization functions. When you're done with a
variable, you need to clear it out, using one of the appropriate
functions.
A variable should be initialized once only, or at least cleared out between
different initializations. After a variable has been initialized, it can be
assigned any number of times.
For efficiency reasons, avoid to initialize and clear out a variable in loops.
Instead, initialize it before entering the loop, and clear it out after
exiting the loop.
You don't need to be concerned about allocating additional space for MPFI
variables, since any variable uses a memory space of fixed size.
Hence unless you change its precision, or clear and reinitialize it,
an interval variable will have the same allocated space during all its
lifetime.
4.4 Getting the Latest Version of MPFI
The latest version of MPFI is available from
`http://perso.ens-lyon.fr/nathalie.revol/software.html'.
5. Interval Functions
The interval functions expect arguments of type mpfi_t.
The MPFI interval functions have an interface that is close to the
corresponding MPFR
functions. The function prefix for interval operations is
mpfi_.
MPFI intervals are represented by their endpoints; this representation
should be invisible to the user, unfortunately it is not...
It is assumed that both endpoints have the
same precision; however when this does not hold, the largest precision
is considered. The user has
to specify the precision of each variable. A computation that assigns a
variable will take place with the precision of the assigned variable.
For more information on precision (precision of a variable,
precision of a calculation), see the MPFR documentation.
5.1 Return Values
Four integer values (of C type int)
can be returned by a typical mpfi function. These values
indicate whether none, one or two endpoints of the computed interval are
exact: since they are rounded values, they can differ from the exact
result. Here are their names:
MPFI_FLAGS_BOTH_ENDPOINTS_EXACT
MPFI_FLAGS_LEFT_ENDPOINT_INEXACT: the left endpoint is inexact
whereas the right endpoint is exact;
MPFI_FLAGS_RIGHT_ENDPOINT_INEXACT: the right endpoint is inexact
whereas the left endpoint is exact;
MPFI_FLAGS_BOTH_ENDPOINTS_INEXACT
To test the exactness of one endpoint, the following functions are available
(their names are self-explanatory):
MPFI_BOTH_ARE_EXACT
MPFI_LEFT_IS_INEXACT
MPFI_RIGHT_IS_INEXACT
MPFI_BOTH_ARE_INEXACT
5.2 Rounding Modes and Precision Handling
Only two rounding modes are useful when computing with intervals
represented by their endpoints, namely downward and upward roundings
used for outward rounding:
MPFI_RNDU: round towards plus infinity
MPFI_RNDD: round towards minus infinity
The four rounding modes provided by MPFR are still available,
see MPFR documentation to get their names and information on how
to modify them.
The default computing precision is handled by MPFR, getting or setting
its value is performed using the following MPFR functions
(cf. MPFR documentation):
- Macro: void mpfr_set_default_prec (mp_prec_t prec)
- Sets the default precision to be exactly prec bits. The
precision of a variable means the number of bits used to store the mantissas
of its endpoints.
All
subsequent calls to
mpfi_init will use this precision, but previously
initialized variables are unaffected.
This default precision is set to 53 bits initially.
The precision prec can be any integer between MPFR_PREC_MIN and
MPFR_PREC_MAX.
- Macro: mp_prec_t mpfr_get_default_prec ()
- Returns the default MPFR/MPFI precision in bits.
The following two functions are useful for changing the precision during a
calculation. A typical use would be for adjusting the precision gradually in
iterative algorithms like Newton-Raphson, making the computation precision
closely match the actual accurate part of the numbers.
- Function: int mpfi_set_prec (mpfi_t x, mp_prec_t prec)
- Resets the precision of x to be exactly prec bits.
The previous value stored in x is lost. It is equivalent to
a call to
mpfi_clear(x) followed by a call to
mpfi_init2(x, prec), but more efficient as no allocation is done in
case the current allocated space for the mantissas of the endpoints
of x is enough.
It returns a non-zero value iff the memory allocation failed.
In case you want to keep the previous value stored in x,
use mpfi_round_prec instead.
- Function: mp_prec_t mpfi_get_prec (mpfi_t x)
- Return the largest precision actually used for assignments of x, i.e.
the number of bits used to store the mantissas of its endpoints.
Should the two endpoints have different precisions, the largest one is returned.
- Function: int mpfi_round_prec (mpfi_t x, mp_prec_t prec)
- Rounds x with precision prec, which
may be different from that of x.
If prec is greater or equal to the precision of x, then new
space is allocated for the endpoints' mantissas, and they are filled with zeroes.
Otherwise, the mantissas are outwards rounded to precision prec.
In both cases, the precision of x is changed to prec.
It returns a value indicating whether the possibly rounded endpoints are exact or not,
cf. 5.1 Return Values.
5.3 Initialization and Assignment Functions
5.3.1 Initialization Functions
An mpfi_t object must be initialized before storing the first value in
it. The functions mpfi_init and mpfi_init2 are used for that
purpose.
- Function: void mpfi_init (mpfi_t x)
- Initializes x, and sets its value to NaN, to prevent from using
an unassigned variable inadvertently.
Normally, a variable should be initialized once only
or at least be cleared, using
mpfi_clear, between consecutive
initializations. The
precision of x is the default precision, which can be changed
by a call to mpfr_set_default_prec.
- Function: void mpfi_init2 (mpfi_t x, mp_prec_t prec)
- Initializes x, sets its precision (or more precisely the precision
of its endpoints) to be exactly
prec bits, and sets its endpoints to NaN.
Normally, a variable should be initialized once only or at
least be cleared, using
mpfi_clear, between consecutive initializations.
To change the precision of a variable which has already been initialized,
use mpfi_set_prec instead, or mpfi_round_prec if you want to keep its value.
- Function: void mpfi_clear (mpfi_t x)
- Frees the space occupied by x. Make sure to call this function for all
mpfi_t variables when you are done with them.
Here is an example on how to initialize interval variables:
| | {
mpfi_t x, y;
mpfi_init (x); /* use default precision */
mpfi_init2 (y, 256); /* precision exactly 256 bits */
...
/* Unless the program is about to exit, do ... */
mpfi_clear (x);
mpfi_clear (y);
}
|
5.3.2 Assignment Functions
These functions assign new values to already initialized intervals
(see section 5.3.1 Initialization Functions).
- Function: int mpfi_set (mpfi_t rop, mpfi_t op)
-
- Function: int mpfi_set_ui (mpfi_t rop, unsigned long int op)
-
- Function: int mpfi_set_si (mpfi_t rop, long int op)
-
- Function: int mpfi_set_d (mpfi_t rop, double op)
-
- Function: int mpfi_set_z (mpfi_t rop, mpz_t op)
-
- Function: int mpfi_set_q (mpfi_t rop, mpq_t op)
-
- Function: int mpfi_set_fr (mpfi_t rop, mpfr_t op)
- Sets the value of rop from op, outward rounded to the precision of rop:
op then belongs to rop.
The returned value indicates whether none, one or both endpoints are exact.
Please note that even a
long int may have to be rounded,
if the destination precision is less than the machine word width.
- Function: int mpfi_set_str (mpfi_t rop, char *s, int base)
- Sets rop to the value of the string s, in base base (between
2 and 36), outward rounded to the precision of rop:
op then belongs to rop.
The exponent is read in decimal.
The string is of the form `number' or
`[ number1 , number 2 ]'.
Each endpoint has the form `M@N' or, if the
base is 10 or less, alternatively `MeN' or `MEN'.
`M' is the mantissa and
`N' is the exponent. The mantissa is always in the specified base. The
exponent is
in decimal.
The argument base may be in the ranges 2 to 36.
This function
returns 1 if the input is incorrect, -1 if an internal overflow occurred
and 0 otherwise.
- Function: void mpfi_swap (mpfi_t x, mpfi_t y)
- Swaps the values x and y efficiently. Warning: the
precisions are exchanged too; in case the precisions are different,
mpfi_swap is thus not equivalent to three mpfi_set calls
using a third auxiliary variable.
5.3.3 Combined Initialization and Assignment Functions
- Function: int mpfi_init_set (mpfi_t rop, mpfi_t op)
-
- Function: int mpfi_init_set_ui (mpfi_t rop, unsigned long int op)
-
- Function: int mpfi_init_set_si (mpfi_t rop, long int op)
-
- Function: int mpfi_init_set_d (mpfi_t rop, double op)
-
- Function: int mpfi_init_set_z (mpfi_t rop, mpz_t op)
-
- Function: int mpfi_init_set_q (mpfi_t rop, mpq_t op)
-
- Function: int mpfi_init_set_fr (mpfi_t rop, mpfr_t op)
- Initializes rop and sets its value from op, outward rounded so
that op belongs to rop.
The precision of rop will be taken from the active default precision,
as set by
mpfr_set_default_prec.
The returned value indicates whether none, one or both endpoints are exact.
- Function: int mpfi_init_set_str (mpfi_t rop, char *s, int base)
- Initializes rop and sets its value
to the value of the string s, in base base (between
2 and 36), outward rounded to the precision of rop:
op then belongs to rop. The exponent is read in decimal.
See
mpfi_set_str.
5.4 Interval Functions with Floating-point Results
Some functions on intervals return floating-point results,
such as the center or the width, also called diameter, of an interval.
- Function: int mpfi_diam_abs (mpfr_t rop, mpfi_t op)
- Sets the value of rop to the upward rounded diameter of op,
or in other words to the upward rounded difference between the right endpoint
of op and its left endpoint.
Returns 0 if the diameter is exact and a positive value if the rounded
value is greater than the exact diameter.
- Function: int mpfi_diam_rel (mpfr_t rop, mpfi_t op)
- Sets the value of rop to the upward rounded relative diameter of op,
or in other words to the upward rounded difference between the right endpoint
of op and its left endpoint, divided by the absolute value
of the center of op if it is not zero.
Returns 0 if the result is exact and a positive value if the returned value
is an overestimation.
- Function: int mpfi_diam (mpfr_t rop, mpfi_t op)
- Sets the value of rop to the relative diameter of op
if op does not contain zero and to its absolute diameter otherwise.
Returns 0 if the result is exact and a positive value if the returned value
is an overestimation.
- Function: int mpfi_mag (mpfr_t rop, mpfi_t op)
- Sets the value of rop to the magnitude of op,
i.e. to the largest absolute value of the elements of op.
Returns 0 if the result is exact and a positive value if the returned value
is an overestimation.
- Function: int mpfi_mig (mpfr_t rop, mpfi_t op)
- Sets the value of rop to the mignitude of op,
i.e. to the smallest absolute value of the elements of op.
Returns 0 if the result is exact and a negative value if the returned value
is an underestimation.
- Function: int mpfi_mid (mpfr_t rop, mpfi_t op)
- Sets rop to the middle of op.
Returns 0 if the result is exact, a positive value if rop > the
middle of op and a negative value if rop < the middle of op.
- Function: void mpfi_alea (mpfr_t rop, mpfi_t op)
- Sets rop to a floating-point number
picked up at random in op, according to a uniform distribution.
5.5 Conversion Functions
- Function: double mpfi_get_d (mpfi_t op)
- Converts op to a double, which is the center of op rounded to the
nearest double.
- Function: void mpfi_get_fr (mpfr_t rop, mpfi_t op)
- Converts op to a floating-point number, which is the center of op
rounded to nearest.
5.6 Basic Arithmetic Functions
- Function: int mpfi_add (mpfi_t rop, mpfi_t op1, mpfi_t op2)
-
- Function: int mpfi_add_d (mpfi_t rop, mpfi_t op1, double op2)
-
- Function: int mpfi_add_ui (mpfi_t rop, mpfi_t op1, unsigned long int op2)
-
- Function: int mpfi_add_si (mpfi_t rop, mpfi_t op1, long int op2)
-
- Function: int mpfi_add_z (mpfi_t rop, mpfi_t op1, mpz_t op2)
-
- Function: int mpfi_add_q (mpfi_t rop, mpfi_t op1, mpq_t op2)
-
- Function: int mpfi_add_fr (mpfi_t rop, mpfi_t op1, mpfr_t op2)
- Sets rop to op1 + op2.
Returns a value indicating whether none, one or both endpoints are exact.
- Function: int mpfi_sub (mpfi_t rop, mpfi_t op1, mpfi_t op2)
-
- Function: int mpfi_sub_d (mpfi_t rop, mpfi_t op1, double op2)
-
- Function: int mpfi_d_sub (mpfi_t rop, double op1, mpfi_t op2)
-
- Function: int mpfi_sub_ui (mpfi_t rop, mpfi_t op1, unsigned long int op2)
-
- Function: int mpfi_ui_sub (mpfi_t rop, unsigned long int op1, mpfi_t op2)
-
- Function: int mpfi_sub_si (mpfi_t rop, mpfi_t op1, long int op2)
-
- Function: int mpfi_si_sub (mpfi_t rop, long int op1, mpfi_t op2)
-
- Function: int mpfi_sub_z (mpfi_t rop, mpfi_t op1, mpz_t op2)
-
- Function: int mpfi_z_sub (mpfi_t rop, mpz_t op1, mpfi_t op2)
-
- Function: int mpfi_sub_q (mpfi_t rop, mpfi_t op1, mpq_t op2)
-
- Function: int mpfi_q_sub (mpfi_t rop, mpq_t op1, mpfi_t op2)
-
- Function: int mpfi_sub_fr (mpfi_t rop, mpfi_t op1, mpfr_t op2)
-
- Function: int mpfi_fr_sub (mpfi_t rop, mpfr_t op1, mpfi_t op2)
- Sets rop to op1 - op2.
Returns a value indicating whether none, one or both endpoints are exact.
- Function: int mpfi_mul (mpfi_t rop, mpfi_t op1, mpfi_t op2)
-
- Function: int mpfi_mul_d (mpfi_t rop, mpfi_t op1, double op2)
-
- Function: int mpfi_mul_ui (mpfi_t rop, mpfi_t op1, unsigned long int op2)
-
- Function: int mpfi_mul_si (mpfi_t rop, mpfi_t op1, long int op2)
-
- Function: int mpfi_mul_z (mpfi_t rop, mpfi_t op1, mpz_t op2)
-
- Function: int mpfi_mul_q (mpfi_t rop, mpfi_t op1, mpq_t op2)
-
- Function: int mpfi_mul_fr (mpfi_t rop, mpfi_t op1, mpfr_t op2)
- Sets rop to op1 * op2.
Multiplication by an interval containing only zero results in 0.
Returns a value indicating whether none, one or both endpoints are exact.
Division is defined even if the divisor contains zero: when the divisor
contains zero in its interior, the result is the whole real interval [-Inf, Inf].
When the divisor has one of its endpoints equal to 0,
for instance, [1,2]/[+0,1] results in [1, Inf].
It is not guaranteed in the current version that everything behaves properly
if the divisor contains only 0.
In this example, both endpoints are exact.
The extended interval division, returning two semi-infinite intervals when
the divisor contains 0, should be available soon.
- Function: int mpfi_div (mpfi_t rop, mpfi_t op1, mpfi_t op2)
-
- Function: int mpfi_div_d (mpfi_t rop, mpfi_t op1, double op2)
-
- Function: int mpfi_d_div (mpfi_t rop, double op1, mpfi_t op2)
-
- Function: int mpfi_div_ui (mpfi_t rop, mpfi_t op1, unsigned long int op2)
-
- Function: int mpfi_ui_div (mpfi_t rop, unsigned long int op1, mpfi_t op2)
-
- Function: int mpfi_div_si (mpfi_t rop, mpfi_t op1, long int op2)
-
- Function: int mpfi_si_div (mpfi_t rop, long int op1, mpfi_t op2)
-
- Function: int mpfi_div_z (mpfi_t rop, mpfi_t op1, mpz_t op2)
-
- Function: int mpfi_z_div (mpfi_t rop, mpz_t op1, mpfi_t op2)
-
- Function: int mpfi_div_q (mpfi_t rop, mpfi_t op1, mpq_t op2)
-
- Function: int mpfi_q_div (mpfi_t rop, mpq_t op1, mpfi_t op2)
-
- Function: int mpfi_div_fr (mpfi_t rop, mpfi_t op1, mpfr_t op2)
-
- Function: int mpfi_fr_div (mpfi_t rop, mpfr_t op1, mpfi_t op2)
- Sets rop to op1/op2.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_neg (mpfi_t rop, mpfi_t op)
- Sets rop to -op.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_sqr (mpfi_t rop, mpfi_t op)
- Sets rop to the nonnegative square of op.
Returns an indication of whether none, one or both endpoints are exact.
Indeed, in interval arithmetic, the square of an interval is a nonnegative interval
whereas the product of an interval by itself can contain negative values.
- Function: int mpfi_inv (mpfi_t rop, mpfi_t op)
- Sets rop to 1/op.
Inverse is defined even if the interval contains zero: when the denominator
contains zero, the result is the whole real interval ]-Inf, Inf[.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_sqrt (mpfi_t rop, mpfi_t op)
- Sets rop to the square root of op.
Sets rop to NaN if op is negative.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_abs (mpfi_t rop, mpfi_t op)
- Sets rop to the interval containing the absolute value of every element of op.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_mul_2exp (mpfi_t rop, mpfi_t op1, unsigned long int op2)
-
- Function: int mpfi_mul_2ui (mpfi_t rop, mpfi_t op1, unsigned long int op2)
-
- Function: int mpfi_mul_2si (mpfi_t rop, mpfi_t op1, long int op2)
- Sets rop to op1 times 2 raised to op2.
Returns an indication of whether none, one or both endpoints are exact.
Just increases the exponents of the endpoints by op2
when rop and op1 are identical.
- Function: int mpfi_div_2exp (mpfi_t rop, mpfi_t op1, unsigned long int op2)
-
- Function: int mpfi_div_2ui (mpfi_t rop, mpfi_t op1, unsigned long int op2)
-
- Function: int mpfi_div_2si (mpfi_t rop, mpfi_t op1, long int op2)
- Sets rop to op1 divided by 2 raised to op2.
Returns an indication of whether none, one or both endpoints are exact.
Just decreases the exponents of the endpoints by op2
when rop and op1 are identical.
5.7 Special Functions
These functions are based on their MPFR counterparts. For more information,
see the MPFR documentation or related bibliography.
- Function: int mpfi_log (mpfi_t rop, mpfi_t op)
- Sets rop to the natural logarithm of op,
with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
If op contains negative numbers, then rop has at least one
NaN endpoint.
- Function: int mpfi_exp (mpfi_t rop, mpfi_t op)
- Sets rop to the exponential of op,
with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_exp2 (mpfi_t rop, mpfi_t op)
- Sets rop to 2 to the power op, with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
The interval sine and cosine functions are not yet available. They should
return [-1,1] when the input interval is infinite.
- Function: void mpfi_sin_cos (mpfi_t sop, mpfi_t cop, mpfi_t op)
- Sets sop to the sine of op, cop to the cosine of op,
with the precision of the result (sop and cop).
- Function: int mpfi_acos (mpfi_t rop, mpfi_t op)
-
- Function: int mpfi_asin (mpfi_t rop, mpfi_t op)
-
- Function: int mpfi_atan (mpfi_t rop, mpfi_t op)
- Sets rop to the arc-cosine, arc-sine or arc-tangent of op,
with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_cosh (mpfi_t cop, mpfi_t op)
-
- Function: int mpfi_sinh (mpfi_t sop, mpfi_t op)
-
- Function: int mpfi_tanh (mpfi_t top, mpfi_t op)
- Sets cop to the hyperbolic cosine of op,
sop to the hyperbolic sine of op,
top to the hyperbolic tangent of op,
with the precision of the result.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_acosh (mpfi_t rop, mpfi_t op)
-
- Function: int mpfi_asinh (mpfi_t rop, mpfi_t op)
-
- Function: int mpfi_atanh (mpfi_t rop, mpfi_t op)
- Sets rop to the inverse hyperbolic cosine, sine or tangent of op,
with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_log1p (mpfi_t rop, mpfi_t op)
- Sets rop to the natural logarithm of one plus op,
with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
If op contains negative numbers, then rop has at least one
NaN endpoint.
- Function: int mpfi_expm1 (mpfi_t rop, mpfi_t op)
- Sets rop to the exponential of op, minus one,
with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_log2 (mpfi_t rop, mpfi_t op)
-
- Function: int mpfi_log10 (mpfi_t rop, mpfi_t op)
- Sets rop to log[t] op with t=2 or 10 the base for the
logarithm, with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
If op contains negative numbers, then rop has at least one
NaN endpoint.
- Function: int mpfi_const_log2 (mpfi_t rop)
- Sets rop to the logarithm of 2
with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_const_pi (mpfi_t rop)
- Sets rop to the value of Pi with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
- Function: int mpfi_const_euler (mpfi_t rop)
- Sets rop to the Euler's constant,
with the precision of rop.
Returns an indication of whether none, one or both endpoints are exact.
5.8 Comparison Functions
The comparison of two intervals is not clearly defined when they overlap.
MPFI proposes default comparison functions, but they can easily be customized
according to the user's needs.
The default comparison functions return a positive value if the first interval has all
its elements strictly lower than all elements of the second one,
a negative value if the first interval has all its elements strictly greater than all
elements of the second one and 0 otherwise, i.e. if they overlap or if one is contained
in the other.
- Function: int mpfi_cmp (mpfi_t op1, mpfi_t op2)
-
- Function: int mpfi_cmp_d (mpfi_t op1, double op2)
-
- Function: int mpfi_cmp_ui (mpfi_t op1, unsigned long int op2)
-
- Function: int mpfi_cmp_si (mpfi_t op1, long int op2)
-
- Function: int mpfi_cmp_z (mpfi_t op1, mpz_t op2)
-
- Function: int mpfi_cmp_q (mpfi_t op1, mpq_t op2)
-
- Function: int mpfi_cmp_fr (mpfi_t op1, mpfr_t op2)
- Compares op1 and op2. Return a positive value if op1 <
op2, zero if op1 overlaps or contains op2, and a negative value if op1 >
op2.
In case one of the operands is invalid (which is represented by at least one NaN endpoint), it returns 1, even if
both are invalid.
- Function: int mpfi_is_pos (mpfi_t op)
- Returns a positive value if op contains only positive numbers,
the left endpoint can be zero.
- Function: int mpfi_is_strictly_pos (mpfi_t op)
- Returns a positive value if op contains only positive numbers.
- Function: int mpfi_is_nonneg (mpfi_t op)
- Returns a positive value if op contains only nonnegative numbers.
- Function: int mpfi_is_neg (mpfi_t op)
- Returns a positive value if op contains only negative numbers,
the right endpoint can be zero.
- Function: int mpfi_is_strictly_neg (mpfi_t op)
- Returns a positive value if op contains only negative numbers.
- Function: int mpfi_is_nonpos (mpfi_t op)
- Returns a positive value if op contains only nonpositive numbers.
- Function: int mpfi_is_zero (mpfi_t op)
- Returns a positive value if op contains only 0.
- Function: int mpfi_has_zero (mpfi_t op)
- Returns a positive value if op contains 0 (and possibly other numbers).
- Function: int mpfi_nan_p (mpfi_t op)
- Returns non-zero if op is invalid, i.e. at least one of its
endpoints is a Not-a-Number (NaN), zero otherwise.
- Function: int mpfi_inf_p (mpfi_t op)
- Returns non-zero if at least one of the endpoints of op is
plus or minus infinity, zero otherwise.
- Function: int mpfi_bounded_p (mpfi_t op)
- Returns non-zero if op is a bounded interval, i.e. neither invalid
nor (semi-)infinite.
5.9 Input and Output Functions
Functions that perform input from a stdio stream, and functions that output to
a stdio stream. Passing a NULL pointer for a stream argument to any of
these functions will make them read from stdin and write to
stdout, respectively.
When using any of these functions, it is a good idea to include `stdio.h'
before `mpfr.h', since that will allow `mpfr.h' to define prototypes
for these functions.
The input and output functions are based on the representation by endpoints.
The input function has to be improved. For the time being, it is
mandatory to insert spaces between the interval brackets and the
endpoints and also around the comma separating the endpoints.
- Function: size_t mpfi_out_str (FILE *stream, int base, size_t n_digits, mpfi_t op)
- Outputs op on stdio stream stream, as a string of digits in
base base. The output is an opening square bracket "[", followed by the lower
endpoint, a separating comma, the upper endpoint and a closing square bracket "]".
For each endpoint, the output is performed by mpfr_out_str.
The following piece of information is taken from MPFR documentation.
The base may vary from 2 to 36. For each endpoint, it prints at most
n_digits significant digits, or if n_digits is 0, the maximum
number of digits accurately representable by op.
In addition to the significant digits, a decimal point at the right of the
first digit and a
trailing exponent, in the form `eNNN', are printed. If base
is greater than 10, `@' will be used instead of `e' as
exponent delimiter.
Returns the number of bytes written, or if an error occurred, return 0.
- Function: size_t mpfi_inp_str (mpfi_t rop, FILE *stream, int base)
- Inputs a string in base base from stdio stream stream,
and puts the
read float in rop. The string is of the form `number' or
`[ number1 , number 2 ]'.
Each endpoint has the form `M@N' or, if the
base is 10 or less, alternatively `MeN' or `MEN'.
`M' is the mantissa and
`N' is the exponent. The mantissa is always in the specified base. The
exponent is
in decimal.
The argument base may be in the ranges 2 to 36.
Unlike the corresponding mpz function, the base will not be determined
from the leading characters of the string if base is 0. This is so that
numbers like `0.23' are not interpreted as octal.
Returns the number of bytes read, or if an error occurred, return 0.
- Function: void mpfi_print_binary (mpfi_t op)
- Outputs op on stdout
in raw binary format for each endpoint (the exponent is in decimal, yet).
The last bits from the least significant limb which do not belong to
the mantissa are printed between square brackets;
they should always be zero.
5.10 Functions Operating on Endpoints
- Function: int mpfi_get_left (mpfr_t rop, mpfi_t op)
- Sets rop to the left endpoint of op, rounded toward minus infinity.
It returns a negative value if rop differs from the left endpoint
of op (due to rounding) and 0 otherwise.
- Function: int mpfi_get_right (mpfr_t rop, mpfi_t op)
- Sets rop to the right endpoint of op, rounded toward plus infinity.
It returns a positive value if rop differs from the right endpoint
of op (due to rounding) and 0 otherwise.
The following function should never be used... but it helps to return correct
intervals when there is a bug.
- Function: int mpfi_revert_if_needed (mpfi_t rop)
- Swaps the endpoints of rop if they are not properly ordered,
i.e. if the lower endpoint is greater than the right one.
It returns a non-zero value if the endpoints have been swapped, zero otherwise.
- Function: int mpfi_put (mpfi_t rop, mpfi_t op)
-
- Function: int mpfi_put_d (mpfi_t rop, double op)
-
- Function: int mpfi_put_ui (mpfi_t rop, unsigned long int op)
-
- Function: int mpfi_put_si (mpfi_t rop, long int op)
-
- Function: int mpfi_put_z (mpfi_t rop, mpz_t op)
-
- Function: int mpfi_put_q (mpfi_t rop, mpq_t op)
-
- Function: int mpfi_put_fr (mpfi_t rop, mpfr_t op)
- Extends the interval rop so that it contains op.
In other words, rop is set to the convex hull of rop and op.
It returns a value indicating whether none, one or both endpoints are inexact
(due to possible roundings).
- Function: int mpfi_interv_d (mpfi_t rop, double op1, double op2)
-
- Function: int mpfi_interv_ui (mpfi_t rop, unsigned long int op1, unsigned long int op2)
-
- Function: int mpfi_interv_si (mpfi_t rop, long int op1, long int op2)
-
- Function: int mpfi_interv_z (mpfi_t rop, mpz_t op1, mpz_t op2)
-
- Function: int mpfi_interv_q (mpfi_t rop, mpq_t op1, mpq_t op2)
-
- Function: int mpfi_interv_fr (mpfi_t rop, mpfr_t op1, mpfr_t op2)
- Sets rop to the interval having as endpoints op1 and op2.
The values of op1 and op2 are given in any order.
It returns a value indicating whether none, one or both endpoints are inexact
(due to possible roundings).
5.11 Set Functions on Intervals
- Function: int mpfi_is_strictly_inside (mpfi_t op1, mpfi_t op2)
- Returns a positive value if the second interval op2 is contained in
the interior of op1, 0 otherwise.
- Function: int mpfi_is_inside (mpfi_t op1, mpfi_t op2)
-
- Function: int mpfi_is_inside_d (mpfi_t op1, double op2)
-
- Function: int mpfi_is_inside_ui (mpfi_t op1, unsigned long int op2)
-
- Function: int mpfi_is_inside_si (mpfi_t op1, long int op2)
-
- Function: int mpfi_is_inside_z (mpfi_t op1, mpz_t op2)
-
- Function: int mpfi_is_inside_q (mpfi_t op1, mpq_t op2)
-
- Function: int mpfi_is_inside_fr (mpfi_t op1, mpfr_t op2)
- Returns a positive value if op2 is contained in op1,
0 otherwise.
- Function: int mpfi_is_empty (mpfi_t op)
- Returns a positive value if op is empty (its endpoints are in reverse order)
and 0 otherwise. Nothing is done in arithmetic or special functions
to handle empty intervals: this is the responsability of the user
to avoid computing with empty intervals.
- Function: int mpfi_intersect (mpfi_t rop, op1, op2)
- Sets rop to the intersection (possibly empty) of the intervals
op1 and op2.
It returns a value indicating whether none, one or both endpoints are inexact
(due to possible roundings).
Warning: this function can return an empty interval (i.e. with endpoints
in reverse order).
- Function: int mpfi_union (mpfi_t rop, op1, op2)
- Sets rop to the convex hull of the union of the intervals op1 and op2.
It returns a value indicating whether none, one or both endpoints are inexact
(due to possible roundings).
5.12 Miscellaneous Interval Functions
- Function: int mpfi_increase (mpfi_t rop, mpfr_t op)
- Subtracts op to the lower endpoint of rop and adds it to
the upper endpoint of rop, sets the resulting interval to rop.
It returns a value indicating whether none, one or both endpoints are inexact.
- Function: int mpfi_blow (mpfi_t rop, mpfi_t op1, double op2)
- Sets rop to the interval whose center is the center of op1
and whose radius is the radius of op1 multiplied by 2 times (1 + abs(op2)).
It returns a value indicating whether none, one or both endpoints are inexact.
- Function: int mpfi_bisect (mpfi_t rop1, mpfi_t rop2, mpfi_t op)
- Splits op into two halves and sets them to rop1 and rop2.
Due to outward rounding, the two halves rop1 and rop2 may overlap.
It returns a value >0 if the splitting point is greater than the exact centre,
<0 if it is smaller and 0 if it is the exact centre.
5.13 Error Handling
- Macro: void MPFI_ERROR ({char *} msg)
- If there is no error, sets the error number to 1 and prints the message msg.
- Function: int mpfi_is_error ()
- Returns 1 if the error number is set (to 1).
- Function: void mpfi_set_error (int op)
- Sets the error number to op.
- Function: void mpfi_reset_error ()
- Resets the error number to 0.
Contributors
MPFI has been written by Fabrice Rouillier and Nathalie Revol.
Its development has greatly benefited from the patient and supportive
help of the MPFR team.
References
This is a largely lacunary list of introductory references.
- MPFR team (SPACES project, INRIA Lorraine and LORIA),
"MPFR. The Multiple Precision Floating-Point Reliable Library",
available at
http://www.mpfr.org.
-
The main Web site for interval computations is
http://cs.utep.edu/interval-comp/main.html.
-
G. Alefeld and J. Herzberger, "Introduction to interval analysis",
Academic Press, 1983.
-
R. Baker Kearfott, "Rigorous global search: continuous problems",
Kluwer, 1996.
-
T. Hickey and Q. Ju and M. H. Van Emden,
"Interval arithmetic: From principles to implementation",
Journal of the ACM, vol. 48, no 4, pp 1038--1068, September 2001.
-
E. Hansen, "Global optimization using interval analysis",
Marcel Dekker, 1992.
-
A. Neumaier, "Interval methods for systems of equations",
Cambridge University Press, 1990.
-
H. Ratschek and J. Rokne, "New computer methods for global optimization",
Ellis Horwood Ltd, 1988.
Concept Index
Function and Type Index
Table of Contents
Short Table of Contents
MPFR/MPFI Copying Conditions
1. Introduction to MPFI
2. Installing MPFI
3. Reporting Bugs
4. MPFI Basics
5. Interval Functions
Contributors
References
Concept Index
Function and Type Index
About this document
This document was generated by Nathalie Revol on October, 9 2002
using texi2html
The buttons in the navigation panels have the following meaning:
| Button |
Name |
Go to |
From 1.2.3 go to |
|
[ < ] |
Back
|
previous section in reading order
|
1.2.2
|
|
[ > ] |
Forward
|
next section in reading order
|
1.2.4
|
|
[ << ] |
FastBack
|
previous or up-and-previous section
|
1.1
|
|
[ Up ] |
Up
|
up section
|
1.2
|
|
[ >> ] |
FastForward
|
next or up-and-next section
|
1.3
|
|
[Top] |
Top
|
cover (top) of document
|
|
|
[Contents] |
Contents
|
table of contents
|
|
|
[Index] |
Index
|
concept index
|
|
|
[ ? ] |
About
|
this page
|
|
where the Example assumes that the current position
is at Subsubsection One-Two-Three of a document of
the following structure:
- 1. Section One
- 1.1 Subsection One-One
- 1.2 Subsection One-Two
- 1.2.1 Subsubsection One-Two-One
- 1.2.2 Subsubsection One-Two-Two
- 1.2.3 Subsubsection One-Two-Three
<== Current Position
- 1.2.4 Subsubsection One-Two-Four
- 1.3 Subsection One-Three
- 1.4 Subsection One-Four
This document was generated
by Nathalie Revol on October, 9 2002
using texi2html