\input texinfo    @c -*-texinfo-*-
@c %**start of header
@setfilename mpfi.info
@settitle MPFI 1.5.4.
@synindex tp fn
@iftex
@afourpaper
@end iftex
@comment %**end of header

@dircategory Software libraries
@direntry
* mpfi: (mpfi.info).               Multiple Precision Floating-Point Interval Library.
@end direntry

@c smallbook

@iftex
@finalout
@end iftex

@c Note: the edition number is listed in *three* places; please update
@c all three.  Also, update the month and year where appropriate.

@c ==> Update edition number for settitle and subtitle, and in the
@c ==> following paragraph; update date, too.


@ifinfo
This file documents MPFI, a library for interval arithmetic,
which is built upon the MPFR multiple precision floating-point
arithmetic library

Copyright (C) 2002-2018, Ouragan team, Inria Paris, France,
Arenaire team and AriC team, INRIA Rhone-Alpes and LIP, ENS Lyon, France,
and Lab. ANO, University of Sciences and Technologies of Lille, France.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@end ifinfo

@setchapternewpage on
@titlepage
@c  use the new format for titles

@title MPFI 1.5.4.
@subtitle Multiple Precision Floating-Point Interval Library
@subtitle August 2018

@author AriC, INRIA Grenoble - Rhone-Alpes,
@author Spaces, INRIA Lorraine,
@author Arenaire, INRIA Rhone-Alpes,
@author Lab. ANO, USTL (Univ. of Lille)

@c Include the Distribution inside the titlepage so
@c that headings are turned off.

@tex
\global\parindent=0pt
\global\parskip=8pt
\global\baselineskip=13pt
@end tex

@page
@vskip 0pt plus 1filll
@c Copyright @copyright{} 2002-2018 Spaces, Arenaire and AriC INRIA projects, Lab. ANO - USTL

@sp 2

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@end titlepage
@headings double

@ifinfo
@node Top, Copying, (dir), (dir)

@top MPFI 1.5.4.

This manual documents how to install and use the Multiple Precision
Floating-Point Interval Library

@end ifinfo

@menu
* Copying::                     
* Introduction to MPFI::        
* Installing MPFI::             
* Reporting Bugs::              
* MPFI Basics::                 
* Interval Functions::          
* Contributors::                
* References::                  
* Concept Index::               
* Function Index::              

Interval Functions


Initialization and Assignment Functions

* Initializing Intervals::      
* Assigning Intervals::         
* Simultaneous Interval Init & Assign::  

@detailmenu
 --- The Detailed Node Listing ---

Interval Functions

* Return Values::
* Precision Handling::
* Initializing and Assigning Intervals::  
* Floating-point Quantities::   
* Converting Intervals::        
* Interval Arithmetic::         
* Special Functions::           
* Interval Comparison::         
* I/O of Intervals::            
* Operating on the Endpoints::  
* Set Operations::              
* Miscellaneous Interval Functions::  
* Error Handling::              

Initialization and Assignment Functions

* Initializing Intervals::      
* Assigning Intervals::         
* Simultaneous Interval Init & Assign::  

@end detailmenu
@end menu

@node Copying, Introduction to MPFI, Top, Top
@comment  node-name, next, previous,  up
@unnumbered MPFI Copying Conditions
@cindex Copying conditions
@cindex Conditions for copying MPFI

