gecoder 0.7.0 → 0.7.1

data/lib/gecoder/interface/constraints/bool/boolean.rb

@@ -1,17 +1,21 @@
 module Gecode
   class FreeBoolVar
+    # Initiates a boolean constraint with this variable or +var+.
     def |(var)
       Constraints::Bool::ExpressionNode.new(self, @model) | var
     end
     
+    # Initiates a boolean constraint with this variable and +var+.
     def &(var)
       Constraints::Bool::ExpressionNode.new(self, @model) & var
     end
     
+    # Initiates a boolean constraint with this variable exclusive or +var+.
     def ^(var)
       Constraints::Bool::ExpressionNode.new(self, @model) ^ var
     end
     
+    # Initiates a boolean constraint with this variable implies +var+.
     def implies(var)
       Constraints::Bool::ExpressionNode.new(self, @model).implies var
     end
@@ -20,7 +24,7 @@ module Gecode
   # A module that gathers the classes and modules used in boolean constraints.
   module Constraints::Bool
     # Describes a boolean expression (following after must*).
-    class Expression
+    class Expression #:nodoc:
       def ==(expression, options = {})
         @params.update Gecode::Constraints::Util.decode_options(options)
         @model.add_constraint BooleanConstraint.new(@model, 
@@ -49,7 +53,77 @@ module Gecode
       end
     end
     
-    # Describes a boolean constraint.
+    # Describes a constraint on a boolean expression.
+    # 
+    # == Boolean expressions
+    # 
+    # A boolean expression consists of several boolean variable with various 
+    # boolean operators. The available operators are:
+    # 
+    # [<tt>|</tt>] Or
+    # [<tt>&</tt>] And
+    # [<tt>^</tt>] Exclusive or
+    # [+implies+]  Implication
+    # 
+    # === Examples
+    # 
+    #   # +b1+ and +b2+
+    #   b1 & b2
+    #   
+    #   # (+b1+ and +b2+) or +b3+ 
+    #   (b1 & b1) | b3
+    # 
+    #   # (+b1+ and +b2+) or (+b3+ exclusive or +b1+)
+    #   (b1 & b2) | (b3 ^ b1)
+    #   
+    #   # (+b1+ implies +b2+) and (+b3+ implies +b2+)
+    #   (b1.implies b2) & (b3.implies b2)
+    #   
+    # == Domain
+    # 
+    # A domain constraint just specifies that a boolean expression must be true
+    # or false. Negation and reification are supported.
+    # 
+    # === Examples
+    # 
+    #   # +b1+ and +b2+ must be true.
+    #   (b1 & b2).must_be.true
+    #   
+    #   # (+b1+ implies +b2+) and (+b3+ implies +b2+) must be false.
+    #   ((b1.implies b2) & (b3.implies b2)).must_be.false
+    # 
+    #   # +b1+ and +b2+ must be true. We reify it with +bool+ and select the
+    #   # strength +domain+.
+    #   (b1 & b2).must_be.true(:reify => bool, :strength => :domain)
+    # 
+    # == Equality
+    # 
+    # A constraint with equality specifies that two boolean expressions must be
+    # equal. Negation and reification are supported. Any of <tt>==</tt>, 
+    # +equal+ and +equal_to+ may be used for equality.
+    # 
+    # === Examples
+    # 
+    #   # +b1+ and +b2+ must equal +b1+ or +b2+.
+    #   (b1 & b2).must == (b1 | b2)
+    #   
+    #   # +b1+ and +b2+ must not equal +b3+. We reify it with +bool+ and select 
+    #   # the strength +domain+.
+    #   (b1 & b2).must_not.equal(b3, :reify => bool, :select => :domain)
+    #   
+    # == Implication
+    # 
+    # A constraint using +imply+ specified that one boolean expression must
+    # imply the other. Negation and reification are supported.
+    # 
+    # === Examples
+    #   
+    #   # +b1+ must imply +b2+
+    #   b1.must.imply b2
+    #   
+    #   # +b1+ and +b2+ must not imply +b3+. We reify it with +bool+ and select
+    #   # +domain+ as strength.
+    #   (b1 & b2).must_not.imply b3
     class BooleanConstraint < Gecode::Constraints::ReifiableConstraint
       def post
         lhs, rhs, negate, strength, reif_var = @params.values_at(:lhs, :rhs, 
@@ -87,7 +161,7 @@ module Gecode
   
     # A module containing the methods for the basic boolean operations. Depends
     # on that the class mixing it in defined #model.
-    module OperationMethods
+    module OperationMethods #:nodoc
       include Gecode::Constraints::LeftHandSideMethods
       
       private
@@ -130,7 +204,7 @@ module Gecode
   
     # Describes a binary tree of expression nodes which together form a boolean 
     # expression.
-    class ExpressionTree
+    class ExpressionTree #:nodoc:
       include OperationMethods
     
       # Constructs a new expression with the specified nodes. The proc should 
@@ -153,7 +227,7 @@ module Gecode
     end
   
     # Describes a single node in a boolean expression.
-    class ExpressionNode
+    class ExpressionNode #:nodoc:
       include OperationMethods
     
       attr :model

data/lib/gecoder/interface/constraints/bool/linear.rb

@@ -0,0 +1,29 @@
+module Gecode
+  class FreeBoolVar
+    # Creates a linear expression where the bool variables are summed.
+    def +(var)
+      Gecode::Constraints::Int::Linear::ExpressionNode.new(self, 
+        @model) + var
+    end
+    
+    alias_method :pre_linear_mult, :* if instance_methods.include? '*'
+
+    # Creates a linear expression where the bool variable is multiplied with 
+    # a constant integer.
+    def *(int)
+      if int.kind_of? Fixnum
+        Gecode::Constraints::Int::Linear::ExpressionNode.new(self, 
+          @model) * int
+      else
+        pre_linear_mult(int) if respond_to? :pre_linear_mult
+      end
+    end
+    
+    # Creates a linear expression where the specified variable is subtracted 
+    # from this one.
+    def -(var)
+      Gecode::Constraints::Int::Linear::ExpressionNode.new(self, 
+        @model) - var
+    end
+  end
+end

data/lib/gecoder/interface/constraints/bool_enum/boolean.rb

@@ -15,9 +15,25 @@ module Gecode
     end
   end
   
+  # A module that gathers the classes and modules used by boolean enumeration 
+  # constraints.
   module Constraints::BoolEnum
-    # Describes an expression stub started with a bool var enum following by 
-    # #conjunction.
+    # Describes a CompositeStub for the conjunction constraint, which constrain
+    # the conjunction of all boolean variables in an enumeration.
+    # 
+    # == Example
+    # 
+    #   # The conjunction of all variables in +bool_enum+ must be true. I.e. all
+    #   # boolean variables must take the value true.
+    #   bool_enum.conjunction.must_be.true
+    #   
+    #   # The conjunction of all variables in +bool_enum+ must equal b1.
+    #   bool_enum.conjunction.must ==  b1
+    #   
+    #   # The conjunction of all variables in +bool_enum+ must not equal b1 and 
+    #   # b2. It's reified it with +bool+ and selects the strength +domain+.
+    #   bool_enum.conjunction.must_not.equal(b1 & b2, :reify => bool, 
+    #     :strength => :domain)
     class ConjunctionStub < Gecode::Constraints::Bool::CompositeStub
       def constrain_equal(variable, params, constrain)
         enum, strength = @params.values_at(:lhs, :strength)
@@ -35,8 +51,22 @@ module Gecode
       end
     end
     
-    # Describes an expression stub started with a bool var enum following by 
-    # #disjunction.
+    # Describes a CompositeStub for the disjunction constraint, which constrain
+    # the disjunction of all boolean variables in an enumeration.
+    # 
+    # == Example
+    # 
+    #   # The disjunction of all variables in +bool_enum+ must be true. I.e. at
+    #   # least one of the boolean variables must take the value true.
+    #   bool_enum.disjunction.must_be.true
+    #   
+    #   # The disjunction of all variables in +bool_enum+ must equal b1.
+    #   bool_enum.conjunction.must ==  b1
+    #   
+    #   # The disjunction of all variables in +bool_enum+ must not equal b1 and 
+    #   # b2. It's reified it with +bool+ and selects the strength +domain+.
+    #   bool_enum.disjunction.must_not.equal(b1 & b2, :reify => bool, 
+    #     :strength => :domain)
     class DisjunctionStub < Gecode::Constraints::Bool::CompositeStub
       def constrain_equal(variable, params, constrain)
         enum, strength = @params.values_at(:lhs, :strength)

data/lib/gecoder/interface/constraints/bool_var_constraints.rb

@@ -15,12 +15,12 @@ module Gecode
   # (but not enumerations).
   module Constraints::Bool
     # Describes a boolean expression.
-    class Expression < Gecode::Constraints::Expression
+    class Expression < Gecode::Constraints::Expression #:nodoc:
     end
     
     # A composite expression which is an bool expression with a left hand side 
     # resulting from a previous constraint.
-    class CompositeExpression < Gecode::Constraints::CompositeExpression
+    class CompositeExpression < Gecode::Constraints::CompositeExpression #:nodoc:
       # The block given should take three parameters. The first is the variable 
       # that should be the left hand side, if it's nil then a new one should be
       # created. The second is the has of parameters. The block should return 
@@ -49,16 +49,20 @@ module Gecode
       end
     end
     
-    # Describes a stub that produces an int variable, which can then be used with 
-    # the normal bool variable constraints. An example for boolean composite 
-    # constraints would be conjunction.
+    # Describes a stub that produces an int variable, which can then be used 
+    # with the normal int variable constraints. An example would be the 
+    # conjunction constraint.
     #
     #   bools.conjunction.must == b1 | b2
+    #
+    # <tt>bools.conjunction</tt> produces a boolean variable which the 
+    # constraint <tt>.must == b1 | b2</tt> is then applied to. In the above 
+    # case two constraints (and one temporary variable) are required, but in 
+    # the case of equality only one constraint is required.
     # 
-    # "bools.conjunction" produces a bool variable which the constraint 
-    # ".must == b1 | b2" is then applied to.In the above case two constraints 
-    # (and one temporary variable) are required, but in the case of equality 
-    # only one constraint is required.
+    # Whether a constraint involving a reification stub supports negation, 
+    # reification, strength options and so on depends on the constraint on the
+    # right hand side.
     class CompositeStub < Gecode::Constraints::CompositeStub
       def initialize(model, params)
         super(CompositeExpression, model, params)
@@ -68,3 +72,4 @@ module Gecode
 end
 
 require 'gecoder/interface/constraints/bool/boolean'
+require 'gecoder/interface/constraints/bool/linear'

data/lib/gecoder/interface/constraints/int/arithmetic.rb

@@ -4,10 +4,10 @@ class Gecode::FreeIntVar
     Gecode::Constraints::Int::Arithmetic::AbsExpressionStub.new(@model, 
       :lhs => self)
   end
-  
-  # Creates a linear expression where the int variable is multiplied with 
-  # a constant integer.
+
   alias_method :pre_arith_mult, :* if instance_methods.include? '*'
+  
+  # Begins a multiplication constraint involving the two int variable.
   def *(var)
     if var.kind_of? Gecode::FreeIntVar
       Gecode::Constraints::Int::Arithmetic::MultExpressionStub.new(
@@ -19,9 +19,18 @@ class Gecode::FreeIntVar
 end
 
 # A module that gathers the classes and modules used by arithmetic constraints.
-module Gecode::Constraints::Int::Arithmetic 
-  # Describes an expression stub started with an integer variable followed by 
-  # #abs .
+module Gecode::Constraints::Int::Arithmetic #:nodoc:
+  # Describes a CompositeStub for absolute value constraints, which constrain
+  # the absolute value of an integer variable.
+  # 
+  # == Examples
+  #   
+  #   # The absolute value of +x+ must be less than 2.
+  #   x.abs.must < 2
+  #   
+  #   # The absolute value of +x+ must be in the range 5..7, with +bool+ as 
+  #   # reification variable and +value+ as strength.
+  #   x.abs.must_be.in(5..7, :reify => bool, :strength => :value)
   class AbsExpressionStub < Gecode::Constraints::Int::CompositeStub
     def constrain_equal(variable, params, constrain)
       lhs, strength = @params.values_at(:lhs, :strength)
@@ -34,8 +43,17 @@ module Gecode::Constraints::Int::Arithmetic
     end
   end
   
-  # Describes an expression stub started with an integer variable followed by 
-  # #* .
+  # Describes a CompositeStub for multiplication constraint, which constrain
+  # the value of the multiplication of two variables.
+  # 
+  # == Examples
+  #   
+  #   # The value of +x*y+ must be equal to their sum.
+  #   (x*y).must == x + y
+  #   
+  #   # The valye of +x*y+ must be less than 17, with +bool+ as reification 
+  #   # variable and +domain+ as strength.
+  #   (x*y).must_be.less_than(17, :reify => bool, :strength => :domain)
   class MultExpressionStub < Gecode::Constraints::Int::CompositeStub
     def constrain_equal(variable, params, constrain)
       lhs, lhs2, strength = @params.values_at(:lhs, :var, :strength)

data/lib/gecoder/interface/constraints/int/domain.rb

@@ -16,8 +16,22 @@ module Gecode::Constraints::Int
   end
   
   # A module that gathers the classes and modules used in domain constraints.
-  module Domain
-    # Describes a range domain constraint.
+  module Domain #:nodoc:
+    # Range domain constraints specify that an integer variable must be 
+    # contained within a specified range of integers. Supports reification and
+    # negation.
+    # 
+    # == Examples
+    # 
+    #   # +x+ must be in the range 1..10
+    #   x.must_be.in 1..10
+    #   
+    #   # +x+ must not be in the range -5...5
+    #   x.must_not_be.in -5...5
+    #   
+    #   # Specifies the above, but but reifies the constraint with the boolean 
+    #   # variable +bool+ and specified +value+ as strength.
+    #   x.must_not_be.in(-5...5, :reify => bool, :strength => :value)
     class RangeDomainConstraint < Gecode::Constraints::ReifiableConstraint
       def post
         var, domain, reif_var, strength = @params.values_at(:lhs, :domain, 
@@ -31,7 +45,20 @@ module Gecode::Constraints::Int
       negate_using_reification
     end
     
-    # Describes a enum domain constraint.
+    # Enum domain constraints specify that an integer variable must be contained
+    # in an enumeration of integers. Supports reification and negation.
+    # 
+    # == Examples
+    # 
+    #   # +x+ must be in the enumeration [3,5,7].
+    #   x.must_be.in [3,5,7]
+    #   
+    #   # +x+ must not be in the enumeration [5,6,7,17].
+    #   x.must_not_be.in [5,6,7,17]
+    #   
+    #   # Specifies the above, but but reifies the constraint with the boolean 
+    #   # variable +bool+ and specified +value+ as strength.
+    #   x.must_not_be.in(-[5,6,7,17], :reify => bool, :strength => :value)
     class EnumDomainConstraint < Gecode::Constraints::ReifiableConstraint
       def post
         space = @model.active_space

data/lib/gecoder/interface/constraints/int/linear.rb

@@ -6,9 +6,10 @@ module Gecode
         @model) + var
     end
     
+    alias_method :pre_linear_mult, :* if instance_methods.include? '*'
+
     # Creates a linear expression where the int variable is multiplied with 
     # a constant integer.
-    alias_method :pre_linear_mult, :* if instance_methods.include? '*'
     def *(int)
       if int.kind_of? Fixnum
         Gecode::Constraints::Int::Linear::ExpressionNode.new(self, 
@@ -27,7 +28,7 @@ module Gecode
   end
   
   module Constraints::Int
-    class Expression
+    class Expression #:nodoc:
       # Add some relation selection based on whether the expression is negated.
       alias_method :pre_linear_initialize, :initialize
       def initialize(model, params)
@@ -67,7 +68,9 @@ module Gecode
         if expression.nil?
           simple_expression?(@params[:lhs])
         else
-          expression.kind_of?(Gecode::FreeIntVar) or expression.kind_of?(Fixnum)
+          expression.kind_of?(Gecode::FreeIntVar) or
+            expression.kind_of?(Gecode::FreeBoolVar) or
+            expression.kind_of?(Fixnum)
         end
       end
       
@@ -82,12 +85,13 @@ module Gecode
       def add_linear_constraint(relation_type, right_hand_side)
         # Bind parameters.
         lhs = @params[:lhs]
-        if lhs.kind_of? Gecode::FreeIntVar
+        if lhs.kind_of?(Gecode::FreeIntVar) or lhs.kind_of?(Gecode::FreeBoolVar)
           lhs = lhs * 1 # Convert to Gecode::Raw::LinExp
         end
         if not (right_hand_side.respond_to? :to_minimodel_lin_exp or
-            right_hand_side.kind_of? Gecode::FreeIntVar or 
-            right_hand_side.kind_of? Fixnum)
+            right_hand_side.kind_of?(Gecode::FreeIntVar) or
+            right_hand_side.kind_of?(Gecode::FreeBoolVar) or  
+            right_hand_side.kind_of?(Fixnum))
           raise TypeError, 'Invalid right hand side of linear equation.'
         end
         
@@ -107,8 +111,34 @@ module Gecode
   end
   
   # A module that gathers the classes and modules used in linear constraints.
-  module Constraints::Int::Linear
-    # Describes a linear constraint.
+  module Constraints::Int::Linear #:nodoc:
+    # Linear constraints specify that an integer variable must have a linear 
+    # equation containing variables must hold. The same relations and options
+    # used in +SimpleRelationConstraint+ can also be used for linear 
+    # constraints.
+    # 
+    # Boolean variables can also be used instead of integer variables. In that
+    # case a boolean variable assigned true is equal to 1 and a boolean variable
+    # assigned false is equal to 0. There is one exception: boolean variables 
+    # can not be used alone as left hand side.
+    # 
+    # Do not mix boolean and integer variables. Even if possible it's not 
+    # supported, and might be removed in the future.
+    # 
+    # == Examples
+    # 
+    #   # The sum of the int variables +x+ and +y+ must equal +z+ + 3.
+    #   (x + y).must == z + 3
+    #   
+    #   # Another way of writing the above. 
+    #   z.must == x + y - 3
+    #   
+    #   # The inequality 10(x + y) > 3x must not hold. 
+    #   (x + y)*10.must_not > x*3
+    #   
+    #   # Specifies the above, but reifies the constraint with the boolean 
+    #   # variable +bool+ and gives it propagation strength +domain+.
+    #   (x + y)*10.must_not_be.greater_than(x*3, :reify => bool, :strength => :domain)
     class LinearConstraint < Gecode::Constraints::ReifiableConstraint
       def post
         lhs, rhs, relation_type, reif_var, strength = @params.values_at(:lhs, 
@@ -116,7 +146,7 @@ module Gecode
         reif_var = reif_var.bind if reif_var.respond_to? :bind
         if rhs.respond_to? :to_minimodel_lin_exp
           rhs = rhs.to_minimodel_lin_exp
-        elsif rhs.kind_of? Gecode::FreeIntVar
+        elsif rhs.respond_to? :bind
           rhs = rhs.bind * 1
         end
 
@@ -128,10 +158,46 @@ module Gecode
         end
       end
     end
-    
-    # Describes a simple relation constraint.
+
+    # Simple relation constraints specify that an integer variable must have a
+    # specified relation to a constant integer or another integer variable. The 
+    # following relations are supported (the aliases of each relation are also 
+    # listed).
+    # 
+    # * <, lesser, lesser_than
+    # * >, greater, greater_than
+    # * >=, greater_or_equal, greater_than_or_equal_to
+    # * <=, less_or_equal, less_than_or_equal_to
+    # * ==, equal, equal_to
+    # 
+    # Each can be negated by using +must_not+ instead of +must+.
+    # 
+    # Two options (given as a hash) are available:
+    # 
+    # [strength] Specifies the propagation strength of the constraint. Must be
+    #            one of +value+, +bounds+, +domain+ and +default+. The
+    #            strength generally progresses as +value+ -> +bounds+ -> 
+    #            +domain+ (+value+ being the weakest, but usually cheapest, 
+    #            while +domain+ is the strongest but usually costly).
+    # [reify]    Specifies a boolean variable that should be used for 
+    #            reification (see +ReifiableConstraint+).
+    # 
+    # == Examples
+    # 
+    #   # Int variable +x+ must not equal 0.
+    #   x.must_not.equal(0)
+    #   
+    #   # Another way of writing the above. 
+    #   x.must_not == 0
+    #   
+    #   # +x+ must be strictly larger than +y+.
+    #   x.must > y
+    #   
+    #   # Specifies the above, but reifies the constraint with the boolean 
+    #   # variable +bool+.
+    #   x.must_be.greater_than(y, :reify => bool)
     class SimpleRelationConstraint < Gecode::Constraints::ReifiableConstraint
-      def post        
+      def post
         # Fetch the parameters to Gecode.
         lhs, relation, rhs, reif_var, strength = @params.values_at(:lhs, 
           :relation_type, :element, :reif, :strength)
@@ -149,7 +215,7 @@ module Gecode
   
     # Helper methods for linear expressions. Classes mixing in this module must
     # have a method #model which gives the model the expression is operating in. 
-    module Helper
+    module Helper #:nodoc:
       include Gecode::Constraints::LeftHandSideMethods
       
       private
@@ -181,7 +247,7 @@ module Gecode
     
     # Describes a binary tree of expression nodes which together form a linear 
     # expression.
-    class ExpressionTree
+    class ExpressionTree #:nodoc:
       include Helper
     
       # Constructs a new expression with the specified variable
@@ -204,7 +270,7 @@ module Gecode
     end
     
     # Describes a single node in a linear expression.
-    class ExpressionNode
+    class ExpressionNode #:nodoc:
       include Helper
     
       attr :model
@@ -218,7 +284,7 @@ module Gecode
       # Gecode::Raw::MiniModel::LinExpr
       def to_minimodel_lin_exp
         expression = @value
-        if expression.kind_of? Gecode::FreeIntVar
+        if expression.respond_to? :bind
           # Minimodel requires that we do this first.
           expression = expression.bind * 1
         end