quicopt 0.1.0 → 0.4.0

data/lib/quicopt/model.rb

@@ -9,24 +9,28 @@
 # expressions (+x + y <= 5+) builds a +Constraint+ — neither evaluates to a number
 # or a boolean.
 #
-# Expressions are normalised as they are built: an +Expression+ is always a
+# Expressions are collected as they are built: an +Expression+ is always a
 # constant plus a map of linear terms plus a map of quadratic terms, never an
 # unreduced operator tree. That is what makes the degree check exact — anything
 # that would exceed degree 2 raises at the point of multiplication rather than
-# reaching the service, per the "raise loudly, never approximate" rule the sibling
+# reaching the service, per the "raise loudly, never approximate" rule the other
 # clients follow.
 #
-# Only flat (unindexed) variables exist here. The wire schema also carries index
-# sets, parameter tables and quantified constraints; the Ruby DSL deliberately
-# does not — see the layered front-ends in the other clients for those.
+# Only flat (unindexed) variables exist here. The message format also carries
+# index sets and quantified constraints; the Ruby DSL deliberately does not — the
+# Python and Julia clients reach those. It does carry permutations, partitions
+# and lookup tables (+quicopt/structured+) and terms that switch
+# (+quicopt/indicators+), which enter an +Expression+ as factors of degree 1,
+# alongside the variables.
 
 module Quicopt
   # Base class of every error this gem raises.
   class Error < StandardError; end
 
-  # An expression outside the linear/quadratic subset the DSL serves — e.g. a
-  # product of three variables, or a division by a variable. Raised at the point
-  # of construction so the offending term is still in the backtrace.
+  # An expression Quicopt cannot express, because it is neither linear nor
+  # quadratic — a product of three variables, say, or a division by a variable.
+  # Raised at the point of construction so the offending term is still in the
+  # backtrace.
   class UnsupportedExpression < Error; end
 
   # Number and term rendering shared by the DSL's +to_s+ methods. Presentation
@@ -43,7 +47,7 @@ module Quicopt
       value == value.to_i ? value.to_i.to_s : value.to_s
     end
 
-    # One term, dropping a unit coefficient (+x+, +-x+, +3*x+).
+    # One term, dropping a unit coefficient (<tt>x</tt>, <tt>-x</tt>, <tt>3*x</tt>).
     def term(coefficient, factors)
       return factors if coefficient == 1.0
       return "-#{factors}" if coefficient == -1.0
@@ -59,7 +63,7 @@ module Quicopt
   # what lets +3 * x+ parse: Ruby hands the multiplication back to us rather than
   # failing in +Integer#*+.
   module Operators
-    # @return [Expression] +self + other+
+    # @return [Expression] <tt>self + other</tt>
     def +(other)
       to_expr.plus(Expression.cast(other))
     end
@@ -76,7 +80,7 @@ module Quicopt
     end
 
     # Division by a numeric constant only — dividing by an expression is not a
-    # polynomial and has no wire form.
+    # polynomial, and a Quicopt model is a polynomial.
     #
     # @return [Expression] +self / divisor+
     # @raise [UnsupportedExpression] if +divisor+ is not a nonzero number
@@ -90,7 +94,7 @@ module Quicopt
       to_expr.scale(1.0 / divisor)
     end
 
-    # Integer powers 0, 1 and 2 only — the degree the subset admits.
+    # Integer powers 0, 1 and 2 only — a Quicopt model is linear or quadratic.
     #
     # @return [Expression] +self ** exponent+
     # @raise [UnsupportedExpression] on any other exponent
@@ -101,7 +105,8 @@ module Quicopt
       when 2 then to_expr.times(to_expr)
       else
         raise UnsupportedExpression,
-              "exponent #{exponent.inspect} is outside the linear/quadratic subset (0, 1 or 2)"
+              "exponent #{exponent.inspect} is not supported: a Quicopt model is " \
+              "linear or quadratic, so the exponent must be 0, 1 or 2"
       end
     end
 
@@ -125,12 +130,28 @@ module Quicopt
       Constraint.build(self, other, :ge)
     end
 
+    # A strict comparison, for +Quicopt.holds+ only: no constraint row can be
+    # strict, so +Model#add+ refuses it.
+    #
+    # @return [Constraint] the comparison +self < other+
+    def <(other)
+      Constraint.build(self, other, :lt)
+    end
+
+    # A strict comparison, for +Quicopt.holds+ only (see +<+).
+    #
+    # @return [Constraint] the comparison +self > other+
+    def >(other)
+      Constraint.build(self, other, :gt)
+    end
+
     # Builds an *equality row*, not a boolean — +x == 5+ is a constraint.
     #
     # A non-numeric, non-expression operand falls back to identity, so an