This library is @dfn{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.@refill

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.@refill

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
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.@refill

Also, for our own protection, we must make certain that everyone finds out
that there is no warranty for the 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.@refill

The precise conditions of the license for the MPFI library are found in the
Lesser General Public License that accompany the source code.
As MPFI is built upon MPFR and share its license,
see the file COPYING.LESSER in the main MPFR directory.@refill

@node Introduction to MPFI, Installing MPFI, Copying, Top
@comment  node-name,  next,  previous,  up
@chapter 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.  The purpose of an arbitrary precision interval arithmetic is on the
one hand to get @dfn{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 rounding provided, for each operation or function, by MPFR.  Further
advantages of using MPFR are its portability and compliance with the IEEE 754
standard for floating-point arithmetic.


This version of MPFI is released under the GNU Lesser General Public
License.
It is permitted to link MPFI to non-free programs, as long as when
distributing them the MPFI source code and a means to re-link with a
modified MPFI is provided.

As interval arithmetic currently undergoes standardization, through
the work of the IEEE-1788 working group, future versions of MPFI
may evolve in order to reflect the standardized definitions and behaviours.


@c @section How to use this Manual
@c 
@c Everyone should read @ref{MPFI Basics}.  If you need to install the library
@c yourself, you need to read @ref{Installing MPFI}, too.
@c 
@c The rest of the manual can be used for later reference, although it is
@c probably a good idea to glance through it.


@node Installing MPFI, Reporting Bugs, Introduction to MPFI, Top
@comment  node-name,  next,  previous,  up
@chapter Installing MPFI
@cindex Installation

To build MPFI, you first have to install MPFR (version 4.0.1 or above)
on your computer.
You need a C compiler, preferably GCC, but any reasonable compiler
should work.
And you need a standard Unix @samp{make} program, plus some other
standard Unix utility programs.

@section How to Install

Here are the steps needed to install the MPFI library on Unix systems.
In the MPFI source directory, type the following commands.

@enumerate
@item
@samp{./configure}

This will prepare the build and setup the options according to your system.
You can give options to specify the install directories (instead of the
default @file{/usr/local}), and so on.

You can specify the path to GMP and MPFR libraries with configure
options: @samp{--with-gmp=DIR} assumes that GMP is installed in the
@samp{DIR} directory.
Alternatively, you can use the @samp{--with-gmp-lib=DIR} and
@samp{--with-gmp-include=DIR} to specify respectively the GMP lib and GMP
include directories.
Options @samp{--with-mpfr=DIR}, @samp{--with-mpfr-include=DIR}, and
@samp{--with-mpfr-lib=DIR} have the same usage for the MPFR library.

See the @file{INSTALL} file and the output of @samp{./configure
--help} for a description of standard options.

@item
@samp{make}

This will compile MPFI, and create a library archive file @file{libmpfi.a}.
On most platforms, a dynamic library will be produced too.

@item
@samp{make check}

This will make sure MPFI was built correctly.
If any test fails, information about this failure can be found in the
@file{tests/test-suite.log} file. If you want the contents of this file to
be automatically output in case of failure, you can set the @samp{VERBOSE}
environment variable to 1 before running @samp{make check}, for instance
by typing:

@samp{VERBOSE=1 make check}

If you get error messages from the test program, please
report this to
@samp{mpfi-users@@lists.gforge.inria.fr}.
(See @xref{Reporting Bugs}, for information on what to include in useful
bug reports.)

@item
@samp{make install}

This will copy
the file @file{mpfi.h} to the directory @file{/usr/local/include},
the library files (@file{libmpfi.a} and possibly others) to the directory
@file{/usr/local/lib},
the file @file{mpfi.info} to the directory @file{/usr/local/share/info},
and some other documentation files to the directory
@file{/usr/local/share/doc/mpfi}
(or if you passed the @samp{--prefix} option to @file{configure},
using the prefix directory given as argument to @samp{--prefix}
instead of @file{/usr/local}).
@end enumerate

@section Other `make' targets

There are some other useful make targets:

@itemize @bullet
@item
@samp{info}

Create an info version of the manual, in @file{mpfi.info}.

This file is already provided in the MPFI archives.

@item
@samp{pdf}

Create a PDF version of the manual, in @file{mpfi.pdf}.

@item
@samp{dvi}

Create a DVI version of the manual, in @file{mpfi.dvi}.

@item
@samp{ps}

Create a Postscript version of the manual, in @file{mpfi.ps}.

@item
@samp{html}
Create a HTML version of the manual, in @file{mpfi.html}.

@item
@samp{clean}

Delete all object files and archive files, but not the configuration files.

@item
@samp{uninstall}
Delete all files copied by @samp{make install}.
@end itemize


@section Known Build Problems

The installation procedure and MPFI itself have been tested
only on 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 @samp{mpfi-users@@lists.gforge.inria.fr}.
@xref{Reporting Bugs}.

@section Getting the Latest Version of MPFI

The latest version of MPFI is available from
@url{https://gforge.inria.fr/frs/?group_id=157}.


@node Reporting Bugs, MPFI Basics, Installing MPFI, Top
@comment  node-name,  next,  previous,  up
@chapter Reporting Bugs
@cindex 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 we expect
you will 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 @samp{cc -V} on some machines or,
if you're using gcc, @samp{gcc -v}.  Also, include the output from @samp{uname
-a}, along with the version of GMP and of MPFR you use.

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: @samp{mpfi-users@@lists.gforge.inria.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.


@node MPFI Basics, Interval Functions, Reporting Bugs, Top
@comment  node-name,  next,  previous,  up
@chapter MPFI Basics


@cindex @file{mpfi.h}
All declarations needed to use MPFI are collected in the include file
@file{mpfi.h}. The declarations useful for inputs and outputs are to be found
in @file{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:

@example
#include "mpfi.h"
#include "mpfi_io.h"
@end example

@section Nomenclature and Types

As MPFI is built upon MPFR, it is advisable to read MPFR's manual first.

@cindex Interval
@tindex @code{mpfi_t}
@noindent
An @dfn{interval} is a closed 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 @code{mpfi_t}.

MPFI functions operate on valid intervals (defined below), their behavior with
non-valid intervals as input is undefined.
@itemize
@item
A @dfn{valid interval} can have finite or infinite endpoints, but its left
endpoint is not larger than its right endpoint and cannot be +infinity or -0
(respectively, the right endpoint cannot be -infinity or +0). @footnote{The
restriction on the infinite values follows the definition of interval, and the
sign of the zero bounds allows a simple implementation of the four arithmetic
operations as explained in the paper of T. Hickey, Q. Ju, and M. H. Van Emden,
@cite{Interval arithmetic: From principles to implementation}
(@xref{References}).}  As a consequence, the unique representation of the zero
singleton is @math{[+0, -0]}.
@end itemize

MPFI functions may return intervals that are not valid as input value. Their
semantic defined as follows:
@itemize
@item
One (or both) NaN endpoint(s) indicates that an invalid operation has been
performed and that the resulting interval has no mathematical meaning.
@item
An @dfn{empty interval} has its left endpoint larger than its right endpoint.
@end itemize

Both the meaning of "invalid operation", the representation of the empty set
and its handling may change in future versions of MPFI, according to the
standardization of interval arithmetic in IEEE-1788.

Some functions on intervals return a floating-point value: among such
functions are @code{mpfi_get_left} that returns the left endpoint of
an interval and @code{mpfi_diam_abs} that gets the width of the
input interval.

@cindex Floating-point number
@tindex @code{mpfr_t}
@noindent
A @dfn{Floating point number} or @dfn{Float} for short, is an arbitrary precision
significand (aslso called mantissa) with a limited precision exponent.  The C data type for such objects
is @code{mpfr_t}.

@cindex Precision
@tindex @code{mpfr_prec_t}
@comment a changer en mpfr_prec_t quand on demandera MPFR 3.0.0 ou plus
@noindent
The @dfn{Precision} is the number of bits used to represent the significand
of a floating-point number;
the corresponding C data type is @code{mpfr_prec_t} (renamed
@code{mpfr_prec_t} since MPFR version 3.0.0, both types are
compatible).

MPFI assumes that both endpoints of an interval use the same precision.
@c The behaviour is undefined if this is not the case.
However when this does not hold, the largest precision is considered. 


@section Function Classes

There is only one class of functions in the MPFI library:

@enumerate
@item
@tindex @code{mpfi_t}
Functions for interval arithmetic based on floating-point numbers,
with names beginning with
@code{mpfi_}.  The associated type is @code{mpfi_t}.  There are around 170
functions in this class.
@end enumerate


@section 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,
@code{mpfi_exp}, can be used like this: @code{mpfi_exp (x, x)}.  
This
computes the set of exponentials of every real belonging to @var{x}
and puts the result back in @var{x}.

Before you can give a value to 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 only once, or at least be 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.

@c TO DO later: a section on "Special values and exceptions" and possibly a section on "Memory handling / Multithreading"

@node Interval Functions, Contributors, MPFI Basics, Top
@comment  node-name,  next,  previous,  up
@chapter Interval Functions
@cindex Interval functions

The interval functions expect arguments of type @code{mpfi_t}.

The MPFI interval functions have an interface that is close to the 
corresponding MPFR
functions.  The function prefix for interval operations is
@code{mpfi_}.

MPFI intervals are represented by their endpoints; this representation
should be invisible to the user, unfortunately it is not...
@c An alternative representation could be to store the center and the
@c radius of the interval.
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.
@cindex User-defined precision
For more information on precision (precision of a variable,
precision of a calculation), see the MPFR documentation.


@menu
* Return Values::
* Precision Handling::
* Initializing and Assigning Intervals::  
* Floating-point Quantities::   
* Converting Intervals::        
* Interval Arithmetic::         
* Special Functions::           
* Interval Comparison::         
* I/O of Intervals::            
* Operating on the Endpoints::  
* Set Operations::              
* Miscellaneous Interval Functions::  
* Error Handling::              
@end menu

@comment @node Return Values, Rounding Modes and Precision Handling, Interval Functions, Interval Functions
@node Return Values, Precision Handling, Interval Functions, Interval Functions
@comment  node-name,  next,  previous,  up
@cindex Return values
@section Return Values

Four integer values (of C type @code{int})
can be returned by a typical @code{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:
@itemize @bullet
@tindex @code{MPFI_FLAGS_BOTH_ENDPOINTS_EXACT}
@item @code{MPFI_FLAGS_BOTH_ENDPOINTS_EXACT}
@tindex @code{MPFI_FLAGS_LEFT_ENDPOINT_INEXACT}
@item @code{MPFI_FLAGS_LEFT_ENDPOINT_INEXACT}: the left endpoint is inexact
whereas the right endpoint is exact;
@tindex @code{MPFI_FLAGS_RIGHT_ENDPOINT_INEXACT}
@item @code{MPFI_FLAGS_RIGHT_ENDPOINT_INEXACT}: the right endpoint is inexact
whereas the left endpoint is exact;
@tindex @code{MPFI_FLAGS_BOTH_ENDPOINTS_INEXACT}
@item @code{MPFI_FLAGS_BOTH_ENDPOINTS_INEXACT}
@end itemize
To test the exactness of one endpoint, the following functions are available
(their names are self-explanatory):
@itemize @bullet
@tindex @code{MPFI_BOTH_ARE_EXACT}
@item @code{MPFI_BOTH_ARE_EXACT}
@tindex @code{MPFI_LEFT_IS_INEXACT}
@item @code{MPFI_LEFT_IS_INEXACT}
@tindex @code{MPFI_RIGHT_IS_INEXACT}
@item @code{MPFI_RIGHT_IS_INEXACT}
@tindex @code{MPFI_BOTH_ARE_INEXACT}
@item @code{MPFI_BOTH_ARE_INEXACT}
@end itemize


@comment @node Rounding Modes and Precision Handling, Initializing and Assigning Intervals, Return Values, Interval Functions
@node Precision Handling, Initializing and Assigning Intervals, Return Values, Interval Functions
@comment  node-name,  next,  previous,  up
@comment @cindex Rounding modes
@cindex Precision
@section Precision Handling

@comment Only two rounding modes are useful when computing with intervals
@comment represented by their endpoints, namely downward and upward roundings
@comment used for outward rounding:
@comment @itemize @bullet
@comment @item @code{MPFI_RNDU}: round towards plus infinity
@comment @item @code{MPFI_RNDD}: round towards minus infinity
@comment @end itemize
@comment The four rounding modes provided by MPFR are still available,
@comment see MPFR documentation to get their names and information on how
@comment 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):

@deftypefn Macro void mpfr_set_default_prec (mpfr_prec_t @var{prec})
Sets the default precision to be @strong{exactly} @var{prec} bits.  The
precision of a variable means the number of bits used to store the significands
of its endpoints.
All
subsequent calls to @code{mpfi_init} will use this precision, but previously
initialized variables are unaffected.
This default precision is set to 53 bits initially.
The precision @var{prec} can be any integer between @code{MPFR_PREC_MIN} and
@code{MPFR_PREC_MAX}.

Note: when MPFR is built with the @samp{--enable-thread-safe} configure option,
the default precision is local to each thread. See MPFR documentation for more information.
@end deftypefn

@deftypefn Macro mpfr_prec_t mpfr_get_default_prec ()
Returns the default MPFR/MPFI precision in bits.
@end deftypefn

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.

@deftypefun void mpfi_set_prec (mpfi_t @var{x}, mpfr_prec_t @var{prec})
Resets the precision of @var{x} to be @strong{exactly} @var{prec} bits.
The previous value stored in @var{x} is lost. It is equivalent to
a call to @code{mpfi_clear(x)} followed by a call to 
@code{mpfi_init2(x, prec)}, but more efficient as no allocation is done in
case the current allocated space for the significands of the endpoints
of @var{x} is enough.
The precision @var{prec} can be any integer between @code{MPFR_PREC_MIN} and
@code{MPFR_PREC_MAX}.
In case you want to keep the previous value stored in @var{x},
use @code{mpfi_round_prec} instead.
@end deftypefun

@deftypefun mpfr_prec_t mpfi_get_prec (mpfi_t @var{x})
Return the largest precision actually used for assignments of @var{x}, i.e.\
the number of bits used to store the significands of its endpoints.
Should the two endpoints have different precisions, the largest one is returned.
@end deftypefun

@deftypefun int mpfi_round_prec (mpfi_t @var{x}, mpfr_prec_t @var{prec})
Rounds @var{x} with precision @var{prec}, which
may be different from that of @var{x}. 
If @var{prec} is greater or equal to the precision of @var{x}, then new
space is allocated for the endpoints' significands, and they are filled with zeroes.
Otherwise, the significands are rounded outwards to precision @var{prec}.
In both cases, the precision of @var{x} is changed to @var{prec}.
It returns a value indicating whether the possibly rounded endpoints are exact or not,
cf. @ref{Return Values}.
@end deftypefun

@comment @node Initializing and Assigning Intervals, Floating-point Quantities, Rounding Modes and Precision Handling, Interval Functions
@node Initializing and Assigning Intervals, Floating-point Quantities, Precision Handling, Interval Functions
@comment  node-name,  next,  previous,  up
@section Initialization and Assignment Functions

@menu
* Initializing Intervals::      
* Assigning Intervals::         
* Simultaneous Interval Init & Assign::  
@end menu

@node Initializing Intervals, Assigning Intervals, Initializing and Assigning Intervals, Initializing and Assigning Intervals
@comment  node-name,  next,  previous,  up
@subsection Initialization Functions
@cindex Interval initialization functions

An @code{mpfi_t} object must be initialized before storing the first value in
it.  The functions @code{mpfi_init} and @code{mpfi_init2} are used for that
purpose.

@deftypefun void mpfi_init (mpfi_t @var{x})
Initializes @var{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 @code{mpfi_clear}, between consecutive
initializations.  The
precision of @var{x} is the default precision, which can be changed
by a call to @code{mpfr_set_default_prec}.

Warning! In a given program, some other libraries might change the default
precision and not restore it. Thus it is safer to use @code{mpfi_init2}.
@end deftypefun

@deftypefun void mpfi_init2 (mpfi_t @var{x}, mpfr_prec_t @var{prec})
Initializes @var{x}, sets its precision (or more precisely the precision
of its endpoints) to be @strong{exactly}
@var{prec} bits, and sets its endpoints to NaN.
Normally, a variable should be initialized once only or at
least be cleared, using @code{mpfi_clear}, between consecutive initializations.
To change the precision of a variable which has already been initialized,
use @code{mpfi_set_prec} instead, or @code{mpfi_round_prec} if you want to keep its value.
@end deftypefun

@deftypefun void mpfi_clear (mpfi_t @var{x})
Frees the space occupied by the significands of the endpoints of @var{x}.  Make sure to call this function for all
@code{mpfi_t} variables when you are done with them.
@end deftypefun


@need 2000
Here is an example on how to initialize interval variables:
@example
@{
  mpfi_t x, y;
  mpfi_init (x);			/* use default precision */
  mpfi_init2 (y, 256);		/* precision @emph{exactly} 256 bits */
  @dots{}
  /* Unless the program is about to exit, do ... */
  mpfi_clear (x);
  mpfi_clear (y);
@}
@end example

@deftypefun void mpfi_inits (mpfi_t @var{x}, ...)
Initialize all the @code{mpfi_t} variables of the given @code{va_list},
set their precision to the default precision and their value to NaN@.
See @code{mpfi_init} for more details.
The @code{va_list} is assumed to be composed only of type @code{mpfi_t}
(or equivalently @code{mpfi_ptr}).
It begins from @var{x}, and ends when it encounters a null pointer (whose
type must also be @code{mpfi_ptr}).

Warning! In a given program, some other libraries might change the default
precision and not restore it. Thus it is safer to use @code{mpfi_inits2}.
@end deftypefun

@deftypefun void mpfi_inits2 (mpfr_prec_t @var{prec}, mpfi_t @var{x}, ...)
Initialize all the @code{mpfi_t} variables of the given variable
argument @code{va_list}, set their precision to be @strong{exactly}
@var{prec} bits and their value to NaN@.
See @code{mpfi_init2} for more details.
The @code{va_list} is assumed to be composed only of type @code{mpfi_t}
(or equivalently @code{mpfi_ptr}).
It begins from @var{x}, and ends when it encounters a null pointer (whose
type must also be @code{mpfi_ptr}).
@end deftypefun

@deftypefun void mpfi_clears (mpfi_t @var{x}, ...)
Free the space occupied by all the @code{mpfi_t} variables of the given
@code{va_list}. See @code{mpfi_clear} for more details.
The @code{va_list} is assumed to be composed only of type @code{mpfi_t}
(or equivalently @code{mpfi_ptr}).
It begins from @var{x}, and ends when it encounters a null pointer (whose
type must also be @code{mpfi_ptr}).
@end deftypefun

Here is an example of how to use multiple initialization functions
(since @code{NULL} is not necessarily defined in this context, we use
@code{(mpfi_ptr) 0} instead, but @code{(mpfi_ptr) NULL} is also correct).

@example
@{
  mpfi_t a, b, c;

  mpfi_inits (a, b, c, (mpfi_ptr) 0); /* Use default precision */
  @dots{}
  mpfi_clears (a, b, c, (mpfi_ptr) 0);

  /* Another possibility is to specify the precision */
  mpfi_inits2 (200, a, b, c, (mpfi_ptr) 0); /* Use @emph{exactly} 200 bits */
  @dots{}
  mpfi_clears (a, b, c, (mpfi_ptr) 0);
@}
@end example


@node Assigning Intervals, Simultaneous Interval Init & Assign, Initializing Intervals, Initializing and Assigning Intervals
@comment  node-name,  next,  previous,  up
@subsection Assignment Functions
@cindex Interval assignment functions

These functions assign new values to already initialized intervals
(@pxref{Initializing Intervals}).

@deftypefun int mpfi_set (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_set_ui (mpfi_t @var{rop}, unsigned long int @var{op})
@deftypefunx int mpfi_set_si (mpfi_t @var{rop}, long int @var{op})
@deftypefunx int mpfi_set_d (mpfi_t @var{rop}, double @var{op})
@deftypefunx int mpfi_set_flt (mpfi_t @var{rop}, float @var{op})
@deftypefunx int mpfi_set_ld (mpfi_t @var{rop}, long double @var{op})
@deftypefunx int mpfi_set_z (mpfi_t @var{rop}, mpz_t @var{op})
@deftypefunx int mpfi_set_q (mpfi_t @var{rop}, mpq_t @var{op})
@deftypefunx int mpfi_set_fr (mpfi_t @var{rop}, mpfr_t @var{op})
Sets the value of @var{rop} from @var{op}, rounded outward to the precision of @var{rop}:
@var{op} then belongs to @var{rop}.
The returned value indicates whether none, one or both endpoints are exact.
Please note that even a @code{long int} may have to be rounded,
if the destination precision is less than the machine word width.

No support (yet) for huge (signed or unsigned) integer, nor for float128, nor for decimal64.
@end deftypefun

@deftypefun int mpfi_set_str (mpfi_t @var{rop}, char *@var{s}, int @var{base})
Sets @var{rop} to the value of the string @var{s}, in base @var{base} (between
2 and 36), outward rounded to the precision of @var{rop}:
@var{op} then belongs to @var{rop}.
The exponent is read in decimal.
The string is of the form @samp{number} or
@samp{[ number1 , number 2 ]}.
@c where the spaces around the floating-point endpoints are mandatory.
Each endpoint has the form @samp{M@@N} or, if the
base is 10 or less, alternatively @samp{MeN} or @samp{MEN}.
@samp{M} is the significand and
@samp{N} is the exponent.  The significand is always in the specified base.  The
exponent is 
@c either in the specified base or, if @var{base} is negative, 
in decimal.
The argument @var{base} may be in the ranges 2 to 36.

This function returns 1 if the input is incorrect, and 0 otherwise.
@end deftypefun

@deftypefun void mpfi_swap (mpfi_t @var{x}, mpfi_t @var{y})
Swaps the values @var{x} and @var{y} efficiently. Warning: the
precisions are exchanged too; in case the precisions are different,
@code{mpfi_swap} is thus not equivalent to three @code{mpfi_set} calls
using a third auxiliary variable.
@end deftypefun

@node Simultaneous Interval Init & Assign,  , Assigning Intervals, Initializing and Assigning Intervals
@comment  node-name,  next,  previous,  up
@subsection Combined Initialization and Assignment Functions
@cindex Initialization and assignment functions

@deftypefun int mpfi_init_set (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_init_set_ui (mpfi_t @var{rop}, unsigned long int @var{op})
@deftypefunx int mpfi_init_set_si (mpfi_t @var{rop}, long int @var{op})
@deftypefunx int mpfi_init_set_d (mpfi_t @var{rop}, double @var{op})
@deftypefunx int mpfi_init_set_z (mpfi_t @var{rop}, mpz_t @var{op})
@deftypefunx int mpfi_init_set_q (mpfi_t @var{rop}, mpq_t @var{op})
@deftypefunx int mpfi_init_set_fr (mpfi_t @var{rop}, mpfr_t @var{op})
Initializes @var{rop} and sets its value from @var{op}, outward rounded so
that @var{op} belongs to @var{rop}.
The precision of @var{rop} will be taken from the active default precision,
as set by @code{mpfr_set_default_prec}.
The returned value indicates whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_init_set_str (mpfi_t @var{rop}, char *@var{s}, int @var{base})
Initializes @var{rop} and sets its value 
to the value of the string @var{s}, in base @var{base} (between
2 and 36), outward rounded to the precision of @var{rop}:
@var{op} then belongs to @var{rop}. The exponent is read in decimal. 
See @code{mpfi_set_str}.
@end deftypefun


@node Floating-point Quantities, Converting Intervals, Initializing and Assigning Intervals, Interval Functions
@comment  node-name,  next,  previous,  up
@section Interval Functions with Floating-point Results
@cindex 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.

@deftypefun int mpfi_diam_abs (mpfr_t @var{rop}, mpfi_t @var{op})
Sets the value of @var{rop} to the upward rounded diameter of @var{op},
or in other words to the upward rounded difference between the right endpoint
of @var{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.
@end deftypefun

@deftypefun int mpfi_diam_rel (mpfr_t @var{rop}, mpfi_t @var{op})
Sets the value of @var{rop} to the upward rounded relative diameter of @var{op},
or in other words to the upward rounded difference between the right endpoint
of @var{op} and its left endpoint, divided by the absolute value
of the center of @var{op} if it is not zero.
Returns 0 if the result is exact and a positive value if the returned value
is an overestimation, in this case the returned value may not be the correct
rounding of the exact value.
@end deftypefun

@deftypefun int mpfi_diam (mpfr_t @var{rop}, mpfi_t @var{op})
Sets the value of @var{rop} to the relative diameter of @var{op}
if @var{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, it may not be the correct rounding of the exact value
in the latter case.
@end deftypefun

@deftypefun int mpfi_mag (mpfr_t rop, mpfi_t op)
Sets the value of @var{rop} to the magnitude of @var{op},
i.e.\ to the largest absolute value of the elements of @var{op}.
Returns 0 if the result is exact and a positive value if the returned value
is an overestimation.
@end deftypefun

@deftypefun int mpfi_mig (mpfr_t rop, mpfi_t op)
Sets the value of @var{rop} to the mignitude of @var{op},
i.e.\ to the smallest absolute value of the elements of @var{op}.
Returns 0 if the result is exact and a negative value if the returned value
is an underestimation.
@end deftypefun

@deftypefun int mpfi_mid (mpfr_t rop, mpfi_t op)
Sets @var{rop} to the middle of @var{op}.
Returns 0 if the result is exact, a positive value if @var{rop} > the
middle of @var{op} and a negative value if @var{rop} < the middle of @var{op}.
@end deftypefun

@deftypefun void mpfi_alea (mpfr_t rop, mpfi_t op)
Sets @var{rop} to a floating-point number
picked up at random in @var{op}, according to a uniform distribution.

This function is deprecated and may disappear in future versions of MPFI;
@code{mpfi_urandom} should be used instead.
@end deftypefun

@deftypefun void mpfi_urandom (mpfr_t rop, mpfi_t op, gmp_randstate_t state)
Sets @var{rop} to a floating-point number picked up at random in
@var{op}, according to a uniform distribution.

The argument @var{state} should be initialized with one of the GMP
random state initialization functions
@ifinfo
(@pxref{Random State Initialization,,, gmp.info,GNU MP}).
@end ifinfo
@ifnotinfo
(see Section ``Random State Initialization'' in @cite{GNU MP} manual).
@end ifnotinfo
@end deftypefun

@deftypefun void mpfi_nrandom (mpfr_t rop, mpfi_t op, gmp_randstate_t state)
Sets @var{rop} to a floating-point number picked up at random in
@var{op}, according to a normal distribution.

The argument @var{state} should be initialized as for @code{mpfi_urandom}.

Caveat: the normal distribution on the set of floating-point numbers is different from the normal distribution on the set of real numbers. No guarantee is given on the quality of the distribution.
@end deftypefun

@deftypefun void mpfi_erandom (mpfr_t rop, mpfi_t op, gmp_randstate_t state)
Sets @var{rop} to a floating-point number picked up at random in
@var{op}, according to an exponential distribution.

The argument @var{state} should be initialized as for @code{mpfi_urandom}.

Caveat: the exponential distribution on the set of floating-point numbers is different from the exponential distribution on the set of real numbers. No guarantee is given on the quality of the distribution.
@end deftypefun


@node Converting Intervals, Interval Arithmetic, Floating-point Quantities, Interval Functions
@comment  node-name,  next,  previous,  up
@section Conversion Functions
@cindex Conversion functions

@deftypefun double mpfi_get_d (mpfi_t @var{op})
Converts @var{op} to a double, which is the center of @var{op} rounded to the
nearest double.
@end deftypefun

@deftypefun void mpfi_get_fr (mpfr_t @var{rop}, mpfi_t @var{op})
Converts @var{op} to a floating-point number, which is the center of @var{op}
rounded to nearest.
@end deftypefun


@node Interval Arithmetic, Special Functions, Converting Intervals, Interval Functions
@comment  node-name,  next,  previous,  up
@section Basic Arithmetic Functions
@cindex Interval arithmetic functions
@cindex Arithmetic functions

@deftypefun int mpfi_add      (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_add_d    (mpfi_t @var{rop}, mpfi_t @var{op1}, double @var{op2})
@deftypefunx int mpfi_add_ui   (mpfi_t @var{rop}, mpfi_t @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpfi_add_si   (mpfi_t @var{rop}, mpfi_t @var{op1}, long int @var{op2})
@deftypefunx int mpfi_add_z    (mpfi_t @var{rop}, mpfi_t @var{op1}, mpz_t @var{op2})
@deftypefunx int mpfi_add_q    (mpfi_t @var{rop}, mpfi_t @var{op1}, mpq_t @var{op2})
@deftypefunx int mpfi_add_fr (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfr_t @var{op2})
Sets @var{rop} to @var{op1} + @var{op2}.
Returns a value indicating whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_sub (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_sub_d (mpfi_t @var{rop}, mpfi_t @var{op1}, double @var{op2})
@deftypefunx int mpfi_d_sub (mpfi_t @var{rop}, double @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_sub_ui (mpfi_t @var{rop}, mpfi_t @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpfi_ui_sub (mpfi_t @var{rop}, unsigned long int @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_sub_si (mpfi_t @var{rop}, mpfi_t @var{op1}, long int @var{op2})
@deftypefunx int mpfi_si_sub (mpfi_t @var{rop}, long int @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_sub_z (mpfi_t @var{rop}, mpfi_t @var{op1}, mpz_t @var{op2})
@deftypefunx int mpfi_z_sub (mpfi_t @var{rop}, mpz_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_sub_q (mpfi_t @var{rop}, mpfi_t @var{op1}, mpq_t @var{op2})
@deftypefunx int mpfi_q_sub (mpfi_t @var{rop}, mpq_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_sub_fr (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfr_t @var{op2})
@deftypefunx int mpfi_fr_sub (mpfi_t @var{rop}, mpfr_t @var{op1}, mpfi_t @var{op2})
Sets @var{rop} to @var{op1} @minus{} @var{op2}.
Returns a value indicating whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_mul (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_mul_d (mpfi_t @var{rop}, mpfi_t @var{op1}, double @var{op2})
@deftypefunx int mpfi_mul_ui (mpfi_t @var{rop}, mpfi_t @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpfi_mul_si (mpfi_t @var{rop}, mpfi_t @var{op1}, long int @var{op2})
@deftypefunx int mpfi_mul_z (mpfi_t @var{rop}, mpfi_t @var{op1}, mpz_t @var{op2})
@deftypefunx int mpfi_mul_q (mpfi_t @var{rop}, mpfi_t @var{op1}, mpq_t @var{op2})
@deftypefunx int mpfi_mul_fr (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfr_t @var{op2})
@c @ifinfo
Sets @var{rop} to @var{op1} * @var{op2}.
@c @end ifinfo
@c @iftex
@c @tex
@c Set @var{rop} to $@var{op1} \times @var{op2}$.
@c @end tex
@c @end iftex
Multiplication by an interval containing only zero results in 0.
Returns a value indicating whether none, one or both endpoints are exact.
@end deftypefun


@ifinfo
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,
@c the rules defined by the IEEE 754 norm for the division by signed zeroes apply:
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.
@end ifinfo
@iftex
@tex
Division is defined even if the divisor contains zero: when the divisor
contains zero in its interior, the result is the whole real interval $[-\infty, \infty]$.
When the divisor has one of its endpoints equal to 0,
the rules defined by the IEEE 754 norm for the division by signed zeroes
apply: for instance, $[1,2]/[0^+,1]$ results in $[1, \infty]$.
@end tex
@end iftex
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.

@deftypefun int mpfi_div (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_div_d (mpfi_t @var{rop}, mpfi_t @var{op1}, double @var{op2})
@deftypefunx int mpfi_d_div (mpfi_t @var{rop}, double @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_div_ui (mpfi_t @var{rop}, mpfi_t @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpfi_ui_div (mpfi_t @var{rop}, unsigned long int @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_div_si (mpfi_t @var{rop}, mpfi_t @var{op1}, long int @var{op2})
@deftypefunx int mpfi_si_div (mpfi_t @var{rop}, long int @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_div_z (mpfi_t @var{rop}, mpfi_t @var{op1}, mpz_t @var{op2})
@deftypefunx int mpfi_z_div (mpfi_t @var{rop}, mpz_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_div_q (mpfi_t @var{rop}, mpfi_t @var{op1}, mpq_t @var{op2})
@deftypefunx int mpfi_q_div (mpfi_t @var{rop}, mpq_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_div_fr (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfr_t @var{op2})
@deftypefunx int mpfi_fr_div (mpfi_t @var{rop}, mpfr_t @var{op1}, mpfi_t @var{op2})
Sets @var{rop} to @var{op1}/@var{op2}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_neg (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to @minus{}@var{op}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_sqr (mpfi_t @var{rop}, mpfi_t @var{op})
@ifinfo
Sets @var{rop} to the nonnegative square of @var{op}.
@end ifinfo
@iftex
@tex
Sets @var{rop} to $@var{op} ^2$.
@end tex
@end iftex
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.
@end deftypefun

@deftypefun int mpfi_inv (mpfi_t @var{rop}, mpfi_t @var{op})
@ifinfo
Sets @var{rop} to 1/@var{op}.
Inverse is defined even if the interval contains zero: when the denominator
contains zero, the result is the whole real interval ]-Inf, Inf[.
@end ifinfo
@iftex
@tex
Sets @var{rop} to $1/@var{op}$.
Inversion is defined even if the interval contains zero: when the denominator
contains zero, the result is the whole real interval $[-\infty, \infty]$.
@end tex
@end iftex
Returns an indication of whether none, one or both endpoints are exact.
@c Signed zeroes, introduced in the IEEE 754 norm for
@c interval arithmetic, are not yet taken into account.
@end deftypefun

@deftypefun int mpfi_sqrt (mpfi_t @var{rop}, mpfi_t @var{op})
@ifinfo
Sets @var{rop} to the square root of @var{op}.
@end ifinfo
@iftex
@tex
Sets @var{rop} to $\sqrt{@var{op}}$.
@end tex
@end iftex
Sets @var{rop} to NaN if @var{op} is negative.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_cbrt (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the cubic root of @var{op}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_abs (mpfi_t @var{rop}, mpfi_t @var{op})
@ifinfo
Sets @var{rop} to the interval containing the absolute value of every element of @var{op}.
@end ifinfo
@iftex
@tex
Sets @var{rop} to $|@var{op} |$, the absolute value of @var{op}.
@end tex
@end iftex
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_mul_2exp (mpfi_t @var{rop}, mpfi_t @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpfi_mul_2ui (mpfi_t @var{rop}, mpfi_t @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpfi_mul_2si (mpfi_t @var{rop}, mpfi_t @var{op1}, long int @var{op2})
@ifinfo
Sets @var{rop} to @var{op1} times 2 raised to @var{op2}.

@code{mpfi_mul_2exp} is identical to @code{mpfi_mul_2ui} and is kept for compatibility
with former versions of MPFI only. It is deprecated and could disappear in future versions of MPFI.
@end ifinfo
@iftex
@tex
Sets @var{rop} to $@var{op1} \times 2^{op2}$.
@end tex
@end iftex
Returns an indication of whether none, one or both endpoints are exact.
Just increases the exponents of the endpoints by @var{op2}
when @var{rop} and @var{op1} are identical.
@end deftypefun

@deftypefun int mpfi_div_2exp (mpfi_t @var{rop}, mpfi_t @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpfi_div_2ui (mpfi_t @var{rop}, mpfi_t @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpfi_div_2si (mpfi_t @var{rop}, mpfi_t @var{op1}, long int @var{op2})
@ifinfo
Sets @var{rop} to @var{op1} divided by 2 raised to @var{op2}.
@end ifinfo
@iftex
@tex
Sets @var{rop} to $@var{op1}/2^{op2}$.
@end tex
@end iftex
Returns an indication of whether none, one or both endpoints are exact.
Just decreases the exponents of the endpoints by @var{op2}
when @var{rop} and @var{op1} are identical.
@end deftypefun

@node Special Functions, Interval Comparison, Interval Arithmetic, Interval Functions
@comment  node-name,  next,  previous,  up
@section Special Functions
@cindex Special functions

These functions are based on their MPFR counterparts. For more information,
see the MPFR documentation or related bibliography.

@deftypefun int mpfi_log (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the natural logarithm of @var{op},
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
If @var{op} contains negative numbers, then @var{rop} has at least one
NaN endpoint.
@end deftypefun

@deftypefun int mpfi_exp (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the exponential of @var{op},
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_exp2 (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to 2 to the power @var{op}, with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_cos (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_sin (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_tan (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the cosine, sine or tangent of @var{op},
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun


@deftypefun int mpfi_sec (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_csc (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_cot (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the secant, cosecant or cotangent of @var{op},
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun


@c @deftypefun void mpfi_sin_cos (mpfi_t @var{sop}, mpfi_t @var{cop}, mpfi_t @var{op})
@c Sets @var{sop} to the sine of @var{op}, @var{cop} to the cosine of @var{op},
@c with the precision of the result (@var{sop} and @var{cop}).
@c @var{sop} and @var{cop} must be different variables.
@c If one of @var{sop} or @var{cop} is NULL, only the other value is returned.
@c @end deftypefun

@deftypefun int mpfi_acos (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_asin (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_atan (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the arc-cosine, arc-sine or arc-tangent of @var{op},
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_atan2 (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfi_t @var{op2})
Sets @var{rop} to the arc-tangent2 of @var{op1} and @var{op2},
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_cosh (mpfi_t @var{cop}, mpfi_t @var{op})
@deftypefunx int mpfi_sinh (mpfi_t @var{sop}, mpfi_t @var{op})
@deftypefunx int mpfi_tanh (mpfi_t @var{top}, mpfi_t @var{op})
Sets @var{cop} to the hyperbolic cosine of @var{op}, 
@var{sop} to the hyperbolic sine of @var{op},
@var{top} to the hyperbolic tangent of @var{op},
with the precision of the result.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_sech (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_csch (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_coth (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the hyperbolic secant, cosecant or cotangent of @var{op},
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun


@deftypefun int mpfi_acosh (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_asinh (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_atanh (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the inverse hyperbolic cosine, sine or tangent of @var{op},
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_log1p (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the natural logarithm of one plus @var{op},
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
If @var{op} contains negative numbers, then @var{rop} has at least one
NaN endpoint.
@end deftypefun

@deftypefun int mpfi_expm1 (mpfi_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the exponential of @var{op}, minus one,
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_log2 (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_log10 (mpfi_t @var{rop}, mpfi_t @var{op})
@ifinfo
Sets @var{rop} to log[t] @var{op} with t=2 or 10 the base for the
logarithm, with the precision of @var{rop}.
@end ifinfo
@iftex
@tex
Sets @var{rop} to $\log _t @var{op}$, with $t=2$ or 10 the base for 
the logarithm, with the precision of @var{rop}.
@end tex
@end iftex
Returns an indication of whether none, one or both endpoints are exact.
If @var{op} contains negative numbers, then @var{rop} has at least one
NaN endpoint.
@end deftypefun

@deftypefun int mpfi_hypot (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfi_t @var{op2})
Sets @var{rop} to the euclidean distance between points in @var{op1} and points in @var{op2},
with the precision of @var{rop}.
Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@deftypefun int mpfi_const_log2 (mpfi_t @var{rop})
@deftypefunx int mpfi_const_pi (mpfi_t @var{rop})
@deftypefunx int mpfi_const_euler (mpfi_t @var{rop})
@deftypefunx int mpfi_const_catalan (mpfi_t @var{rop})
@ifinfo
Sets @var{rop} respectively to the logarithm of 2, to the value of Pi,
to the Euler's constant, and to the Catalan's constant, with the
precision of @var{rop}.
@end ifinfo
@iftex
@tex
Sets @var{rop} respectively to the logarithm of 2, to the value of
$\pi$, to the Euler's constant, and to the Catalan's constant, with
the precision of @var{rop}.
@end tex
@end iftex

Returns an indication of whether none, one or both endpoints are exact.
@end deftypefun

@node Interval Comparison, I/O of Intervals, Special Functions, Interval Functions
@comment  node-name,  next,  previous,  up
@section Comparison Functions
@cindex Interval comparisons functions
@cindex 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 greater than all elements of the second one, a
negative value if the first interval has all its elements strictly lower than
all elements of the second one and 0 otherwise, i.e.\ if they overlap or if one
is contained in the other.

@deftypefun int mpfi_cmp (mpfi_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_cmp_d (mpfi_t @var{op1}, double @var{op2})
@deftypefunx int mpfi_cmp_ui (mpfi_t @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpfi_cmp_si (mpfi_t @var{op1}, long int @var{op2})
@deftypefunx int mpfi_cmp_z (mpfi_t @var{op1}, mpz_t @var{op2})
@deftypefunx int mpfi_cmp_q (mpfi_t @var{op1}, mpq_t @var{op2})
@deftypefunx int mpfi_cmp_fr (mpfi_t @var{op1}, mpfr_t @var{op2})
@ifinfo
Compares @var{op1} and @var{op2}.  Return a positive value if @var{op1} >
@var{op2}, zero if @var{op1} overlaps or contains @var{op2}, and a negative value if @var{op1} <
@var{op2}.
@end ifinfo
@iftex
@tex
Compares @var{op1} and @var{op2}.  Return a positive value if $@var{op1} >
@var{op2}$, zero if @var{op1} overlaps, contains or is contained in @var{op2}, and a negative value if $@var{op1}
< @var{op2}$.
@end tex
@end iftex
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.
@end deftypefun

@deftypefun int mpfi_is_pos (mpfi_t @var{op})
Returns a positive value if @var{op} contains only positive numbers,
the left endpoint can be zero.
@end deftypefun

@deftypefun int mpfi_is_strictly_pos (mpfi_t @var{op})
Returns a positive value if @var{op} contains only positive numbers.
@end deftypefun

@deftypefun int mpfi_is_nonneg (mpfi_t @var{op})
Returns a positive value if @var{op} contains only nonnegative numbers.
@end deftypefun

@deftypefun int mpfi_is_neg (mpfi_t @var{op})
Returns a positive value if @var{op} contains only negative numbers,
the right endpoint can be zero.
@end deftypefun

@deftypefun int mpfi_is_strictly_neg (mpfi_t @var{op})
Returns a positive value if @var{op} contains only negative numbers.
@end deftypefun

@deftypefun int mpfi_is_nonpos (mpfi_t @var{op})
Returns a positive value if @var{op} contains only nonpositive numbers.
@end deftypefun

@deftypefun int mpfi_is_zero (mpfi_t @var{op})
Returns a positive value if @var{op} contains only 0.
@end deftypefun

@deftypefun int mpfi_has_zero (mpfi_t @var{op})
Returns a positive value if @var{op} contains 0 (and possibly other numbers).
@end deftypefun

@deftypefun int mpfi_nan_p (mpfi_t @var{op})
Returns non-zero if @var{op} is invalid, i.e.\ at least one of its
endpoints is a Not-a-Number (NaN), zero otherwise.
@end deftypefun

@deftypefun int mpfi_inf_p (mpfi_t @var{op})
Returns non-zero if at least one of the endpoints of @var{op} is 
plus or minus infinity, zero otherwise.
@end deftypefun

@deftypefun int mpfi_bounded_p (mpfi_t @var{op})
Returns non-zero if @var{op} is a bounded interval, i.e.\ neither invalid
nor (semi-)infinite.
@end deftypefun


@node I/O of Intervals, Operating on the Endpoints, Interval Comparison, Interval Functions
@comment  node-name,  next,  previous,  up
@section Input and Output Functions
@cindex Interval input and output functions
@cindex Input functions
@cindex Output functions
@cindex I/O functions

Functions that perform input from a stdio stream, and functions that output to
a stdio stream.  Passing a NULL pointer for a @var{stream} argument to any of
these functions will make them read from @code{stdin} and write to
@code{stdout}, respectively.

When using any of these functions, it is a good idea to include @file{stdio.h}
before @file{mpfr.h}, since that will allow @file{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.

@deftypefun size_t mpfi_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n_digits}, mpfi_t @var{op})
Outputs @var{op} on stdio stream @var{stream}, as a string of digits in
base @var{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 @code{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
@var{n_digits} significant digits, or if @var{n_digits} is 0, the maximum
number of digits accurately representable by @var{op}.
In addition to the significant digits, a decimal point at the right of the
first digit and a
trailing exponent, in the form @samp{eNNN}, are printed.  If @var{base}
is greater than 10, @samp{@@} will be used instead of @samp{e} as
exponent delimiter.

Returns the number of bytes written, or if an error occurred, return 0.

As @code{mpfi_out_str} outputs an enclosure of the input interval, and as
@code{mpfi_inp_str} provides an enclosure of the interval it reads, these
functions are not reciprocal. More precisely, when they are called one after
the other, the resulting interval contains the initial one, and this inclusion
may be strict.
@end deftypefun

@deftypefun size_t mpfi_inp_str (mpfi_t @var{rop}, FILE *@var{stream}, int @var{base})
Inputs a string in base @var{base} from stdio stream @var{stream},
and puts the
read float in @var{rop}.  The string is of the form @samp{number} or
@samp{[ number1 , number 2 ]}.
@c where the spaces around the floating-point endpoints are mandatory.
Each endpoint has the form @samp{M@@N} or, if the
base is 10 or less, alternatively @samp{MeN} or @samp{MEN}.
@samp{M} is the significand and
@samp{N} is the exponent.  The significand is always in the specified base.  The
exponent is 
@c either in the specified base or, if @var{base} is negative, 
in decimal.

The argument @var{base} may be in the ranges 2 to 36.
@c , or @minus{}36 to
@c @minus{}2.  Negative values are used to specify that the exponent is in
@c decimal.

Unlike the corresponding @code{mpz} function, the base will not be determined
from the leading characters of the string if @var{base} is 0.  This is so that
numbers like @samp{0.23} are not interpreted as octal.

Returns the number of bytes read, or if an error occurred, return 0.
@end deftypefun

@deftypefun void mpfi_print_binary (mpfi_t @var{op})
Outputs @var{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 significand are printed between square brackets;
they should always be zero.
@end deftypefun


@node Operating on the Endpoints, Set Operations, I/O of Intervals, Interval Functions
@comment  node-name,  next,  previous,  up
@section Functions Operating on Endpoints
@cindex Functions operating on endpoints

@deftypefun int mpfi_get_left (mpfr_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the left endpoint of @var{op}, rounded toward minus infinity.
It returns a negative value if @var{rop} differs from the left endpoint
of @var{op} (due to rounding) and 0 otherwise.
@end deftypefun

@deftypefun int mpfi_get_right (mpfr_t @var{rop}, mpfi_t @var{op})
Sets @var{rop} to the right endpoint of @var{op}, rounded toward plus infinity.
It returns a positive value if @var{rop} differs from the right endpoint
of @var{op} (due to rounding) and 0 otherwise.
@end deftypefun

The following function should never be used... but it helps to return correct
intervals when there is a bug.

@deftypefun int mpfi_revert_if_needed (mpfi_t @var{rop})
Swaps the endpoints of @var{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.
@end deftypefun

@deftypefun int mpfi_put (mpfi_t @var{rop}, mpfi_t @var{op})
@deftypefunx int mpfi_put_d (mpfi_t @var{rop}, double @var{op})
@deftypefunx int mpfi_put_ui (mpfi_t @var{rop}, unsigned long int @var{op})
@deftypefunx int mpfi_put_si (mpfi_t @var{rop}, long int @var{op})
@deftypefunx int mpfi_put_z (mpfi_t @var{rop}, mpz_t @var{op})
@deftypefunx int mpfi_put_q (mpfi_t @var{rop}, mpq_t @var{op})
@deftypefunx int mpfi_put_fr (mpfi_t @var{rop}, mpfr_t @var{op})
Extends the interval @var{rop} so that it contains @var{op}.
In other words, @var{rop} is set to the convex hull of @var{rop} and @var{op}.
It returns a value indicating whether none, one or both endpoints are inexact
(due to possible roundings).
@end deftypefun

@deftypefun int mpfi_interv_d (mpfi_t @var{rop}, double @var{op1}, double @var{op2})
@deftypefunx int mpfi_interv_ui (mpfi_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2})
@deftypefunx int mpfi_interv_si (mpfi_t @var{rop}, long int @var{op1}, long int @var{op2})
@deftypefunx int mpfi_interv_z (mpfi_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
@deftypefunx int mpfi_interv_q (mpfi_t @var{rop}, mpq_t @var{op1}, mpq_t @var{op2})
@deftypefunx int mpfi_interv_fr (mpfi_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2})
Sets @var{rop} to the interval having as endpoints @var{op1} and @var{op2}.
The values of @var{op1} and @var{op2} are given in any order, the left
endpoints of @var{rop} is always the minimum of @var{op1} and
@var{rop2}.
It returns a value indicating whether none, one or both endpoints are inexact
(due to possible roundings).
@end deftypefun


@node Set Operations, Miscellaneous Interval Functions, Operating on the Endpoints, Interval Functions
@comment  node-name,  next,  previous,  up
@section Set Functions on Intervals
@cindex Set functions on intervals

@deftypefun int mpfi_is_strictly_inside (mpfi_t @var{op1}, mpfi_t @var{op2})
Returns a positive value if the second interval @var{op2} is contained in
the interior of @var{op1}, 0 otherwise.
@end deftypefun

@deftypefun int mpfi_is_inside (mpfi_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_is_inside_d (double @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_is_inside_ui (unsigned long @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_is_inside_si (long int @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_is_inside_z (mpz_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_is_inside_q (mpq_t @var{op1}, mpfi_t @var{op2})
@deftypefunx int mpfi_is_inside_fr (mpfr_t @var{op1}, mpfi_t @var{op2})
Returns a positive value if @var{op1} is contained in @var{op2},
0 otherwise.
Return 0 if at least one argument is NaN or an invalid interval.
@end deftypefun

@deftypefun int mpfi_is_empty (mpfi_t @var{op})
Returns a positive value if @var{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 responsibility of the user
to avoid computing with empty intervals.
@end deftypefun

@deftypefun int mpfi_intersect (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfi_t @var{op2})
Sets @var{rop} to the intersection (possibly empty) of the intervals
@var{op1} and @var{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).
@end deftypefun

@deftypefun int mpfi_union (mpfi_t @var{rop}, mpfi_t @var{op1}, mpfi_t @var{op2})
Sets @var{rop} to the convex hull of the union of the intervals @var{op1} and @var{op2}.
It returns a value indicating whether none, one or both endpoints are inexact
(due to possible roundings).
@end deftypefun

@node Miscellaneous Interval Functions, Error Handling, Set Operations, Interval Functions
@comment  node-name,  next,  previous,  up
@section Miscellaneous Interval Functions
@cindex Miscellaneous interval functions

@deftypefun int mpfi_increase (mpfi_t @var{rop}, mpfr_t @var{op})
Subtracts @var{op} to the lower endpoint of @var{rop} and adds it to
the upper endpoint of @var{rop}, sets the resulting interval to @var{rop}.
It returns a value indicating whether none, one or both endpoints are inexact.
@end deftypefun

@deftypefun int mpfi_blow (mpfi_t @var{rop}, mpfi_t @var{op1}, double @var{op2})
@ifinfo
Sets @var{rop} to the interval whose center is the center of @var{op1}
and whose radius is the radius of @var{op1} multiplied by (1 + abs(@var{op2})).
@end ifinfo
@iftex
@tex
Sets @var{rop} to the interval whose center is the center of @var{op1}
and whose radius is the radius of @var{op1} multiplied by $(1 + | @var{op2} |)$.
@end tex
@end iftex
It returns a value indicating whether none, one or both endpoints are inexact.
@end deftypefun

@deftypefun int mpfi_bisect (mpfi_t @var{rop1}, mpfi_t @var{rop2}, mpfi_t @var{op})
Splits @var{op} into two halves and sets them to @var{rop1} and @var{rop2}.
Due to outward rounding, the two halves @var{rop1} and @var{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.
@end deftypefun

@deftypefun {const char *} mpfi_get_version ()
Returns the MPFI version number as a NULL terminated string.
@end deftypefun


@node Error Handling,  , Miscellaneous Interval Functions, Interval Functions
@comment  node-name,  next,  previous,  up
@section Error Handling
@cindex Error handling

@deftypefn Macro void MPFI_ERROR ({char *} @var{msg})
If there is no previous error, sets the error number to 1 and prints
the message @var{msg} to the standard error stream. If the error
number is already set, do nothing.
@end deftypefn

@deftypefun int mpfi_is_error ()
Returns 1 if the error number is set (to 1).
@end deftypefun

@deftypefun void mpfi_set_error (int @var{op})
Sets the error number to @var{op}.
@end deftypefun

@deftypefun void mpfi_reset_error ()
Resets the error number to 0.
@end deftypefun

@node Contributors, References, Interval Functions, Top
@comment  node-name,  next,  previous,  up
@unnumbered Contributors

MPFI has been written by Fabrice Rouillier, Nathalie Revol, Sylvain
Chevillard, Hong Diep Nguyen, Christoph Lauter and Philippe Th@'eveny. Its development
has greatly benefited from the patient and supportive help of the MPFR
team.

@node References, Concept Index, Contributors, Top
@comment  node-name,  next,  previous,  up
@unnumbered References

This is a largely lacunary list of introductory references.
@itemize @bullet

@item MPFR team (SPACES project, INRIA Lorraine and LORIA),
"MPFR. The Multiple Precision Floating-Point Reliable Library",
available at @code{http://www.mpfr.org}.

@item
The main Web site for interval computations is
@url{http://cs.utep.edu/interval-comp/main.html}.

@item
The Web site of the IEEE-1788 working group for the standardization
of interval arithmetic is
@url{http://grouper.ieee.org/groups/1788/}.

@item
G. Alefeld and J. Herzberger, "Introduction to interval analysis",
Academic Press, 1983.

@item
R. Baker Kearfott, "Rigorous global search: continuous problems",
Kluwer, 1996.

@item
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.

@item
E. Hansen, "Global optimization using interval analysis",
Marcel Dekker, 1992.

@item
A. Neumaier, "Interval methods for systems of equations",
Cambridge University Press, 1990.

@item
H. Ratschek and J. Rokne, "New computer methods for global optimization",
Ellis Horwood Ltd, 1988.

@item
N. Revol and F. Rouillier, 
"Motivations for an arbitrary precision interval arithmetic and the MPFI library",
Reliable Computing, vol. 11, no 4, pp 275--290, 2005.
@end itemize


@node Concept Index, Function Index, References, Top
@comment  node-name,  next,  previous,  up
@unnumbered Concept Index
@printindex cp

@node Function Index,  , Concept Index, Top
@comment  node-name,  next,  previous,  up
@unnumbered Function and Type Index
@printindex fn


@contents
@bye
