gecoder 0.7.0 → 0.7.1

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

@@ -15,8 +15,22 @@ module Gecode::IntEnumMethods
 end
 
 # A module that gathers the classes and modules used by arithmetic constraints.
-module Gecode::Constraints::IntEnum::Arithmetic 
-  # Describes an expression stub started with an int var enum following by #max.
+module Gecode::Constraints::IntEnum::Arithmetic #:nodoc:
+  # Describes a CompositeStub for the max constraint, which constrains the 
+  # maximum value of the integer variables in an enumeration.
+  # 
+  # == Example
+  # 
+  #   # The maximum must be positive.
+  #   int_enum.max.must > 0
+  #   
+  #   # The maximum must equal a integer variable +max+.
+  #   int_enum.max.must == max
+  #   
+  #   # The maximum must not be negative. The constraint is reified with the 
+  #   # boolean variable +is_negative+ and strength +domain+ is selected.
+  #   int_enum.max.must_not_be.less_than(0, :reify => is_negative, 
+  #     :strength => :domain)
   class MaxExpressionStub < Gecode::Constraints::Int::CompositeStub
     def constrain_equal(variable, params, constrain)
       enum, strength = @params.values_at(:lhs, :strength)
@@ -29,7 +43,21 @@ module Gecode::Constraints::IntEnum::Arithmetic
     end
   end
   
-  # Describes an expression stub started with an int var enum following by #min.
+  # Describes a CompositeStub for the min constraint, which constrains the 
+  # minimum value of the integer variables in an enumeration.
+  # 
+  # == Example
+  # 
+  #   # The minimum must be positive.
+  #   int_enum.min.must > 0
+  #   
+  #   # The minimum must equal a integer variable +min+.
+  #   int_enum.min.must == min
+  #   
+  #   # The minimum must not be non-positive. The constraint is reified with the 
+  #   # boolean variable +is_positive+ and strength +domain+ is selected.
+  #   int_enum.min.must_not_be.less_or_equal(0, :reify => is_positive, 
+  #     :strength => :domain)
   class MinExpressionStub < Gecode::Constraints::Int::CompositeStub
     def constrain_equal(variable, params, constrain)
       enum, strength = @params.values_at(:lhs, :strength)

data/lib/gecoder/interface/constraints/int_enum/channel.rb

@@ -1,6 +1,6 @@
 module Gecode::Constraints::IntEnum
   class Expression
-    # Posts a channel constraint on the variables in the enum with the specified
+    # Adds a channel constraint on the variables in the enum with the specified
     # other set or int enum.
     def channel(enum, options = {})
       if @params[:negate]
@@ -19,8 +19,68 @@ module Gecode::Constraints::IntEnum
   end
   
   # A module that gathers the classes and modules used in channel constraints.
-  module Channel
-    # Describes a channel constraint.
+  module Channel #:nodoc:
+    # Describes a channel constraint which "channels" two enumerations of 
+    # integer variables or one enumeration of integer variables and one 
+    # enumeration of set variables. Channel constraints are used to give 
+    # access to multiple viewpoints when modelling. 
+    # 
+    # When used on two integer enumeration, the channel constraint can be 
+    # thought of as constraining the arrays to be each other's inverses. When 
+    # used with an enumeration of sets the i:th set includes the value of the
+    # j:th integer.  
+    # 
+    # Neither reification nor negation is supported. Selecting strength is only 
+    # supported when using the constraint between two integer enumerations, 
+    # it's not supported when a set enumeration is used.  
+    # 
+    # == Example
+    # 
+    # Lets say that we’re modelling a sequence of numbers that must be distinct
+    # and that we want access to the following two view simultaneously.
+    # 
+    # === First view
+    # 
+    # The sequence is modelled as an array of integer variables where the first 
+    # variable holds the value of the first position in the sequence, the 
+    # second the value of the second position and so on.
+    # 
+    #   # n variables with values from 0 to n-1.
+    #   elements = int_var_array(n, 0...n)
+    #   elements.must_be.distinct
+    # 
+    # That way +elements+ will contain the actual sequence when the problem has 
+    # been solved.
+    # 
+    # === Second view
+    # 
+    # The sequence is modelled as the positions of each value in 0..(n-1) in 
+    # the sequence. That way the first variable would hold the positions of 0 
+    # in the sequence, the second variable would hold the positions of 1 in the 
+    # sequence and so on.
+    # 
+    #   positions = int_var_array(n, 0...n)
+    #   positions.must_be.distinct
+    # 
+    # === Connecting the views
+    #   
+    # In essence the relationship between the two arrays +elements+ and 
+    # +positions+ is that
+    # 
+    #   elements.map{ |e| e.val }[i] == positions.map{ |p| p.val }.index(i)
+    # 
+    # for all i in 0..(n-1). This relationship is enforced by the channel 
+    # constraint as follows. 
+    # 
+    #   elements.must.channel positions
+    # 
+    # == Example (sets)
+    # 
+    #   # +set_enum+ is constrained to channel +int_enum+.
+    #   int_enum.must.channel set_enum
+    # 
+    #   # This is another way of saying the above.
+    #   set_enum.must.channel int_enum
     class ChannelConstraint < Gecode::Constraints::Constraint
       def post
         lhs, rhs, strength = @params.values_at(:lhs, :rhs, :strength)