-    # incidental comparison (+x == nil+, +x == "x"+) still answers +false+ instead
-    # of raising. Hash and Set membership are unaffected either way: they key off
-    # +hash+/+eql?+, which +Variable+ defines separately.
+    # incidental comparison (<tt>x == nil</tt>, <tt>x == "x"</tt>) still
+    # answers +false+ instead of raising. Hash and Set membership are unaffected
+    # either way: they key off <tt>hash</tt>/<tt>eql?</tt>, which +Variable+
+    # defines separately.
     #
     # @return [Constraint, Boolean]
     def ==(other)
@@ -139,19 +160,20 @@ module Quicopt
       Constraint.build(self, other, :eq)
     end
 
-    # A disequality is not representable on the wire, and Ruby would otherwise
-    # derive it from +==+ and silently answer +false+ for every row.
+    # A "not equal to" comparison, for +Quicopt.holds+ only: +Model#add+ refuses
+    # it as a row. Defined so that Ruby does not derive +!=+ from +==+ and
+    # silently answer +false+.
     #
-    # @raise [UnsupportedExpression] always, for an expression-like operand
+    # @return [Constraint, Boolean]
     def !=(other)
       return !equal?(other) unless Expression.castable?(other)
 
-      raise UnsupportedExpression,
-            "!= is not a constraint the wire schema can carry; model it with a binary and a big-M row"
+      Constraint.build(self, other, :ne)
     end
 
     # Lets Ruby fold a numeric on the left into an expression, so +3 * x+ and
-    # +10 - x+ dispatch here instead of failing inside +Integer+/+Float+.
+    # +10 - x+ dispatch here instead of failing inside
+    # <tt>Integer</tt>/<tt>Float</tt>.
     #
     # @param other [Numeric]
     # @return [Array(Expression, Expression)]
@@ -162,17 +184,19 @@ module Quicopt
 
   # A decision variable, owned by the +Model+ that created it.
   #
-  # +index+ is the variable's position in its model; it also fixes the canonical
-  # order of a quadratic term's two factors, so +x * y+ and +y * x+ land on the
+  # +index+ is the variable's position in its model; it also fixes the order of a
+  # quadratic term's two factors (see +order+), so +x * y+ and +y * x+ land on the
   # same coefficient.
   class Variable
     include Operators
 
     # @return [Model] the model that declared this variable
     attr_reader :model
-    # @return [String] the wire name; solutions come back keyed by it
+    # @return [String] the variable's name; solutions come back keyed by it
     attr_reader :name
-    # @return [Symbol] +:CONTINUOUS+, +:INTEGER+ or +:BINARY+
+    # @return [Symbol] +:CONTINUOUS+, +:INTEGER+, +:BINARY+, or one of the two
+    #   domains that also allow 0: +:SEMICONTINUOUS+ (0 or any value within the
+    #   bounds) and +:SEMIINTEGER+ (0 or a whole number within them)
     attr_reader :domain
     # @return [Float] the lower bound (may be +-Float::INFINITY+)
     attr_reader :lower
@@ -199,6 +223,34 @@ module Quicopt
       Expression.new(linear: { self => 1.0 })
     end
 
+    # Whether the variable is in use: 1 when its value is not 0, else 0. Made
+    # for a variable declared with +semi: true+, which is 0 or within its
+    # bounds: a delivery of either nothing or 10 to 25 units, say. A fee per
+    # delivery is then
+    #
+    #   fee * ship.active
+    #
+    # and a model that is otherwise linear stays one the service solves exactly.
+    #
+    # @return [Expression] a 0/1 expression
+    def active
+      Conditions.term(:indicator, to_expr)
+    end
+
+    # Where this variable sorts among its model's terms: before every read of a
+    # permutation or lookup table, then by +index+.
+    #
+    # @api private
+    def order
+      [0, @index]
+    end
+
+    # @return [Array<Variable>] this variable alone
+    # @api private
+    def variables
+      [self]
+    end
+
     # Identity equality, kept separate from +==+ (which builds a constraint) so
     # variables stay usable as Hash and Set keys.
     def eql?(other)
@@ -210,7 +262,7 @@ module Quicopt
       object_id.hash
     end
 
-    # @return [String] the variable's wire name
+    # @return [String] the variable's name
     def to_s
       @name
     end
@@ -221,8 +273,12 @@ module Quicopt
     end
   end
 
