quicopt 0.1.0 → 0.4.0

data/lib/quicopt/client.rb

@@ -11,15 +11,13 @@ 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
-# 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
-# rather than minting a fresh one per run.
+# 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+ / …). Every request carries your API key as
+# <tt>Authorization: Bearer</tt>. Register at https://quicopt.com/signup to
+# receive one by email.
 #
 # Two entry points mirror the two service endpoints:
 #
@@ -28,26 +26,50 @@ 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 Quicopt service a +Client+ targets when no +base_url+ is given. The
+  # Python, Julia and R clients default to the same address.
+  DEFAULT_BASE_URL = "https://quicoptapi.pgi.fz-juelich.de"
+
+  # 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,11 +85,45 @@ 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+
-    # if it did not report one.
+    # The kind of model the service recognised
+    # (<tt>LP</tt>/<tt>MILP</tt>/<tt>QUBO</tt>/…), or +nil+ if it did not report
+    # one.
     #
     # @return [String, nil]
     def model_class
@@ -77,7 +133,7 @@ module Quicopt
 
   # A non-2xx service response.
   #
-  # +reason+ is the service's stable snake_case code (+size_exceeded+,
+  # +reason+ is the service's stable snake_case code (<tt>size_exceeded</tt>,
   # +unsupported_model+, +quota_exhausted+, +not_done+, +too_many_inflight+,
   # +queue_full+, +parse_error+, …) — match on it, not on the message. +display+
   # is the framed text to print; +status_code+ the HTTP status.
@@ -100,23 +156,27 @@ module Quicopt
     end
   end
 
-  # Environment variable overriding where the free key is cached. Point it at
-  # durable storage in an environment whose home directory does not survive the
-  # run (CI, containers), where the default location is wiped between sessions
-  # and every run would otherwise mint a fresh key.
+  # Environment variable a +Client+ reads its API key from when none is passed.
+  # It keeps the key out of your code.
+  API_KEY_ENV = "QUICOPT_API_KEY"
+
+  # Environment variable overriding where the client saves a key the server
+  # issued itself. A server that gives a caller without a key a new one on the
+  # first call has the client save that key and reuse it in later runs. Point the
+  # variable at durable storage where the home directory does not survive the
+  # run (CI, containers).
   KEY_PATH_ENV = "QUICOPT_KEY_PATH"
 
-  # A connection to a Quicopt service at +base_url+ — the public free tier
-  # (+DEFAULT_BASE_URL+) unless another URL is given.
+  # A connection to a Quicopt service at +base_url+, by default
+  # <tt>DEFAULT_BASE_URL</tt>.
   #
-  # The client holds the API key: pass a known one, or let the first keyless call
-  # mint one — which is then cached on disk and reused by later runs, so one
-  # caller keeps one key.
+  # The client holds your API key: the one passed as +api_key:+, else the one in
+  # the environment variable <tt>QUICOPT_API_KEY</tt>. Register at
+  # https://quicopt.com/signup to receive a key by email.
   #
-  #   client = Quicopt::Client.new
+  #   client = Quicopt::Client.new(api_key: "…")   # the key from your sign-up email
   #   result = client.solve(model)
   #   puts result.display
