quicopt 0.1.0 → 0.3.0

data/lib/quicopt/client.rb

@@ -11,11 +11,11 @@ require "zlib"
 
 # quicopt/client — talk to the Quicopt service over HTTP.
 #
-# Encode a model to wire bytes (+Quicopt::Wire+), POST it, read the result back.
-# Transport is stdlib +net/http+, so the gem's only runtime dependency stays
-# +google-protobuf+. The request body is the versioned wire bytes; the response is
-# the service's result JSON (+status+ / +objective+ / +solution+ / a
-# ready-to-print +display+ / …). The first keyless call mints an API key, returned
+# Encode a model (+Quicopt::Wire+), POST it, read the result back. Requests go
+# out over stdlib +net/http+, so the gem's only runtime dependency stays
+# +google-protobuf+. The request body is the encoded model; the response is the
+# service's result JSON (+status+ / +objective+ / +solution+ / a ready-to-print
+# +display+ / …). The first keyless call mints an API key, returned
 # in the +X-Quicopt-Api-Key+ response header; it is cached at
 # +$XDG_CACHE_HOME/quicopt/free_key+ and replayed as +Authorization: Bearer+ on
 # every later call — including from a later *process*, so one caller keeps one key
@@ -28,26 +28,51 @@ require "zlib"
 #
 # A non-2xx response raises +QuicoptError+, carrying the service's stable +reason+
 # code and the framed +display+ text.
+#
+# The service decides how long a solve may run unless the call passes
+# +time_limit:+, which rides the query string like +project:+. The service grants
+# at most its own maximum and reports both numbers in +solver_data+; the client
+# warns when it granted less, and waits on the socket (or polls) long enough for
+# the time it asked for.
 module Quicopt
   # The public Quicopt free-tier endpoint a +Client+ targets when no +base_url+
   # is given. Mirrors the Python and Julia clients' default, so every client
   # reaches the same server out of the box.
   DEFAULT_BASE_URL = "https://try.quicoptapi.pgi.fz-juelich.de"
 
-  # The modelling front-end this client authors with, sent as the
-  # +source_language+ call tag. It names the *front-end*, not the language — the
-  # Ruby DSL is one front-end among the clients' several (+jump+, +pyomo+,
-  # +pulp+, +mathopt+), so it carries its own name here.
+  # The modelling library a model was written in, sent as the +source_language+
+  # call tag. It names the *library*, not the programming language — the service
+  # also sees +jump+, +pyomo+, +pulp+ and +mathopt+ — so this gem's own DSL
+  # carries its own name here.
   SOURCE_LANGUAGE = "quicopt-ruby"
 
+  # How long a request may take beyond the solve itself — waiting in the queue,
+  # reading the model, writing the answer — before the client stops waiting on a
+  # solve whose time limit it set.
+  WAIT_MARGIN = 60.0
+
+  # The arrangement the service found for one permutation (see
+  # +Model#permutation+), both ways round and counted from 0: +item_at[k]+ is the
+  # item in slot +k+ — for a route, the stops in the order visited — and
+  # +slot_of[i]+ the slot of item +i+.
+  Arrangement = Data.define(:item_at, :slot_of)
+
+  # The assignment the service found for one partition (see +Model#partition+),
+  # parts counted from 0: +part_of[i]+ is the part of item +i+ and +size_of[b]+
+  # the number of items in part +b+.
+  Grouping = Data.define(:part_of, :size_of)
+
   # A finished solve, parsed from the service's result JSON.
   #
