mirror of https://github.com/CGAL/cgal
551 lines
25 KiB
TeX
551 lines
25 KiB
TeX
=============================================================================
|
|
% The CGAL Reference Manual
|
|
% Chapter: Geometric Optimisation
|
|
% Section: Smallest Enclosing Sphere
|
|
% =============================================================================
|
|
|
|
\begin{ccRefClass}{QP_solver<Traits>}
|
|
|
|
% -----------------------------------------------------------------------------
|
|
\ccDefinition An object of class \ccRefName\ is a data structure
|
|
that represents a point $\tilde{x}$ attaining the minimum of a convex
|
|
quadratic objective function $f(x)=c^{T}x+x^{T}Dx$ on
|
|
a domain $R \subseteq \R^{n}$ given as the intersection $R=\{ x\in\R^n
|
|
\mid \mbox{$Ax\gtreqless b$, $l \le x \le u$}\}$ of halfspaces and
|
|
hyperplanes. In other words, an object of class \ccRefName\ represents
|
|
a solution to the convex mathematical program
|
|
\begin{eqnarray*}
|
|
\mbox{(QP)}&\mbox{minimize} & c^{T}x+x^{T}Dx \\
|
|
&\mbox{subject to} & Ax \gtreqless b, \\
|
|
&& l \leq x \leq u,
|
|
\end{eqnarray*}
|
|
over the $n$ variables $x=(x_0,\ldots,x_{n-1})$.
|
|
|
|
Here, $A \in \R^{m \times n}$, $b \in \R^{m}$, $c \in \R^{n}$, and in
|
|
addition, the matrix $D \in \R^{n \times n}$ is positive-semidefinite.
|
|
The symbol ``$\gtreqless$'' in the program's constraint $Ax \gtreqless
|
|
b$ means that any row of this may either be an inequality $(Ax)_i \leq b_i$ or
|
|
$(Ax)_i \geq b_i$, or an equality $(Ax)_i = b_i$. Furthermore, $l\in
|
|
(\R\cup\{-\infty\})^n$ and $r\in (\R\cup\{\infty\})^n$, so that each
|
|
variable $x_i$, $i\in\{0,\ldots,n-1\}$, can be \emph{free} (if
|
|
$l_i=-\infty$ and $r_i=\infty$), \emph{bounded from above} (if
|
|
$u_i\not=\infty$) and/or \emph{bounded from below} (if
|
|
$l_i\not=-\infty)$. In case $l$ is the zero vector and all entries of
|
|
$u$ are $\infty$, the program (QP) is said to be in \emph{standard
|
|
form}.
|
|
|
|
A point $x \in \R^{n}$ with $x\in R$ is called a \emph{feasible
|
|
solution}; a feasible solution $x$ is said to be an \emph{optimal
|
|
feasible solution} if $f(x')\geq f(x)$ for all $x'\in R$. If
|
|
$R=\emptyset$, the program (QP) is said to be \emph{infeasible};
|
|
it is \emph{feasible} if $\R\not=\emptyset$. If $f$ is bounded from
|
|
below on $R$, the quadratic program (QP) is called \emph{bounded},
|
|
otherwise \emph{unbounded}. A quadratic program that is feasible and
|
|
bounded always has an optimal feasible solution (which need not be
|
|
unique), and we call such a program \emph{optimally solvable}.
|
|
|
|
While a feasible solution $\tilde{x}$ can be specified by listing its
|
|
entries $\tilde{x}_i$, $i\in\{0,\ldots,n-1\}$, it can also be
|
|
described by specifying for each variable $x_i$ which of the
|
|
constraints $l_i\leq \tilde{x}_i$ and $\tilde{x}_i\leq u_i$ is tight,
|
|
and in case none is, by explicitly stating the value $\tilde{x}_i$.
|
|
Along these lines, the algorithm will represent a feasible solution
|
|
$\tilde{x}$ by a certain
|
|
\begin{itemize}
|
|
\item subset $B\subseteq \{0,\ldots,n-1\}$,
|
|
\item the values $\tilde{x}_i$ for all $i\in B$, and
|
|
\item for all $i\in \{0,\ldots,n-1\}\setminus B$ whether
|
|
(a)~$\tilde{x}_i=0$, (b)~the \emph{lower bound} $l_i \leq \tilde{x}_i$
|
|
holds with equality, or (c)~the \emph{upper bound} $\tilde{x}_i\leq
|
|
u_i$ holds with equality.
|
|
\end{itemize}
|
|
The variables $x_i$, $i\in B$, are called \emph{basic} and the
|
|
remaining variables \emph{nonbasic} (with respect to $\tilde{x}$ and
|
|
$B$). Notice that in case of a problem in standard form, all nonbasic
|
|
variables are zero (and therefore need not be queried).
|
|
|
|
\paragraph{Usage.}
|
|
An object of class \ccRefName\ is constructed by specifing $A, b, c,
|
|
D, l, u$, and for each constraint from $Ax \gtreqless b$ whether it
|
|
needs to hold with inequality ($\leq$ or $\geq$) or with equality.
|
|
The algorithm then determines the object's \emph{status}, which
|
|
reflects whether the quadratic program (QP) is infeasible, unbounded,
|
|
or optimally solvable. You can query the status by calling
|
|
\ccc{status()}. If according to this the program is optimally
|
|
solvable, an optimal feasible solution $\tilde{x}$ is computed
|
|
together with the value $f(\tilde{x})$, which you can query using the
|
|
access functions \ccc{solution_numerator()},
|
|
\ccc{solution_denominator()},
|
|
\ccc{basic_original_variables_numerator_begin()},
|
|
\ccc{nonbasic_original_variables_numerator_begin()}, and
|
|
\ccc{variables_common_denominator()}. The value $f(\tilde{x})$ and
|
|
entries $\tilde{x}_i$ of the computed optimally
|
|
feasible solution $\tilde{x}$ are represented as quotients over the
|
|
number type \ccc{Traits::ET}. The routines
|
|
\ccc{solution_numerator()},
|
|
\ccc{basic_original_variables_numerator_begin()} and
|
|
\ccc{nonbasic_original_variables_numerator_begin()} return the
|
|
respective numerators; the denominator of $f(\tilde{x})$ is
|
|
\ccc{solution_denominator()}, and all entries $\tilde{x}_i$ have
|
|
(identical) denominator \ccc{variables_common_denominator()}.
|
|
Alternatively, you can also invoke the routines \ccc{solution()} and
|
|
\ccc{variables_value_begin()} to query $f(\tilde{x})$ and $\tilde{x}$;
|
|
the result of these routines are quotients, i.e., numbers of type
|
|
\ccc{CGAL::Quotient<Traits::ET>}.
|
|
|
|
|
|
In case of a problem (QP) in standard form it suffices to query the
|
|
values of the basic variables of $\tilde{x}$ (as returned by
|
|
\ccc{basic_original_variables_numerator_begin()}); the values
|
|
$\tilde{x}_i$ of all other (nonbasic) variables are, as explained
|
|
above, zero in this case.
|
|
|
|
In case the algorithm determines that the program (QP) is unbounded,
|
|
it computes a feasible solution $\tilde{x}$ and an \emph{unbounded
|
|
direction} $w\in\R^n$ such that $\tilde{x}-\alpha w$ is a feasible
|
|
solution of (QP) for any real $\alpha\geq 0$ with the property that
|
|
$g(\alpha):= f(\tilde{x}-\alpha w)$ is not bounded from below on
|
|
$\R_+$. The feasible solution $\tilde{x}$ is queried in the same way
|
|
as the optimal feasible solution in the case when the program is
|
|
optimally solvable; the unbounded direction $w$ can be accessed using
|
|
\ccc{unbounded_direction_begin()}.
|
|
|
|
When (QP) is either unbounded or optimally solvable, the feasible
|
|
solution $\tilde{x}$ computed in this way is called the instance's
|
|
\emph{current solution}.
|
|
|
|
\paragraph{Specializations.}
|
|
In order to improve performance, the algorithm can be tailored to
|
|
specific variants of the quadratic program. In particular, if the
|
|
program is (at compile time) known to be linear (i.e., $D=0$), or in
|
|
standard form, or symmetric (meaning $D^{T}=D$), or if the constraint
|
|
matrix $A$ is known to have full row rank and $Ax \gtreqless b$
|
|
consists of equalities only then compile-time flags in the traits
|
|
class \ccc{Traits} can be used to specialize the algorithm. The
|
|
resulting code will take advantage of the given additional knowledge
|
|
and therefore run (much) faster. The examples below illustrate this.
|
|
|
|
\paragraph{Exactness of the solution.}
|
|
In contrast to many other quadratic programming solvers, the
|
|
algorithm's output (\ccc{status()}, \ccc{solution()}, etc.)\ is
|
|
\emph{correct} for all inputs. (In other words, the optimal feasible
|
|
solution computed by the algorithm is not a point $\tilde{x}'$ that is
|
|
\emph{close}, $\|\tilde{x}'-\tilde{x}\|\le \epsilon$, to an actual
|
|
optimal feasible solution $\tilde{x}$ of the input program, but it
|
|
computes an optimal feasible solution. In contrast to this, many
|
|
solvers merely compute \emph{floating-point approximations} to optimal
|
|
feasible solutions and cannot correctly decide for all possible input
|
|
programs (QP) whether they are infeasible or not.)
|
|
|
|
For this to work, the algorithm requires that the number type
|
|
\ccc{Traits::ET}, which is used for internal calculations, is an
|
|
\emph{exact number type}, meaning that it correctly models the
|
|
rational numbers (in particular, without rounding errors).
|
|
(Technically,
|
|
\ccc{Number_type_traits<Traits::ET>::Has_exact_ring_operations} must
|
|
be \ccc{CGAL::Tag_true}, see the documentation of concept
|
|
\ccc{QPSolverTraits}.)
|
|
|
|
\paragraph{Pricing strategies.}
|
|
The solver's underlying algorithm is an \emph{iterative method}.
|
|
After having found an initial feasible solution the algorithm steps
|
|
from feasible solution to feasible solution, always improving the
|
|
solution. The performance of the algorithm is greatly influenced by
|
|
the \emph{pricing strategy} that is used during the so-called
|
|
\emph{pricing step}. In this repeatedly occurding phase, the algorithm
|
|
determines whether or not the current solution is optimal, and if it
|
|
is not, selects one from (usually) many possible \emph{improved
|
|
solutions}. The pricing strategy determines \emph{which} improved
|
|
solution is taken for the next iteration.
|
|
|
|
Four ready-to-use pricing strategies are provided: \emph{full exact
|
|
pricing}, \emph{full filtered pricing}, \emph{partial exact pricing},
|
|
and \emph{partial filtered pricing}. (Currently, it is not possible
|
|
to run the algorithm with a user-defined pricing strategy.)
|
|
|
|
The two filtered pricing strategy allow for an \emph{inexact} number
|
|
type \ccc{Traits::NT} like e.g.\ \ccc{double} to be used during the
|
|
pricing step: instead of running expensive exact arithmetic
|
|
internally, the algorithm will then use the fast number-type
|
|
\ccc{Traits::NT} to determine the next improved solution --- still in
|
|
such a way that exact solutions are obtained in the end. If the
|
|
inexact number type \ccc{Traits::NT} is considerable faster than
|
|
\ccc{Traits::ET}, filtered pricing can result in increased performance
|
|
of the algorithm.
|
|
|
|
The two partial pricing strategies incorporate the techniques of
|
|
\emph{random sampling} to speed up the pricing step. They work best
|
|
for quadratic programs with high \emph{variables-to-constraints ratio}
|
|
$n/m$.
|
|
|
|
%Any feasible solution of (QP) can be specified by a
|
|
%subset $B\subseteq\{1,\ldots,n\}$ of the variables and their values
|
|
%$x_{B}$ in such a way that all variables $\{1,\ldots,n\}\setminus B$
|
|
%have value zero; in this case, the variables in $B$ are said to be
|
|
%\emph{basic} and the variables in $\{1,\ldots,n\}\setminus B$ are
|
|
%called \emph{nonbasic}. (Nonbasic variables always have value zero; a
|
|
%basic variable might have value zero.)
|
|
|
|
\ccInclude{CGAL/QP_solver.h}
|
|
|
|
\ccRequirements
|
|
\ccIndexRequirements
|
|
|
|
The class \ccRefName\ expects a model of the concept
|
|
\ccc{QPSolverTraits} as its template argument.
|
|
|
|
\ccTypes \ccIndexClassTypes
|
|
|
|
\ccNestedType{ET}{a typedef to \ccc{Traits::ET}.}
|
|
|
|
\ccNestedType{A_iterator}{a typedef to \ccc{Traits::A_iterator}.\\
|
|
Note: as described in the documentation of concept
|
|
\ccc{QPSolverTraits}, \ccc{A_iterator} iterates over the
|
|
\emph{columns} of the matrix $A$.}
|
|
|
|
\ccNestedType{B_iterator}{a typedef to \ccc{Traits::B_iterator}.}
|
|
|
|
\ccNestedType{C_iterator}{a typedef to \ccc{Traits::C_iterator}.}
|
|
|
|
\ccNestedType{D_iterator}{a typedef to \ccc{Traits::D_iterator}. \\
|
|
Note: as described in the documentation of concept
|
|
\ccc{QPSolverTraits}, \ccc{D_iterator} iterates over the
|
|
\emph{rows} of the matrix $D$.}
|
|
\ccNestedType{L_iterator}{a typedef to \ccc{Traits::L_iterator}.}
|
|
\ccNestedType{U_iterator}{a typedef to \ccc{Traits::U_iterator}.}
|
|
\ccNestedType{FL_iterator}{a typedef to \ccc{Traits::FL_iterator}.}
|
|
\ccNestedType{FU_iterator}{a typedef to \ccc{Traits::FU_iterator}.}
|
|
|
|
\ccNestedType{Row_type}{is a typedef to \ccc{Traits::Row_type}.}
|
|
|
|
\ccNestedType{Row_type_iterator}{is a typedef to
|
|
\ccc{Traits::Row_type_iterator}.}
|
|
|
|
\ccNestedType{Is_linear}{a typedef to \ccc{Traits::Is_linear}.}
|
|
|
|
\ccNestedType{Is_symmetric}{a typedef to \ccc{Traits::Is_symmetric}.}
|
|
|
|
\ccNestedType{Has_equalities_only_and_full_rank}{is a typedef to
|
|
\ccc{Traits::Has_equalities_only_and_full_rank}.}
|
|
|
|
\ccNestedType{Is_in_standard_form}{a typedef to \ccc{Traits::Is_in_standard_form}.}
|
|
|
|
%\ccNestedType{Use_perturbation}{is a typedef to
|
|
%\ccc{Traits::Use_perturbation}.}
|
|
|
|
%\ccNestedType{Pricing_strategy}{a typedef to
|
|
%\ccc{QP_pricing_strategy<Traits>}. \ccc{Pricing_strategy} is a base
|
|
%class of all four ready-to-use pricing strategies.}
|
|
|
|
\ccNestedType{Basic_variable_value_iterator}{a STL random access
|
|
iterator with value type \ccc{ET} used to access the numerators of
|
|
the basic variables of a feasible (or optimal feasible) solution,
|
|
see \ccc{basic_original_variables_numerator_begin()} below.}
|
|
|
|
\ccNestedType{Basic_variable_index_iterator}{a STL random access
|
|
iterator with value type \ccc{int} used to access the indices of the
|
|
basic variables of a feasible (or optimal feasible) solution, see
|
|
\ccc{basic_original_variables_numerator_begin()} below.}
|
|
|
|
\ccNestedType{Nonbasic_variable_iterator}{a STL random access iterator
|
|
with value type \ccc{ET} used to access the nonbasic variables of a
|
|
feasible (or optimal feasible) solution, see
|
|
\ccc{nonbasic_original_variables_begin()} below.}
|
|
|
|
\ccNestedType{Nonbasic_variable_index_iterator}{a STL random access
|
|
iterator with value type \ccc{int} used to access the indices of the
|
|
nonbasic variables of a feasible (or optimal feasible) solution, see
|
|
\ccc{nonbasic_original_variables_begin()} below.}
|
|
|
|
\ccNestedType{Variable_value_iterator}{a STL random access iterator
|
|
with value type \ccc{CGAL::Quotient<ET>} used to access all (i.e.,
|
|
basic and nonbasic) variables of a feasible (or optimal feasible)
|
|
solution, see \ccc{variables_value_begin()} below.}
|
|
|
|
%KKT
|
|
%\ccNestedType{Lambda_value_iterator}{a STL random access iterator with value type}
|
|
|
|
%The following enum type is provided by the class \ccRefName\ :
|
|
|
|
\ccEnum{enum Strategy { FULL_EXACT_PRICING, FULL_FILTERED_PRICING,
|
|
PARTIAL_EXACT_PRICING, PARTIAL_FILTERED_PRICING };}{enumeration used
|
|
to specify one of the four pricing strategies to use.}
|
|
|
|
\ccEnum{enum Status { INFEASIBLE, UNBOUNDED, OPTIMAL };}{enumeration used to
|
|
indicate the status of a quadratic program.}
|
|
|
|
\ccEnum{enum Bound_identifier { ZERO, LOWER, UPPER };}{enumeration
|
|
used to describe the assignment of a nonbasic variable $x_i$ of a
|
|
feasible solution to either the value zero, to its lower bound $l_i$,
|
|
or to its upper bound $u_i$, see \ccc{nonbasic_variables_begin()}.}
|
|
|
|
\ccCreation
|
|
\ccIndexClassCreation
|
|
\ccCreationVariable{qp}
|
|
|
|
\ccConstructor{( int n, int m, A_iterator a_it, B_iterator b_it,
|
|
C_iterator c_it, D_iterator d_it, Row_type_iterator r_it =
|
|
CGAL::Const_oneset_iterator<Row_type>( Rep::EQUAL), Strategy
|
|
strategy = FULL_EXACT_PRICING)} {creates a variable of type \ccRefName\ and solves the
|
|
quadratic program (QP) assuming the vector $l$ is the zero vector and
|
|
all entries of $u$ are $\infty$ (i.e., (QP) is assumed to be in
|
|
standard form). The matrix $A$ of (QP) is given by \ccc{a_it}, which
|
|
is an iterator over the columns of $A$. Similarly, \ccc{d_it}
|
|
iterates over the rows of $D$. The iterator \ccc{r_it} specifies for
|
|
each row of $Ax \gtreqless b$ whether it is an inequality ($\leq$ or
|
|
$\geq$) or an equality constraint. \ccRequire
|
|
\ccc{a_it} iterates over $n$ columns each of which has $m$ elements,
|
|
\ccc{d_it} iterates over $n$ rows each of which having $n$ elements,
|
|
and similarly \ccc{c_it} and \ccc{r_it} iterate over $n$ elements, and
|
|
\ccc{b_it} iterates over $m$ elements. Furthermore, the matrix $D$
|
|
specified by \ccc{d_it} must be positive-semidefinite, and $n>0$.}
|
|
|
|
\ccConstructor{( int n, int m, A_iterator a_it, B_iterator b_it,
|
|
C_iterator c_it, D_iterator d_it, Row_type_iterator r_it, FL_iterator
|
|
fl_it, L_iterator lb_it, FU_iterator fu_it, U_iterator ub_it,
|
|
Strategy
|
|
strategy = FULL_EXACT_PRICING)}
|
|
{creates a variable of type \ccRefName\ and solves the quadratic
|
|
program (QP). The matrix $A$ of (QP) is given by \ccc{a_it}, which is
|
|
an iterator over the columns of $A$. Similarly, \ccc{d_it} iterates
|
|
over the rows of $D$. The iterator \ccc{r_it} specifies for each row
|
|
of $Ax \gtreqless b$ whether it is an inequality ($\leq$ or $\geq$) or
|
|
an equality constraint. \ccc{fl_it} iterates over $n$ Boolean values,
|
|
one for each variable $x_i$, $i\in\{0,\ldots,n-1\}$, and specifies
|
|
whether $l_i>-\infty$. If so, the corresponding entry from the
|
|
iterator \ccc{lb_it} is taken as $l_i$; otherwise $l_i$ is set to
|
|
$-\infty$. Similarly, \ccc{fu_it} iterates over $n$ Boolean values
|
|
specifying whether $u_i$ is finite or not; if it is, the corresponding
|
|
entry from the iterator \ccc{ub_it} is taken as $u_i$, otherwise
|
|
$u_i:=\infty$. \ccRequire \ccc{a_it} iterates
|
|
over $n$ columns each of which has $m$ elements, \ccc{d_it} iterates
|
|
over $n$ rows each of which having $n$ elements, and similarly
|
|
\ccc{c_it}, \ccc{r_it}, \ccc{fl_it}, \ccc{lb_it}, \ccc{fu_it}, and
|
|
\ccc{ub_it} iterate over $n$ elements, and \ccc{b_it} iterates over
|
|
$m$ elements. Furthermore, the matrix $D$ specified by \ccc{d_it}
|
|
must be positive-semidefinite, and $n>0$.}
|
|
|
|
\ccUnchecked
|
|
|
|
\ccAccessFunctions
|
|
\begin{ccIndexMemberFunctions}
|
|
\ccIndexMemberFunctionGroup{access}
|
|
|
|
\ccMemberFunction{Status status() const;}{returns the status of the
|
|
quadratic program, that is, whether (QP) is infeasible, unbounded, or
|
|
optimally solvable.}
|
|
|
|
\ccMemberFunction{CGAL::Quotient<ET> solution( ) const;}{ returns the
|
|
value $f(\tilde{x})$ where $\tilde{x}$ is the instance's current
|
|
solution (i.e., some feasible solution in case (QP) is unbounded and
|
|
an optimal feasible solution in case the program is optimally
|
|
solvable). The number $f(\tilde{x})$ is returned as a quotient over
|
|
\ccc{ET}. \ccPrecond \ccc{status()} returns \ccc{UNBOUNDED} or
|
|
\ccc{OPTIMAL}.}
|
|
|
|
\ccMemberFunction{Basic_variable_value_iterator
|
|
basic_variables_value_begin( ) const;}{returns a const-iterator
|
|
referring to the numerator of the first basic variable of the current
|
|
solution $\tilde{x}$. Normally, you use the resulting iterator
|
|
together with the iterator returned by
|
|
\ccc{basic_variables_index_begin()}; while the former iterates over
|
|
the numerators of the basic variables, the latter iterates over the
|
|
indices (i.e., numbers in $\{0,\ldots,n-1\}$) of the corresponding
|
|
variables. \ccPrecond \ccc{status()} returns \ccc{UNBOUNDED} or \ccc{OPTIMAL}.}
|
|
|
|
\ccMemberFunction{Basic_variable_value_iterator
|
|
basic_variables_value_end( ) const;}{returns the past-the-end
|
|
const-iterator corresponding to \ccc{basic_variables_value_begin()}.
|
|
\ccPrecond \ccc{status()} returns \ccc{UNBOUNDED} or \ccc{OPTIMAL}.}
|
|
|
|
\ccMemberFunction{Basic_variable_index_iterator
|
|
basic_variables_index_begin( ) const;}{returns a const-iterator referring
|
|
to the first index in the list of basic variables.
|
|
\ccPrecond \ccc{status()} returns \ccc{UNBOUNDED} or \ccc{OPTIMAL}.}
|
|
|
|
\ccMemberFunction{Basic_variable_index_iterator
|
|
basic_variables_index_end ( ) const;}{returns the past-the-end
|
|
const-iterator corresponding to
|
|
\ccc{basic_variables_index_begin()}. \ccPrecond \ccc{status()} returns
|
|
\ccc{UNBOUNDED} or \ccc{OPTIMAL}.}
|
|
|
|
\ccMemberFunction{Nonbasic_variable_value_iterator
|
|
nonbasic_variables_begin( ) const;}{returns a const-iterator referring
|
|
to the first nonbasic variable of the current solution $\tilde{x}$.
|
|
The value type of the iterator is \ccc{Bound_identifier}; a value of
|
|
\ccc{ZERO} means that the corresponding nonbasic variable $x_i$ is
|
|
zero in the current solution $\tilde{x}$, a value of
|
|
\ccc{LOWER} means that $\tilde{x}_i=l_i$, and a value of \ccc{UPPER}
|
|
implies $\tilde{x}_i=u_i$. Normally, you use the resulting iterator
|
|
together with the iterator returned by
|
|
\ccc{nonbasic_variables_index_begin()}; while the former iterates over
|
|
the nonbasic variables, the latter iterates over the indices (i.e.,
|
|
numbers in $\{0,\ldots,n-1\}$) of the corresponding variables. \\
|
|
Note: in case of a program (QP) in standard form, this iterator will
|
|
have yield \ccc{ZERO} for all nonbasic variables. \ccPrecond
|
|
\ccc{status()} returns \ccc{UNBOUNDED} or \ccc{OPTIMAL}.}
|
|
|
|
\ccMemberFunction{Nonbasic_variable_value_iterator
|
|
nonbasic_variables_end( ) const;}{returns the past-the-end
|
|
const-iterator corresponding to \ccc{nonbasic_variables_begin()}.
|
|
\ccPrecond \ccc{status()} returns \ccc{UNBOUNDED} or \ccc{OPTIMAL}.}
|
|
|
|
\ccMemberFunction{Nonbasic_variable_index_iterator
|
|
nonbasic_variables_index_begin( ) const;}{returns a const-iterator referring
|
|
to the first index in the list of nonbasic variables.
|
|
\ccPrecond \ccc{status()} returns \ccc{UNBOUNDED} or \ccc{OPTIMAL}.}
|
|
|
|
\ccMemberFunction{Nonasic_variable_index_iterator
|
|
nonbasic_variables_index_end ( ) const;}{returns the past-the-end
|
|
const-iterator corresponding to
|
|
\ccc{nonbasic_variables_index_begin()}. \ccPrecond \ccc{status()}
|
|
returns \ccc{UNBOUNDED} or \ccc{OPTIMAL}.}
|
|
|
|
\ccMemberFunction{Variable_value_iterator variables_value_begin()
|
|
const;}{returns a const-iterator referring to the entry $\tilde{x}_0$
|
|
of the current solution $\tilde{x}$. \ccPrecond
|
|
\ccc{status()} returns \ccc{UNBOUNDED} or \ccc{OPTIMAL}.}
|
|
|
|
\ccMemberFunction{Variable_value_iterator variables_value_end()
|
|
const;}{returns the past-the-end const-iterator corresponding to
|
|
\ccc{variables_value_begin()}. \ccPrecond \ccc{status()} returns
|
|
\ccc{UNBOUNDED} or \ccc{OPTIMAL}.}
|
|
|
|
|
|
%KKT
|
|
%% \begin{ccAdvanced}
|
|
%% \ccHeading{Access to $\lambda$}
|
|
|
|
%% \ccMemberFunction{Lambda_value_iterator
|
|
%% lambda_value_begin( ) const;}{returns a const-iterator referring to the
|
|
%% $\lambda$ associated with the first constraint in user defined order of the
|
|
%% constraints.}
|
|
|
|
%% \ccMemberFunction{Lambda_value_iterator
|
|
%% lambda_value_end( ) const;}{returns the corresponding pas-the-end
|
|
%% const-iterator.}
|
|
%% \end{ccAdvanced}
|
|
|
|
\ccHeading{Access to quadratic program}
|
|
|
|
\ccMemberFunction{int number_of_variables ( ) const;}{returns the number of
|
|
variables of the quadratic program as specified in the constructor call.}
|
|
|
|
\ccMemberFunction{int number_of_constraints( ) const;}{returns the number of
|
|
constraints of the quadratic program as specified in the constructor call.}
|
|
|
|
\ccMemberFunction{A_iterator a_begin( ) const;}{returns a random access
|
|
const-iterator referring to the first column of the matrix $A$.}
|
|
|
|
\ccMemberFunction{A_iterator a_end( ) const;}{returns a random access
|
|
const-iterator referring to the last column of of the matrix $A$.}
|
|
|
|
\ccMemberFunction{B_iterator b_begin( ) const;}{returns a random
|
|
access const-iterator referring to the first entry of the vector $b$.}
|
|
|
|
\ccMemberFunction{B_iterator b_end( ) const;}{returns a random access
|
|
const-iterator referring to the last entry of the vector $b$.}
|
|
|
|
\ccMemberFunction{C_iterator c_begin( ) const;}{returns a random access
|
|
const-iterator referring to the first entry of the vector $c$.}
|
|
|
|
\ccMemberFunction{C_iterator c_end( ) const;}{returns a random access
|
|
const-iterator referring to the last entry of the vector $c$.}
|
|
|
|
\ccMemberFunction{D_iterator d_begin( ) const;}{returns a random access
|
|
const-iterator referring to the first row of the matrix $D$.}
|
|
|
|
\ccMemberFunction{D_iterator d_end( ) const;}{returns a random access
|
|
const-iterator referring to the last row of the matrix $D$.}
|
|
|
|
\ccMemberFunction{Row_type_iterator row_type_begin( ) const;}{returns a
|
|
random access const-iterator referring to the first entry of the row
|
|
type vector (see \ccc{r_it} in the documentation of the constructor).}
|
|
|
|
\ccMemberFunction{Row_type_iterator row_type_end( ) const;}{returns a
|
|
random access const-iterator referring to the last entry of the row
|
|
type vector (see \ccc{r_it} in the documentation of the constructor).}
|
|
% -----------------------------------------------------------------------------
|
|
\ccPredicates
|
|
\ccIndexMemberFunctionGroup{predicates}
|
|
|
|
\ccMemberFunction{bool is_basic( int i) const;}{returns \ccc{true} if
|
|
and only if variable $x_{i}$, $i \in \{0,\ldots,n-1\}$, is basic in
|
|
the current solution.\ccPrecond \ccc{status()} returns \ccc{UNBOUNDED}
|
|
or \ccc{OPTIMAL}}
|
|
|
|
% -----------------------------------------------------------------------------
|
|
%\ccModifiers
|
|
%\ccIndexMemberFunctionGroup{modifiers}
|
|
|
|
|
|
|
|
% -----------------------------------------------------------------------------
|
|
\ccHeading{Validity Check}
|
|
\ccIndexMemberFunctionGroup{validity check}
|
|
%\ccIndexSubitem[t]{validity check}{\ccc{Min_sphere_d}}
|
|
An object \ccVar\ is valid if and only if \ccc{qp.status()} returns
|
|
one of the following three values and their corresponding requirements
|
|
are met.
|
|
\begin{itemize}
|
|
\item \ccc{OPTIMAL}: The feasible solution $\tilde{x}$ computed by the
|
|
algorithm fulfills $f(\tilde{x}) \leq f(x)$ for all $x \in R$.
|
|
\item \ccc{INFEASIBLE}: $R = \emptyset$.
|
|
\item \ccc{UNBOUNDED}: The feasible solution $\tilde{x}$ and the
|
|
unbounded direction $w$ computed by the algorithm fulfill
|
|
\begin{itemize}
|
|
\item[(i)] $\tilde{x}-\alpha w$ is feasible for all $\alpha\ge 0$, and
|
|
\item[(ii)] the function $g(\alpha):= f(\tilde{x}-\alpha w)$ is not
|
|
bounded from below on the interval $[0,\infty)$.
|
|
\end{itemize}
|
|
\end{itemize}
|
|
|
|
\ccMemberFunction{ bool is_solution_valid() const;}{ returns \ccc{true} iff
|
|
\ccVar\ is valid.}
|
|
|
|
% -----------------------------------------------------------------------------
|
|
%\ccHeading{Miscellaneous}
|
|
%\ccIndexMemberFunctionGroup{miscellaneous}
|
|
|
|
|
|
\end{ccIndexMemberFunctions}
|
|
|
|
|
|
% -----------------------------------------------------------------------------
|
|
\ccSeeAlso
|
|
%
|
|
\ccRefIdfierPage{CGAL::QP_MPS_instance<IT,ET>}
|
|
% \ccRefIdfierPage{CGAL::QP_full_exact_pricing<Traits>}\\
|
|
% \ccRefIdfierPage{CGAL::QP_full_filtered_pricing<Traits, NT, ET2NT>}\\
|
|
% \ccRefIdfierPage{CGAL::QP_partial_exact_pricing<Traits>}\\
|
|
% \ccRefIdfierPage{CGAL::QP_partial_filtered_pricing<Traits, NT, ET2NT>}\\
|
|
% -----------------------------------------------------------------------------
|
|
|
|
\ccImplementation
|
|
\ccIndexImplementation
|
|
%\ccIndexSubitem[t]{incremental algorithm}{\ccc{Min_sphere_of_spheres_d}}
|
|
%\ccIndexSubitem[t]{farthest-first heuristic}{\ccc{Min_sphere_of_spheres_d}}
|
|
|
|
The current implementation does not guarantee termination for all
|
|
instances; in rare cases, the algorithm cycles forever. (Termination
|
|
can always be guaranteed by using symbolic perturbation, and this
|
|
feature will be added in a future release.)
|
|
|
|
\ccExample
|
|
|
|
The following example solves the quadratic programming problem
|
|
\begin{eqnarray*}
|
|
\mbox{(QP)}&\mbox{minimize} & x_0^2 + 3x_1 \\
|
|
&\mbox{subject to} & x_0+2x_1=1, \\
|
|
&& 0 \le x_0 \le \infty, \\
|
|
&& 0 \le x_1 \le 1.
|
|
\end{eqnarray*}
|
|
\ccIncludeExampleCode{../examples/QP_solver/small_example.C}
|
|
Please refer also to the documentation of class
|
|
\ccc{CGAL::QP_MPS_instance<IT,ET>}; using it, you can read programs of
|
|
the form (QP) from MPS-files.
|
|
\end{ccRefClass}
|
|
|
|
% ===== EOF ===================================================================
|
|
|