lib(gfd)


   The GFD library is an interface to the gecode finite domain constraint
   solver. Gecode (www.gecode.org) is an open-source toolkit for developing
   constraint-based systems in C++, and includes a high-performance constraint 
   solver.

   This interface provides a high degree of compatibility with the finite 
   domain portion of the IC library, and to a lesser extent, with the FD
   library as well. This means that programs originally written for the
   IC library should run with GFD with little modifications, beyond 
   renaming any explicit calls to the ic family of modules.
 
   The main differences from the IC library are:

       Real interval arithmetic and variables are not supported.

       Domain variables have finite bounds, and the maximum bounds are
       determined by gecode. Like FD, default finite bounds are given to 
       domain variables that are not explicitly given bounds.

       Constraint propagation is performed in gecode, and each propagation
       phase is atomic at the ECLiPSe level. Posting of constraints and 
       propagation of their consequences are separate in gecode. GFD uses a
       demon suspended goal to perform the propagation: after the posting
       of any constraint (and other changes to the problem that needs 
       propagation), the suspended goal is scheduled and woken. When the
       woken goal is executed, propagation is performed. The goal is suspended
       at priority 9, so if the posting of the constraint is executed at
       normal priority (12), the propagation will happen immediately. However,
       if the posting is done at a priority 10 or higher, then the propagation
       is delayed, allowing multiple constraints to be posted without
       propagation. 

       GFD supports constraints that are supported by Gecode,
       so the exact set of constraints supported is different from IC. 
       However, the same basic arithmetic operators and relations are 
       supported, allowing for very similar arithmetic expressions. Also,
       many, if not most, of the constraints in IC are supported, along with
       many constraints not supported by IC. See the detailed documentation
       for more information.

       All constraints can be called from the gfd module, and in
       addition, some constraints can be called from modules that specify
       the consistency level: gfd_gac (generalised arc consistency, aka
       domain consistency), gfd_bc (bounds consistency), gfd_vc (value
       consistency (naive)). The calls to gfd uses the default consistency 
       defined for the constraint by gecode. These consistency levels maps 
       directly to those defined for the constraints, so if gecode supports 
       different consistency levels for a constraint, GFD supports it as 
       well. In  particular (and unlike IC), most arithmetic operations can 
       be bounds (the default) as well as domain consistent.

       gfd:search/6 interfaces to gecode's search-engines, where the
       entire search is performed in gecode, and the whole search appears
       atomic at the ECLiPSe level. The syntax for search/6 is designed to
       be as compatible with IC's search/6, although there are some 
       differences. The exact equivalent to IC's search/6, where the search
       is performed at the ECLiPSe level, is available via the gfd_search
       module (in fact it shares the same code with IC's search/6). This
       provides more flexibility, but is likely to be less efficient,
       because the search is done in ECLiPSe, and also because 
       it is not optimised for use with gecode. In addition,
       gfd also provide predicates for both variable selection and
       value choice that are optimised for gecode, which should be more
       efficient than those provided by gfd_search.

       The suspension lists supported by GFD are different from IC.
       Currently, only the 'any' suspension list (for any changes to the
       variable's domain) found in FD but not IC, is supported. Not that
       the GFD constraints are implemented in gecode directly, and therefore
       do not use GFD's suspension lists. 


      
   The following can be used inside arithmetic integer expressions:
   
   X
	    Variables.  If X is not yet a domain variable, it is turned 
	    into one.

   123
	    Integer constants.

   -Expr
	    Sign change.

   abs(Expr)
	    The absolute value of Expr.

   E1+E2
	    Addition.

   E1-E2
	    Subtraction.

   E1*E2
	    Multiplication.

   E1//E2
	    Integer division. Truncate towards zero.

   E1/E2
	    Division, defined only where E2 evenly divides E1 (non-inlined),

   E1 rem E2
	    Integer remainder (modulus), same sign as E1.

   Expr^N
	    Power, Expr to the power N. N is a non-negative integer. 
            Mapped to sqr(Expr) if N = 2.

   min(E1,E2)
	    Minimum.

   max(E1,E2)
	    Maximum.

   sqr(Expr)
	    Square.  Logically equivalent to Expr*Expr.

   isqrt(Expr)
	    Integer square root. Truncated to nearest smaller integer.
            Always non-negative

   sqrt(Expr)
	    Square root, defined only where Expr is the square of an integer.
            Always non-negative (non-inlined).

   inroot(Expr,N)
	    Integer Nth root. N is a positive integer. Truncated to nearest smaller integer.
            For even N, result is the non-negative root. 

   rsqr(Expr)
	    Reverse of the sqr function.  Negative root is not excluded (non-inlined).

   rpow(E1,N)
	    Reverse of exponentiation. i.e. finds X in E1 = X^N. N is a
            positive integer (non-inlined).

   sum(ExprCol)
	    Sum of a collection of expressions.

   sum(IntCol*ExprCol)
	    Scalar product of a collection of integers and expressions.
            IntCol and ExprCol must be the same size.

   min(ExprCol)
	    Minimum of a collection of expressions.

   max(ExprCol)
	    Maximum of a collection of expressions.

   element(ExprIdx, Col)
            Element constraint, Evaluate to the ExprIdx'th element of Col.
	    ExprIdx can be an integer expression. 

   Functional/reified constraints
            Written without last argument, which is taken as the value of
            the expression. Only reified constraints (whose last argument
            is the 0/1 boolean) and constraints that can be written as 
            functions (last argument is a domain variable) are allowed.
            Expressions in relational constraints are restricted to 
            inlined expressions only.
            (non-inlined).

   eval(Expr)
	    Equivalent to Expr.
  
 ConLev: Expr
	    Expr is passed to Gecode at constraint level ConLev.
            ConLev can be gfd_gac, gfd_bc, gfd_vc, gfd. 
   

The following can be used inside logical constraint expressions:
   
   X
	    Boolean variables with 0..1 domain.  If X is not yet a
            domain variable, it is turned into one.

   1
	    boolean constants. 0 for false, 1 for true.

   E1 and E2
	    Reified constraint conjunction.  
            E1 and E2 are logical constraint expressions.

   E1 or E2
	    Reified constraint disjunction.
            E1 and E2 are logical constraint expressions.

   E1 xor E2
	    Reified constraint exclusive disjunction/non-equivalence. 
            E1 and E2 are logical constraint expressions.

   E1 => E2
	    Reified constraint implication.
            E1 and E2 are logical constraint expressions.

   E1 <=> E2
	    Reified constraint equivalence.
            E1 and E2 are logical constraint expressions.

   neg E
	    Reified constraint negation. 
            E is a logical constraint expression.

   element(ExprIdx, BoolCol)
            Element constraint, Evaluate to the ExprIdx'th element of BoolCol.
	    ExprIdx can be an inlined integer expression. BoolCol is a
	    collection of boolean values or domain variable.

   Reified constraints
            Written without last argument, which is taken as the truth
            value of the expression. Reified relational constraints
            are supported inlined and only inlined integer expressions
            are allowed.
            (non-inlined except reified relational constraints).

   eval(Expr)
	    Equivalent to Expr.
  
   ConLev: Expr
	    Expr is passed to Gecode at constraint level ConLev.
            ConLev can be gfd_gac, gfd_bc, gfd_vc, gfd.
   