-  # +objective+ and +feasible+ are +nil+ when the class or outcome leaves them
-  # undefined (an unconstrained heuristic, or no incumbent). +display+ is the
-  # framed, ready-to-print summary the service renders for every backend alike —
-  # print it rather than formatting your own.
+  # +objective+ and +feasible+ are +nil+ where the outcome leaves them undefined —
+  # a model with nothing to feasibility-check, or a run that found no solution.
+  # +display+ is the framed, ready-to-print summary the service renders the same
+  # way for every kind of model — print it rather than formatting your own.
+  # +structures+ holds the +Arrangement+ of each permutation and the +Grouping+
+  # of each partition the model declares, by name, and is empty for a model with
+  # none.
   Result = Data.define(:job_id, :status, :objective, :feasible, :solution,
-                       :solve_time_seconds, :solver_data, :display) do
+                       :solve_time_seconds, :solver_data, :display, :structures) do
     # Build a +Result+ from the service's decoded result JSON.
     #
     # Missing optional keys default rather than raise, so a partial result (e.g.
@@ -63,10 +88,43 @@ module Quicopt
           solution: body["solution"] || {},
           solve_time_seconds: body["solve_time_seconds"] || 0.0,
           solver_data: body["solver_data"] || {},
-          display: body["display"].to_s)
+          display: body["display"].to_s,
+          structures: (body["structures"] || {}).transform_values { |s| arrangement(s) })
+    end
+
+    # One structure's value from the result JSON, where items, slots and parts
+    # count from 1: a permutation's +Arrangement+, a partition's +Grouping+, or
+    # +nil+ when none came back.
+    #
+    # @api private
+    def self.arrangement(json)
+      return nil if json.nil?
+      if json.key?("part_of")
+        return Grouping.new(part_of: json["part_of"].map { |b| b.to_i - 1 },
+                            size_of: json["size_of"].map(&:to_i))
+      end
+
+      Arrangement.new(item_at: json["item_at"].map { |i| i.to_i - 1 },
+                      slot_of: json["slot_of"].map { |k| k.to_i - 1 })
+    end
+
+    # Warn when the service ran this solve for less time than its +time_limit+
+    # asked for. The service grants at most its maximum and reports what was
+    # asked and what it granted side by side in +solver_data+.
+    #
+    # @return [Result] +self+
+    # @api private
+    def warn_if_lowered
+      asked = solver_data["time_limit_s"]
+      granted = solver_data["time_budget_s"]
+      if asked && granted && granted < asked
+        warn "quicopt: the service ran this solve for #{Format.number(granted.to_f)} s, not the " \
+             "#{Format.number(asked.to_f)} s asked for: #{Format.number(granted.to_f)} s is the most it grants"
+      end
+      self
     end
 
-    # The class the service routed the model to (+LP+/+MILP+/+QUBO+/…), or +nil+
+    # The kind of model the service recognised (+LP+/+MILP+/+QUBO+/…), or +nil+
     # if it did not report one.
     #
     # @return [String, nil]
@@ -125,7 +183,7 @@ module Quicopt
       "DELETE" => Net::HTTP::Delete
     }.freeze
 
-    # The content type of a request body: the wire bytes are opaque binary.
+    # The content type of a request body: an encoded model is opaque binary.
     OCTET_STREAM = "application/octet-stream"
 
     # @return [String] the service base URL, without a trailing slash
@@ -165,19 +223,34 @@ module Quicopt
     # Solve +model+ synchronously, blocking until the result returns.
     #
     # @param model [Quicopt::Model, Quicopt::Wire::PB::Program, String] a model —
-    #   lowered and encoded here — or a +Program+ / pre-encoded wire bytes if you
-    #   built them yourself
+    #   encoded here — or a +Program+ / already-encoded bytes if you built them
+    #   yourself
     # @param project [String, nil] an optional project tag, so calls on one key
     #   can be invoiced per project. Sent as a query param, never baked into the
     #   model.
+    # @param time_limit [Numeric, nil] how many seconds the solve may run, in
+    #   place of the time the service would choose. A solver that proves its
+    #   answer sooner stops sooner; a search, which cannot prove it is done, runs
+    #   for all of it. The service grants at most its maximum (120 s on the free
+    #   tier), and a warning says so when it granted less. The client waits for
+    #   the answer at least this long plus a minute.
     # @param config [Hash, nil] optional service parameters, sent as the query
     #   string
     # @param gzip [Boolean] gzip-compress the request body
     # @return [Result]
     # @raise [QuicoptError] on a non-2xx response
