gecoder 0.2.0

data/lib/gecoder/interface.rb

@@ -0,0 +1,6 @@
+require 'gecoder/interface/binding_changes'
+require 'gecoder/interface/model'
+require 'gecoder/interface/search'
+require 'gecoder/interface/constraints'
+require 'gecoder/interface/enum_wrapper'
+require 'gecoder/interface/branch'

data/lib/gecoder/interface/binding_changes.rb

@@ -0,0 +1,111 @@
+# This file adds a small layer on top of the bindings. It alters the allocation 
+# of variables so that a single array is allocated in each space which is then 
+# used to store variable. The variables themselves are not directly returned, 
+# rather they are represented as the index in that store, which allows the 
+# variable to be retrieved back given a space.
+#
+# This layer should be moved to the C++ side instead when possible for better
+# performance.
+module Gecode::Raw
+  class Space
+    # Creates the specified number of integer variables in the store. Returns
+    # the indices with which they can then be accessed using int_var.
+    def new_int_vars(min, max, count = 1)
+      int_var_store.new_vars(min, max, count)
+    end
+    
+    # Gets the int variable with the specified index, nil if none exists.
+    def int_var(index)
+      int_var_store[index]
+    end
+    
+    private
+    
+    # Retrieves the store used for integer variables. Creates one if none
+    # exists.
+    def int_var_store
+      if @int_var_store.nil?
+        @int_var_store = Gecode::Raw::IntVarStore.new(self) 
+      end
+      return @int_var_store
+    end
+  end
+
+  # A store in which int variables are created and stored.
+  class IntVarStore
+    # Design note: The store used to double its size when it needed to grow
+    # leaving unallocated slots (in rev 16). This was changed to only growing
+    # the amount of space needed because the additional information about which
+    # slot is the next unallocated one could not be encoded without changes to
+    # the bindings (and without that information we can not deduce the store
+    # from the new copy of space). So for additional performance the bindings 
+    # should grow the array more than needed (when this is moved to the bindings).
+    
+    private
+  
+    # A string that identifies the array used by the store.
+    ARRAY_IDENTIFIER = 'int_array'
+  
+    public
+    
+    # Creates a store for the specified space with the specified capacit.
+    def initialize(space)
+      @var_array = space.int_var_array(ARRAY_IDENTIFIER)
+      if @var_array.nil?
+        # Create a new one.
+        @var_array = Gecode::Raw::IntVarArray.new(space, 0)
+        space.own(@var_array, ARRAY_IDENTIFIER)
+      end
+
+      @size = @var_array.size
+      @next_index = @size
+      @space = space
+    end
+    
+    # Creates the specified number of new int variables with the specified
+    # range as domain. Returns the indices of the created variables as an array.
+    def new_vars(min, max, count = 1)
+      grow(@next_index + count) # See the design note for more information.
+      count.times do |i|
+        @var_array[@next_index] = Gecode::Raw::IntVar.new(@space, 
+          min, max)
+        @next_index += 1
+      end
+      
+      ((@next_index - count)...@next_index).to_a
+    end
+
+    # Returns the int var with the specified index, nil if none exists.
+    def [](index)
+      if index < 0 or index >= @next_index
+        return nil
+      end
+      return @var_array.at(index)
+    end
+
+    private
+    
+    # Grows the store to the new size.
+    def grow(new_size)
+      if new_size <= @size
+        raise ArgumentError, 'New size must be larger than the old one.'
+      end
+      
+      new_array = Gecode::Raw::IntVarArray.new(@space, new_size)
+      @var_array.size.times do |i|
+        new_array[i] = @var_array[i]
+      end
+      @space.own(new_array, ARRAY_IDENTIFIER)
+      @var_array = new_array
+      @size = new_size
+    end
+  end
+  
+  class IntVar
+    # Aliases to make method-names more ruby-like.
+    alias_method :assigned?, :assigned
+    alias_method :in?, :in
+    alias_method :range?, :range
+  end
+end
+

data/lib/gecoder/interface/branch.rb

