% =============================================================================
% The CGAL Reference Manual
% Chapter: Geometric Optimisation
% Section: Smallest Enclosing Sphere of Spheres
% -----------------------------------------------------------------------------
% file  : doc_tex/basic/Optimisation/Optimisation_ref/Traits.tex
% author: Kaspar Fischer (fischerk@inf.ethz.ch)
% -----------------------------------------------------------------------------
% $Id$
% $Date$
% $CGAL_Package$
% =============================================================================

\begin{ccRefConcept}{QPSolverTraits}

% -----------------------------------------------------------------------------
\ccDefinition

A model of concept \ccc{QPSolverTraits} must provide the
following constants, types, predicates and operations.

\ccHasModels
\ccc{CGAL::QP_solver_MPS_traits_d<MPS,L,S,H,F>}
%\ccc{CGAL::Min_sphere_of_spheres_d_traits_2<K,FT,UseSqrt,Algorithm>} \\
%\ccc{CGAL::Min_sphere_of_spheres_d_traits_3<K,FT,UseSqrt,Algorithm>} \\
%\ccc{CGAL::Min_sphere_of_spheres_d_traits_d<K,FT,Dim,UseSqrt,Algorithm>}

\ccConstants \ccEnum{enum Row_type {LESS_EQUAL, EQUAL,
GREATER_EQUAL};}{constants used to specify whether a constraint from
$Ax \gtreqless b$ is an inequality or equality constraint.}

\ccTypes

\ccNestedType{ET}{a model for the CGAL concept \ccc{RingNumberType}
that implements \emph{exact arithmetic} (meaning that
\ccc{Number_type_traits<Traits::ET>::Has_exact_ring_operations} equals
\ccc{CGAL::Tag_true}). In addition, division is required for the case
where the remainder is zero. {\sc Todo: concept for integral domain?}
Furthermore, the value types of the value types of the iterators
\ccc{A_iterator} and \ccc{D_iterator}, and also the value types of the
iterators \ccc{B_iterator}, \ccc{C_iterator}, \ccc{L_iterator}, and
\ccc{U_iterator} must be implicitly convertible to \ccc{ET} without
loss (meaning that the same value is obtained if we converted from
\ccc{ET} back to the original value type).}

\ccNestedType{A_iterator}{model of the \stl \ concept
\ccc{RandomAccessIterator}. The value type of \ccc{A_iterator} must
again be a model of the \stl\ concept \ccc{RandomAccessIterator} and
refers to the elements of a column of the matrix $A$.}

\ccNestedType{B_iterator}{model of the \stl \ concept
\ccc{RandomAccessIterator} referring to the entries of the vector
$b$.}

\ccNestedType{C_iterator}{model of the \stl \ concept
\ccc{RandomAccessIterator} referring to the entries of the vector
$c$.}

\ccNestedType{D_iterator}{model of the \stl \ concept
\ccc{RandomAccessIterator}. The value type of \ccc{D_iterator} is a
model of the \stl \ concept \ccc{RandomAccessIterator} and refers to
the elements of a row of the matrix $D$.}

\ccNestedType{FL_iterator}{model of the \stl \ concept
\ccc{RandomAccessIterator} used to specify whether a lower bound $l_i$
from the program's constraints $l\le x\le u$ is finite (i.e.,
different from $-\infty$) or not.  The value type of \ccc{FL_iterator}
must be convertible to \ccc{bool}.}

\ccNestedType{FU_iterator}{model of the \stl \ concept
\ccc{RandomAccessIterator} used to specify whether an upper bound $u_i$
from the program's constraints $l\le x\le u$ is finite (i.e.,
different from $\infty$) or not.  The value type of \ccc{FU_iterator}
must be convertible to \ccc{bool}.}

\ccNestedType{L_iterator}{model of the \stl \ concept
\ccc{RandomAccessIterator} used to access the lower bounds $l_i$ from
the program's constraints $l\le x\le u$.}

\ccNestedType{U_iterator}{model of the \stl \ concept
\ccc{RandomAccessIterator} used to access the upper bounds $u_i$ from
the program's constraints $l\le x\le u$.}

\ccNestedType{Row_type}{enumeration type providing the three constants
\ccc{LESS_EQUAL}, \ccc{EQUAL}, \ccc{GREATER_EQUAL} used to describe
the constraint type of the rows of $Ax\gtreqless b$.}

\ccNestedType{Row_type_iterator}{model of the STL concept
\ccc{RandomAccessIterator} with value type
\ccc{QPSolverTraits::Row_type} used to describe the constraint type of
the rows of $Ax\gtreqless b$.}

\ccNestedType{Is_linear}{Is either \ccc{CGAL::Tag_true} or
\ccc{CGAL::Tag_false}. If it coincides with \ccc{CGAL::Tag_true} the
algorithm assumes $D=0$. \\ Note: the algorithm can, of course, solve
instances with $D=0$ even if \ccc{Is_linear} is
\ccc{CGAL::Tag_false}, albeit less efficiently.}

\ccNestedType{Is_symmetric}{ Is either \ccc{CGAL::Tag_true} or
\ccc{CGAL::Tag_false}. If it coincides with \ccc{CGAL::Tag_true}, the
algorithm assumes the matrix $D$ to be symmetric. As a consequence, the
number of accesses to entries of $D$ are halfed.  \\ Note: the
algorithm can, of course, solve instances with symmetric matrices $D$
even if \ccc{Is_symmetric} is \ccc{CGAL::Tag_false}, albeit less
efficiently.}

\ccNestedType{Has_equalities_only_and_full_rank}{ Is either
\ccc{CGAL::Tag_true} or \ccc{CGAL::Tag_false}.  If it is
\ccc{CGAL::Tag_true}, the solver assumes that all constraints from
$Ax\gtreqless b$ are equality constraints and that $A$ has full row
rank. As a result, the algorithm can speed up certain computation
phases.  \\ Note: the algorithm can, of course, solve instances with
$Ax= b$ and full row rank even if
\ccc{Has_equalities_only_and_full_rank} is \ccc{CGAL::Tag_false},
albeit less efficiently.}

\ccNestedType{Is_in_standard_form}{ Is either \ccc{CGAL::Tag_true} or
\ccc{CGAL::Tag_false}.  If it is \ccc{CGAL::Tag_true}, the solver
assumes that all constraints from $l\le x \le u$ have $l_i=0$ and
$u_i=\infty$ for all $i\in\{0,\ldots,n-1\}$.  \\ Note: the algorithm
can, of course, solve instances in standard form even if
\ccc{Is_in_standard_form} is \ccc{CGAL::Tag_false}, albeit less
efficiently.}

%% \ccNestedType{Use_perturbation}{
%% Is either \ccc{CGAL::Tag_true} or \ccc{CGAL::Tag_false}. If
%% \ccc{Use_perturbation} is of type \ccc{CGAL::Tag_true}, symbolic perturbation
%% is used and cycling is avoided, such that the algorithm always terminates.
%% With symbolic perturbation a small performance penalty is incurred.  Implementation note: \ccc{Use_perturbation} must be \ccc{CGAL::Tag_false}, currently.}

%\ccAccessFunctions

\ccCreationVariable{traits}

%\ccMemberFunction{ FT radius(const
%Sphere& s);}{ returns the radius of sphere \ccc{s}.
%\ccPostcond The returned number is
% greater or equal to~$0$.}

%\ccMemberFunction{ Cartesian_const_iterator center_cartesian_begin(const Sphere& s);}{
%  returns an iterator referring to the first of the \ccc{D} Cartesian
%  coordinates of the center of \ccc{s}.}

\end{ccRefConcept}