-  # A normalised polynomial of degree ≤ 2 over a model's variables:
-  # +constant + Σ cᵢ·xᵢ + Σ qᵢⱼ·xᵢxⱼ+.
+  # A polynomial of degree ≤ 2 over a model's variables, always kept in collected
+  # form: <tt>constant + Σ cᵢ·xᵢ + Σ qᵢⱼ·xᵢxⱼ</tt>.
+  #
+  # A value read from a permutation (<tt>route.item_at(0)</tt>) or a lookup
+  # table (<tt>dist[i, j]</tt>) counts as one factor, like a variable:
+  # +2 * dist[i, j]+ is linear, +x * dist[i, j]+ quadratic.
   #
   # Instances are immutable — every operator returns a new expression — so an
   # expression can be shared, reused and stored without aliasing surprises.
@@ -231,7 +287,8 @@ module Quicopt
 
     # @return [Float] the constant term
     attr_reader :constant
-    # @return [Hash{Variable=>Float}] linear coefficients, in insertion order
+    # @return [Hash{Variable=>Float}] linear coefficients, in insertion order.
+    #   A read of a permutation or lookup table is a key here too.
     attr_reader :linear
     # @return [Hash{Array(Variable,Variable)=>Float}] quadratic coefficients,
     #   keyed by the factor pair in model order, in insertion order
@@ -280,7 +337,7 @@ module Quicopt
       degree.zero?
     end
 
-    # @return [Expression] +self + other+
+    # @return [Expression] <tt>self + other</tt>
     def plus(other)
       Expression.new(constant: @constant + other.constant,
                      linear: Expression.merge(@linear, other.linear),
@@ -297,7 +354,7 @@ module Quicopt
                      quadratic: @quadratic.transform_values { |c| c * f })
     end
 
-    # Multiply two expressions, staying inside the degree-2 subset.
+    # Multiply two expressions, staying at degree 2 or below.
     #
     # A constant factor just scales; two linear factors expand into quadratic
     # terms. Anything else would exceed degree 2 and raises instead.
@@ -310,7 +367,8 @@ module Quicopt
 
       if degree > 1 || other.degree > 1
         raise UnsupportedExpression,
-              "product of degree #{degree} and degree #{other.degree} exceeds the quadratic subset"
+              "multiplying degree #{degree} by degree #{other.degree} gives a cubic or " \
+              "higher term; a Quicopt model is linear or quadratic"
       end
 
       quadratic = {}
@@ -326,21 +384,31 @@ module Quicopt
                      quadratic: Expression.prune(quadratic))
     end
 
-    # Every variable this expression mentions, in first-use order.
+    # Every variable this expression mentions, in first-use order — including
+    # those in the positions of a lookup table read.
     #
     # @return [Array<Variable>]
     def variables
+      factors.flat_map(&:variables).uniq
+    end
+
+    # Every factor of every term — variables and reads of permutations and lookup
+    # tables — in first-use order.
+    #
+    # @return [Array<Variable, Placement, TableEntry, Condition, Extremum>]
+    # @api private
+    def factors
       seen = @linear.keys
       @quadratic.each_key { |a, b| seen |= [a, b] }
       seen
     end
 
-    # Renders the polynomial, e.g. +3*x + 2*y - 4+.
+    # Renders the polynomial, e.g. <tt>-4 + 3\*x + 2\*y</tt>.
     def to_s
       terms = []
       terms << Format.number(@constant) unless @constant.zero?
-      @linear.each { |v, c| terms << Format.term(c, v.name) }
-      @quadratic.each { |(a, b), c| terms << Format.term(c, "#{a.name}*#{b.name}") }
+      @linear.each { |v, c| terms << Format.term(c, v.to_s) }
+      @quadratic.each { |(a, b), c| terms << Format.term(c, "#{a}*#{b}") }
       return "0" if terms.empty?
 
       terms.join(" + ").gsub(" + -", " - ")
@@ -383,23 +451,29 @@ module Quicopt
     #
     # @api private
     def self.pair(left, right)
-      (left.index <= right.index ? [left, right] : [right, left]).freeze
+      ((left.order <=> right.order) <= 0 ? [left, right] : [right, left]).freeze
     end
   end
 
   # One constraint row: a residual expression compared against zero.
   #
   # +expr+ is +lhs - rhs+, so the row is +expr <= 0+, +expr >= 0+ or +expr == 0+.
-  # The lowering in +Quicopt::Wire+ splits that into the body +f+ (the variable
-  # terms) and the numeric +bound+ (the constant, moved to the other side), which
-  # is the shape the wire's function-in-set rows take.
+  # +Quicopt::Wire+ then splits that into the body (the variable terms) and the
+  # numeric +bound+ (the constant, moved to the other side), which is the form
+  # Quicopt sends.
+  #
+  # A comparison built with +<+, +>+ or +!=+ is not a row — +Model#add+ refuses it
+  # — but it can be turned into a 0/1 expression with +Quicopt.holds+.
   class Constraint
     # The comparison operator each sense renders as.
