cgal/Algebraic_kernel_d/doc_tex/Algebraic_kernel_d/models.tex

% TODO: remove references to Gmpfr and Gmpfi, since they will be part of CGAL.

\section{Models}

\subsection{Generic Algebraic Kernels}

The package provides generic models of the univariate and bivariate algebraic 
kernel, namely \ccc{CGAL::Algebraic_kernel_d_1<Coeff>} and \ccc{CGAL::Algebraic_kernel_d_2<Coeff>},
respectively. Both kernels support a large set of number types as their 
template argument, which defines the supported coefficient type. The supported 
types are, for instance, \ccc{Gmpz} and  \ccc{Gmpq} as well as the corresponding types
of LEDA and CORE. 

The \ccc{CGAL::Algebraic_kernel_d_1<Coeff>} represents an algebraic real root by a square 
free polynomial and an isolating interval that uniquely defines the root. 
The current method to isolate roots is the Bitstream Descartes
method~\cite{eigenwillig-phd-08}. 
The used method to refine the approximation of an algebraic real root is a 
slightly modified (filtered) version of the one presented in~\cite{abbott-qir-06}. 
The method has quadratic convergence.

\ccc{CGAL::Algebraic_kernel_d_2<Coeff>} is based on an algorithm computing a 
geometric-topological analysis of a single curve~\cite{ekw-fast-07} and of a
pair of curves~\cite{ek-exact-08}.
The main idea behind both analyses is to compute the critical
x-coordinates of curves and curve pairs by projection (resultants), and compute
additional information about the critical fibers using subresultants
and Sturm-Habicht sequences~\cite{grlr-sturm-habicht-98}. 
With that information, the fiber at    
critical x-coordinates is computed by a variant of the Bitstream
Descartes method.
See also \cite{kerber-phd-09} for a comprehensive description of
these techniques. 
Almost all functors in the class that take a \ccc{Polynomial_2}
object as argument trigger such an analysis as a main computation
step. For efficiency, these analyses (of single curves and curve
pairs) are therefore cached internally for efficiency. For instance,
computing the pairwise solutions of 10 \ccc{Polynomial_2} objects
requires 10 curve analyses and 45 curve pair analyses to be computed
internally. 

A point $p$ of type \ccc{Algebraic_real_2} is represented
by its $x$-coordinate $x_0$ (as described in the \ccc{Algebraic_kernel_d_1}
paragraph above), an algebraic curve where $p$ lies on, and an
integer $i$, denoting that $p$ is the $i$th point in the fiber at $x_0$,
counted from the bottom (ignoring a possible vertical line at $x_0$).
Note that this determines the point uniquely, but the $y$-coordinate 
is not stored internally in terms of an \ccc{Algebraic_real_1} object.
Querying such a representation by calling \ccc{Compute_y_2} is a
time-consuming step, and should be avoided for efficiency reasons if possible.


\subsection{Algebraic Kernels Based on RS}

The package offers two univariate algebraic kernels that are based on 
the library \rs~\cite{cgal:r-rs}, namely \ccc{CGAL::Algebraic_kernel_rs_gmpz_d_1}
and \ccc{CGAL::Algebraic_kernel_rs_gmpq_d_1}. As the names indicate, 
the kernels are based on the library \rs~\cite{cgal:r-rs} and support univariate 
polynomials over \ccc{CGAL::Gmpz} or \ccc{CGAL::Gmpq}, respectively. 

In general we encourage to use \ccc{CGAL::Algebraic_kernel_rs_gmpz_d_1}
instead of \ccc{CGAL::Algebraic_kernel_rs_gmpq_d_1}. This is caused by
the fact that the most efficient way to compute operations (such as gcd)
on polynomials with rational coefficients is to use the corresponding
implementation for polynomials with integer coefficients.  That is,
the \ccc{CGAL::Algebraic_kernel_rs_gmpq_d_1} is slightly slower due to
overhead caused by the necessary conversions.  However, since this may
not always be a major issue, the \ccc{CGAL::Algebraic_kernel_rs_gmpq_d_1}
is provided for convenience.


The core of both kernels is the implementation of the interval Descartes 
algorithm~\cite{cgal:rz-jcam-04} of the library \rs~\cite{cgal:r-rs}, 
which is used to isolate the roots of the polynomial. 
The \rs~library restricts its attention to univariate integer
polynomials and some substantial gain of efficiency can be made by using a kernel
that does not follow the generic programming paradigm, by avoiding
interfaces between layers.  Specifically, working with
only one number type allows to optimize some polynomial operations
as well as memory handling.  The implementation of these kernels
make heavy use of the \mpfr~\cite{cgal:mt-mpfr} and \mpfi~\cite{cgal:r-mpfi}
libraries, and of their \cgal\ interfaces, \ccc{Gmpfr} and \ccc{Gmpfi}.
The algebraic numbers (roots of the polynomials) are represented
in the two \rs~kernels by a \ccc{Gmpfi} interval and a pointer to
the polynomial of which they are roots.  See \cite{cgal:lpt-wea-09} 
for more details on the implementation, tests of these kernels,
comparisons with other algebraic kernels and discussions about the
efficiency.  


%--------------------------------------------------
% \subsubsection{Installation of the kernel}
% 
% As said before, this kernel depends on several libraries. First of
% all, it requires CGAL to be compiled with GMP support. Secondly,
% this needs the libraries MPFI and RS.
% 
% MPFI can be obtained from \ccc{http://gforge.inria.fr/projects/mpfi/}.
% As for RS, it can be downloaded from
% \ccc{http://www.loria.fr/equipes/vegas/rs}, you should get the
% right package for your architecture and operating system. Once both
% libraries are installed, you may want to set the environment variables
% {\tt MPFI\_INC\_DIR} and {\tt RS\_INC\_DIR} pointing to the include
% directories and {\tt MPFI\_LIB\_DIR} and {\tt RS\_LIB\_DIR} pointing to
% the library directories.
% 
% In order to create the \ccc{cmake} script to compile a program using these
% kernels, you should use the example {\tt CMakeLists.txt} from the
% {\tt examples/Algebraic\_kernel\_d} directory.
%--------------------------------------------------