@@ -0,0 +1,102 @@
+module Gecode
+  class Model
+    private
+    
+    # Maps the names of the supported variable branch strategies to the 
+    # corresponding constant in Gecode. 
+    BRANCH_VAR_CONSTANTS = {
+      :none                 => Gecode::Raw::BVAR_NONE,
+      :smallest_min         => Gecode::Raw::BVAR_MIN_MIN,
+      :largest_min          => Gecode::Raw::BVAR_MIN_MAX, 
+      :smallest_max         => Gecode::Raw::BVAR_MAX_MIN, 
+      :largest_max          => Gecode::Raw::BVAR_MAX_MAX, 
+      :smallest_size        => Gecode::Raw::BVAR_SIZE_MIN, 
+      :largest_size         => Gecode::Raw::BVAR_SIZE_MAX,
+      :smallest_degree      => Gecode::Raw::BVAR_DEGREE_MIN, 
+      :largest_degree       => Gecode::Raw::BVAR_DEGREE_MAX, 
+      :smallest_min_regret  => Gecode::Raw::BVAR_REGRET_MIN_MIN,
+      :largest_min_regret   => Gecode::Raw::BVAR_REGRET_MIN_MAX,
+      :smallest_max_regret  => Gecode::Raw::BVAR_REGRET_MAX_MIN, 
+      :largest_max_regret   => Gecode::Raw::BVAR_REGRET_MAX_MAX
+    }
+    
+    # Maps the names of the supported value branch strategies to the 
+    # corresponding constant in Gecode. 
+    BRANCH_VALUE_CONSTANTS = {
+      :min        => Gecode::Raw::BVAL_MIN,
+      :med        => Gecode::Raw::BVAL_MED,
+      :max        => Gecode::Raw::BVAL_MAX,
+      :split_min  => Gecode::Raw::BVAL_SPLIT_MIN,
+      :split_max  => Gecode::Raw::BVAL_SPLIT_MAX
+    }
+    
+    public
+  
+    # Specifies which variables that should be branched on. One can optionally
+    # also select which of the variables that should be used first with the
+    # :variable option and which value in that variable's domain that should be 
+    # used with the :value option. If nothing is specified then :variable uses
+    # :none and value uses :min.
+    #
+    # The following values can be used with :variable
+    # [:none]                 The first unassigned variable.
+    # [:smallest_min]         The one with the smallest minimum.
+    # [:largest_min]          The one with the largest minimum.
+    # [:smallest_max]         The one with the smallest maximum.
+    # [:largest_max]          The one with the largest maximum.
+    # [:smallest_size]        The one with the smallest size.
+    # [:largest_size]         The one with the larges size.
+    # [:smallest_degree]      The one with the smallest degree. The degree of a 
+    #                         variable is defined as the number of dependant 
+    #                         propagators. In case of ties, choose the variable 
+    #                         with smallest domain.
+    # [:largest_degree]       The one with the largest degree. The degree of a 
+    #                         variable is defined as the number of dependant 
+    #                         propagators. In case of ties, choose the variable 
+    #                         with smallest domain.
+    # [:smallest_min_regret]  The one with the smallest min-regret. The 
+    #                         min-regret of a variable is the difference between
+    #                         the smallest and second-smallest value still in 
+    #                         the domain.
+    # [:largest_min_regret]   The one with the largest min-regret. The 
+    #                         min-regret of a variable is the difference between
+    #                         the smallest and second-smallest value still in 
+    #                         the domain.
+    # [:smallest_max_regret]  The one with the smallest max-regret The 
+    #                         max-regret of a variable is the difference between
+    #                         the largest and second-largest value still in 
+    #                         the domain.
+    # [:largest_max_regret]   The one with the largest max-regret. The 
+    #                         max-regret of a variable is the difference between
+    #                         the largest and second-largest value still in 
+    #                         the domain.
+    #
+    # The following values can be used with :value
+    # [:min]        Selects the smallest value.
+    # [:med]        Select the median value.
+    # [:max]        Selects the largest vale
+    # [:split_min]  Selects the lower half of the domain.
+    # [:split_max]  Selects the upper half of the domain.
+    def branch_on(variables, options = {})
+      # Extract optional arguments.
+      var_strat = options.delete(:variable) || :none
+      val_strat = options.delete(:value) || :min
+
+      # Check that the options are correct.
+      unless options.empty?
+        raise ArgumentError, 'Unknown branching option given: ' + 
+          options.keys.join(', ')
+      end
+      unless BRANCH_VAR_CONSTANTS.include? var_strat
+        raise ArgumentError, "Unknown variable selection strategy: #{var_strat}"
+      end
+      unless BRANCH_VALUE_CONSTANTS.include? val_strat
+        raise ArgumentError, "Unknown value selection strategy: #{val_strat}"
+      end
+
+      # Add the branching.
+      Gecode::Raw.branch(active_space, variables.to_int_var_array, 
+        BRANCH_VAR_CONSTANTS[var_strat], BRANCH_VALUE_CONSTANTS[val_strat])
+    end
+  end
+end

data/lib/gecoder/interface/constraints.rb

@@ -0,0 +1,10 @@
+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

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