-    SENSES = { le: "<=", ge: ">=", eq: "==" }.freeze
+    SENSES = { le: "<=", ge: ">=", eq: "==", lt: "<", gt: ">", ne: "!=" }.freeze
+    # The senses a constraint row can have.
+    ROWS = %i[le ge eq].freeze
 
     # @return [Expression] the residual +lhs - rhs+
     attr_reader :expr
-    # @return [Symbol] +:le+, +:ge+ or +:eq+
+    # @return [Symbol] +:le+, +:ge+ or +:eq+ for a row; +:lt+, +:gt+ or +:ne+ for
+    #   a comparison only +Quicopt.holds+ takes
     attr_reader :sense
 
     # Build a row from the two sides of a comparison.
@@ -448,8 +522,8 @@ module Quicopt
   #   m.maximize(3 * x + 2 * y)
   #   m.add(x + y <= 5)
   #
-  # The model is the authoring surface; +to_program+ / +encode+ lower it to the
-  # wire IR, and +Quicopt::Client#solve+ ships it.
+  # You build the model; +to_program+ / +encode+ turn it into the message the
+  # service reads, and +Quicopt::Client#solve+ sends it.
   class Model
     # @return [Array<Variable>] the declared variables, in declaration order
     attr_reader :variables
@@ -459,10 +533,25 @@ module Quicopt
     attr_reader :objective
     # @return [String] +"min"+ or +"max"+
     attr_reader :sense
+    # @return [Array<Permutation>] the declared permutations, in declaration order
+    attr_reader :permutations
+    # @return [Array<LookupTable>] the declared lookup tables, in declaration order
+    attr_reader :tables
+    # @return [Array<Partition>] the declared partitions, in declaration order
+    attr_reader :partitions
+    # @return [Array<Block>] the declared blocks, in declaration order
+    attr_reader :blocks
 
     def initialize
       @variables = []
       @by_name = {}
+      @permutations = []
+      @partitions = []
+      @tables = []
+      @blocks = []
+      @structured = {}
+      @interned = {}
+      @reads = 0
       @constraints = []
       @objective = Expression.new
       @sense = "min"
@@ -470,27 +559,46 @@ module Quicopt
 
     # Declare a continuous variable.
     #
+    # With +semi: true+ the variable is 0 or within its bounds, never in between:
+    # a shipment of either nothing or 2.5 to 8 tonnes. Such a variable is called
+    # semicontinuous. Its bounds must then be finite, and when 0 lies within them
+    # it is an ordinary variable.
+    #
     # @param lower [Numeric, nil] the lower bound; +nil+ means unbounded below
     # @param upper [Numeric, nil] the upper bound; +nil+ means unbounded above
-    # @param name [String, nil] the wire name; auto-generated when omitted
+    # @param name [String, nil] the variable's name; auto-generated when omitted
     # @param start [Numeric, nil] the starting point; defaults to 0 clamped into
-    #   the bounds, matching the other clients' front-ends
+    #   the bounds, matching the Python and Julia clients (to 0 with +semi+)
+    # @param semi [Boolean] whether the variable may also be 0
     # @return [Variable]
-    def num_var(lower = nil, upper = nil, name = nil, start: nil)
-      declare(:CONTINUOUS, lower, upper, name, start)
+    # @raise [ArgumentError] with +semi+, if a bound is missing or infinite
+    def num_var(lower = nil, upper = nil, name = nil, start: nil, semi: false)
+      declare(semi ? :SEMICONTINUOUS : :CONTINUOUS, lower, upper, name, start)
     end
 
     # Declare an integer variable.
     #
     # Bounds of exactly +[0, 1]+ declare a +:BINARY+ variable rather than an
-    # integer one — the same normalisation the other front-ends apply, so the
-    # same model reaches the service as the same IR whichever client authored it.
+    # integer one — the same rule the Python and Julia clients apply, so the same
+    # model means the same thing whichever language wrote it.
+    #
+    # With +semi: true+ the variable is 0 or a whole number within its bounds,
+    # never in between: a delivery of either nothing or 10 to 25 units. Such a
+    # variable is called semi-integer. Its bounds must then be finite.
     #
+    #   ship = m.int_var(10, 25, "ship", semi: true)   # none, or 10 to 25 units
+    #   m.minimize(2 * ship + 30 * ship.active)         # 2 per unit, 30 per delivery
+    #
+    # @param semi [Boolean] whether the variable may also be 0
     # @return [Variable]
-    def int_var(lower = nil, upper = nil, name = nil, start: nil)
+    # @raise [ArgumentError] with +semi+, if a bound is missing or infinite
+    def int_var(lower = nil, upper = nil, name = nil, start: nil, semi: false)
       lo = coerce_bound(lower, -Float::INFINITY)
       hi = coerce_bound(upper, Float::INFINITY)
