mirror of https://github.com/CGAL/cgal
512 lines
16 KiB
PHP
512 lines
16 KiB
PHP
@! ============================================================================
|
|
@! The CGAL Library
|
|
@! Implementation: Basic Stuff for Optimisation Algorithms
|
|
@! ----------------------------------------------------------------------------
|
|
@! file : web/Optimisation_basic.aw
|
|
@! author: Sven Schönherr <sven@inf.ethz.ch>
|
|
@! ----------------------------------------------------------------------------
|
|
@! $CGAL_Chapter: Geometric Optimisation $
|
|
@! $CGAL_Package: Optimisation_basic WIP $
|
|
@! $Id$
|
|
@! $Date$
|
|
@! ============================================================================
|
|
|
|
@documentclass[twoside]{article}
|
|
@usepackage[latin1]{inputenc}
|
|
@usepackage{a4wide2}
|
|
@usepackage{amssymb}
|
|
@usepackage{cc_manual,cc_manual_index}
|
|
@article
|
|
|
|
\input{cprog.sty}
|
|
\setlength{\skip\footins}{3ex}
|
|
|
|
\pagestyle{headings}
|
|
|
|
@! LaTeX macros
|
|
\newcommand{\remark}[2]{[\textbf{#1:} \emph{#2}]}
|
|
|
|
\newcommand{\linebreakByHand}{\ccTexHtml{\linebreak[4]}{}}
|
|
\newcommand{ \newlineByHand}{\ccTexHtml{\\}{}}
|
|
\newcommand{\SaveSpaceByHand}{} %%%%% [2]{\ccTexHtml{#1}{#2}}
|
|
|
|
\renewcommand{\sectionmark}[1]{\markboth{\uppercase{#1}}{}}
|
|
|
|
|
|
@! ============================================================================
|
|
@! Title
|
|
@! ============================================================================
|
|
|
|
\thispagestyle{empty}
|
|
|
|
\RCSdef{\rcsRevision}{$Id$}
|
|
\RCSdefDate{\rcsDate}{$Date$}
|
|
\newcommand{\cgalWIP}{{\footnotesize{} (\rcsRevision{} , \rcsDate) }}
|
|
|
|
@t vskip 20 mm
|
|
@t title titlefont centre "Basic Stuff for"
|
|
@t vskip 0 mm
|
|
@t title titlefont centre "Optimisation Algorithms*"
|
|
@t vskip 10 mm
|
|
@t title smalltitlefont centre "Sven Schönherr"
|
|
\begin{center}
|
|
\textbf{ETH Z{\"u}rich}
|
|
\end{center}
|
|
@t vskip 10 mm
|
|
{\small
|
|
\begin{center}
|
|
\begin{tabular}{l}
|
|
\verb+$CGAL_Package: Optimisation_basic WIP+\cgalWIP\verb+$+ \\
|
|
\verb+$CGAL_Chapter: Geometric Optimisation $+ \\
|
|
\end{tabular}
|
|
\end{center}
|
|
}
|
|
@t vskip 30 mm
|
|
|
|
\renewcommand{\thefootnote}{\fnsymbol{footnote}}
|
|
\footnotetext[1]{This work was supported by the ESPRIT IV LTR Projects
|
|
No.~21957 (CGAL) and No.~28155 (GALIA), and by a grant from the Swiss
|
|
Federal Office for Education and Sciences for the latter.}
|
|
\renewcommand{\thefootnote}{\arabic{footnote}}
|
|
|
|
@! --------
|
|
@! Abstract
|
|
@! --------
|
|
|
|
\begin{abstract}
|
|
We provide macros for checking assertions, pre- and postconditions and
|
|
warnings, for encapsulating code for debugging, and a failure function
|
|
for the checking functions of the optimisation algorithms.
|
|
\end{abstract}
|
|
|
|
@! --------
|
|
@! Contents
|
|
@! --------
|
|
|
|
\clearpage
|
|
|
|
\newlength{\defaultparskip}
|
|
\setlength{\defaultparskip}{\parskip}
|
|
\setlength{\parskip}{1ex}
|
|
|
|
\tableofcontents
|
|
|
|
\setlength{\parskip}{\defaultparskip}
|
|
|
|
|
|
@! ============================================================================
|
|
@! Introduction
|
|
@! ============================================================================
|
|
|
|
\clearpage
|
|
\markright{\uppercase{Introduction}}
|
|
\section{Introduction}
|
|
|
|
We provide macros for checking assertions, pre- and postconditions and
|
|
warnings, for encapsulating code for debugging, and a failure function for the
|
|
checking functions of the optimisation algorithms.
|
|
|
|
|
|
@! ============================================================================
|
|
@! Macros
|
|
@! ============================================================================
|
|
|
|
\clearpage
|
|
\section{Macros}
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
@! Checking
|
|
@! ----------------------------------------------------------------------------
|
|
|
|
\subsection{Checking}
|
|
|
|
The following macros are used to perform several checks. We distinguish four
|
|
groups of checks, namely checking for assertions, for preconditions, for
|
|
postconditions and for warnings. Each group consists of macros for normal
|
|
checks, exactness checks, expensive checks, and expensive exactness checks.
|
|
|
|
@macro<check macros>(2) many = @begin
|
|
@<normal checks>(@1,@2)
|
|
|
|
@<exactness checks>(@1,@2)
|
|
|
|
@<expensive checks>(@1,@2)
|
|
|
|
@<expensive exactness checks>(@1,@2)
|
|
|
|
@end
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
\subsubsection{Normal Checks}
|
|
|
|
@macro<normal checks>(2) many = @begin
|
|
#if ( defined( CGAL_OPTIMISATION_NO_@1S) \
|
|
|| defined( CGAL_NO_@1S) || defined( NDEBUG))
|
|
# define CGAL_optimisation_@2(EX) ((void)0)
|
|
# define CGAL_optimisation_@2_msg(EX,MSG) ((void)0)
|
|
# define CGAL_optimisation_@2_code(CODE)
|
|
# undef CGAL_OPTIMISATION_@1_TAG
|
|
#else
|
|
# define CGAL_optimisation_@2(EX) \
|
|
((EX)?((void)0): ::CGAL::@2_fail( # EX ,__FILE__,__LINE__,0))
|
|
# define CGAL_optimisation_@2_msg(EX,MSG) \
|
|
((EX)?((void)0): ::CGAL::@2_fail( # EX ,__FILE__,__LINE__,MSG))
|
|
# define CGAL_optimisation_@2_code(CODE) CODE
|
|
# define CGAL_OPTIMISATION_@1_TAG 1
|
|
#endif // optimisation @2s
|
|
@end
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
\subsubsection{Exactness Checks}
|
|
|
|
@macro<exactness checks>(2) many = @begin
|
|
#if ( ! ( defined( CGAL_OPTIMISATION_CHECK_EXACTNESS) \
|
|
|| defined( CGAL_CHECK_EXACTNESS) ) \
|
|
|| defined( CGAL_OPTIMISATION_NO_@1S) \
|
|
|| defined( CGAL_NO_@1S) || defined( NDEBUG))
|
|
# define CGAL_optimisation_exactness_@2(EX) ((void)0)
|
|
# define CGAL_optimisation_exactness_@2_msg(EX,MSG) ((void)0)
|
|
# define CGAL_optimisation_exactness_@2_code(CODE)
|
|
# undef CGAL_OPTIMISATION_EXACTNESS_@1_TAG
|
|
#else
|
|
# define CGAL_optimisation_exactness_@2(EX) \
|
|
((EX)?((void)0): ::CGAL::@2_fail( # EX ,__FILE__,__LINE__,0))
|
|
# define CGAL_optimisation_exactness_@2_msg(EX,MSG) \
|
|
((EX)?((void)0): ::CGAL::@2_fail( # EX ,__FILE__,__LINE__,MSG))
|
|
# define CGAL_optimisation_exactness_@2_code(CODE) CODE
|
|
# define CGAL_OPTIMISATION_EXACTNESS_@1_TAG 1
|
|
#endif // optimisation exactness @2s
|
|
@end
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
\subsubsection{Expensive Checks}
|
|
|
|
@macro<expensive checks>(2) many = @begin
|
|
#if ( ! ( defined( CGAL_OPTIMISATION_CHECK_EXPENSIVE) \
|
|
|| defined( CGAL_CHECK_EXPENSIVE) ) \
|
|
|| defined( CGAL_OPTIMISATION_NO_@1S) \
|
|
|| defined( CGAL_NO_@1S) || defined( NDEBUG))
|
|
# define CGAL_optimisation_expensive_@2(EX) ((void)0)
|
|
# define CGAL_optimisation_expensive_@2_msg(EX,MSG) ((void)0)
|
|
# define CGAL_optimisation_expensive_@2_code(CODE)
|
|
# undef CGAL_OPTIMISATION_EXPENSIVE_@1_TAG
|
|
#else
|
|
# define CGAL_optimisation_expensive_@2(EX) \
|
|
((EX)?((void)0): ::CGAL::@2_fail( # EX ,__FILE__,__LINE__,0))
|
|
# define CGAL_optimisation_expensive_@2_msg(EX,MSG) \
|
|
((EX)?((void)0): ::CGAL::@2_fail( # EX ,__FILE__,__LINE__,MSG))
|
|
# define CGAL_optimisation_expensive_@2_code(CODE) CODE
|
|
# define CGAL_OPTIMISATION_EXPENSIVE_@1_TAG 1
|
|
#endif // optimisation expensive @2s
|
|
@end
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
\subsubsection{Expensive Exactness Checks}
|
|
|
|
@macro<expensive exactness checks>(2) many = @begin
|
|
#if ( ! ( defined( CGAL_OPTIMISATION_CHECK_EXACTNESS) \
|
|
|| defined( CGAL_OPTIMISATION_CHECK_EXPENSIVE) \
|
|
|| defined( CGAL_CHECK_EXACTNESS) \
|
|
|| defined( CGAL_CHECK_EXPENSIVE) ) \
|
|
|| defined( CGAL_OPTIMISATION_NO_@1S) \
|
|
|| defined( CGAL_NO_@1S) || defined( NDEBUG))
|
|
# define CGAL_optimisation_expensive_exactness_@2(EX) \
|
|
((void)0)
|
|
# define CGAL_optimisation_expensive_exactness_@2_msg(EX,MSG) \
|
|
((void)0)
|
|
# define CGAL_optimisation_expensive_exactness_@2_code(CODE)
|
|
# undef CGAL_OPTIMISATION_EXPENSIVE_EXACTNESS_@1_TAG
|
|
#else
|
|
# define CGAL_optimisation_expensive_exactness_@2(EX) \
|
|
((EX)?((void)0): ::CGAL::@2_fail( # EX ,__FILE__,__LINE__,0))
|
|
# define CGAL_optimisation_expensive_exactness_@2_msg(EX,MSG) \
|
|
((EX)?((void)0): ::CGAL::@2_fail( # EX ,__FILE__,__LINE__,MSG))
|
|
# define CGAL_optimisation_expensive_exactness_@2_code(CODE) CODE
|
|
# define CGAL_OPTIMISATION_EXPENSIVE_EXACTNESS_@1_TAG 1
|
|
#endif // optimisation expensive exactness @2s
|
|
@end
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
@! Debugging
|
|
@! ----------------------------------------------------------------------------
|
|
|
|
\subsection{Debugging}
|
|
|
|
The \ccc{CGAL_optimisation_debug} macro can be used to encapsulate code, that
|
|
should not be compiled into the production version, e.g.~diagnose output. The
|
|
following piece of code
|
|
|
|
@macro<optimisation debug macro usage> zero = @begin
|
|
CGAL_optimisation_debug {
|
|
// do something
|
|
}
|
|
@end
|
|
|
|
is expanded to
|
|
|
|
@macro<optimisation debug macro on> zero = @begin
|
|
if ( 1) {
|
|
// do something
|
|
}
|
|
@end
|
|
|
|
in development versions, and to
|
|
|
|
@macro<optimisation debug macro off> zero = @begin
|
|
if ( 0) {
|
|
// do something
|
|
}
|
|
@end
|
|
|
|
in production versions of the program. The latter will be discarded if
|
|
compiled with the \ccc{-O} option.
|
|
|
|
@macro<optimisation debug macro> = @begin
|
|
#if ( defined( CGAL_OPTIMISATION_NO_DEBUG) \
|
|
|| defined( CGAL_NO_DEGUG) || defined( NDEBUG))
|
|
# define CGAL_optimisation_debug if ( 0)
|
|
#else
|
|
# define CGAL_optimisation_debug if ( 1)
|
|
#endif // optimisation debug
|
|
@end
|
|
|
|
|
|
@! ============================================================================
|
|
@! Functions
|
|
@! ============================================================================
|
|
|
|
\section{Functions}
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
@! Function _optimisation_is_valid_fail
|
|
@! ----------------------------------------------------------------------------
|
|
|
|
\subsection{Function \ccFont \_optimisation\_is\_valid\_fail}
|
|
|
|
This function is called from the checking functions of the
|
|
optimisation algorithms if a check fails. First, we declare the
|
|
function.
|
|
|
|
@macro<Function _optimisation_is_valid_fail declaration> = @begin
|
|
bool
|
|
_optimisation_is_valid_fail( CGAL::Verbose_ostream& verr,
|
|
const char* message);
|
|
@end
|
|
|
|
The function prints a failure \ccc{message} to the \cgal\ verbose
|
|
stream \ccc{verr}.
|
|
|
|
@macro<Function _optimisation_is_valid_fail> = @begin
|
|
bool
|
|
_optimisation_is_valid_fail( CGAL::Verbose_ostream& verr,
|
|
const char* message)
|
|
{
|
|
verr << "FAILED." << std::endl;
|
|
verr << " --> " << message << std::endl;
|
|
verr << " object is NOT valid!" << std::endl;
|
|
return( false);
|
|
}
|
|
@end
|
|
|
|
|
|
@! ==========================================================================
|
|
@! Files
|
|
@! ==========================================================================
|
|
|
|
\clearpage
|
|
\section{Files}
|
|
|
|
@i share/namespace.awi
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
@! assertions.h
|
|
@! ----------------------------------------------------------------------------
|
|
|
|
\subsection{include/CGAL/Optimisation/assertions.h}
|
|
|
|
@file <include/CGAL/Optimisation/assertions.h> = @begin
|
|
@<file header with coauthor>(
|
|
"include/CGAL/Optimisation/assertions.h",
|
|
"assertion macros for optimisation algorithms",
|
|
"Geert-Jan Giezeman")
|
|
|
|
#ifndef CGAL_OPTIMISATION_ASSERTIONS_H
|
|
#define CGAL_OPTIMISATION_ASSERTIONS_H
|
|
|
|
// macro definitions
|
|
// =================
|
|
|
|
// assertions
|
|
// ----------
|
|
@<check macros>("ASSERTION","assertion")
|
|
|
|
// preconditions
|
|
// -------------
|
|
@<check macros>("PRECONDITION","precondition")
|
|
|
|
// postconditions
|
|
// --------------
|
|
@<check macros>("POSTCONDITION","postcondition")
|
|
|
|
// warnings
|
|
// --------
|
|
@<check macros>("WARNING","warning")
|
|
|
|
#endif // CGAL_OPTIMISATION_ASSERTIONS_H
|
|
|
|
@<end of file line>
|
|
@end
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
@! debug.h
|
|
@! ----------------------------------------------------------------------------
|
|
|
|
\subsection{include/CGAL/Optimisation/debug.h}
|
|
|
|
@file <include/CGAL/Optimisation/debug.h> = @begin
|
|
@<file header>(
|
|
"include/CGAL/Optimisation/debug.h",
|
|
"debug macro for optimisation algorithms")
|
|
|
|
#ifndef CGAL_OPTIMISATION_DEBUG_H
|
|
#define CGAL_OPTIMISATION_DEBUG_H
|
|
|
|
// macro definitions
|
|
// =================
|
|
|
|
// debug
|
|
// -----
|
|
@<optimisation debug macro>
|
|
|
|
#endif // CGAL_OPTIMISATION_DEBUG_H
|
|
|
|
@<end of file line>
|
|
@end
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
@! basic.h
|
|
@! ----------------------------------------------------------------------------
|
|
|
|
\subsection{include/CGAL/Optimisation/basic.h}
|
|
|
|
@file <include/CGAL/Optimisation/basic.h> = @begin
|
|
@<file header>(
|
|
"include/CGAL/Optimisation/basic.h",
|
|
"basic things for optimisation algorithms")
|
|
|
|
#ifndef CGAL_OPTIMISATION_BASIC_H
|
|
#define CGAL_OPTIMISATION_BASIC_H
|
|
|
|
// includes
|
|
#ifndef CGAL_BASIC_H
|
|
# include <CGAL/basic.h>
|
|
#endif
|
|
#ifndef CGAL_OPTIMISATION_ASSERTIONS_H
|
|
# include <CGAL/Optimisation/assertions.h>
|
|
#endif
|
|
#ifndef CGAL_OPTIMISATION_DEBUG_H
|
|
# include <CGAL/Optimisation/debug.h>
|
|
#endif
|
|
#ifndef CGAL_IO_VERBOSE_OSTREAM_H
|
|
# include <CGAL/IO/Verbose_ostream.h>
|
|
#endif
|
|
|
|
@<namespace begin>("CGAL")
|
|
|
|
// Function declarations
|
|
// =====================
|
|
|
|
// is_valid failure function
|
|
// -------------------------
|
|
@<Function _optimisation_is_valid_fail declaration>
|
|
|
|
@<namespace end>("CGAL")
|
|
|
|
#endif // CGAL_OPTIMISATION_BASIC_H
|
|
|
|
@<end of file line>
|
|
@end
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
@! basic.C
|
|
@! ----------------------------------------------------------------------------
|
|
|
|
\subsection{src/Optimisation/basic.C}
|
|
|
|
@file <src/Optimisation/basic.C> = @begin
|
|
@<file header>(
|
|
"src/Optimisation/basic.C",
|
|
"basic things for optimisation algorithms")
|
|
|
|
#include <CGAL/Optimisation/basic.h>
|
|
|
|
@<namespace begin>("CGAL")
|
|
|
|
// Function implementations
|
|
// ========================
|
|
|
|
// is_valid failure function
|
|
// -------------------------
|
|
@<Function _optimisation_is_valid_fail>
|
|
|
|
@<namespace end>("CGAL")
|
|
|
|
@<end of file line>
|
|
@end
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
@! optimisation_Window_stream.h
|
|
@! ----------------------------------------------------------------------------
|
|
|
|
\subsection{include/CGAL/IO/optimisation\_Window\_stream.h}
|
|
|
|
@file <include/CGAL/IO/optimisation_Window_stream.h> = @begin
|
|
@<file header>(
|
|
"include/CGAL/IO/optimisation_Window_stream.h",
|
|
"graphical output to window stream for optimisation algorithms")
|
|
|
|
#include <CGAL/IO/Min_circle_2_Window_stream.h>
|
|
#include <CGAL/IO/Min_ellipse_2_Window_stream.h>
|
|
|
|
@<end of file line>
|
|
@end
|
|
|
|
@! ----------------------------------------------------------------------------
|
|
@! File Header
|
|
@! ----------------------------------------------------------------------------
|
|
|
|
\subsection*{File Header}
|
|
|
|
@i share/file_header.awi
|
|
|
|
And here come two specific file headers for the product files of this
|
|
web file.
|
|
|
|
@macro <file header>(2) many = @begin
|
|
@<copyright notice>
|
|
@<file name>(@1)
|
|
@<file description>(
|
|
"Optimisation_basic",
|
|
"Geometric Optimisation",
|
|
"Optimisation_basic",
|
|
"$Id$","$Date$",
|
|
"Sven Schönherr <sven@@inf.ethz.ch>",
|
|
"ETH Zürich (Bernd Gärtner <gaertner@@inf.ethz.ch>)",
|
|
"@2")
|
|
@end
|
|
|
|
@macro <file header with coauthor>(3) many = @begin
|
|
@<copyright notice>
|
|
@<file name>(@1)
|
|
@<file description>(
|
|
"Optimisation_basic",
|
|
"Geometric Optimisation",
|
|
"Optimisation_basic",
|
|
"$Id$","$Date$",
|
|
"@3, Sven Schönherr <sven@@inf.ethz.ch>",
|
|
"ETH Zürich (Bernd Gärtner <gaertner@@inf.ethz.ch>)",
|
|
"@2")
|
|
@end
|
|
|
|
@! ===== EOF ==================================================================
|