@@ -0,0 +1,15 @@
+module Gecode
+  class IntVarEnumConstraintExpression
+    # Posts a distinct constraint on the variables in the enum.
+    def distinct
+      if @negate
+        # The best we could implement it as from here would be a bunch of 
+        # reified pairwise equality constraints. 
+        raise Gecode::MissingConstraintError, 'A negated distinct has not ' + 
+          'been implemented.'
+      end
+      
+      Gecode::Raw::distinct(@space, @var_array, Gecode::Raw::ICL_DEF)
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+module Gecode
+  class FreeIntVar
+    # Creates a linear expression where the int variables are summed.
+    def +(var)
+      Gecode::LinearConstraintExpressionNode.new(self, active_space) + var
+    end
+    
+    # Creates a linear expression where the int variable is multiplied with 
+    # a constant integer.
+    def *(int)
+      Gecode::LinearConstraintExpressionNode.new(self, active_space) * int
+    end
+    
+    # Creates a linear expression where the specified variable is subtracted 
+    # from this one.
+    def -(var)
+      Gecode::LinearConstraintExpressionNode.new(self, active_space) - var
+    end
+  end
+  
+  module LinearConstraintHelper
+    OPERATION_TYPES = [:+, :-, :*]
+  
+    # Define methods for the available operations.
+    OPERATION_TYPES.each do |name|
+      module_eval <<-"end_code"
+        def #{name}(expression)
+          unless expression.kind_of? Gecode::LinearConstraintExpressionTree
+            expression = Gecode::LinearConstraintExpressionNode.new(expression)
+          end
+          Gecode::LinearConstraintExpressionTree.new(self, expression, :#{name})
+        end
+      end_code
+    end
+    
+    # Specifies that a constraint must hold for the linear expression.
+    def must
+      Gecode::LinearConstraintExpression.new(self)
+    end
+    
+    # Specifies that the negation of a constraint must hold for the linear
+    # expression.
+    def must_not
+      Gecode::LinearConstraintExpression.new(self, true)
+    end
+  end
+  
+  # Describes a linear constraint that starts with a linear expression followed 
+  # by must or must_not.
+  class LinearConstraintExpressionTree
+    include Gecode::LinearConstraintHelper
+  
+    # 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 space
+      @left.space || @right.space
+    end
+  end
+  
+  # Describes a single node in a linear constrain expression.
+  class LinearConstraintExpressionNode
+    include Gecode::LinearConstraintHelper
+  
+    attr :space
+  
+    def initialize(value, space = nil)
+      @value = value
+      @space = space
+    end
+    
+    # Converts the linear expression to an instance of 
+    # Gecode::Raw::MiniModel::LinExpr
+    def to_minimodel_lin_exp
+      expression = @value
+      if expression.kind_of? FreeIntVar
+        # Minimodel requires that we do this first.
+        expression = expression.bind * 1
+      end
+      expression
+    end
+  end
+  
+  # Describes a linear constraint expression that starts with a linear 
+  # expression followed by must or must_not.
+  class LinearConstraintExpression
+    # TODO: this is awfully similar to IntVarConstrainExpression. There should
+    # be some way to combine them.
+  
+    # 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
+    }
+    
+    # Constructs the expression with the specified left hand side. The 
+    # expression can optionally be negated.
+    def initialize(left_hand_side, negate = false)
+      @lhs = left_hand_side
+      unless negate
+        @method_relations = RELATION_TYPES
+      else
+        @method_relations = NEGATED_RELATION_TYPES
+      end
+    end
+    
+    RELATION_TYPES.each_key do |name|
+      module_eval <<-"end_code"
+        def #{name}(expression)
+          post_relation_constraint(@method_relations[:#{name}], expression)
+        end
+      end_code
+    end
+    
+    private
+    
+    # Places the relation constraint corresponding to the specified (integer)
+    # relation type (as specified by Gecode) in relation to the specifed 
+    # element.
+    # 
+    # Raises TypeError if the element is of a type that doesn't allow a relation
+    # to be specified.
+    def post_relation_constraint(relation_type, right_hand_side)
+      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
+      
+      (@lhs.to_minimodel_lin_exp - right_hand_side).post(@lhs.space, 
+        relation_type, Gecode::Raw::ICL_DEF)
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+module Gecode
+  class FreeIntVar
+    # Specifies that a constraint must hold for the integer variable.
+    def must
+      Gecode::IntVarConstraintExpression.new(active_space, self.bind)
+    end
+    
+    # Specifies that the negation of a constraint must hold for the integer 
+    # variable.
+    def must_not
+      Gecode::IntVarConstraintExpression.new(active_space, self.bind, true)
+    end
+  end
+  
+  # Describes a constraint expression that starts with a single integer variable
+  # followed by must or must_not.
+  class IntVarConstraintExpression
+    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
+    }
+      
+    public
+    
+    # Constructs a new expression with the specified space and (bound) variable 
+    # as source. The expression can optionally be negated.
+    def initialize(space, var, negate = false)
+      @space = space
+      @var = var
+      unless negate
+        @method_relations = RELATION_TYPES
+      else
+        @method_relations = NEGATED_RELATION_TYPES
+      end
+    end
+    
+    RELATION_TYPES.each_key do |name|
+      module_eval <<-"end_code"
+        def #{name}(element)
+          post_relation_constraint(@method_relations[:#{name}], element)
+        end
+      end_code
+    end
+    
+    private
+    
+    # Places the relation constraint corresponding to the specified (integer)
+    # relation type (as specified by Gecode) in relation to the specifed 
+    # element.
+    # 
+    # Raises TypeError if the element is of a type that doesn't allow a relation
+    # to be specified.
+    def post_relation_constraint(relation_type, element)
+      if element.kind_of? Fixnum
+        Gecode::Raw::rel(@space, @var, relation_type, element, 
+          Gecode::Raw::ICL_DEF)
+      else
+        raise TypeError, 'Relations only allow Fixnum.'
+      end
+    end
+  end
+end