-      domain = lo.zero? && hi == 1.0 ? :BINARY : :INTEGER
+      domain = if semi then :SEMIINTEGER
+               elsif lo.zero? && hi == 1.0 then :BINARY
+               else :INTEGER
+               end
       declare(domain, lo, hi, name, start)
     end
 
@@ -501,13 +609,209 @@ module Quicopt
       declare(:BINARY, 0.0, 1.0, name, start)
     end
 
-    # Look a variable up by its wire name.
+    # Look a variable up by name.
     #
     # @return [Variable, nil]
     def variable(name)
       @by_name[name.to_s]
     end
 
+    # Declare an ordering as a decision: +n_items+ items placed in as many
+    # slots, one item per slot, both numbered from 0. For a route the items are
+    # the stops and the slots are the visits, so slot 0 holds the first stop
+    # visited; for a machine the items are the jobs and the slots the positions
+    # in its queue.
+    #
+    # Five stops along a road; find the shortest route through all of them that
+    # visits stop 3 before stop 0:
+    #
+    #   position = [0, 3, 1, 4, 2]                  # km along the road, stops 0 to 4
+    #   m = Quicopt::Model.new
+    #   dist  = m.lookup_table("dist", position.map { |a| position.map { |b| (a - b).abs } })
+    #   route = m.permutation("route", 5)
+    #   route.precede(3, 0)                         # stop 3 is visited before stop 0
+    #   m.minimize((0...4).sum { |k| dist[route.item_at(k), route.item_at(k + 1)] })
+    #
+    #   result = Quicopt::Client.new(api_key: "…").solve(m)
+    #   result.objective                            # 4.0
+    #   result.structures["route"].item_at          # [3, 1, 4, 2, 0]: the stops in the order visited
+    #
+    # A model with a permutation is solved by a search, so its result has the
+    # status +"heuristic"+.
+    #
+    # @param name [String, Symbol] identifies the permutation in the result, as
+    #   +result.structures[name]+; shares one namespace with the model's variables
+    #   and lookup tables
+    # @param n_items [Integer] the number of items, at least 2
+    # @param start [Array<Integer>, nil] the arrangement the service's search
+    #   starts from: +start[i]+ is the slot of item +i+, so it holds each of
+    #   +0...n_items+ once. Left out, item +i+ starts in slot +i+.
+    # @return [Permutation]
+    # @raise [TypeError] if +n_items+ is not an Integer
+    # @raise [ArgumentError] if +n_items+ is below 2, the name is taken, or
+    #   +start+ is not an arrangement of +0...n_items+
+    def permutation(name, n_items, start: nil)
+      unless n_items.is_a?(Integer)
+        raise TypeError, "a permutation's number of items is a whole number, got #{n_items.inspect}"
+      end
+      raise ArgumentError, "a permutation has at least 2 items, got #{n_items}" if n_items < 2
+
+      nm = claim(name)
+      unless start.nil? || (start.is_a?(Array) && start.all?(Integer) && start.sort == (0...n_items).to_a)
+        raise ArgumentError, "permutation #{nm.inspect}: start must hold each of 0 to #{n_items - 1} once " \
+                             "(start[i] is the slot item i starts in)"
+      end
+      permutation = Permutation.new(self, nm, n_items, start&.dup)
+      @permutations << permutation
+      @structured[nm] = permutation
+    end
+
+    # Declare an assignment of +n_items+ items to +n_parts+ parts as a decision:
+    # which team each person joins, which truck each parcel rides in. Items and
+    # parts are both numbered from 0, and a part may stay empty.
+    #
+    # Six players of strengths 7, 5, 4, 3, 2 and 1 form a team of four and a
+    # team of two, as evenly matched as possible:
+    #
+    #   strength = [7, 5, 4, 3, 2, 1]                  # of players 0 to 5
+    #   m = Quicopt::Model.new
+    #   teams = m.partition("teams", 6, 2)             # 6 players into teams 0 and 1
+    #   total = (0...2).map { |t| (0...6).sum { |p| strength[p] * Quicopt.holds(teams.part_of(p) == t) } }
+    #   m.add(teams.size_of(0) == 4)                   # team 0 has four players
+    #   m.minimize(Quicopt.max(total[0], total[1]))
+    #
+    #   result = Quicopt::Client.new(api_key: "…").solve(m)
+    #   result.objective                               # 11.0
+    #   result.structures["teams"].part_of             # [1, 0, 1, 0, 0, 0]: players 0 and 2 form team 1
+    #
+    # @param name [String, Symbol] identifies the partition in the result, as
+    #   +result.structures[name]+; shares one namespace with the model's
+    #   variables, permutations and lookup tables
+    # @param n_items [Integer] the number of items, at least 1
+    # @param n_parts [Integer] the number of parts, at least 2
+    # @param start [Array<Integer>, nil] the assignment the service's search
+    #   starts from: +start[i]+ is the part of item +i+, one of +0...n_parts+.
+    #   Left out, item +i+ starts in part +i % n_parts+.
+    # @return [Partition]
+    # @raise [TypeError] if +n_items+ or +n_parts+ is not an Integer
+    # @raise [ArgumentError] if +n_items+ is below 1, +n_parts+ below 2, the
+    #   name is taken, or +start+ does not give each item a part
+    def partition(name, n_items, n_parts, start: nil)
+      unless n_items.is_a?(Integer)
+        raise TypeError, "a partition's number of items is a whole number, got #{n_items.inspect}"
+      end
+      unless n_parts.is_a?(Integer)
+        raise TypeError, "a partition's number of parts is a whole number, got #{n_parts.inspect}"
+      end
+      raise ArgumentError, "a partition has at least 1 item, got #{n_items}" if n_items < 1
+      raise ArgumentError, "a partition has at least 2 parts, got #{n_parts}" if n_parts < 2
+
+      nm = claim(name)
+      unless start.nil? || (start.is_a?(Array) && start.size == n_items &&
+                            start.all? { |b| b.is_a?(Integer) && b >= 0 && b < n_parts })
+        raise ArgumentError, "partition #{nm.inspect}: start gives each of the #{n_items} items a part " \
+                             "from 0 to #{n_parts - 1}"
+      end
+      partition = Partition.new(self, nm, n_items, n_parts, start&.dup)
+      @partitions << partition
+      @structured[nm] = partition
+    end
+
+    # Declare the variables of one subproblem as a block: one customer's
+    # supply, one project's staffing. The constraints over a block's own
+    # variables alone, such as that customer's demand, hold in every solution
+    # the service returns. A block changes nothing else about the model: the
+    # same solutions are feasible and the objective is the same.
+    #
+    #   supply = (0...3).map { |w| m.int_var(10, 25, "ship_#{w}", semi: true) }
+    #   m.block("customer", supply)
+    #
+    # @param name [String, Symbol] the block's name, distinct from every other
+    #   block's
+    # @param vars [Array<Variable>] its variables, each with finite bounds and in
+    #   no other block
+    # @return [Block]
+    # @raise [TypeError] if a member is not a variable
+    # @raise [ArgumentError] if the block is empty, the name is taken, a member
+    #   belongs to another model or block or has an infinite bound
+    def block(name, vars)
+      raise TypeError, "a block's name is a String or a Symbol, got #{name.inspect}" unless name.is_a?(String) || name.is_a?(Symbol)
+
+      nm = name.to_s
+      raise ArgumentError, "a block's name cannot be empty" if nm.empty?
+      raise ArgumentError, "there is already a block named #{nm.inspect}" if @blocks.any? { |b| b.name == nm }
+
+      members = Array(vars)
+      raise ArgumentError, "block #{nm.inspect} has no variables" if members.empty?
+
+      members.each_with_index do |v, k|
+        raise TypeError, "block #{nm.inspect}: a member is a variable, got #{v.class}" unless v.is_a?(Variable)
+        raise ArgumentError, "variable #{v.name.inspect} belongs to a different Quicopt::Model" unless v.model.equal?(self)
+        raise ArgumentError, "variable #{v.name.inspect} is listed twice in block #{nm.inspect}" if members[0...k].any? { |u| u.equal?(v) }
+        if (owner = @blocks.find { |b| b.variables.any? { |u| u.equal?(v) } })
+          raise ArgumentError, "variable #{v.name.inspect} is already in block #{owner.name.inspect}"
+        end
+        unless v.lower.finite? && v.upper.finite?
+          raise ArgumentError, "variable #{v.name.inspect} has bounds [#{v.lower}, #{v.upper}]; " \
+                               "a block's variables need finite bounds"
+        end
+      end
+      block = Block.new(nm, members.dup.freeze)
+      @blocks << block
+      block
+    end
+
+    # Declare a table of data that can be indexed by decisions. A model sometimes
+    # needs a number from a table at a position that is not known yet: the distance
+    # between the first and the second stop of a route whose ordering the service
+    # is still choosing, or the price of an option an integer variable picks. A
+    # Ruby array cannot be indexed this way; the table returned here can.
+    #
+    #   price  = m.lookup_table("price", [3.0, 1.0, 4.0, 1.5])
+    #   choice = m.int_var(0, 3, "choice")
+    #   m.minimize(price[choice])                   # picks option 1, at 1.0
+    #
+    # Indexing with whole numbers only gives the entry itself; indexing with an
+    # expression, such as +Permutation#item_at+ or an integer variable, gives an
+    # expression whose value is the entry at the positions the service chooses.
+    #
+    # The whole table is sent with the model, so a very large table makes the
+    # request large.
+    #
+    # @param name [String, Symbol] the table's name; shares one namespace with the
+    #   model's variables and permutations
+    # @param values [Array<Numeric>, Array<Array<Numeric>>] a vector (indexed
+    #   +table[i]+) or a matrix (<tt>table[i, j]</tt>, every row the same
+    #   length) of numbers, none of them NaN
+    # @return [LookupTable]
+    # @raise [TypeError] if +values+ is neither a vector nor a matrix of numbers
+    # @raise [ArgumentError] if it is empty, ragged or holds NaN, or the name is
+    #   taken
+    def lookup_table(name, values)
+      nm = claim(name)
+      data, shape = table_data(nm, values)
+      table = LookupTable.new(self, nm, data, shape)
+      @tables << table
+      @structured[nm] = table
+    end
+
+    # The +order+ of the next read of a permutation, partition or lookup table,
+    # or of a term that switches: after every variable, then in the order they
+    # were first made.
+    #
+    # @api private
+    def next_order
+      [1, @reads += 1]
+    end
+
+    # The term stored under +key+, built by the block on first use, so that
+    # equal terms are one object.
+    #
+    # @api private
+    def intern(key)
+      @interned[key] ||= yield
+    end
+
     # Minimize +expr+.
     #
     # @return [Expression] the objective now set
