gecoder-with-gecode 0.7.1 → 0.8.0

data/ext/gecode-2.1.1/doxygen/doxygen.hh.in

@@ -0,0 +1,1111 @@
+/*
+ *  Main authors:
+ *     Christian Schulte <schulte@gecode.org>
+ *     Guido Tack <tack@gecode.org>
+ *
+ *  Copyright:
+ *     Christian Schulte, 2005
+ *     Guido Tack, 2005
+ *
+ *  Last modified:
+ *     $Date: 2008-02-29 08:26:04 +0100 (Fri, 29 Feb 2008) $ by $Author: tack $
+ *     $Revision: 6360 $
+ *
+ *  This file is part of Gecode, the generic constraint
+ *  development environment:
+ *     http://www.gecode.org
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining
+ *  a copy of this software and associated documentation files (the
+ *  "Software"), to deal in the Software without restriction, including
+ *  without limitation the rights to use, copy, modify, merge, publish,
+ *  distribute, sublicense, and/or sell copies of the Software, and to
+ *  permit persons to whom the Software is furnished to do so, subject to
+ *  the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be
+ *  included in all copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ *  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ */
+
+/*
+ * No code, just contains the group definitions of the
+ * Doxygen-generated documentation
+ */
+
+
+/**
+ * \defgroup Task Functionality by programming task
+ */
+
+/**
+ * \defgroup TaskModel Programming models
+ * \ingroup Task
+ */
+
+/**
+ * \defgroup TaskModelScript Setting up scripts
+ *
+ * Scripts (or models) are programmed by inheriting from the class
+ * Gecode::Space. For many examples see \ref Example.
+ *
+ * \ingroup TaskModel
+ */
+
+/**
+ * \defgroup TaskModelInt Using finite domain integers
+ * \ingroup TaskModel
+ */
+
+/**
+ * \defgroup TaskModelIntVars Integer variables
+ * \ingroup TaskModelInt
+ */
+
+/**
+ * \defgroup TaskModelSearch Search engines
+ *
+ * Defines search engines. All search engines (but Gecode::LDS, where
+ * it is not needed) support recomputation. The behaviour of recomputation
+ * is controlled by a passing a search option object (see the class 
+ * Gecode::Search::Options).
+ *
+ * Requires \code #include "gecode/search.hh" \endcode
+ * \ingroup TaskModel
+ */
+
+/**
+ * \defgroup TaskModelSet Using finite integer sets
+ * \ingroup TaskModel
+ */
+
+/**
+ * \defgroup TaskModelSetVars Set variables
+ * \ingroup TaskModelSet
+ */
+
+/**
+ * \defgroup TaskModelCpltSet Using finite integer sets with complete domain representation
+ * \ingroup TaskModel
+ */
+
+/**
+ * \defgroup TaskModelCpltSetVars Set variables with complete domain representation
+ * \ingroup TaskModelCpltSet
+ */
+
+/**
+ * \defgroup TaskModelMiniModel Direct modelling
+ * \ingroup TaskModel
+ */
+
+/**
+ * \defgroup TaskSearch Programming search engines
+ * \ingroup Task
+ */
+
+/**
+ * \defgroup TaskActor Programming actors
+ * \ingroup Task
+ */
+
+/**
+ * \defgroup TaskActorInt Programming integer actors
+ * \ingroup TaskActor
+ */
+
+/**
+ * \defgroup TaskActorSet Programming set actors
+ * \ingroup TaskActor
+ */
+
+/**
+ * \defgroup TaskActorCpltSet Programming CpltSet actors
+ * \ingroup TaskActor
+ */
+
+/**
+ * \defgroup TaskVar Programming variables
+ * \ingroup Task
+ */
+
+/**
+ * \defgroup TaskVarView Programming views for variables
+ * \ingroup TaskVar
+ */
+
+/**
+ * \defgroup TaskTest Testing
+ * \ingroup Task
+ */
+
+/**
+ * \defgroup TaskReflSer Reflection and serialization
+ * \ingroup Task
+ *
+ * Reflection allows you to query a Space object for the propagators, 
+ * branchings, and variables that it contains.
+ *
+ * Serialization provides methods for producing a text or binary 
+ * representation of a space that can be used to recreate a copy of the space.
+ */
+
+/**
+ * \defgroup TaskReflection Reflection API
+ *
+ * The reflection API provides information about the propagators, branchings,
+ * and variables in a space. More detailed, step-by-step information can be 
+ * found in the \ref PageReflection "reflection tutorial".
+ *
+ * Requires \code #include "gecode/kernel.hh" \endcode
+ *
+ * \ingroup TaskReflSer
+ */
+
+#include "doxygen/reflection.hh"
+
+/**
+ * \defgroup TaskSerialization Serialization
+ *
+ * The serialization API lets you produce text or binary representations of a 
+ * space, and recreate a copy of the original space from that representation.  
+ * It provides funcionality for creating variables and posting propagators in 
+ * a space using the specifications obtained through reflection.
+ *
+ * Requires \code #include "gecode/serialization.hh" \endcode
+ *
+ * \ingroup TaskReflSer
+ */
+
+/**
+ * \defgroup Func Common functionality
+ */
+
+/**
+ * \defgroup FuncMem Memory management
+ * \ingroup Func
+ */  
+
+/**
+ * \defgroup FuncThrow Gecode exceptions
+ * \ingroup Func
+ */
+
+/**
+ * \defgroup FuncSupport Support algorithms and datastructures
+ *
+ * These are some common datastructures used in the implementation of
+ * %Gecode. Maybe they can be also useful to others.
+ *
+ * In order to use them, one needs to include the appropriate header-file
+ * as described in the class and function documentation.
+ * \ingroup Func
+ */  
+
+/**
+ * \defgroup FuncIter Range and value iterators
+ *
+ * Both range and value iterators have a rather simple interface
+ * for controlling iteration (which deviates from what you might be
+ * used to from other iterators).
+ *
+ * The application operator (if \c i is an iterator, it is invoked by \c i() )
+ * tests whether an iterator has not yet reached
+ * its end (in this case, \c true is returned). The prefix
+ * increment operator (if \c i is an iterator, this is invoked as \c ++i)
+ * moves the iterator to the next element (either next value or next range).
+ *
+ * Value iterators provide access to the value by the member function
+ * \c val(). Range iterators provide access to the smallest, largest, and
+ * width of the current range by \c min(), \c max(), and \c width()
+ * respectively.
+ * 
+ * Requires \code #include "gecode/iter.hh" \endcode
+ * \ingroup Func
+ */
+
+/**
+ * \defgroup FuncIterRanges Range iterators
+ *
+ * A range iterator provides incremental access to a sequence of increasing
+ * ranges.
+ *
+ * Requires \code #include "gecode/iter.hh" \endcode
+ * \ingroup FuncIter
+ */
+
+/**
+ * \defgroup FuncIterRangesVirt Range iterators with virtual member functions
+ *
+ * A range iterator provides incremental access to a sequence of increasing
+ * ranges. Iterators with virtual member functions have to be used when
+ * they are combined dynamically, and the actual types hence cannot be
+ * specified as template arguments.
+ *
+ * Requires \code #include "gecode/iter.hh" \endcode
+ * \ingroup FuncIterRanges
+ */
+
+/**
+ * \defgroup FuncIterValues Value iterators
+ *
+ * A value iterator provides incremental access to a sequence of increasing
+ * values. 
+ *
+ * Requires \code #include "gecode/iter.hh" \endcode
+ * \ingroup FuncIter
+ */
+
+/**
+ * \defgroup FuncIterValuesVirt Value iterators with virtual member functions
+ *
+ * A value iterator provides incremental access to a sequence of increasing
+ * values. Iterators with virtual member functions have to be used when
+ * they are combined dynamically, and the actual types hence cannot be
+ * specified as template arguments.
+ *
+ * Requires \code #include "gecode/iter.hh" \endcode
+ * \ingroup FuncIterValues
+ */
+
+/**
+ * \defgroup Other Other available functionality
+ *
+ */
+
+/**
+ * \defgroup FuncIntProp Integer propagators
+ *
+ * This module contains a description of all predefined integer 
+ * propagators. They can be reused, for example, for rewriting
+ * newly defined integer propagators into already available
+ * propagators.
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncIntSelView Integer view selection for branching
+ *
+ * Contains a description of view selection strategies on integer
+ * views that can be used together with the generic view/value
+ * branching class Gecode::ViewValBranching (argument \a ViewSel).
+ *
+ * All view selection classes require 
+ * \code #include "gecode/int/branch.hh" \endcode
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncIntSelVal Integer value selection for branching
+ *
+ * Contains a description of value selection strategies on integer
+ * views that can be used together with the generic view/value
+ * branching class Gecode::ViewValBranching (argument \a ValSel).
+ *
+ * All value selection classes require 
+ * \code #include "gecode/int/branch.hh" \endcode
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncSetProp Set propagators
+ *
+ * This module contains a description of all predefined finite set
+ * propagators. They can be reused, for example, for rewriting
+ * newly defined finite set propagators into already available
+ * propagators.
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncSetSelView Set view selection for branching
+ *
+ * Contains a description of view selection strategies on set
+ * views that can be used together with the generic view/value
+ * branching class Gecode::ViewValBranching (argument \a ViewSel).
+ *
+ * All view selection classes require 
+ * \code #include "gecode/set/branch.hh" \endcode
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncSetSelVal Set value selection for branching
+ *
+ * Contains a description of value selection strategies on set
+ * views that can be used together with the generic view/value
+ * branching class Gecode::ViewValBranching (argument \a ValSel).
+ *
+ * All value selection classes require 
+ * \code #include "gecode/set/branch.hh" \endcode
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncCpltSetProp CpltSet propagators
+ *
+ * This module contains a description of all predefined
+ * propagators for CpltSet variables. They can be reused, for example, for 
+ * rewriting newly defined CpltSet propagators into already available
+ * propagators.
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncCpltSetSelView CpltSet view selection for branching
+ *
+ * Contains a description of view selection strategies on CpltSet
+ * views that can be used together with the generic view/value
+ * branching class Gecode::ViewValBranching (argument \a ViewSel).
+ *
+ * All view selection classes require 
+ * \code #include "gecode/cpltset/branch.hh" \endcode
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup FuncCpltSetSelVal CpltSet value selection for branching
+ *
+ * Contains a description of value selection strategies on CpltSet
+ * views that can be used together with the generic view/value
+ * branching class Gecode::ViewValBranching (argument \a ValSel).
+ *
+ * All value selection classes require 
+ * \code #include "gecode/cpltset/branch.hh" \endcode
+ * \ingroup Other
+ */
+
+/**
+ * \defgroup Example Example scripts (models)
+ *
+ * All scripts are compiled into simple standalone programs. All
+ * programs understand the several generic and problem-specific
+ * commandline options. An overview of the options is available
+ * by invoking the standalone programs with the <code>-help</code>
+ * commandline option.
+ *
+ */
+
+/**
+ * \defgroup ExProblem Scripts for problems
+ * \ingroup Example
+ *
+ * These scripts are for small problems that exemplify how to model
+ * with %Gecode.
+ *
+ */
+
+/**
+ * \defgroup ExStress Scripts for stress tests
+ * \ingroup Example
+ *
+ * These scripts are for stressing certain system features, typically
+ * the implementation of a particular constraint.
+ *
+ */
+
+/*
+ * Collect some definitions for which no reasonable place exists
+ *
+ */
+
+/**
+ * \namespace Gecode::Support 
+ * \brief %Support algorithms and datastructures
+ */
+
+/**
+ * \mainpage Gecode Reference Documentation
+ *
+ * This document provides reference information about
+ * <A HREF="http://www.gecode.org">%Gecode</A>.
+ * The documentation is structured into three major groups: 
+ * getting started, common programming tasks, and  
+ * available functionality.
+ *
+ * This document corresponds to %Gecode version @VERSION@, please consult
+ * the changelog for \ref SectionChangeList "recent changes".
+ *
+ * \section SecStart Getting started
+ *
+ * For your first steps with %Gecode, the following pages may be of interest:
+ *  - \ref PageComp
+ *  - \ref PageUsage
+ *  - \ref PageNotation
+ *  - \ref PageGlossary
+ *
+ * To get started with modelling in %Gecode, you may also want to have a look 
+ * at our \ref Example.
+ *
+ * \section SecByTask Programming tasks
+ *
+ * Documentation is available for the following tasks:
+ *  - \ref TaskModel
+ *  - \ref TaskSearch
+ *  - \ref TaskActor "Programming propagators and branchings"
+ *  - \ref TaskVar
+ *  - \ref TaskTest
+ *  - \ref TaskReflSer
+ *
+ * \section SecByFunc Available functionality
+ *
+ * The most important functionality is:
+ *  - \ref FuncMem
+ *  - \ref FuncThrow
+ *
+ * The complete functionality can be found \ref Func "here".
+ *
+ * The part \ref Other documents existing propagators, variable 
+ * implementations, and so on which serves as documentation of examples.
+ *
+ * \section SecIndex List and index content
+ *
+ * Additionally, the documentation also features the following parts:
+ *  - \ref PageLic
+ *  - \ref PageChange
+ *
+ * The following lists and indices are available
+ *  - \ref PageCodeStat
+ *  - <a class="el" href="modules.html">List of all modules</a> 
+ *  - <a class="el" href="annotated.html">List of all classes including brief documentation</a>
+ *  - <a class="el" href="namespaces.html">List of all namespaces including brief documentation</a>
+ *  - <a class="el" href="files.html">List of all files</a>
+ *  - <a class="el" href="hierarchy.html">Class hierarchy</a>
+ *  - <a class="el" href="classes.html">Alphabetical class index</a>
+ *  - <a class="el" href="namespacemembers.html">Namespace members</a>
+ *  - <a class="el" href="functions.html">Class members</a>
+ *  - <a class="el" href="globals.html">File members</a>
+ */
+
+/**
+ * \page PageNotation Notational conventions
+ *
+ * Throughout this reference documentation we use some notational conventions
+ * designed to keep the documentation concise yet understandable. Please
+ * read the following carefully.
+ *
+ * \section NotationArray Array notation
+ *
+ * We allow ourselves to refer to the \f$i\f$-th element of an array \f$x\f$ 
+ * by \f$x_i\f$. The size of an array \f$x\f$ (either provided by a member 
+ * function \c %size() or clear from context) is denoted \f$|x|\f$.
+ *
+ * \section NotationHome The home space
+ *
+ * Many functions and member functions take an argument \a home of 
+ * type \c Space*. The home space serves as manager to many
+ * operations used by variables, views, propagators, spaces, and so
+ * on. It provides
+ * services such as failure management, propagation control, 
+ * memory management, and so on. To keep the documentation concise
+ * the home space is not documented for functions
+ * and member functions.
+ *
+ * \section NotationShare Sharing in update and copy
+ *
+ * In member functions that either copy or update an object during
+ * cloning, an argument \a share of type \c bool is available. This
+ * Boolean value controls whether during cloning the data structure at
+ * hand will be shared among the newly created cloned space and the original
+ * or whether two independent copies are created. Some functions (such
+ * as \c copy for spaces (Gecode::Space) or \c copy for propagators
+ * (Gecode::Propagator) also feature this argument. Here it is used
+ * to pass on the Boolean value to other datastructures used inside spaces
+ * or propagators.
+ *
+ * The actual value the \a share argument has is defined by the search
+ * engine: when a search engine uses the \a clone member function of
+ * a space it decides whether sharing is to be used in the cloning of
+ * the space or not. If the search engine is single-threaded, it will
+ * use full sharing (\a share will be true). Only if the search engine
+ * uses concurrency or parallelism with more than a single thread,
+ * it will pass false as value. This means that by not sharing data structures
+ * among spaces which are to be used in different threads, all parts of
+ * %Gecode but the actual search engine do not need to provide concurrency
+ * control.
+ *
+ * As examples for data structures which are sensitive to sharing, consider
+ * Gecode::SharedArray, Gecode::IntSet, and Gecode::DFA.
+ */
+
+/**
+  \page PageGlossary Brief glossary
+
+This page gives brief explanations about some of the most
+frequently occurring terms (currently limited to important
+entities manifest in the implementation) used in the %Gecode
+reference documentation.
+
+\section GlossaryActor Actor
+
+An actor is a branching (\ref GlossaryBranching), a propagator
+(\ref GlossaryPropagator), or an advisor (\ref
+GlossaryAdvisor). Actors provide common functionality such as
+member functions for copying during cloning, memory allocation,
+and so on. Actors are implemented by the class
+Gecode::Actor. More on programming actors can be found in the
+module \ref TaskActor.
+
+\section GlossaryBranching Branching
+
+A branching defines the shape of the search tree. Branchings are
+also known as labelings or distributors, and a branching creates
+a series of choice points. Branchings are implemented by the
+class Gecode::Branching. A common abstraction for defining
+branchings based on view and value selection is provided by the
+class Gecode::ViewValBranching.
+
+\section GlossaryBranchingDesc Branching description
+
+A branching description speeds up recomputation by providing
+batch recomputation. It is created by a branching (\ref
+GlossaryBranching) and allows to replay the effect of that
+branching without the need to first perform constraint
+propagation. The base-class for branching descriptions is
+Gecode::BranchingDesc. An example for a branching description
+that works together with branchings based on view and value
+selection is Gecode::PosValDesc.
+
+\section GlossarySpace Computation space
+
+A computation space (space for short) comprises all entities for
+a constraint problem to be solved, including all actors (\ref
+GlossaryActor) and variables (\ref GlossaryVariable). A space can
+be seen as corresponding to a node in the search tree. It
+organizes constraint propagation, the branching process,
+exploration, and memory management. Spaces are implemented by the
+class Gecode::Space. They provide functionality for \ref
+TaskModelScript, \ref TaskSearch, and \ref FuncMemSpace.
+
+\section GlossaryME Modification event
+
+A modification event describes how a view (\ref GlossaryView) or
+variable implementation (\ref GlossaryVarImp) is changed by an
+update operation performed on the view or variable. Each variable
+domain defines its own modification events (see \ref
+TaskActorIntMEPC and \ref TaskActorSetMEPC). However modification
+events that describe generic events such as failure, no
+modification, or assignment to a single value are predefined (see
+\ref TaskVarMEPC).
+
+\section GlossaryPropCond Propagation condition
+
+A propagation condition defines when a propagator requires to be
+re-executed. Re-execution is controlled by the modification events
+that occur on the variables the propagator depends on (see \ref
+GlossaryPropagator). Propagation conditions and the relation
+between propagation conditions and modification events depends on
+the variable domain (see \ref TaskActorIntMEPC and \ref
+TaskActorSetMEPC). However, the propagation conditions that
+states re-execution when a variable becomes assigned is generic
+(see \ref TaskVarMEPC).
+
+\section GlossaryPropagator Propagator
+
+A propagator implements a constraint (actually, a constraint can
+be implemented by a collection of propagators). Execution by a
+propagator is defined by its dependencies: the views (referring to
+some variables) together with their propagation conditions. A
+propagator is implemented by inheriting from the class
+Gecode::Propagator. Common abstractions for propagators are also
+available (see \ref TaskPropPat, \ref TaskPropRePat, and \ref
+TaskPropSetPat).
+
+\section GlossaryAdvisor Advisor
+
+An advisor supports a single propagator. An advisor is executed
+whenever the view it has subscribed to is modified. Execution of
+an advisor amounts to executing the advise member function of the
+advisor's propagator where the advisor and delta information
+(\ref GlossaryDelta) are passed as arguments. An advisor is
+implemented by inheriting from the class Gecode::Advisor.
+
+\section GlossaryDelta Delta information
+
+Delta information is implemented as an object which is a subclass
+of Gecode::Delta. A Delta object describes how the domain of a
+variable has been changed by an operation on the variable. Delta
+objects are passed together with advisors to the advise member
+function of a propagator.
+
+\section GlossaryMED Modification event delta
+
+A propagator maintains a delta of modification events for all
+variable types. A modification event delta is available to the
+propagate and cost member functions of a propagator and describes
+the modification events that have occurred since the last execution of a
+propagator.  A modification event delta is highly abstract: it
+does not reveal for which variable a particular modification
+event occurred, it only reveals that a certain modification event
+has occurred for any variable of a given variable
+type. Modification events for a particular variable type can be
+extracted from a modification event delta through the respective
+view or variable implementation (see for example \ref
+TaskActorIntView or \ref TaskActorSetView).
+
+\section GlossaryVariable Variable
+
+A variable is used for modeling problems, be it for direct
+modeling or for modeling through some interface. A variable
+provides only those operations useful for modeling and excludes
+in particular operations that can modify the variable domain
+directly. A variable is implemented by a variable implementation
+(see below).
+
+\section GlossaryVarImp Variable implementation
+
+A variable implementation is implemented by inheriting from
+Gecode::Variable. It implements the variable domain and provides
+operations to access and modify the domain. Examples of variable
+implementations are Gecode::Int::IntVarImp and
+Gecode::Set::SetVarImp.
+
+\section GlossaryView View
+
+A view offers essentially the same interface as a variable
+implementation and allows both domain access and
+modification. Typically, several views exist for the same
+variable implementation to obtain several constraints from the
+same propagator. Examples of views are \ref TaskActorIntView and
+\ref TaskActorSetView.
+
+*/
+ 
+/**
+ * \page PageUsage Compiling and linking against Gecode
+ *
+ * \section SecUsageInclude Including header files
+ *
+ * Deciding which header files must be included when using %Gecode is
+ * quite straightforward. There are the following header files for inclusion:
+ *  - gecode/support.hh must always included (support.hh header is 
+ *    included from kernel.hh)
+ *  - gecode/kernel.hh must always be included (the header files below
+ *    also always include kernel.hh).
+ *  - gecode/search.hh must be included, if search engines are used 
+ *    (see for example \ref TaskModelSearch).
+ *  - gecode/int.hh must be included, if any integer functionality is used
+ *    (see for example \ref TaskModelInt and \ref TaskActorInt).
+ *  - gecode/set.hh must be included, if any finite set functionality is used
+ *    (see for example \ref TaskModelSet and \ref TaskActorSet).
+ *  - gecode/cpltset.hh must be included, if any complete finite set 
+ *    functionality is used
+ *    (see for example \ref TaskModelCpltSet and \ref TaskActorCpltSet).
+ *  - gecode/minimodel.hh must be included, if direct modelling support
+ *    is used (see for example \ref TaskModelMiniModel).
+ *  - gecode/serialization.hh must be included, if support for serialization
+ *    is used.
+ *
+ * Other functionality is available through a set of header files. For example
+ * to access the implementation of particular propagators, a particular header
+ * file must be included. The header file to be included is always mentioned
+ * in the documentation of the class or function.
+ *
+ * \section SecUsageLink Linking libraries
+ *
+ * Setting the exact name for a library on a particular platform aside,
+ * inclusion of header files basically coincides with against which
+ * library must be linked. That is:
+ *  - If gecode/support.hh is included, linking againg the support library is 
+ *    required.
+ *  - If gecode/kernel.hh is included, linking against the kernel library is
+ *    required.
+ *  - If gecode/search.hh is included, linking against the search library is
+ *    required.
+ *  - If gecode/int.hh is included, linking against the integer library is
+ *    required.
+ *  - If gecode/set.hh is included, linking against the set library is
+ *    required.
+ *  - If gecode/cpltset.hh is included, linking against the cpltset library is
+ *    required.
+ *  - If gecode/minimodel.hh is included, linking against the minimodel
+ *    library is required.
+ *  - If gecode/serialization.hh is included, linking against the 
+ *    serialization library is required.
+ *
+ * The functionality in \ref FuncIter requires no
+ * library for linking. Reusing integer or set propagators of course
+ * require the integer or set library.
+ *
+ * If there is a difference between library and DLL (such as on Windows)
+ * linking must be done against the appropriate library and the
+ * corresponding DLL must be available for execution (such as in the
+ * PATH environment variable).
+ *
+ * The libraries contain code that is executed at link time (for registering
+ * part of the reflection functionality).  If you create static libraries,
+ * this code will not be linked into your executable as it is not directly
+ * referenced. You will have to tell your linker to include all symbols from 
+ * the library (e.g. using -Wl,--whole-archive on Linux). Please refer to your
+ * linker documentation.
+ *
+ * \section SecUsageLibraries Library names
+ *
+ * \subsection SULA Windows with Visual Studio
+ *
+ *  - Support library and DLL: GecodeSupport.lib and GecodeSupport.dll
+ *  - Kernel library and DLL: GecodeKernel.lib and GecodeKernel.dll
+ *  - Search library and DLL: GecodeSearch.lib and GecodeSearch.dll
+ *  - Integer library and DLL: GecodeInt.lib and GecodeInt.dll
+ *  - Set library and DLL: GecodeSet.lib and GecodeSet.dll
+ *  - CpltSet library and DLL: GecodeCpltSet.lib and GecodeCpltSet.dll
+ *  - Minimodel library and DLL: GecodeMiniModel.lib and GecodeMiniModel.dll
+ *  - Serialization library and DLL: GecodeSerialization.lib and 
+ *    GecodeSerialization.dll
+ *
+ * \subsection SULB Unix (Linux, MacOS X)
+ *
+ * Depending on whether %Gecode was compiled as a static or as a dynamic
+ * library, different filename suffixes are used on different Unix platforms.
+ * All library names follow the following scheme:
+ *
+ *  - Support library: libgecodesupport.&lt;EXT&gt;
+ *  - Kernel library: libgecodekernel.&lt;EXT&gt;
+ *  - Search library: libgecodesearch.&lt;EXT&gt;
+ *  - Integer library: libgecodeint.&lt;EXT&gt;
+ *  - Set library: libgecodeset.&lt;EXT&gt;
+ *  - CpltSet library: libgecodecpltset.&lt;EXT&gt;
+ *  - Minimodel library: libgecodeminimodel.&lt;EXT&gt;
+ *  - Serialization library: libgecodeserialization.&lt;EXT&gt;
+ *
+ * where &lt;EXT&gt; depends on the library type and platform:
+ *
+ *  - libgecode[...].a for static libaries on all Unix flavors
+ *  - libgecode[...].so for shared libraries on Linux
+ *  - libgecode[...].dylib for shared libraries on MacOS X
+ *
+ * You can use for example
+ * 
+ * <code>gcc -L$GPREFIX/lib -lgecodekernel</code>
+ *
+ * to link the kernel library, if the libraries are found in
+ * <code>$GPREFIX/lib</code>.
+ */
+ 
+/**
+ * \page PageComp Compiling and installing Gecode
+ *
+ * The %Gecode library, including examples and documentation, can be built
+ * on all recent versions of Windows, Linux, and MacOS X. Porting to other
+ * Unix flavors should be easy, if any change is necessary at all.
+ *
+ * \section Prerequisites
+ *
+ * In order to compile %Gecode, you need a standard Unix toolchain including
+ * the following programs:
+ *
+ *  - a bash-compatible shell
+ *  - GNU make
+ *  - sed
+ *  - cp
+ *  - diff
+ *  - tar
+ *  - perl
+ *
+ * These are available in all standard installations of Linux. On MacOS X,
+ * you need to install the Apple developer tools. For
+ * Windows, we require the
+ * <a href="http://www.cygwin.com/">Cygwin environment</a> that provides
+ * all necessary tools.
+ *
+ * We currently support
+ *   - the Microsoft Visual C++ compilers for Windows. The Microsoft
+ *     Visual C++ 2005 Express Edition is available free of charge from
+ *     <a href="http://msdn.microsoft.com/vstudio/express/visualc/">the MSDN
+ *     web pages</a>. 
+ *   - the GNU Compiler Collection (gcc) for Windows and Unix flavors such as
+ *     Linux and MacOS X. The GNU gcc is open source software and available
+ *     from <a href="http://gcc.gnu.org/">the GCC home page</a>. It is included
+ *     in all Linux distributions and the Apple MacOS X developer tools.
+ *     %Gecode requires at least version 3.4 of gcc. We recommend using version
+ *     4.2 or higher. Very unfortunately, the parser used in versions of gcc
+ *     before 3.4 is broken and hence cannot compile %Gecode.
+ *
+ * The Intel C++ compiler is currently not supported.
+ *
+ * \section CompConf Configuring the sources
+ *
+ * %Gecode uses GNU autoconf to acquire information about the system it is
+ * compiled on. Typically, you need to run the <code>configure</code>
+ * script in the toplevel directory.
+ *
+ * To setup %Gecode for your particular system, you may need to add one or
+ * more of the following options to <code>configure</code>:
+ *
+ *  - When using the Microsoft Visual C++ compiler, add
+ *    <code>CC=cl CXX=cl</code> to your
+ *    invocation of <code>configure</code>
+ *  - To install %Gecode somewhere else than the default
+ *    <code>/usr/local</code>, use the <code>--prefix=[...]</code> switch
+ *  - You can enable and disable the individual modules %Gecode consists of
+ *    using <code>--enable-[MODULE]</code> and <code>--disable-[MODULE]</code>
+ *
+ * You can get a list of all supported configuration options by calling 
+ * <code>configure</code> with the <code>--help</code> switch.
+ *
+ * \subsection CompConfExamples Example configurations
+ *
+ * To compile %Gecode on a <b>Windows machine using the Microsoft compiler</b>, use
+ *
+ * <code>./configure CC=cl CXX=cl</code>
+ *
+ * To compile only the %Gecode library <b>without examples</b> on a Unix machine, use
+ *
+ * <code>./configure --disable-examples</code>
+ *
+ * To compile on a <b>Unix machine</b> using a different than the default
+ * <code>gcc</code> compiler, and install under <code>/opt/gecode</code>, use
+ *
+ * <code>./configure --prefix=/opt/gecode CC=gcc-4.0 CXX=g++-4.0</code>
+ *
+ * To compile a <b>debug build</b> on Unix, turning on all assertions and not
+ * inlining anything, use
+ *
+ * <code>./configure --enable-debug</code>
+ *
+ * To compile on <b>Cygwin</b>, but linking against the <b>Windows libraries</b> instead
+ * of the Cygwin libraries, use
+ *
+ * <code>./configure CC="gcc -mno-cygwin" CXX="g++ -mno-cygwin"</code>
+ * Note that we only support building static libraries on Cygwin.
+ *
+ * To compile on a system using a different than the default compiler,
+ * and a <code>/bin/sh</code> that is not bash compatible (e.g. a
+ * <b>Solaris machine</b>), use
+ *
+ * <code>./configure --with-host-os=linux \ </code><br>
+ * <code>&nbsp;&nbsp;&nbsp;CC="gcc-4.0" CXX="g++-4.0" \ </code><br>
+ * <code>&nbsp;&nbsp;&nbsp;SHELL="/bin/bash"</code><br>
+ * <code>make SHELL="/bin/bash"</code>
+ *
+ * You can compile as <b>"universal binary" on a Mac OS
+ * machine</b>. Configure with
+ *
+ * <code>./configure --with-architectures=i386,ppc</code>
+ *
+ * For building universal binaries on a PowerPC machine, you have to supply
+ * the path to the universal SDK (which is the default on Intel based Macs):
+ * 
+ * <code>./configure --with-architectures=i386,ppc</code>
+ * <code>&nbsp;&nbsp;&nbsp;--with-sdk=/Developer/SDKs/MacOSX10.4u.sdk</code>
+ *
+ * \subsection CompConfUsr Passing options for compilation
+ *
+ * Additional options for compilation can be passed to the compiler
+ * from the make commandline via the variable <code>CXXUSR</code>. For
+ * example, to pass to gcc the additional option "-mtune=i686" the following
+ * can be used:
+ *
+ * <code>make CXXUSR="-mtune=i686"</code>
+ *
+ * \subsection CompConfSepDir Compiling in a separate directory
+ *
+ * The %Gecode library can be built in a separate directory. This is useful
+ * if you do not want to clutter the source tree with all the object files
+ * and libraries.
+ *
+ * Configuring %Gecode in a separate directory is easy. Assume that the
+ * sources can be found in directory <code>$GSOURCEDIR</code>, change to
+ * the directory where you want to compile %Gecode and call
+ *
+ * <code>$GSOURCEDIR/configure [options]</code>
+ *
+ * This will generate all necessary files in the new build directory.
+ *
+ * \section CompComp Compiling the sources
+ *
+ * After successful configuration, simply invoking
+ *
+ * <code>make</code>
+ *
+ * in the toplevel %Gecode directory will compile the whole library.
+ *
+ * \section CompExamples Running the examples
+ *
+ * After compiling the examples, they can be run directly from the command
+ * line. For instance, try the %Golomb Rulers Problem:
+ *
+ * <code>./examples/golomb</code>
+ *
+ * or (when running Windows):
+ *
+ * <code>./examples/golomb.exe</code>
+ * 
+ * On some platforms, you may need to set environment variables like
+ * <code>LD_LIBRARY_PATH</code> (Linux) or <code>DYLD_LIBRARY_PATH</code>
+ * (Mac OS) to the toplevel compile directory (where the dynamic libraries
+ * are placed after compilation).
+ *
+ * For more information on example scripts see \ref Example.
+ *
+ * \section Installation Installation
+ *
+ * After a successful compilation, you can install the %Gecode library
+ * and all header files necessary for compiling against it by invoking
+ *
+ * <code>make install</code>
+ *
+ * in the build directory.
+ *
+ * \section DepMngmt Dependency management
+ *
+ * The dependencies between source files are not handled automatically. If you
+ * are using a Gecode version from our subversion repository or if you
+ * modified any of the source files, you will have to call
+ * <code>make depend</code> before compilation in order to determine the
+ * source dependencies.
+ *
+ * Dependency management is only needed for recompiling Gecode after changing
+ * something. In an unmodified version (or after a <code>make clean</code>)
+ * all files are compiled anyway.
+ *
+ * \section UnsupPlatfrms Compiling for unsupported platforms
+ *
+ * If you want to try compiling Gecode on a platform that we do not
+ * mention, you can override the platform tests during
+ * <code>configure</code>. There are two options to specify the type of
+ * platform:
+ *
+ *  - <code>--with-host-os=[linux|darwin|windows]</code>
+ *  - <code>--with-compiler-vendor=[gnu|microsoft]</code>
+ *
+ * Using the first option, you can state that your platform should behave like
+ * Linux, Darwin (which is actually BSD), or Windows. This affects mainly
+ * the filenames and the tools used to generate shared and static libraries.
+ *
+ * The second option says
+ * that your compiler can be used very much like the gnu compiler
+ * <code>gcc</code>, or the Microsoft compiler <code>cl</code>.
+ * Please let us know of any successfull attempt at
+ * compiling Gecode on other platforms.
+ *
+ * \section MakeTargets Useful Makefile targets
+ *
+ * The main %Gecode Makefile supports the following useful targets:
+ *
+ *  - <code>all</code> compiles all parts of the library that were enabled
+ *                     during <code>configure</code>, and the examples if
+ *                     enabled
+ *  - <code>install</code> installs library, headers and examples (if enabled)
+ *                         into the <code>prefix</code> given at
+ *                         <code>configure</code>
+ *  - <code>clean</code> removes object files
+ *  - <code>veryclean</code> removes object files, libraries, and all files 
+ +                           generated during <code>make</code>
+ *  - <code>distclean</code> removes object files, libraries, and all
+ *                           generated files
+ *  - <code>depend</code> generates dependencies between source files
+ *  - <code>test</code> compiles the test suite
+ *  - <code>doc</code> generates this reference documentation using doxygen
+ *  - <code>installdoc</code> installs the documentation
+ *  - <code>dist</code> creates a source distribution as a tgz archive, not 
+ *    including the contributions found in the <code>contribs</code> directory
+ *  - <code>distdir</code> creates a source distribution in a directory, not 
+ *    including the contributions found in the <code>contribs</code> directory
+ *  - <code>distdoc</code> creates tgz and zip archives of the documentation
+ *  - <code>distzip</code> creates a binary distribution as a zip archive
+ *  - <code>disttgz</code> creates a binary distribution as a tgz archive
+ *
+ * \section CompileGist Compilation with Gist
+ *
+ * The %Gecode Interactive Search Tool (Gist) is a graphical search engine for 
+ * %Gecode, built on top of the
+ * <a href="http://trolltech.com/products/qt">Qt GUI toolkit</a>.
+ *
+ * In order to compile %Gecode with Gist, you need an installation of the Qt 
+ * library including the development header files.  The source code for Qt is 
+ * <a href="http://trolltech.com/downloads/opensource">available from 
+ * Trolltech under the GPL license.</a>
+ *
+ * <b>
+ * Please note that if you want to develop closed-source software with %Gecode
+ * and Gist, you will need to get a commercial license for Qt from Trolltech!
+ * </b>
+ *
+ * If you are developing on Windows using the Microsoft Visual C++ compiler, 
+ * make sure to compile the Qt library with the same compiler (this is 
+ * possible with Qt version 4.3.2, even if the download page does not say so).
+ *
+ * If the <code>qmake</code> tool is in your shell path, all you need to do to 
+ * enable Gist is to configure %Gecode with the switch 
+ * <code>--enable-gist</code>.
+ */
+
+
+/**
+ * \page PageHowToChange_2 How to Change from Gecode 1.3.1 to Gecode 2.0.x
+ *
+
+As Gecode 2.0.0 is a major revision of Gecode, your programs that are written
+for Gecode 1.3.1 are likely to require some modifications before they work
+again. All modifications are straightforward, though.
+
+This short summary shows how to adapt your models and linker invocation, for
+changes to propagator implementations, etc, please consult the changelog.
+
+\section SecChange2IntBool IntVar and BoolVar
+
+Boolean variables (BoolVar) are not any longer integer variables
+(IntVar). The same holds for variable arrays (BoolVarArray,
+IntVarArray). So, you can not mix Boolean and integer variables
+in the same array (use two different arrays) and you can not cast
+between them. If you want to link the value of a BoolVar to the
+value of an IntVar you have to use a \ref TaskModelIntChannel
+"channel constraint".  Posting constraints remains unchanged, as
+all constraints offer two overloaded versions (one for IntVar,
+one for BoolVar).
+
+\section SecChange2Regular Regular constraint
+
+The regular constraint has been renamed to extensional (after
+all, it is an extensionally specified constraint). The old name
+is still available in the MiniModel module. 
+
+If you want to use regular expressions, you have to add
+   \code #include "gecode/int/minimodel.hh" \endcode
+to your file as they moved to the MiniModel module.
+
+\section SecChange2Bool Boolean constraints
+
+In order to make the interface to Boolean constraints more
+regular and similar to set constraints, Boolean constraints are
+available as rel constraints. That is, instead of
+   \code bool_and(home, x, y, z); \endcode
+you have to write
+   \code rel(home, x, BOT_AND, y, z); \endcode
+Likewise, for arrays you have to write
+   \code rel(home, BOT_AND, x, y); \endcode
+instead of
+   \code bool_and(home, x, y); \endcode
+More information is available \ref TaskModelIntRelBool "here".
+
+\section SecChange2Branching Branching
+
+Values and types for selecting how to branch have been made uniform. 
+Replace BVAL_* by INT_VAL_*, BVAR_* by INT_VAR_*, and so on.
+
+\section SecChange2GCC Global cardinality constraint
+
+The interface for the global cardinality constraint has been
+simplified.  The constraint is now called count. Please check the
+documentation for \ref TaskModelIntCard "details".
+
+\section SecChange2Sorted Sortedness constraint
+
+The sortedness constraint has been renamed to sorted.
+
+\section Linking
+
+Some generic functionality has been put into its own library (\code
+libgecodesupport \endcode on Unix systems, \code GecodeSupport.dll \endcode on
+Windows). You have to link against this library now.
+
+*/