-    def solve(model, project: nil, config: nil, gzip: false)
+    # @raise [TypeError] if +time_limit+ is not a number
+    # @raise [ArgumentError] if +time_limit+ is not positive and finite
+    #
+    # @example Give a search half a minute
+    #   result = client.solve(m, time_limit: 30)
+    #   result.solver_data["time_budget_s"]   # => 30.0
+    def solve(model, project: nil, time_limit: nil, config: nil, gzip: false)
+      time_limit = Client.check_time_limit(time_limit)
+      wait = time_limit.nil? ? @timeout : [@timeout, time_limit + WAIT_MARGIN].max
       Result.from_json(request("POST", "/v1/solve", to_wire(model),
-                               config: meta_config(model, project, config), gzip: gzip))
+                               config: meta_config(model, project, time_limit, config),
+                               gzip: gzip, timeout: wait)).warn_if_lowered
     end
 
     # Submit +model+ for asynchronous solving and return a handle to poll.
@@ -185,13 +258,39 @@ module Quicopt
     # Use this for the first call against a freshly-booted server: the worker
     # warms up before claiming, which can time out a cold synchronous call.
     #
+    # +time_limit+ works as for +solve+; +Job#result+ then polls at least that
+    # long plus a minute by default.
+    #
     # @return [Job] a handle to the queued job; call +Job#result+ to await it
     # @raise [QuicoptError] on a non-2xx response
-    def submit(model, project: nil, config: nil, gzip: false)
+    # @raise [TypeError] if +time_limit+ is not a number
+    # @raise [ArgumentError] if +time_limit+ is not positive and finite
+    def submit(model, project: nil, time_limit: nil, config: nil, gzip: false)
+      time_limit = Client.check_time_limit(time_limit)
       body = request("POST", "/v1/jobs", to_wire(model),
-                     config: meta_config(model, project, config), gzip: gzip)
+                     config: meta_config(model, project, time_limit, config), gzip: gzip)
       remember(body["api_key"]) # /v1/jobs echoes a minted key in the 202 body too
-      Job.new(self, body["job_id"])
+      Job.new(self, body["job_id"], time_limit)
+    end
+
+    # Check a time limit before it is sent.
+    #
+    # @param time_limit [Numeric, nil] seconds, or +nil+ to leave the choice to
+    #   the service
+    # @return [Float, nil]
+    # @raise [TypeError] if it is not a number
+    # @raise [ArgumentError] if it is not positive and finite
+    # @api private
+    def self.check_time_limit(time_limit)
+      return nil if time_limit.nil?
+      raise TypeError, "time_limit is a number of seconds, got #{time_limit.inspect}" unless time_limit.is_a?(Numeric)
+
+      seconds = time_limit.to_f
+      unless seconds.finite? && seconds.positive?
+        raise ArgumentError, "time_limit is a positive, finite number of seconds, got #{time_limit}"
+      end
+
+      seconds
     end
 
     # Perform one HTTP request, retrying once if a *cached* key is rejected.
@@ -209,13 +308,13 @@ module Quicopt
     # @return [String] the raw response body
     # @raise [QuicoptError] on a non-2xx response
     # @api private
-    def request_raw(method, path, data = nil, config: nil, gzip: false)
-      attempt(method, path, data, config: config, gzip: gzip)
+    def request_raw(method, path, data = nil, config: nil, gzip: false, timeout: nil)
+      attempt(method, path, data, config: config, gzip: gzip, timeout: timeout)
     rescue QuicoptError => e
       raise unless e.status_code == 401 && @from_cache
 
       discard_key
-      attempt(method, path, data, config: config, gzip: gzip)
+      attempt(method, path, data, config: config, gzip: gzip, timeout: timeout)
     end
 
     # Perform one HTTP request and return the raw response body.