@@ -528,24 +832,31 @@ module Quicopt
     # @return [Constraint] the row just added
     # @raise [TypeError] if handed something that is not a constraint — most
     #   often a bare expression, or a comparison Ruby already reduced to a boolean
+    # @raise [ArgumentError] for a comparison with +<+, +>+ or +!=+, which no row
+    #   can express
     def add(constraint)
       unless constraint.is_a?(Constraint)
         raise TypeError,
               "add expects a constraint such as `x + y <= 5`, got #{constraint.class}"
       end
+      unless Constraint::ROWS.include?(constraint.sense)
+        raise ArgumentError,
+              "#{constraint} is not a constraint Quicopt can hold: use <=, >= or ==, " \
+              "or turn the comparison into a 0/1 expression with Quicopt.holds"
+      end
       check_ownership(constraint.expr)
       @constraints << constraint
       constraint
     end
 
-    # Lower this model to the wire IR.
+    # Turn this model into the structured message the service reads.
     #
     # @return [Quicopt::Modeler::V1::Program]
     def to_program
       Wire.program(self)
     end
 
-    # Lower this model and serialize it to wire bytes.
+    # Turn this model into the message the service reads and encode it.
     #
     # @return [String] binary protobuf bytes
     def encode
@@ -558,8 +869,18 @@ module Quicopt
       lines << "subject to" unless @constraints.empty?
       @constraints.each { |c| lines << "  #{c}" }
       @variables.each do |v|