-  #   client.api_key   # => the key the first call minted (and cached)
   class Client
     # The HTTP methods this client issues, and the request class for each.
     REQUESTS = {
@@ -125,36 +185,43 @@ 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
     attr_reader :base_url
-    # @return [String, nil] the API key in use; set on the first mint
+    # @return [String, nil] the API key in use
     attr_accessor :api_key
     # @return [Float] the per-request socket timeout, in seconds
     attr_accessor :timeout
-    # @return [Pathname] where the free key is cached
+    # @return [Pathname] where a key the server issued is saved
     attr_reader :key_path
 
     # Bind a client to a service endpoint.
     #
     # @param base_url [String] the service base URL; a trailing slash is stripped
-    # @param api_key [String, nil] a known API key, or +nil+ to reuse the cached
-    #   free key (minting one on the first keyless call). A key passed here is
-    #   used as-is and never written to the cache, so authenticating with a key
-    #   you already hold cannot clobber the free key of whoever runs the code.
+    # @param key [String, nil] your API key, given as the second argument; the
+    #   same as +api_key:+
+    # @param api_key [String, nil] your API key. When +nil+, the client reads the
+    #   key from the environment variable <tt>QUICOPT_API_KEY</tt>, and failing
+    #   that uses a key saved by an earlier run (see +key_path:+). A key passed
+    #   here or read from the environment is used as-is and never saved.
     # @param timeout [Numeric] the per-request socket timeout, in seconds
-    # @param key_path [String, Pathname, nil] where to cache the free key;
-    #   defaults to +Client.default_key_path+
-    # @param cache [Boolean] +false+ keeps the key in memory only, neither
-    #   reading nor writing the cache file
-    def initialize(base_url = DEFAULT_BASE_URL, api_key = nil, timeout: 60.0,
-                   key_path: nil, cache: true)
+    # @param key_path [String, Pathname, nil] where to save a key the server
+    #   issued itself, on a first call without a key; defaults to
+    #   +Client.default_key_path+
+    # @param cache [Boolean] +false+ keeps an issued key in memory only, neither
+    #   reading nor writing the file
+    def initialize(base_url = DEFAULT_BASE_URL, key = nil, api_key: key,
+                   timeout: 60.0, key_path: nil, cache: true)
       @base_url = base_url.to_s.sub(%r{/+\z}, "")
       @timeout = timeout
       @key_path = Pathname(key_path || Client.default_key_path).expand_path
       @cache = cache
+      api_key = Client.env_key if api_key.nil?
+      # A key the caller holds — passed, or set in the environment — is never
+      # written to the cache, so it cannot clobber the issued key of whoever runs
+      # the code, and is never discarded on a 401.
       @explicit = !api_key.nil?
       @api_key = @explicit ? api_key : (cache ? Client.read_key(@key_path) : nil)
       # Only a key that came off disk may be discarded and re-minted on a 401 —
@@ -165,19 +232,35 @@ 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, may
+    #   stop sooner too, once it stops finding better answers. 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 +268,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 +318,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 +332,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 +352,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)
 
@@ -261,11 +371,12 @@ module Quicopt
 
     # Render a config mapping as a URL query-string suffix.
     #
-    # Escapes per RFC 3986, so a space becomes +%20+ and never +'+'+ — the form
-    # the service's query parser round-trips unambiguously, and the form the
-    # other clients send. Ruby's stock helpers (+URI.encode_www_form+,
-    # +CGI.escape+, +URI.encode_www_form_component+) all emit +'+'+ here, so none
-    # of them can be used.
+    # Escapes per RFC 3986, so a space becomes +%20+ and never <tt>'+'</tt> —
+    # the form the service's query parser round-trips unambiguously, and the
+    # form the other clients send. Ruby's stock helpers
+    # (<tt>URI.encode_www_form</tt>, +CGI.escape+,
+    # +URI.encode_www_form_component+) all emit <tt>'+'</tt> here, so none of
+    # them can be used.
     #
     # @param config [Hash, nil]
     # @return [String] +"?k=v&…"+ if +config+ is non-empty, else +""+
@@ -313,6 +424,15 @@ module Quicopt
       { "error" => text }
     end
 
+    # The API key set in the environment variable +API_KEY_ENV+, stripped of
+    # surrounding whitespace; +nil+ when the variable is unset or blank.
+    #
+    # @return [String, nil]
+    def self.env_key
+      key = ENV.fetch(API_KEY_ENV, "").strip
+      key.empty? ? nil : key
+    end
+
     # The default location of the cached free key:
     # +$XDG_CACHE_HOME/quicopt/free_key+, falling back to +~/.cache+ when the
     # variable is unset, unless +KEY_PATH_ENV+ overrides the whole path.
@@ -359,43 +479,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,16 +567,20 @@ 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.
     #
-    # @return [Hash] the job state (+queued+/+running+/+done+/+failed+) and its
-    #   log tail, as returned by the service
+    # @return [Hash] the job state
+    #   (<tt>queued</tt>/<tt>running</tt>/<tt>done</tt>/<tt>failed</tt>) and
+    #   its log tail, as returned by the service
     def status
       @client.request("GET", "/v1/jobs/#{@job_id}")
     end
@@ -463,15 +589,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)
+    #   non-<tt>not_done</tt> error, or once +timeout+ elapses
+    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