gecoder 0.2.0 → 0.3.0

data/lib/gecoder/interface/branch.rb

@@ -95,7 +95,7 @@ module Gecode
       end
 
       # Add the branching.
-      Gecode::Raw.branch(active_space, variables.to_int_var_array, 
+      Gecode::Raw.branch(active_space, variables.to_var_array, 
         BRANCH_VAR_CONSTANTS[var_strat], BRANCH_VALUE_CONSTANTS[val_strat])
     end
   end

data/lib/gecoder/interface/constraints.rb

@@ -1,10 +1,126 @@
-require 'gecoder/interface/constraints/relation'
-require 'gecoder/interface/constraints/distinct'
-require 'gecoder/interface/constraints/linear'
-
 module Gecode
   # An error signaling that the constraint specified is missing (e.g. one tried
   # to negate a constraint, but no negated form is implemented).
   class MissingConstraintError < StandardError
   end
-end
+  
+  # A module containing all the constraints.
+  module Constraints
+    # A module that should be mixed in to class of objects that should be usable
+    # as left hand sides (i.e. the part before must*) when specifying 
+    # constraints. Assumes that a method #expression is defined which produces
+    # a new expression given the current constraint parameters.
+    module LeftHandSideMethods
+      # Specifies that a constraint must hold for the integer variable enum.
+      def must
+        expression update_params(:negate => false)
+      end
+      alias_method :must_be, :must
+      
+      # Specifies that the negation of a constraint must hold for the integer 
+      # variable.
+      def must_not
+        expression update_params(:negate => true)
+      end
+      alias_method :must_not_be, :must_not
+      
+      private
+      
+      # Updates the parameters with the specified new parameters.
+      def update_params(params_to_add)
+        @constraint_params ||= {}
+        @constraint_params.update(params_to_add)
+      end
+    end
+    
+    # Describes a constraint expressions. An expression is produced by calling
+    # some form of must on a left hand side. The expression waits for a right 
+    # hand side so that it can post the corresponding constraint.
+    class Expression
+      # Constructs a new expression with the specified parameters. The 
+      # parameters shoud at least contain the keys :lhs, and :negate.
+      #
+      # Raises ArgumentError if any of those keys are missing.
+      def initialize(model, params)
+        unless params.has_key?(:lhs) and params.has_key?(:negate)
+          raise ArgumentError, 'Expression requires at least :lhs, ' + 
+            "and :negate as parameter keys, got #{params.keys.join(', ')}."
+        end
+        
+        @model = model
+        @params = params
+      end
+    end
+    
+    # Base class for all constraints.
+    class Constraint
+      # Creates a constraint with the specified parameters, bound to the 
+      # specified model. 
+      def initialize(model, params)
+        @model = model
+        @params = params.clone
+      end
+      
+      # Posts the constraint, adding it to the model. This is an abstract 
+      # method and should be overridden by all sub-classes.
+      def post
+        raise NoMethodError, 'Abstract method has not been implemented.'
+      end
+    end
+  
+    # A module that provides some utility-methods for decoding options given to
+    # constraints.
+    module OptionUtil
+      private
+      
+      # Maps the name used in options to the value used in Gecode for 
+      # propagation strengths.
+      PROPAGATION_STRENGTHS = {
+        :default  => Gecode::Raw::ICL_DEF,
+        :value    => Gecode::Raw::ICL_VAL,
+        :bounds   => Gecode::Raw::ICL_BND,
+        :domain   => Gecode::Raw::ICL_DOM
+      }
+      
+      public
+      
+      module_function
+      
+      # Decodes the common options to constraints: strength and reification. 
+      # Returns a hash with up to two values. :strength is the strength that 
+      # should be used for the constraint and :reif is the (bound) boolean 
+      # variable that should be used for reification. The decoded options are 
+      # removed from the hash (so in general the hash will be consumed in the 
+      # process).
+      # 
+      # Raises ArgumentError if an unrecognized option is found in the specified
+      # hash. Or if an unrecognized strength is given. Raises TypeError if the
+      # reification variable is not a boolean variable.
+      def decode_options(options)
+        # Propagation strength.
+        strength = options.delete(:strength) || :default
+        unless PROPAGATION_STRENGTHS.include? strength
+          raise ArgumentError, "Unrecognized propagation strength #{strength}."
+        end
+        
+        # Reification.
+        reif_var = options.delete(:reify)
+        unless reif_var.nil? or reif_var.kind_of? FreeBoolVar
+          raise TypeError, 'Only boolean variables may be used for reification.'
+        end
+        
+        # Check for unrecognized options.
+        unless options.empty?
+          raise ArgumentError, 'Unrecognized constraint option: ' + 
+            options.keys.first.to_s
+        end
+        return {:strength => PROPAGATION_STRENGTHS[strength], :reif => reif_var}
+      end
+    end
+  end
+end
+
+require 'gecoder/interface/constraints/reifiable_constraints'
+require 'gecoder/interface/constraints/int_var_constraints'
+require 'gecoder/interface/constraints/int_enum_constraints'
+require 'gecoder/interface/constraints/bool_var_constraints'

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

@@ -0,0 +1,160 @@
+module Gecode
+  class FreeBoolVar
+    def |(var)
+      Constraints::Bool::ExpressionNode.new(self, @model) | var
+    end
+    
+    def &(var)
+      Constraints::Bool::ExpressionNode.new(self, @model) & var
+    end
+  end
+  
+  module Constraints::Bool
+    # Add some relation selection based on whether the expression is negated.
+    alias_method :pre_bool_rel_initialize, :initialize
+    class Expression
+      def ==(expression)
+        add_boolean_constraint(expression)
+      end
+      alias_method :equal, :==
+      alias_method :equal_to, :==
+      
+      def true
+        # Bind parameters.
+        lhs = @params[:lhs]
+        unless lhs.respond_to? :to_minimodel_lin_exp
+          lhs = ExpressionNode.new(lhs, @model)
+        end
+
+        @model.add_constraint BooleanConstraint.new(@model, 
+          @params.update(:expression => lhs.to_minimodel_lin_exp))
+      end
+      
+      def false
+        # Bind parameters.
+        lhs = @params[:lhs]
+        unless lhs.respond_to? :to_minimodel_lin_exp
+          lhs = ExpressionNode.new(lhs, @model)
+        end
+        
+        @params.update(:expression => Gecode::Raw::MiniModel::BoolExpr.new(
+            lhs.to_minimodel_lin_exp, Gecode::Raw::MiniModel::BoolExpr::BT_NOT))
+        @model.add_constraint BooleanConstraint.new(@model, @params)
+      end
+      
+      private
+      
+      # Adds the boolean constraint corresponding to equivalence between the 
+      # left and right hand sides.
+      #
+      # Raises TypeError if the element is of a type that doesn't allow a 
+      # relation to be specified.
+      def add_boolean_constraint(right_hand_side = nil)
+        # Bind parameters.
+        lhs = @params[:lhs]
+        unless lhs.respond_to? :to_minimodel_lin_exp
+          lhs = ExpressionNode.new(lhs, @model)
+        end
+        unless right_hand_side.respond_to? :to_minimodel_lin_exp
+          right_hand_side = ExpressionNode.new(right_hand_side, @model)
+        end
+        
+        expression = ExpressionTree.new(lhs, right_hand_side, 
+          Gecode::Raw::MiniModel::BoolExpr::BT_EQV)
+        @model.add_constraint BooleanConstraint.new(@model, 
+          @params.update(:expression => expression.to_minimodel_lin_exp))
+      end
+    end
+    
+    # Describes a boolean constraint.
+    class BooleanConstraint < Gecode::Constraints::ReifiableConstraint
+      def post
+        unless @params[:reif].nil?
+          @params[:expression] = Gecode::Raw::MiniModel::BoolExpr.new(
+            @params[:expression], Gecode::Raw::MiniModel::BoolExpr::BT_EQV, 
+            Gecode::Raw::MiniModel::BoolExpr.new(@params[:reif].bind))
+        end
+        @params[:expression].post(@model.active_space, !@params[:negate])
+      end
+    end
+  
+    # A module containing the methods for the basic boolean operations. Depends
+    # on that the class mixing it in defined #model.
+    module OperationMethods
+      include Gecode::Constraints::LeftHandSideMethods
+      
+      private
+    
+      # Maps the names of the methods to the corresponding bool operation type
+      # in Gecode.
+      OPERATION_TYPES = {
+        :|  => Gecode::Raw::MiniModel::BoolExpr::BT_OR,
+        :&  => Gecode::Raw::MiniModel::BoolExpr::BT_AND
+      }
+      
+      public
+      
+      OPERATION_TYPES.each_pair do |name, operation|
+        module_eval <<-"end_code"
+          def #{name}(expression)
+            unless expression.kind_of? ExpressionTree
+              expression = ExpressionNode.new(expression)
+            end
+            ExpressionTree.new(self, expression, #{operation})
+          end
+        end_code
+      end
+      
+      private
+      
+      # Produces an expression for the lhs module.
+      def expression(params)
+        params.update(:lhs => self)
+        Gecode::Constraints::Bool::Expression.new(model, params)
+      end
+    end
+  
+    # Describes a binary tree of expression nodes which together form a boolean 
+    # expression.
+    class ExpressionTree
+      include OperationMethods
+    
+      # Constructs a new expression with the specified variable
+      def initialize(left_node, right_node, operation)
+        @left = left_node
+        @right = right_node
+        @operation = operation
+      end
+      
+      # Converts the boolean expression to an instance of 
+      # Gecode::Raw::MiniModel::BoolExpr
+      def to_minimodel_lin_exp
+        Gecode::Raw::MiniModel::BoolExpr.new(@left.to_minimodel_lin_exp,
+          @operation, @right.to_minimodel_lin_exp)
+      end
+      
+      # Fetches the space that the expression's variables is in.
+      def model
+        @left.model || @right.model
+      end
+    end
+  
+    # Describes a single node in a boolean expression.
+    class ExpressionNode
+      include OperationMethods
+    
+      attr :model
+    
+      def initialize(value, model = nil)
+        @value = value
+        @model = model
+      end
+      
+      # Converts the linear expression to an instance of 
+      # Gecode::Raw::MiniModel::BoolExpr
+      def to_minimodel_lin_exp
+        Gecode::Raw::MiniModel::BoolExpr.new(@value.bind)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Gecode
+  class FreeBoolVar
+    include Gecode::Constraints::LeftHandSideMethods
+    
+    private
+    
+    # Produces an expression for the lhs module.
+    def expression(params)
+      params.update(:lhs => self)
+      Constraints::Bool::Expression.new(@model, params)
+    end
+  end
+  
+  # A module containing constraints that have int variables as left hand side
+  # (but not enumerations).
+  module Constraints::Bool
+    # Describes a boolean expression.
+    class Expression < Gecode::Constraints::Expression
+    end
+  end
+end
+
+require 'gecoder/interface/constraints/bool/boolean'

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

@@ -0,0 +1,258 @@
+module Gecode
+  class FreeIntVar
+    # Creates a linear expression where the int variables are summed.
+    def +(var)
+      Gecode::Constraints::Int::Linear::ExpressionNode.new(self, 
+        @model) + var
+    end
+    
+    # Creates a linear expression where the int variable is multiplied with 
+    # a constant integer.
+    def *(int)
+      Gecode::Constraints::Int::Linear::ExpressionNode.new(self, 
+        @model) * int
+    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
+  
+  module Constraints::Int
+    class Expression
+      private
+    
+      # Maps the names of the methods to the corresponding integer relation 
+      # type in Gecode.
+      RELATION_TYPES = { 
+        :== => Gecode::Raw::IRT_EQ,
+        :<= => Gecode::Raw::IRT_LQ,
+        :<  => Gecode::Raw::IRT_LE,
+        :>= => Gecode::Raw::IRT_GQ,
+        :>  => Gecode::Raw::IRT_GR }
+      # The same as above, but negated.
+      NEGATED_RELATION_TYPES = {
+        :== => Gecode::Raw::IRT_NQ,
+        :<= => Gecode::Raw::IRT_GR,
+        :<  => Gecode::Raw::IRT_GQ,
+        :>= => Gecode::Raw::IRT_LE,
+        :>  => Gecode::Raw::IRT_LQ
+      }
+      
+      # Various method aliases for the class. Maps the original name to an 
+      # array of aliases.
+      METHOD_ALIASES = { 
+        :== => [:equal, :equal_to],
+        :>  => [:greater, :greater_than],
+        :>= => [:greater_or_equal, :greater_than_or_equal_to],
+        :<  => [:less, :less_than],
+        :<= => [:less_or_equal, :less_than_or_equal_to]
+      }
+      
+      public
+    
+      # Add some relation selection based on whether the expression is negated.
+      alias_method :pre_linear_initialize, :initialize
+      def initialize(model, params)
+        pre_linear_initialize(model, params)
+        unless params[:negate]
+          @method_relations = RELATION_TYPES
+        else
+          @method_relations = NEGATED_RELATION_TYPES
+        end
+      end
+      
+      # Define the relation methods.
+      RELATION_TYPES.each_key do |name|
+        module_eval <<-"end_code"
+          def #{name}(expression, options = {})
+            relation = @method_relations[:#{name}]
+            @params.update(
+              Gecode::Constraints::OptionUtil.decode_options(options))
+            if self.simple_expression? and simple_expression?(expression)
+              # A relation constraint is enough.
+              add_relation_constraint(relation, expression)
+            else
+              add_linear_constraint(relation, expression)
+            end
+          end
+        end_code
+      end
+      
+      # Various aliases.
+      METHOD_ALIASES.each_pair do |orig, alias_names|
+        alias_names.each do |name|
+          alias_method name, orig
+        end
+      end
+      
+      protected
+      
+      # Checks whether the given expression is simple enough to be used in a 
+      # simple relation constraint. Returns true if it is, false otherwise. If
+      # no expression is given then the this expression's left hand side is 
+      # checked.
+      def simple_expression?(expression = nil)
+        if expression.nil?
+          simple_expression?(@params[:lhs])
+        else
+          expression.kind_of?(Gecode::FreeIntVar) or expression.kind_of?(Fixnum)
+        end
+      end
+      
+      private
+      
+      # Places the linear constraint corresponding to the specified (integer)
+      # relation type (as specified by Gecode) in relation to the specifed 
+      # expression.
+      # 
+      # Raises TypeError if the element is of a type that doesn't allow a 
+      # relation to be specified.
+      def add_linear_constraint(relation_type, right_hand_side)
+        # Bind parameters.
+        lhs = @params[:lhs]
+        if lhs.kind_of? Gecode::FreeIntVar
+          lhs = lhs * 1 # Convert to Gecode::Raw::LinExp
+        end
+        if right_hand_side.respond_to? :to_minimodel_lin_exp
+          right_hand_side = right_hand_side.to_minimodel_lin_exp
+        elsif right_hand_side.kind_of? Gecode::FreeIntVar
+          right_hand_side = right_hand_side.bind * 1
+        elsif not right_hand_side.kind_of? Fixnum
+          raise TypeError, 'Invalid right hand side of linear equation.'
+        end
+        
+        @params.update(:relation_type => relation_type, :lhs => lhs, 
+          :rhs => right_hand_side)
+        @model.add_constraint Linear::LinearConstraint.new(@model, @params)
+      end
+      
+      # Places the relation constraint corresponding to the specified (integer)
+      # relation type (as specified by Gecode) in relation to the specifed 
+      # element.
+      def add_relation_constraint(relation_type, element)
+        # Bind parameters.
+        @params[:lhs] = @params[:lhs].bind
+        if element.kind_of? FreeIntVar
+          element = element.bind
+        end
+      
+        @model.add_constraint Linear::SimpleRelationConstraint.new(@model, 
+          @params.update(:relation_type => relation_type, :element => element))
+      end
+    end
+  end
+  
+  # A module that gathers the classes and modules used in linear constraints.
+  module Constraints::Int::Linear
+    # Describes a linear constraint.
+    class LinearConstraint < Gecode::Constraints::ReifiableConstraint
+      def post
+        lhs, rhs, relation_type, reif_var, strength = @params.values_at(:lhs, 
+          :rhs, :relation_type, :reif, :strength)
+        reif_var = reif_var.bind if reif_var.respond_to? :bind
+
+        final_exp = (lhs.to_minimodel_lin_exp - rhs)
+        if reif_var.nil?
+          final_exp.post(@model.active_space, relation_type, strength)
+        else
+          final_exp.post(@model.active_space, relation_type, reif_var)
+        end
+      end
+    end
+    
+    # Describes a simple relation constraint.
+    class SimpleRelationConstraint < Gecode::Constraints::ReifiableConstraint
+      def post        
+        # Fetch the parameters to Gecode.
+        params = @params.values_at(:lhs, :relation_type, :element, :reif, 
+          :strength)
+        params[3] = params[3].bind unless params[3].nil? # Bind reification var.
+        params.delete_if{ |x| x.nil? }
+        Gecode::Raw::rel(@model.active_space, *params)
+      end
+    end
+  
+    # 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
+      include Gecode::Constraints::LeftHandSideMethods
+      
+      private
+    
+      OPERATION_TYPES = [:+, :-, :*]
+    
+      public
+    
+      # Define methods for the available operations.
+      OPERATION_TYPES.each do |name|
+        module_eval <<-"end_code"
+          def #{name}(expression)
+            unless expression.kind_of? ExpressionTree
+              expression = ExpressionNode.new(expression)
+            end
+            ExpressionTree.new(self, expression, :#{name})
+          end
+        end_code
+      end
+      
+      private
+      
+      # Produces an expression for the lhs module.
+      def expression(params)
+        params.update(:lhs => self)
+        Gecode::Constraints::Int::Expression.new(model, params)
+      end
+    end
+    
+    # Describes a binary tree of expression nodes which together form a linear 
+    # expression.
+    class ExpressionTree
+      include Helper
+    
+      # Constructs a new expression with the specified variable
+      def initialize(left_node, right_node, operation)
+        @left = left_node
+        @right = right_node
+        @operation = operation
+      end
+      
+      # Converts the linear expression to an instance of 
+      # Gecode::Raw::MiniModel::LinExpr
+      def to_minimodel_lin_exp
+        @left.to_minimodel_lin_exp.send(@operation, @right.to_minimodel_lin_exp)
+      end
+      
+      # Fetches the space that the expression's variables is in.
+      def model
+        @left.model || @right.model
+      end
+    end
+    
+    # Describes a single node in a linear expression.
+    class ExpressionNode
+      include Helper
+    
+      attr :model
+    
+      def initialize(value, model = nil)
+        @value = value
+        @model = model
+      end
+      
+      # Converts the linear expression to an instance of 
+      # Gecode::Raw::MiniModel::LinExpr
+      def to_minimodel_lin_exp
+        expression = @value
+        if expression.kind_of? Gecode::FreeIntVar
+          # Minimodel requires that we do this first.
+          expression = expression.bind * 1
+        end
+        expression
+      end
+    end
+  end
+end