-        lines << "  #{v.name} in #{v.domain} [#{Format.number(v.lower)}, #{Format.number(v.upper)}]"
+        range = "[#{Format.number(v.lower)}, #{Format.number(v.upper)}]"
+        range = "{0} ∪ #{range}" if %i[SEMICONTINUOUS SEMIINTEGER].include?(v.domain)
+        lines << "  #{v.name} in #{v.domain} #{range}"
       end
+      @permutations.each do |p|
+        rules = p.precedences.map { |a, b| "#{a} before #{b}" }
+        rules = rules.empty? ? "" : ", with #{rules.join(', ')}"
+        lines << "  #{p.name} is an ordering of items 0 to #{p.n_items - 1}#{rules}"
+      end
+      @partitions.each { |p| lines << "  #{p.name} puts items 0 to #{p.n_items - 1} in parts 0 to #{p.n_parts - 1}" }
+      @tables.each { |t| lines << "  #{t.name} is a #{t.shape.join(' × ')} lookup table" }
+      @blocks.each { |b| lines << "  #{b.name} is a block of #{b.variables.join(', ')}" }
       lines.join("\n")
     end
 
@@ -575,8 +896,15 @@ module Quicopt
       hi = coerce_bound(upper, Float::INFINITY)
       raise ArgumentError, "lower bound #{lo} exceeds upper bound #{hi}" if lo > hi
 
+      semi = %i[SEMICONTINUOUS SEMIINTEGER].include?(domain)
+      if semi && !(lo.finite? && hi.finite?)
+        raise ArgumentError, "a variable that is 0 or in [#{lo}, #{hi}] needs finite bounds"
+      end
+      start = 0.0 if semi && start.nil?
+
       nm = name.nil? ? auto_name : name.to_s
       raise ArgumentError, "duplicate variable name #{nm.inspect}" if @by_name.key?(nm)