data/lib/gecoder/interface/constraints/int_enum/count.rb

@@ -16,9 +16,9 @@ module Gecode
 end
 
 # A module that gathers the classes and modules used in count constraints.
-module Gecode::Constraints::IntEnum::Count
+module Gecode::Constraints::IntEnum::Count #:nodoc:
   # Describes an expression 
-  class Expression < Gecode::Constraints::IntEnum::Expression
+  class Expression < Gecode::Constraints::IntEnum::Expression #:nodoc:
     def initialize(model, params)
       super
       unless params[:negate]
@@ -47,7 +47,24 @@ module Gecode::Constraints::IntEnum::Count
     alias_comparison_methods
   end
   
-  # Describes a count constraint.
+  # Describes a count constraint, which constrains the number of times a value
+  # (constant or a variable) may occurr in an enumeration of integer variable.
+  # 
+  # All relations available for +SimpleRelationConstraint+ can be used with
+  # count constraints. Negation and reification is supported.
+  # 
+  # == Examples
+  # 
+  #   # Constrain +int_enum+ to not contain 0 exactly once.
+  #   int_enum.count(0).must_not == 1
+  #   
+  #   # Constrain +int_enum+ to contain +x+ exactly +x_count+ times.
+  #   int_enum.count(x).must == x_count
+  #   
+  #   # Reifies the constraint that +int_enum+ has +x+ zeros with the boolean
+  #   # variable +has_x_zeros+ and selects the strength +domain+.
+  #   int_enum.count(0).must.equal(x, :reify => has_x_zeros, 
+  #     :strength => :domain)
   class CountConstraint < Gecode::Constraints::ReifiableConstraint
     def post
       lhs, element, relation_type, rhs, strength, reif_var = 

data/lib/gecoder/interface/constraints/int_enum/distinct.rb

@@ -32,8 +32,28 @@ module Gecode::Constraints::IntEnum
   end
   
   # A module that gathers the classes and modules used in distinct constraints.
-  module Distinct
-    # Describes a distinct constraint (optionally with offsets).
+  module Distinct #:nodoc:
+    # Describes a distinct constraint, which constrains all integer variables 
+    # in an enumeration to be distinct (different). The constraint can also be
+    # used with constant offsets, so that the variables, with specified offsets
+    # added, must be distinct.
+    # 
+    # The constraint does not support negation nor reification.
+    # 
+    # == Examples
+    # 
+    #   # Constrains all variables in +int_enum+ to be assigned different 
+    #   # values.
+    #   int_enum.must_be.distinct
+    #   
+    #   # The same as above, but also selects that the strength +domain+ should
+    #   # be used.
+    #   int_enum.must_be.distinct(:strength => :domain)
+    #   
+    #   # Uses the offset to constrain that no number may be the previous number
+    #   # incremented by one.
+    #   numbers = int_var_array(8, 0..9)
+    #   numbers.with_offset((1..numbers.size).to_a.reverse).must_be.distinct
     class DistinctConstraint < Gecode::Constraints::Constraint
       def post
         # Bind lhs.

data/lib/gecoder/interface/constraints/int_enum/element.rb

@@ -1,7 +1,26 @@
 # A module that gathers the classes and modules used by element constraints.