@@ -223,12 +322,13 @@ module Quicopt
     # Sets the octet-stream content type (and gzip encoding, if requested) for a
     # body, attaches the bearer key when known, and captures a freshly minted key
     # off the response — including from an error response, since a 502/504 on a
-    # first call may still have minted one.
+    # first call may still have minted one. +timeout+ replaces the client's socket
+    # timeout for this one request.
     #
     # @return [String] the raw response body
     # @raise [QuicoptError] on a non-2xx response
     # @api private
-    def attempt(method, path, data = nil, config: nil, gzip: false)
+    def attempt(method, path, data = nil, config: nil, gzip: false, timeout: nil)
       uri = URI.parse(@base_url + path + Client.query(config))
       request_class = REQUESTS.fetch(method) { raise ArgumentError, "unsupported method #{method}" }
       req = request_class.new(uri)
@@ -242,7 +342,7 @@ module Quicopt
       end
       req["Authorization"] = "Bearer #{@api_key}" if @api_key
 
-      resp = http(uri).start { |conn| conn.request(req) }
+      resp = http(uri, timeout || @timeout).start { |conn| conn.request(req) }
       capture_key(resp) # a 502/504 on a first call still minted a key
       raise QuicoptError.new(resp.code.to_i, Client.decode(resp.body)) unless resp.is_a?(Net::HTTPSuccess)
 
@@ -359,43 +459,45 @@ module Quicopt
 
     private
 
-    def http(uri)
+    def http(uri, timeout)
       conn = Net::HTTP.new(uri.host, uri.port)
       conn.use_ssl = uri.scheme == "https"
-      conn.open_timeout = @timeout
-      conn.read_timeout = @timeout
-      conn.write_timeout = @timeout
+      conn.open_timeout = timeout
+      conn.read_timeout = timeout
+      conn.write_timeout = timeout
       conn
     end
 
-    # Coerce to wire bytes: pre-encoded bytes pass through, a +Program+ is
-    # encoded, and a +Model+ is lowered then encoded — so a caller solves the
-    # *model*, never a hand-built +Program+.
+    # Coerce to encoded bytes: bytes pass through, a +Program+ is encoded, and a
+    # +Model+ becomes a +Program+ and is encoded — so a caller solves the *model*,
+    # never a hand-built +Program+.
     def to_wire(model)
       case model
       when Model, Wire::PB::Program then Wire.encode(model)
       when String then model
       else
-        raise TypeError, "cannot solve a #{model.class}: pass a Quicopt::Model, a Program, or wire bytes"
+        raise TypeError,
+              "cannot solve a #{model.class}: pass a Quicopt::Model, a Program, or encoded bytes"
       end
     end
 
-    # The modelling front-end that authored +model+, or +nil+ for a hand-built
-    # +Program+ / pre-encoded bytes, which have no front-end to attribute.
+    # The modelling library that wrote +model+, or +nil+ for a hand-built
+    # +Program+ / raw bytes, which have none to attribute.
     def source_language(model)
       SOURCE_LANGUAGE if model.is_a?(Model)
     end
 
-    # Merge the per-call metadata tags into the request config (sent as query
-    # params): the front-end tag, unless the caller already set one, and the
-    # optional project id. The model is unchanged — these ride the query string,
-    # not the wire bytes.
-    def meta_config(model, project, config)
+    # Merge the per-call tags into the request config (sent as query params): the
+    # modelling-library tag, unless the caller already set one, the optional
+    # project id and the optional time limit. The model is unchanged — these ride
+    # the query string, not the encoded model.
+    def meta_config(model, project, time_limit, config)
       meta = {}
       (config || {}).each { |k, v| meta[k.to_s] = v }
       src = source_language(model)
       meta["source_language"] = src if src && !meta.key?("source_language")
       meta["project_id"] = project if project
+      meta["time_limit"] = time_limit if time_limit
       meta
     end
 
