[gecode-users] FAQ/Documentation

[stanio at cs.tu-berlin.de]

> let me first elaborate a little bit how Gecode's variables and propagators
> are structured before I actually attempt to give an answer.
> 
> Gecode has three important concepts regarding variables:
>  - variables: they are used for modeling, and the only operations they
> provide are good for modeling. In particular,
>    variables to not provide operations to update their domain. Examples are
> IntVar, BoolVar, etc. Variables are
>    hence provide nothing but an interface to variable implementations
> (actually, variables are implemented as
>    a pointer to variable implementations).
>  - variable implementations: they are the real objects storing the domain
> and which propagators and advisors must be
>    executed when the domain changes. They themselves are constructed in two
> steps: a domain independent stub that is 
>    automatically generated from a simple description (just a few lines). The
> stub is concerned with events, how
>    propagators can be subscribed to, and linking the variable
> implementations to the Gecode kernel etc. The real 
>    variable implementation then inherits from the generated stub and adds
> the variable domain and so on.
>  - views: like variables they are nothing but an interface for variable
> implementations. However, views are used
>    by propagators and branching and provide operations to update variable
> domains, subscribe propagators to changes,
>    and so on. More importantly, for the same variable implementation several
> views exist: a MinusView for a variable
>    implementation x, for example, provides an interface that behaves as if
> the operations on the MinusView are executed
>    on -x rather than x. Examples are IntView, BoolView, MinusView,
> OffsetView, ... For more on views there is paper
>    on the Gecode webpage.
> 
> Propagators themselves have two parts: a post function and the actual
> propagator. A post function (such as rel, distinct, linear, etc.) is used
> for modeling and hence takes variables as arguments. It then chooses the
> right propagator and the right views (converting variables to views by
> passing the underlying reference to the variable implementation).
> 
> Propagators are typically parametric (as templates in C++) with respect to
> the view they are using: for example, the Max propagator is instantiated for
> the max posting function with an IntView whereas it is also instantiated
> with a MinusView for the min posting function.

> Sorry for the long blurb,
> [...]

I find such _blurb_ very useful, even only as a user. When
one knows more about the design of the system, this can
prevent many conceptual mistakes. I don't remember to have
read these explanations on the Gecode website. You might
save a bit of your time, if you put things like that in
kind of FAQ. (Or does it exist?)

Certainly all this can be extracted from the publications
referred from gecode.org, from the doxygen docs and from the
sources, but I find the above condensed manner of
presentation very suitable for a plain text in a FAQ or
similar.

:o)
Have a nice day.

-- 
 cheers
 stanio_