-module Gecode::Constraints::IntEnum::Element 
-  # Describes an expression stub started with an int var enum following with an 
-  # array access using an integer variables .
+module Gecode::Constraints::IntEnum::Element #:nodoc:
+  # Describes a CompositeStub for the element constraint, which places a 
+  # constraint on a variable at the specified position in an enumeration of 
+  # integer variables. It's basically the array access of constraint 
+  # programming.
+  # 
+  # == Example
+  # 
+  #   # The variable at the +x+:th position in +int_enum+ must be larger than
+  #   # +y+.
+  #   int_enum[x].must > y
+  # 
+  #   # The price of +selected_item+ as described by +prices+ must not be 
+  #   # larger than 100.
+  #   prices = wrap_enum([500, 24, 4711, 412, 24])
+  #   prices[selected_item].must_not > 100
+  #   
+  #   # Reify the constraint that the +x+:th variable in +int_enum+ must be in 
+  #   # range 7..17 with the boolean variable +bool+ and select strength 
+  #   # +domain+.  
+  # 
+  #   int_enum[x].must_be.in(7..17, :reify => bool, :strength => :domain)
   class ExpressionStub < Gecode::Constraints::Int::CompositeStub
     def constrain_equal(variable, params, constrain)
       enum, position, strength = @params.values_at(:lhs, :position, :strength)
@@ -17,7 +36,7 @@ module Gecode::Constraints::IntEnum::Element
   end
   
   # Methods needed to add support for element constraints to enums.
-  module AdditionalEnumMethods
+  module AdditionalEnumMethods #:nodoc:
     # This adds the adder for the methods in the modules including it. The 
     # reason for doing it so indirect is that the first #[] won't be defined 
     # before the module that this is mixed into is mixed into an enum.

data/lib/gecoder/interface/constraints/int_enum/equality.rb

@@ -15,8 +15,15 @@ module Gecode::Constraints::IntEnum
   end
   
   # A module that gathers the classes and modules used in equality constraints.
-  module Equality
-    # Describes an equality constraint.
+  module Equality #:nodoc:
+    # Describes an equality constraint, which constrains all variables in an
+    # integer enumeration to be equal. Neither negation nor reification is 
+    # supported.
+    # 
+    # == Example
+    # 
+    #   # Constrains all variables in +int_enum+ to be equal.
+    #   int_enum.must_be.equal
     class EqualityConstraint < Gecode::Constraints::Constraint
       def post
         # Bind lhs.

data/lib/gecoder/interface/constraints/int_enum/sort.rb

@@ -47,8 +47,22 @@ module Gecode::Constraints::IntEnum
   end
 
   # A module that gathers the classes and modules used in sort constraints.
-  module Sort
-    # Describes a sort constraint with target and order.
+  module Sort #:nodoc:
+    # Describes a sort constraint which constrains a target enumeration of 
+    # integer variables to be the sorted version of another set of integer 
+    # variables. Optionally a third enumeration may be used to define the order
+    # in which the the variables should be sorted.
+    # 
+    # Neither negation nor reification is supported.
+    # 
+    # == Example
+    # 
+    #   # Constrains +sorted_numbers+ to be a sorted version of +numbers+. 
+    #   numbers.must_be.sorted(:as => sorted_numbers)
+    #   
+    #   # Constrains +sorted_numbers+ to be +numbers+ sorted in the order 
+    #   # described by the integer variable enumeration +order+. 
+    #   numbers.must_be.sorted(:as => sorted_numbers, :order => order)
     class SortConstraintWithOptions < Gecode::Constraints::Constraint
       def post
         if @params[:target].nil?
@@ -70,7 +84,18 @@ module Gecode::Constraints::IntEnum
       end
     end
     
-    # Describes a sort constraint.
+    # Describes a sort constraint which constrains an enumeration of integer 
+    # variables to be sorted. Supports reification and negation.
+    # 
+    # == Example
+    # 
+    #   # Constrains the variables in +int_enum+ to be sorted ascendingly.
+    #   int_enum.must_be.sorted
+    #   
+    #   # Reifies the constraint that the variables in +int_enum+ to be sorted 
+    #   # ascendingly with the boolean variable +is_sorted+, while selecting 
+    #   # +domain+ as strength.
+    #   int_enum.must_be.sorted(:reify => :is_sorted, :strength => :domain)
     class SortConstraint < Gecode::Constraints::ReifiableConstraint
       def post
         lhs, strength, reif_var = @params.values_at(:lhs, :strength, :reif)

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