@@ -445,10 +547,13 @@ module Quicopt
     attr_reader :client
     # @return [String] the server-assigned job id
     attr_reader :job_id
+    # @return [Float, nil] the time limit the job was submitted with, if any
+    attr_reader :time_limit
 
-    def initialize(client, job_id)
+    def initialize(client, job_id, time_limit = nil)
       @client = client
       @job_id = job_id
+      @time_limit = time_limit
     end
 
     # Fetch the job's metadata and framed log tail.
@@ -463,15 +568,17 @@ module Quicopt
     #
     # @param wait [Boolean] poll past the service's +not_done+ reason until the
     #   worker finishes; when +false+, fetch once
-    # @param timeout [Numeric] maximum time to poll, in seconds
+    # @param timeout [Numeric, nil] maximum time to poll, in seconds. Defaults to
+    #   120 s, or the job's +time_limit+ plus a minute when that is longer.
     # @param poll [Numeric] delay between polls, in seconds
     # @return [Result]
     # @raise [QuicoptError] if +wait+ is false and the job is not yet done, on any
     #   non-+not_done+ error, or once +timeout+ elapses
-    def result(wait: true, timeout: 120.0, poll: 0.5)
+    def result(wait: true, timeout: nil, poll: 0.5)
+      timeout ||= @time_limit.nil? ? 120.0 : [120.0, @time_limit + WAIT_MARGIN].max
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       loop do
-        return Result.from_json(@client.request("GET", "/v1/jobs/#{@job_id}/result"))
+        return Result.from_json(@client.request("GET", "/v1/jobs/#{@job_id}/result")).warn_if_lowered
       rescue QuicoptError => e
         raise if !wait || e.reason != "not_done"
         raise if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline

data/lib/quicopt/indicators.rb

