[gecode-users] FAQ/Documentation

[Christian Schulte]

Stanio, not only are you right, I think you even know that you are right ;-)

We are still collecting material for some documentation. We are also
planning to write a whitepaper that is more concerned with the design ideas.

But time is really the issue.

Christian


On 4/3/08 12:54 PM, "stanio at cs.tu-berlin.de" <stanio at cs.tu-berlin.de> wrote:

>> 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.

--
Christian Schulte, web.ict.kth.se/~cschulte/