@@ -15,7 +15,7 @@ module Gecode
   # variables as left hand side.
   module Constraints::IntEnum
     # Expressions with int enums as left hand sides.
-    class Expression < Gecode::Constraints::Expression
+    class Expression < Gecode::Constraints::Expression #:nodoc:
       # Raises TypeError unless the left hand side is an int enum.
       def initialize(model, params)
         super

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

@@ -14,12 +14,13 @@ module Gecode
   # A module containing constraints that have int variables as left hand side
   # (but not enumerations).
   module Constraints::Int
-    class Expression < Gecode::Constraints::Expression
+    # Describes an integer expression.
+    class Expression < Gecode::Constraints::Expression #:nodoc:
     end
     
     # A composite expression which is an int 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 
@@ -30,16 +31,20 @@ module Gecode
       end
     end
     
-    # Describes a stub that produces an int variable, which can then be used with 
-    # the normal int variable constraints. An example would be the element
+    # Describes a stub that produces an int variable, which can then be used 
+    # with the normal int variable constraints. An example would be the element
     # constraint.
     #
     #   int_enum[int_var].must > rhs
     #
-    # The int_enum[int_var] part produces an int variable which the constraint
-    # ".must > rhs" 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.
+    # <tt>int_enum[int_var]</tt> produces an int variable which the constraint 
+    # <tt>.must > rhs</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.
+    # 
+    # 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)

data/lib/gecoder/interface/constraints/set/cardinality.rb

@@ -3,7 +3,8 @@ module Gecode
     # Starts a constraint on the size of the set.
     def size
       params = {:lhs => self}
-      Gecode::Constraints::Set::Cardinality::SizeExpressionStub.new(@model, params)
+      Gecode::Constraints::Set::Cardinality::SizeExpressionStub.new(
+        @model, params)
     end
   end
 end
@@ -11,9 +12,11 @@ end
 module Gecode::Constraints::Set
   # A module that gathers the classes and modules used in cardinality 
   # constraints.