+      raise ArgumentError, "the name #{nm.inspect} is already declared on this model" if @structured.key?(nm)
 
       variable = Variable.new(self, nm, domain, lo, hi, coerce_start(start, lo, hi), @variables.size)
       @variables << variable
@@ -591,8 +919,8 @@ module Quicopt
       value.to_f
     end
 
-    # 0 clamped into the bounds — finite for any bounds, matching the sibling
-    # front-ends so an unset start lowers identically across clients.
+    # 0 clamped into the bounds — finite for any bounds, matching the Python and
+    # Julia clients so an unset start comes out the same everywhere.
     def coerce_start(start, lower, upper)
       return [[0.0, lower].max, upper].min if start.nil?
       raise ArgumentError, "start must be a number, got #{start.class}" unless start.is_a?(Numeric)
@@ -601,9 +929,53 @@ module Quicopt
     end
 
     def auto_name
-      n = @variables.size + 1
-      n += 1 while @by_name.key?("x#{n}")
-      "x#{n}"
+      number = @variables.size + 1
+      number += 1 while @by_name.key?("x#{number}") || @structured.key?("x#{number}")
+      "x#{number}"
+    end
+
+    # +name+ as a String, checked to be free among the model's variables,
+    # permutations and lookup tables: on the wire one name must mean one thing.
+    def claim(name)
+      unless name.is_a?(String) || name.is_a?(Symbol)
+        raise TypeError, "a name is a String or a Symbol, got #{name.inspect}"
+      end
+
+      nm = name.to_s
+      raise ArgumentError, "a name cannot be empty" if nm.empty?
+      if @by_name.key?(nm) || @structured.key?(nm)
+        raise ArgumentError, "the name #{nm.inspect} is already declared on this model"
+      end
+
+      nm
+    end
+
+    # A table's entries as frozen Floats, and its shape.
+    def table_data(name, values)
+      raise TypeError, "lookup table #{name.inspect}: values is an Array, got #{values.class}" unless values.is_a?(Array)
+      raise ArgumentError, "lookup table #{name.inspect} has no entries" if values.empty?
+
+      if values.all?(Numeric)
+        data = values.map(&:to_f)
+        shape = [data.size]
+        flat = data
+      elsif values.all?(Array)
+        unless values.all? { |row| row.all?(Numeric) }
+          raise TypeError, "lookup table #{name.inspect}: a matrix holds numbers only"
+        end
+        if values.first.empty? || values.any? { |row| row.size != values.first.size }
+          raise ArgumentError, "lookup table #{name.inspect}: every row of a matrix has the same, " \
+                               "nonzero number of entries"
+        end
+        data = values.map { |row| row.map(&:to_f).freeze }
+        shape = [data.size, data.first.size]
+        flat = data.flatten
+      else
+        raise TypeError, "lookup table #{name.inspect}: values is a vector or a matrix of numbers"
+      end
+      raise ArgumentError, "lookup table #{name.inspect} holds NaN" if flat.any?(&:nan?)
+
+      [data.freeze, shape]
     end
 
     def set_objective(expr, sense)
@@ -614,14 +986,38 @@ module Quicopt
       objective
     end
 
-    # Reject variables belonging to another model: their names would collide
-    # arbitrarily and their coefficients would silently merge on the wire.
+    # Reject variables, permutations and tables belonging to another model: their
+    # names would collide arbitrarily and their coefficients would silently merge
+    # on the wire.
     def check_ownership(expr)
-      expr.variables.each do |v|
-        next if v.model.equal?(self)
+      expr.factors.each do |f|
+        next if f.model.equal?(self)
 
-        raise ArgumentError, "variable #{v.name.inspect} belongs to a different Quicopt::Model"
+        what = f.is_a?(Variable) ? "variable #{f.name.inspect}" : f.to_s
+        raise ArgumentError, "#{what} belongs to a different Quicopt::Model"
       end
     end
   end
+
+  # The variables of one subproblem, declared with +Model#block+.
+  class Block
+    # @return [String] the block's name
+    attr_reader :name
+    # @return [Array<Variable>] its variables, in the order given
+    attr_reader :variables
+
+    # Declared with +Model#block+, not built directly.
+    #
+    # @api private
+    def initialize(name, variables)
+      @name = name
+      @variables = variables
+      freeze
+    end
+
+    # @return [String] name and members
+    def inspect
+      "#<Quicopt::Block #{@name}: #{@variables.join(', ')}>"
+    end
+  end
 end