@@ -0,0 +1,235 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: (c) 2026 Tim Bode, PGI-12, Forschungszentrum Jülich
+# frozen_string_literal: true
+
+# quicopt/indicators — terms that switch: whether a variable is in use
+# (+Variable#active+), whether a comparison holds (+Quicopt.holds+), and the
+# smaller or larger of several expressions (+Quicopt.min+, +Quicopt.max+).
+#
+# None of them is a polynomial, and each enters an +Expression+ the way a read of
+# a permutation does (+quicopt/structured+): as one factor of degree 1, a key of
+# the expression's linear terms. So +fee * x.active+ is linear, +q * x.active+
+# quadratic, and the degree check stays exact.
+#
+# Factors are interned per model — asking twice for the same term returns the
+# same object — so +x.active - x.active+ cancels and two equal terms meet on one
+# coefficient. A comparison is mapped to its 0/1 form once, in +Quicopt.holds+,
+# the same mapping as the R client's +holds()+:
+#
+#   a <= b  ⇒  step(b − a + tol)          a >= b  ⇒  step(a − b + tol)
+#   a <  b  ⇒  1 − step(a − b − tol)      a >  b  ⇒  1 − step(b − a − tol)
+#   a == b  ⇒  1 − indicator(a − b)       a != b  ⇒  indicator(a − b)
+#
+# where +step(e)+ is 1 when +e ≥ 0+ and +indicator(e)+ is 1 when +e ≠ 0+; with a
+# tolerance, +==+ and +!=+ compare +|a − b|+ against it instead.
+
+module Quicopt
+  class << self
+    # 1 where the comparison holds and 0 where it does not, as an expression the
+    # service evaluates at the values it chooses. Its main use is a cost or a
+    # discount that applies once a total crosses a level: a warehouse's opening
+    # fee, due once it ships anything, is
+    #
+    #   opening_fee * Quicopt.holds(shipped >= 1)
+    #
+    # and a discount of 30 from 60 units on is +-30 * Quicopt.holds(shipped >= 60)+.
+    #
+    # @param comparison [Constraint] built with +<=+, +>=+, +<+, +>+, +==+ or
+    #   +!=+ between expressions, such as +shipped >= 60+
+    # @param tol [Numeric] how far a comparison may miss and still count as
+    #   holding: +a >= b+ holds from +a = b − tol+ on, +a > b+ from +a > b + tol+.
+    #   Non-negative.
+    # @return [Expression] a 0/1 expression; a number when the comparison
+    #   involves no decision
+    # @raise [TypeError] if +comparison+ is not a comparison — often one Ruby
+    #   already reduced to +true+ or +false+ because both sides were numbers
+    # @raise [ArgumentError] if +tol+ is negative, or the two sides belong to
+    #   different models
+    def holds(comparison, tol: 0.0)
+      unless comparison.is_a?(Constraint)
+        raise TypeError, "holds takes a comparison such as `x >= 3`, got #{comparison.inspect}"
+      end
+      raise ArgumentError, "tol is a non-negative number, got #{tol.inspect}" unless tol.is_a?(Numeric) && tol >= 0
+
+      Conditions.holds(comparison.expr, comparison.sense, tol.to_f)
+    end
+
+    # The smallest of the given expressions, as an expression the service
+    # evaluates. +fee * Quicopt.min(1, a.active + b.active)+ is a fee that is due
+    # once, however many of +a+ and +b+ are in use.
+    #
+    # @param args [Array<Expression, Variable, Numeric>] at least two
+    # @return [Expression] a number when every argument is one
+    # @raise [ArgumentError] on fewer than two arguments, or arguments from
+    #   different models
+    def min(*args)
+      Extremum.build(:min, args)
+    end
+
+    # The largest of the given expressions, as an expression the service
+    # evaluates.
+    #
+    # @param args [Array<Expression, Variable, Numeric>] at least two
+    # @return [Expression] a number when every argument is one
+    # @raise [ArgumentError] on fewer than two arguments, or arguments from
+    #   different models
+    def max(*args)
+      Extremum.build(:max, args)
+    end
+  end
+
+  # The mapping from a comparison to its 0/1 form, and the model a term belongs
+  # to.
+  #
+  # @api private
+  module Conditions
+    module_function
+
+    # +residual+ is +lhs − rhs+; the result follows the table in this file's
+    # header.
+    def holds(residual, sense, tol)
+      return Expression.new(constant: truth(residual.constant, sense, tol) ? 1.0 : 0.0) if residual.constant?
+
+      negated = residual.scale(-1.0)
+      case sense
+      when :le then term(:step, negated.plus(Expression.new(constant: tol)))
+      when :ge then term(:step, residual.plus(Expression.new(constant: tol)))
+      when :lt then one_minus(term(:step, residual.plus(Expression.new(constant: -tol))))
+      when :gt then one_minus(term(:step, negated.plus(Expression.new(constant: -tol))))
+      when :eq then tol.positive? ? term(:near, residual, tol) : one_minus(term(:indicator, residual))
+      when :ne then tol.positive? ? one_minus(term(:near, residual, tol)) : term(:indicator, residual)
+      end
+    end
+
+    # Whether a comparison between two numbers (+value = lhs − rhs+) holds.
+    def truth(value, sense, tol)
+      case sense
+      when :le then -value + tol >= 0
+      when :ge then value + tol >= 0
+      when :lt then (value - tol).negative?
+      when :gt then (-value - tol).negative?
+      when :eq then tol.positive? ? value.abs <= tol : value.zero?
+      when :ne then tol.positive? ? value.abs > tol : !value.zero?
+      end
+    end
+
+    # The interned +Condition+ +op+ over +argument+, as an expression.
+    def term(op, argument, tol = 0.0)
+      model = owner(argument.factors)
+      key = [:condition, op, argument_key(argument), tol]
+      Expression.new(linear: { model.intern(key) { Condition.new(model, op, argument, tol, model.next_order) } => 1.0 })
+    end
+
+    # +1 − e+.
+    def one_minus(expr)
+      Expression.new(constant: 1.0).plus(expr.scale(-1.0))
+    end
+
+    # The one model every factor in +factors+ belongs to.
+    #
+    # @raise [ArgumentError] if they belong to more than one
+    def owner(factors)
+      models = factors.map(&:model).uniq(&:object_id)
+      raise ArgumentError, "the terms of one expression belong to different Quicopt::Models" if models.size > 1
+
+      models.first
+    end
+
+    # An expression as an interning key: its constant and its terms in model
+    # order. Factors are interned, so they key by identity.
+    def argument_key(expr)
+      [expr.constant, expr.linear.sort_by { |f, _| f.order }, expr.quadratic.sort_by { |(a, b), _| [a.order, b.order] }]
+    end
+  end
+
+  # A 0/1 term: +indicator(e)+ (1 when +e ≠ 0+), +step(e)+ (1 when +e ≥ 0+) or
+  # the near test +step(tol − |e|)+. One factor of an +Expression+.
+  #
+  # @api private
+  class Condition
+    # @return [Model]
+    attr_reader :model
+    # @return [Symbol] +:indicator+, +:step+ or +:near+
+    attr_reader :op
+    # @return [Expression] the expression tested
+    attr_reader :argument
+    # @return [Float] the tolerance of +:near+, 0 otherwise
+    attr_reader :tol
+    # @return [Array] where this term sorts among a model's terms
+    attr_reader :order
+
+    def initialize(model, op, argument, tol, order)
+      @model = model
+      @op = op
+      @argument = argument
+      @tol = tol
+      @order = order
+      freeze
+    end
+
+    # @return [Array<Variable>] the variables the tested expression mentions
+    def variables
+      @argument.variables
+    end
+
+    # @return [String] the term as sent, e.g. +step(x + y - 1)+; the indicator of
+    #   a bare variable reads +x.active+
+    def to_s
+      bare = @argument.constant.zero? && @argument.quadratic.empty? && @argument.linear.size == 1 &&
+             @argument.linear.first[0].is_a?(Variable) && @argument.linear.first[1] == 1.0
+      case @op
+      when :indicator then bare ? "#{@argument}.active" : "indicator(#{@argument})"
+      when :step then "step(#{@argument})"
+      when :near then "step(#{Format.number(@tol)} - |#{@argument}|)"
+      end
+    end
+  end
+
+  # The smaller or the larger of several expressions. One factor of an
+  # +Expression+.
+  #
+  # @api private
+  class Extremum
+    # @return [Model]
+    attr_reader :model
+    # @return [Symbol] +:min+ or +:max+
+    attr_reader :op
+    # @return [Array<Expression>] the arguments, in the order given
+    attr_reader :args
+    # @return [Array] where this term sorts among a model's terms
+    attr_reader :order
+
+    # The interned +op+ over +args+ as an expression, or the number itself when
+    # every argument is one.
+    def self.build(op, args)
+      raise ArgumentError, "#{op} takes at least two arguments, got #{args.size}" if args.size < 2
+
+      exprs = args.map { |a| Expression.cast(a) }
+      if exprs.all?(&:constant?)
+        values = exprs.map(&:constant)
+        return Expression.new(constant: op == :min ? values.min : values.max)
+      end
+      model = Conditions.owner(exprs.flat_map(&:factors))
+      key = [:extremum, op, exprs.map { |e| Conditions.argument_key(e) }]
+      Expression.new(linear: { model.intern(key) { new(model, op, exprs.freeze, model.next_order) } => 1.0 })
+    end
+
+    def initialize(model, op, args, order)
+      @model = model
+      @op = op
+      @args = args
+      @order = order
+      freeze
+    end
+
+    # @return [Array<Variable>] the variables the arguments mention
+    def variables
+      @args.flat_map(&:variables).uniq
+    end
+
+    # @return [String] the term as written, e.g. +min(1, a.active + b.active)+
+    def to_s
+      "#{@op}(#{@args.join(', ')})"
+    end
+  end
+end