-  module Cardinality
-    # Describes a cardinality constraint.
-    class CardinalityConstraint < Gecode::Constraints::Constraint
+  module Cardinality #:nodoc:
+    # Describes a cardinality constraint specifically for ranges. This is just
+    # a special case which is used instead of the more general composite 
+    # constraint when the target cardinality is a range. 
+    class CardinalityConstraint < Gecode::Constraints::Constraint #:nodoc:
       def post
         var, range = @params.values_at(:lhs, :range)
         Gecode::Raw::cardinality(@model.active_space, var.bind, range.first, 
@@ -22,14 +25,14 @@ module Gecode::Constraints::Set
     end
     
     # A custom composite stub to change the composite expression used.
-    class CompositeStub < Gecode::Constraints::CompositeStub
+    class CompositeStub < Gecode::Constraints::CompositeStub #:nodoc:
       def initialize(model, params)
         super(Expression, model, params)
       end
     end
     
     # Describes a cardinality expression started with set.size.must .
-    class Expression < Gecode::Constraints::Int::CompositeExpression
+    class Expression < Gecode::Constraints::Int::CompositeExpression #:nodoc:
       def in(range)
         if range.kind_of?(Range) and !@params[:negate]
           @params.update(:range => range)
@@ -40,8 +43,24 @@ module Gecode::Constraints::Set
       end
     end
     
-    # Describes an expression stub started with a set variable followed by 
-    # #size .
+    # Describes a CompositeStub for the cardianlity constraint which constrains
+    # the cardianlity (size) of a set.
+    # 
+    # == Example
+    # 
+    #   # The size of +set+ must be within 1..17
+    #   set.size.must_be.in 1..17
+    #   
+    #   # The size must equal the integer variable +size+.
+    #   set.size.must == size
+    #   
+    #   # The size must not be larger than 17
+    #   set.size.must_not > 17
+    #   
+    #   # We reify the above with a boolean variable called +is_not_large+ and 
+    #   # select the strength +domain+.
+    #   set.size.must_not_be.larger_than(17, :reify => is_not_large, 
+    #     :strength => :domain)
     class SizeExpressionStub < CompositeStub
       def constrain_equal(variable, params, constrain)
         lhs = @params[:lhs]

data/lib/gecoder/interface/constraints/set/connection.rb

@@ -68,8 +68,27 @@ module Gecode::Constraints::Set
 
   # A module that gathers the classes and modules used in connection 
   # constraints.
-  module Connection
-    # Describes an expression stub started with an int var following by #min.
+  module Connection #:nodoc:
+    # Describes a CompositeStub for the min constraint which constrains the 
+    # minimum value of a set variable.
+    # 
+    # == Examples
+    # 
+    #   # Constrains the minimum value of +set+ to be larger than 17.
+    #   set.min.must > 17
+    #   
+    #   # Constrains the minimum value of +set+ to equal the integer variable 
+    #   # +min+.
+    #   set.min.must == min
+    #   
+    #   # Constrains the minimum value of +set+ to not be larger than the 
+    #   # integer variable +ceil+.
+    #   set.min.must_not > ceil
+    #   
+    #   # The same as above but reified with the boolean variable 
+    #   # +is_not_above_ceiling+ and with the strength +domain+ applied.
+    #   set.min.must_not_be.larger_than(ceil, :reify => :is_not_above_ceiling, 
+    #     :strength => :domain) 
     class MinExpressionStub < Gecode::Constraints::Int::CompositeStub
       def constrain_equal(variable, params, constrain)
         set = params[:lhs]
@@ -81,7 +100,26 @@ module Gecode::Constraints::Set
       end
     end
     
-    # Describes an expression stub started with an int var following by #max.
+    # Describes a CompositeStub for the max constraint which constrains the 
+    # maximum value of a set variable.
+    # 
+    # == Examples
+    # 
+    #   # Constrains the maximum value of +set+ to be larger than 17.
+    #   set.max.must > 17
+    #   
+    #   # Constrains the maximum value of +set+ to equal the integer variable 
+    #   # +max+.
+    #   set.max.must == max
+    #   
+    #   # Constrains the maximum value of +set+ to not be less than the 
+    #   # integer variable +floor+.
+    #   set.max.must_not < floor
+    #   
+    #   # The same as above but reified with the boolean variable 
+    #   # +is_not_below_floor+ and with the strength +domain+ applied.
+    #   set.max.must_not_be.less_than(ceil, :reify => :is_not_below_floor, 
+    #     :strength => :domain)
     class MaxExpressionStub < Gecode::Constraints::Int::CompositeStub
       def constrain_equal(variable, params, constrain)
         set = params[:lhs]
@@ -93,7 +131,26 @@ module Gecode::Constraints::Set
       end
     end
     
-    # Describes an expression stub started with an int var following by #max.
+    # Describes a CompositeStub for the sum constraint which constrains the 
+    # sum of all values in a set variable.
+    # 
+    # == Examples
+    # 
+    #   # Constrains the sum of all values in +set+ to be larger than 17.
+    #   set.sum.must > 17
+    #   
+    #   # Constrains the sum of all values in +set+ to equal the integer 
+    #   # variable +sum+.
+    #   set.sum.must == sum
+    #   
+    #   # Constrains the sum of all values in +set+ to not be larger than the 
+    #   # integer variable +resources+.
+    #   set.sum.must_not > resources
+    #   
+    #   # The same as above but reified with the boolean variable 
+    #   # +not_over_budget+ and with the strength +domain+ applied.
+    #   set.sum.must_not_be.larger_than(resources, :reify => :not_over_budget, 
+    #     :strength => :domain)
     class SumExpressionStub < Gecode::Constraints::Int::CompositeStub
       def constrain_equal(variable, params, constrain)
         set, subs = params.values_at(:lhs, :substitutions)
@@ -114,8 +171,17 @@ module Gecode::Constraints::Set
       end
     end
     
-    # Describes a constraint that constrains a set to include a number of 
-    # integer variables.
+    # Describes an include constraint, which constrains the set to include the
+    # values of the specified enumeration of integer variables. 
+    # 
+    # The constraint has the side effect of sorting the integer variables in a 
+    # non-descending order. It does not support reification nor negation.
+    # 
+    # == Examples
+    # 
+    #   # Constrain +set+ to include the values of all variables in 
+    #   # +int_enum+.
+    #   set.must.include int_enum 
     class IncludeConstraint < Gecode::Constraints::Constraint
       def post
         set, variables = @params.values_at(:lhs, :variables)