gecoder 0.7.0 → 0.7.1

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

@@ -15,6 +15,9 @@ module Gecode::Constraints::Set
     # Adds a domain constraint for the specified relation name, constant set
     # and options.
     def add_domain_constraint(relation_name, constant_set, options)
+      unless Gecode::Constraints::Util.constant_set? constant_set
+        raise TypeError, "Expected constant set, got #{constant_set.class}."
+      end
       @params[:rhs] = constant_set
       @params[:relation] = relation_name
       @params.update Gecode::Constraints::Set::Util.decode_options(options)
@@ -28,8 +31,21 @@ module Gecode::Constraints::Set
   end
   
   # A module that gathers the classes and modules used in domain constraints.
-  module Domain
-    # Describes a domain constraint for equality.
+  module Domain #:nodoc:
+    # Describes a domain constraint which constrains a set to be equal to a 
+    # constant set.
+    # 
+    # == Examples
+    # 
+    #   # +set+ must equal [1,2,5]
+    #   set.must == [1,2,5]
+    #   
+    #   # +set+ must not equal 1..67
+    #   set.must_not == 1..67
+    #   
+    #   # +set+ must equal the singleton set 0. The constraint is reified with
+    #   # the boolean varaible +is_singleton_zero+.
+    #   set.must.equal(0, :reify => is_singleton_zero)
     class EqualityDomainConstraint < Gecode::Constraints::ReifiableConstraint
       def post
         var, domain, reif_var, negate = @params.values_at(:lhs, :rhs, :reif, 
@@ -48,7 +64,34 @@ module Gecode::Constraints::Set
       end
     end
   
-    # Describes a domain constraint for the relations other than equality.
+    # Describes a domain constraint which constrains a set to have a specific
+    # relation to a constant set. A constant set may be specified in three ways
+    # 
+    # [Fixnum]                Represents a singleton set.
+    # [Range]                 Represents a set containing all elements in the 
+    #                         range. This represents the set more efficiently 
+    #                         than when another enumeration with the same 
+    #                         elements are used.
+    # [Enumeration of Fixnum] Represents a set containing the enumeration’s 
+    #                         elements.
+    #
+    # The relations allowed are the same as in 
+    # <tt>Set::Relation::RelationConstraint</tt>.
+    #
+    # == Examples
+    # 
+    #   # +set+ must be subset of [1,2,5]
+    #   set.must_be.subset_of [1,2,5]
+    #   
+    #   # +set+ must be disjoint with 1..67
+    #   set.must_be.disjoint_with 1..67
+    #   
+    #   # +set+ must not be a superset of [0].
+    #   set.must_not_be.superset_of 0
+    #   
+    #   # +set+ must be subset of [1,3,5,7]. The constraint is reified with
+    #   # the boolean varaible +only_constains_odd_values+.
+    #   set.must_be.subset_of([1.3.5.7], :reify => only_contains_odd_values) 
     class DomainConstraint < Gecode::Constraints::ReifiableConstraint
       def post
         var, domain, reif_var, relation = @params.values_at(:lhs, :rhs, :reif, 

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

@@ -42,9 +42,9 @@ end
 
 module Gecode::Constraints::Set
   # A module that gathers the classes and modules used in operation constraints.
-  module Operation
+  module Operation #:nodoc:
     # An expression with a set operand and two operands followed by must.
-    class Expression < Gecode::Constraints::Expression
+    class Expression < Gecode::Constraints::Expression #:nodoc:
       Gecode::Constraints::Util::SET_RELATION_TYPES.each_pair do |name, type|
         module_eval <<-"end_code"
           # Creates an operation constraint using the specified expression.
@@ -76,8 +76,39 @@ module Gecode::Constraints::Set
       alias_set_methods
     end
     
-    # Describes a constraint involving a set operator operating on two set 
-    # operands.
+    # Describes an operation constraint, which constrains the result of an
+    # operation with two sets as operands. Either constant sets or set 
+    # variables may be used for the result and operands, with the exception of
+    # that all three may not be constant sets.
+    # 
+    # The typical form is
+    #   set_operand_1.<operation>(set_operand_2).must.<relation>(result_set)
+    # 
+    # The following operations are supported:
+    # 
+    # * union
+    # * disjoint_union
+    # * intersection
+    # * minus
+    # 
+    # The allowed relations are the same as for 
+    # <tt>Set::Relation::RelationConstraint</tt>.
+    # 
+    # Neither reification nor negation is supported.
+    # 
+    # == Examples
+    # 
+    #   # +set_1+ union +set_2+ must equal +set_3+.
+    #   set_1.union(set_2).must == set_3
+    #   
+    #   # +set_1+ intersection [3,5,6] must equal +set_3+.
+    #   set_1.intersection([3,5,6]).must == set_3
+    #   
+    #   # [0,1,2] minus +set_2+ must be superset of +set_3+.
+    #   wrap_enum([0,1,2]).minus(set_2).must_be.superset_of(set_3)
+    #   
+    #   # +set_1+ disjoint union with [0] must be subset of 0..17.
+    #   set_1.disjoint_union(0).must_be.subset_of 0..17
     class OperationConstraint < Gecode::Constraints::Constraint
       def post
         op1, op2, operation, relation, rhs, negate = @params.values_at(:lhs, 

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

@@ -49,8 +49,22 @@ module Gecode::Constraints::Set
   end
   
   # A module that gathers the classes and modules used in relation constraints.
-  module Relation
-    # Describes a relation constraint for equality.
+  module Relation #:nodoc:
+    # Describes a relation constraint which constrains a set variable to be 
+    # equal to another set variable. Equality may either be expressed as
+    # +==+, +equal+ or +equal_to+.
+    # 
+    # == Examples
+    # 
+    #   # +set_1+ must be equal to +set_2+
+    #   set_1.must == set_2
+    #   
+    #   # +set_1+ must not be equal to +set_2+
+    #   set_1.must_not == set_2
+    #   
+    #   # The same as above but reified with the boolean variable 
+    #   # +are_not_equal+.
+    #   set_1.must_not.equal(set_2, :reify => are_not_equal)
     class EqualityRelationConstraint < Gecode::Constraints::ReifiableConstraint
       def post
         var, rhs, reif_var, negate = @params.values_at(:lhs, :rhs, :reif, 
@@ -69,7 +83,29 @@ module Gecode::Constraints::Set
       end
     end
   
-    # Describes a relation constraint for the relations other than equality.
+    # Describes a relation constraint which constrains a set variable to have
+    # a specified relation to another set variable. The allowed relations and
+    # their aliases are
+    # 
+    # * subset, subset_of
+    # * superset, superset_of
+    # * disjoint, disjoint_with
+    # * complement, complement_of
+    # 
+    # == Examples
+    # 
+    #   # +set_1+ must be subset of +set_2+
+    #   set_1.must_be.subset_of set_2
+    #   
+    #   # +set_1+ must not be superset of +set_2+
+    #   set_1.must_not_be.superset_of set_2
+    #   
+    #   # +set_1+ must be disjoint with +set_2+
+    #   set_1.must_be.disjoint set_2
+    #   
+    #   # The same as above but reified with the boolean variable 
+    #   # +are_disjoint+.
+    #   set_1.must_be.disjoint(set_2, :reify => are_disjoint)
     class RelationConstraint < Gecode::Constraints::ReifiableConstraint
       def post
         var, rhs, reif_var, relation = @params.values_at(:lhs, :rhs, :reif, 
@@ -84,7 +120,24 @@ module Gecode::Constraints::Set
       negate_using_reification
     end
     
-    # Describes a relation constraint on the elements of a set.
+    # Describes an element relation constraint which constrains all elements in
+    # a set variable to satisfy an integer relation constraint. The relations
+    # supported are the same as in 
+    # <tt>Int::Linear::SimpleRelationConstraint</tt>.
+    # 
+    # Reification is not supported.
+    # 
+    # == Examples
+    # 
+    #   # All elements in +set+ must be larger than 5.
+    #   set.elements.must > 5
+    #   
+    #   # No element in +set+ may equal 0.
+    #   set.elements.must_not == 0
+    #   
+    #   # No element in +set+ may contain the value of the integer variable
+    #   # +forbidden_number+.
+    #   set.elements.must_not == forbidden_number
     class ElementRelationConstraint < Gecode::Constraints::Constraint
       def post
         var, rhs, relation = @params.values_at(:lhs, :rhs, :relation)
@@ -103,8 +156,8 @@ module Gecode::Constraints::Set
       end
     end
     
-    # Describes an expression which starts with set.element.must* .
-    class ElementExpression < Gecode::Constraints::Expression
+    # Describes an expression which starts with set.elements.must* .
+    class ElementExpression < Gecode::Constraints::Expression #:nodoc:
       Gecode::Constraints::Util::RELATION_TYPES.each_key do |name|
         module_eval <<-"end_code"
           # Creates an elements constraint using the specified expression, which

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

@@ -41,8 +41,17 @@ module Gecode::Constraints::SetEnum
   end
   
   # A module that gathers the classes and modules used in distinct constraints.
-  module Distinct
-    # Describes a set distinct constraint.
+  module Distinct #:nodoc:
+    # Describes a set distinct constraint, which constrains all set variables
+    # in the enumeration to be distinct and of a specified size. Providing a 
+    # size is not optional.
+    # 
+    # Neither negation nor reification is supported.
+    # 
+    # == Examples
+    # 
+    #   # All set variables in +sets+ must have cardinality 4 and be different.
+    #   sets.must_be.distinct(:size => 4)
     class DistinctConstraint < Gecode::Constraints::Constraint
       def post
         sets, size = @params.values_at(:lhs, :size)
@@ -50,7 +59,17 @@ module Gecode::Constraints::SetEnum
       end
     end
     
-    # Describes an at most one set constraint.
+    # Describes an at most one constraint, which constrains all pairs of set 
+    # variables in the enumeration to at most have one element in common and be 
+    # of a specified size. Providing a size is not optional.
+    # 
+    # Neither negation nor reification is supported.
+    # 
+    # == Examples
+    # 
+    #   # All set variables in +sets+ must have cardinality 17 and no pair may
+    #   # have more than one element in common.
+    #   sets.must.at_most_share_one_element(:size => 17)
     class AtMostOneConstraint < Gecode::Constraints::Constraint
       def post
         sets, size = @params.values_at(:lhs, :size)

data/lib/gecoder/interface/constraints/set_enum/operation.rb

@@ -14,8 +14,32 @@ module Gecode::SetEnumMethods
 end
 
 # A module that gathers the classes and modules used by operation constaints.
-module Gecode::Constraints::SetEnum::Operation
-  # Describes a stub started with a set enumeration followed by a set operation.
+module Gecode::Constraints::SetEnum::Operation #:nodoc:
+  # Describes a CompositeStub for the enumeration operation constraint, which 
+  # constrains the result of applying an operation between all set variables in 
+  # a set enumeration. 
+  # 
+  # The supported operations are:
+  # * union
+  # * disjoint_union
+  # * intersection
+  # * minus
+  # 
+  # == Example
+  # 
+  #   # The union of all set variables in +sets+ must be subset of 1..17.
+  #   sets.union.must_be.subset_of 1..17
+  #   
+  #   # The intersection of all set variables must equal [1,3,5].
+  #   sets.intersection.must == [1,3,5]
+  #   
+  #   # The union of all set variable must be a subset of the set variable
+  #   # +universe+.
+  #   sets.union.must_be.subset_of universe
+  #   
+  #   # The same as above, but reified with the boolean variable 
+  #   # +is_within_universe+. 
+  #   sets.union.must_be.subset_of(universe, :reify => is_within_universe)
   class ExpressionStub < Gecode::Constraints::Set::CompositeStub
     def constrain_equal(variable, params, constrain)
       enum, operation = @params.values_at(:lhs, :operation)

data/lib/gecoder/interface/constraints/set_enum/selection.rb

@@ -2,7 +2,7 @@ module Gecode::SetEnumMethods
   # 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.
-  def self.included(mod)
+  def self.included(mod) #:nodoc:
     mod.module_eval do
       # Now we enter the module that the module possibly defining #[] 
       # is mixed into.
@@ -31,24 +31,10 @@ module Gecode::SetEnumMethods
 end
 
 # A module that gathers the classes and modules used by selection constraints.
-module Gecode::Constraints::SetEnum::Selection
-  # Describes an expression stub started with a set var enum following with an 
-  # array access using an integer variable.
-  class SelectExpressionStub < Gecode::Constraints::Set::CompositeStub
-    def constrain_equal(variable, params, constrain)
-      enum, index = @params.values_at(:lhs, :index)
-      if constrain
-        variable.must_be.subset_of enum.upper_bound_range
-      end
-
-      Gecode::Raw::selectSet(@model.active_space, enum.to_set_var_array, 
-        index.bind, variable.bind)
-    end
-  end
-  
+module Gecode::Constraints::SetEnum::Selection #:nodoc:
   # Describes an expression stub started with a set var enum followed with an
   # array access using a set variable.
-  class SetAccessStub < Gecode::Constraints::ExpressionStub
+  class SetAccessStub < Gecode::Constraints::ExpressionStub #:nodoc:
     include Gecode::Constraints::LeftHandSideMethods
     
     # Starts a union selection constraint on the selected sets.
@@ -85,8 +71,69 @@ module Gecode::Constraints::SetEnum::Selection
     end
   end
   
-  # Describes an expression stub started with a set var enum following with an 
-  # array access using a set variable followed by #union.
+  # Describes an expression that starts with an set variable enum followed with
+  # an array access using a set variable followed by some form of must.
+  class SetAccessExpression < Gecode::Constraints::Set::Expression #:nodoc:
+    # Constrains the selected sets to be disjoint.
+    def disjoint
+      if @params[:negate]
+        raise Gecode::MissingConstraintError, 'A negated set selection ' + 
+          'disjoint is not implemented.'
+      end
+      
+      @model.add_constraint DisjointConstraint.new(@model, @params)
+    end
+  end
+
+  # Describes a CompositeStub for the set select constraint, which constrains 
+  # the set in a position specified by an integer variable in an enumeration of 
+  # set variable.
+  # 
+  # == Examples
+  # 
+  #   # The set at the position described by the integer variable 
+  #   # +singleton_zero_position+ in the enumeration +sets+ of set variables 
+  #   # must equal [0].
+  #   sets[singleton_zero_position].must == 0
+  #   
+  #   # The set at the position described by the integer variable +position+ in 
+  #   # the enumeration +sets+ of set variables must be a subset of +set+.
+  #   sets[position].must_be.subset_of set
+  #   
+  #   # The same as above, but reified with the boolean variable +bool+.
+  #   sets[position].must_be.subset_of(set, :reify => bool)
+  class SelectExpressionStub < Gecode::Constraints::Set::CompositeStub
+    def constrain_equal(variable, params, constrain)
+      enum, index = @params.values_at(:lhs, :index)
+      if constrain
+        variable.must_be.subset_of enum.upper_bound_range
+      end
+
+      Gecode::Raw::selectSet(@model.active_space, enum.to_set_var_array, 
+        index.bind, variable.bind)
+    end
+  end
+  
+  # Describes a CompositeStub for the set union selection constraint, 
+  # which constrains the union of sets located at the positions 
+  # specified by a set variable in an enumeration of set variables.
+  # 
+  # == Examples
+  # 
+  #   # The sets in the enumeration set variable +sets+ located at the positions
+  #   # described by the set variable +selected_sets+ must have a union that's
+  #   # a superset of [0,4,17]. 
+  #   sets[selected_sets].union.must_be.superset_of [0,4,17]
+  #   
+  #   # The sets in the enumeration set variable +sets+ located at the positions
+  #   # described by the set variable +selected_sets+ must have a union that's
+  #   # disjoint with the set variable +set+.
+  #   sets[selected_sets].union.must_be.disjoint_with set
+  #   
+  #   # The same as above but reified with the boolean variable 
+  #   # +union_is_disjoint+.
+  #   sets[selected_sets].union.must_be.disjoint_with(set, 
+  #     :reify => union_is_disjoin)
   class UnionExpressionStub < Gecode::Constraints::Set::CompositeStub
     def constrain_equal(variable, params, constrain)
       enum, indices = @params.values_at(:lhs, :indices)
@@ -99,8 +146,40 @@ module Gecode::Constraints::SetEnum::Selection
     end
   end
   
-  # Describes an expression stub started with a set var enum following with an 
-  # array access using a set variable followed by #intersection.
+  # Describes a CompositeStub for the set intersection selection constraint, 
+  # which constrains the intersection of sets located at the positions 
+  # specified by a set variable in an enumeration of set variables.
+  # 
+  # Optionally a universe may also be specified.
+  # 
+  # == Examples
+  # 
+  #   # The sets in the enumeration set variable +sets+ located at the positions
+  #   # described by the set variable +selected_sets+ must have an intersection 
+  #   # that's a superset of [0,4,17]. 
+  #   sets[selected_sets].intersection.must_be.superset_of [0,4,17]
+  #   
+  #   # The sets in the enumeration set variable +sets+ located at the positions
+  #   # described by the set variable +selected_sets+ must have an intersection
+  #   # that's disjoint with the set variable +set+.
+  #   sets[selected_sets].intersection.must_be.disjoint_with set
+  #   
+  #   # The sets in the enumeration set variable +sets+ located at the positions
+  #   # described by the set variable +selected_sets+ must have an intersection
+  #   # that's disjoint with the set variable +set+ inside the universe 0..17.
+  #   sets[selected_sets].intersection(:with => 0..17).must_be.disjoint_with set
+  #   
+  #   # The sets in the enumeration set variable +sets+ located at the positions
+  #   # described by the set variable +selected_sets+ must have an intersection
+  #   # that's disjoint with the set variable +set+ inside the universe 
+  #   # described by the set variable +universe+.
+  #   sets[selected_sets].intersection(:with => universe).must_be.disjoint_with set
+  #   
+  #   
+  #   # The same as above but reified with the boolean variable 
+  #   # +intersection_is_disjoint+.
+  #   sets[selected_sets].intersection(:with => universe).must_be.disjoint_with(
+  #     set, :reifty => intersection_is_disjoin)
   class IntersectionExpressionStub < Gecode::Constraints::Set::CompositeStub
     def constrain_equal(variable, params, constrain)
       enum, indices, universe = @params.values_at(:lhs, :indices, :universe)
@@ -118,21 +197,16 @@ module Gecode::Constraints::SetEnum::Selection
     end
   end
   
-  # Describes an expression that starts with an set variable enum followed with
-  # an array access using a set variable followed by some form of must.
-  class SetAccessExpression < Gecode::Constraints::Set::Expression
-    # Constrains the selected sets to be disjoint.
-    def disjoint
-      if @params[:negate]
-        raise Gecode::MissingConstraintError, 'A negated set selection ' + 
-          'disjoint is not implemented.'
-      end
-      
-      @model.add_constraint DisjointConstraint.new(@model, @params)
-    end
-  end
-  
-  # Describes a disjoint constraint produced by sets[set].must_be.disjoint .
+  # Describes a disjoint constraint, which constrains all set variable is an
+  # enumeration, at the position specified by a set variable, to be disjoint.
+  # 
+  # Does not support negation nor reification.
+  # 
+  # == Examples
+  # 
+  #   # The set variable located in the enumeration +sets+ at positions 
+  #   # described by +disjoint_set_positions+ must be disjoint.
+  #   sets[disjoint_set_positions].must_be.disjoint 
   class DisjointConstraint < Gecode::Constraints::Constraint
     def post
       enum, indices = @params.values_at(:lhs, :indices)