quicopt 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 370fa0c8906d43f509f9262406805bdc0e1357248e8271125b6b76a096a2fd6f
-  data.tar.gz: 0df9e60f7456ae1b0ecae3a9d3ffb668490c684a095e71f4ebfb614f522c15f0
+  metadata.gz: 16cdf553d639def3a3a5cbbdb7c9e4240118dc619595edeb9dd710cee798362d
+  data.tar.gz: 96ce7ae36eb75c68c493a749be503b28240cf843acd5d1196dfaf63410896fcc
 SHA512:
-  metadata.gz: d4d0c6ef70c1f502da08557c366f31695293a52886b72bc6f214d89c902eedb21862dbe3a14223184adaa3eb64873dccf52a54609ce836e4363f92f77ef9344b
-  data.tar.gz: e1d1ac282698f36bbe968c9099029db5f3e12bbbe6fcb7fded6dd83dfe1e49b66bdba22e267ca64845deb12cfd6d93adc24b434066470417dfbad162deeeb40f
+  metadata.gz: 6cc023a263fe6c075da89d9ab6dbdbddc3ad647763a9bd6b58c2f4b50aad76356d686d7256a7ff8fb0c04854419e8df9d8c683586b220d333fcd31808706f441
+  data.tar.gz: 8a375d5f3f93971f46b9e2a496677f17478b55f7af822a26239a77dd1e5a5a4a90e4a85f19365b614f2f2f1ed9d2f35c5af1f2040a8df52f9d17924e856f3df2

data/README.md

@@ -26,7 +26,7 @@ There is no solver on your machine. The service does the solving.
   variables, constraints, objective.
 - [`Quicopt::Permutation`](https://quicopt.github.io/quicopt-ruby/Quicopt/Permutation.html)
   and [`Quicopt::LookupTable`](https://quicopt.github.io/quicopt-ruby/Quicopt/LookupTable.html) —
-  orders as decisions, and data read along them.
+  orderings as decisions, and data read along them.
 - [`Quicopt::Client`](https://quicopt.github.io/quicopt-ruby/Quicopt/Client.html) —
   sending a model, API keys, long-running jobs, errors.
 - [`Quicopt::Result`](https://quicopt.github.io/quicopt-ruby/Quicopt/Result.html) —
@@ -60,10 +60,12 @@ z = m.num_var(0, 10, "z")
 m.maximize(3 * x + 2 * y + z)
 m.add(x + y <= 5)
 
-result = Quicopt::Client.new.solve(m)
+result = Quicopt::Client.new(api_key: "…").solve(m)   # the key from your sign-up email
 puts result.display
 ```
 
+The service needs an API key. Register at https://quicopt.com/signup and the key arrives by email. Without a key, the call fails with a message that links to the sign-up page.
+
 `result.display` is rendered by the service and ready to print — the same summary
 for every kind of model. The structured fields are there too:
 
@@ -152,7 +154,7 @@ m.minimize(suppliers.sum { |s| cart_value[s] + ship_fee[s] * (use[s] - free[s])
 Now all we have to do is to send this to the Quicopt API service:
 ```ruby
 # get the results from the API service
-result = Quicopt::Client.new.solve(m)
+result = Quicopt::Client.new(api_key: "…").solve(m)
 
 # inspect the result
 puts result.display
@@ -243,9 +245,9 @@ Two consequences of that, both deliberate:
 
 Chained comparisons (`1 <= x <= 5`) are not a thing in Ruby. Add two rows.
 
-## Choosing an order
+## Choosing an ordering
 
-Some decisions are orders: the route a van drives through its stops, or the sequence in which a machine works through its jobs. Declare such an order with `permutation`, and read data along it with a lookup table. Here are five stops along a road; find the shortest route through all of them that visits stop 3 before stop 0:
+Some decisions are orderings: the route a van drives through its stops, or the sequence in which a machine works through its jobs. Declare such an ordering with `permutation`, and read data along it with a lookup table. Here are five stops along a road; find the shortest route through all of them that visits stop 3 before stop 0:
 
 ```ruby
 position = [0, 3, 1, 4, 2]                    # km along the road, stops 0 to 4
@@ -256,19 +258,19 @@ 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.solve(m)
+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 permutation places `n` items in `n` slots, one item per slot, both counted from 0. Here the items are the stops and the slots are the visits, so slot 0 holds the first stop visited:
+A permutation places items in as many slots, one item per slot, both counted from 0. Here the items are the stops and the slots are the visits, so slot 0 holds the first stop visited:
 
 - `route.item_at(k)` is the stop in slot `k`: `route.item_at(0)` is the first stop visited.
 - `route.slot_of(i)` is the slot of stop `i`: when it is visited.
 - `route.precede(a, b)` requires stop `a` to be visited before stop `b`. Every solution meets every such requirement.
-- `start:` gives the order the service's search starts from: `m.permutation("route", 5, start: [4, 3, 2, 1, 0])` starts with stop 0 in slot 4, stop 1 in slot 3, and so on.
+- `start:` gives the ordering the service's search starts from: `m.permutation("route", 5, start: [4, 3, 2, 1, 0])` starts with stop 0 in slot 4, stop 1 in slot 3, and so on.
 
-The result holds each permutation's order both ways round, again counted from 0: `item_at`, the item in each slot, and `slot_of`, the slot of each item. Orders are found by a search, which cannot prove that no better order exists, so a model with a permutation comes back with the status `"heuristic"`.
+The result holds each permutation's ordering both ways round, again counted from 0: `item_at`, the item in each slot, and `slot_of`, the slot of each item. Orderings are found by a search, which cannot prove that no better ordering exists, so a model with a permutation comes back with the status `"heuristic"`.
 
 A Ruby array cannot be indexed by a decision the service has not made yet, such as which stop comes first; a lookup table can. `dist[route.item_at(k), route.item_at(k + 1)]` is the length of the leg from the `k`-th stop to the next, whichever stops those turn out to be. A table is a vector, indexed `table[i]`, or a matrix, indexed `table[i, j]`. Indexed by whole numbers only, it gives the entry itself (`dist[0, 1]` is `3.0`). It can also be indexed by an integer variable, to read the entry the service picks:
 
@@ -278,7 +280,7 @@ price  = m.lookup_table("price", [3.0, 1.0, 4.0, 1.5])
 choice = m.int_var(0, 3, "choice")
 m.minimize(price[choice])
 
-result = Quicopt::Client.new.solve(m)
+result = Quicopt::Client.new(api_key: "…").solve(m)
 result.solution                               # {"choice" => 1.0}: option 1 is the cheapest
 result.objective                              # 1.0
 ```
@@ -307,7 +309,7 @@ m.minimize(
   (0...3).sum { |w| opening[w] * Quicopt.holds(ship[w].sum >= 1) }                          # opening fee
 )
 
-result = Quicopt::Client.new.solve(m)
+result = Quicopt::Client.new(api_key: "…").solve(m)
 result.objective                               # 300.0
 result.solution.select { |_, units| units > 0 }.sort.to_h
 # {"ship_0_0" => 25.0, "ship_0_1" => 10.0, "ship_2_0" => 15.0, "ship_2_1" => 20.0, "ship_2_2" => 20.0}
@@ -315,7 +317,7 @@ result.solution.select { |_, units| units > 0 }.sort.to_h
 
 Warehouse 1 stays closed. Warehouse 0 sends its full 25 units to customer 0 and the minimum of 10 to customer 1; warehouse 2 covers the rest. `Quicopt.holds` takes `<=`, `>=`, `<`, `>`, `==` and `!=`, and `tol:` lets a comparison miss by that much and still count: `Quicopt.holds(spend >= 300, tol: 0.01)`. `Quicopt.min` and `Quicopt.max` give the smallest and the largest of several expressions.
 
-`m.partition` splits items into groups the way `permutation` orders them. 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:
+`m.partition` makes a split of items into groups a decision, the way `permutation` makes an ordering one. 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:
 
 ```ruby
 strength = [7, 5, 4, 3, 2, 1]                  # of players 0 to 5
@@ -325,7 +327,7 @@ total = (0...2).map { |t| (0...6).sum { |p| strength[p] * Quicopt.holds(teams.pa
 m.add(teams.size_of(0) == 4)                   # team 0 has four players
 m.minimize(Quicopt.max(total[0], total[1]))
 
-result = Quicopt::Client.new.solve(m)
+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
 result.structures["teams"].size_of             # [4, 2]
@@ -343,7 +345,7 @@ bytes   = m.encode          # the message itself: protobuf bytes, ready to POST
 program = m.to_program      # the same content as a structured object you can read
 Quicopt.decode(bytes)       # bytes back into that object
 
-Quicopt::Client.new.solve(bytes)   # solve an already-encoded model
+Quicopt::Client.new(api_key: "…").solve(bytes)   # solve an already-encoded model
 ```
 
 The message format is a [protobuf](https://protobuf.dev) schema,
@@ -359,22 +361,12 @@ Compare decoded models, never the raw bytes.
 ## The client
 
 ```ruby
-client = Quicopt::Client.new                       # the public free tier
-client = Quicopt::Client.new("http://localhost:8137")
-client = Quicopt::Client.new(url, "my-api-key", timeout: 120)
+client = Quicopt::Client.new(api_key: "…")   # the Quicopt service
+client = Quicopt::Client.new("http://localhost:8137", api_key: "…")
+client = Quicopt::Client.new(api_key: "…", timeout: 120)
 ```
 
-**Keys.** The first call without a key mints one, cached at
-`$XDG_CACHE_HOME/quicopt/free_key` (`~/.cache/…` by default) and replayed as a
-bearer token on every later call — including from later runs, so you keep one key
-without doing anything. A key you passed in is used as-is, never cached and never
-overwritten; `Quicopt::Client.new(url, cache: false)` keeps the minted key in
-memory only.
-
-Where the home directory does not survive the run (CI, containers), the cache is
-wiped between sessions and each run mints a new key. Set `QUICOPT_KEY_PATH` to a
-durable location — or `Client.new(url, key_path: …)` — to keep one key across
-sessions.
+**Keys.** Register at https://quicopt.com/signup and the key arrives by email. Pass it as `api_key:`. To keep the key out of your code, set the environment variable `QUICOPT_API_KEY` instead and create the client as `Quicopt::Client.new`.
 
 **Per-project tagging.** `solve(model, project: "atlas")` tags the call so usage on
 one key can be attributed per project. It rides the query string and is never
@@ -382,7 +374,7 @@ baked into the model.
 
 **Large models.** `solve(model, gzip: true)` compresses the request body.
 
-**Time limit.** The service chooses how long a solve may run. `time_limit:` sets that time instead, in seconds. A solver that proves its answer sooner still stops sooner; a search, which cannot prove it is done, runs for all of it:
+**Time limit.** The service chooses how long a solve may run. `time_limit:` sets that time instead, in seconds. A solver that proves its answer sooner still stops sooner; a search, which cannot prove it is done, may stop sooner too, once it stops finding better answers:
 
 ```ruby
 result = client.solve(m, time_limit: 30)

data/lib/quicopt/client.rb

@@ -15,11 +15,9 @@ require "zlib"
 # 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
-# rather than minting a fresh one per run.
+# +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:
 #
@@ -35,10 +33,9 @@ require "zlib"
 # 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 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
@@ -124,8 +121,9 @@ module Quicopt
       self
     end
 
-    # The kind of model the service recognised (+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
@@ -135,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.
@@ -158,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 = {
@@ -188,31 +190,38 @@ module Quicopt
 
     # @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 —
@@ -230,10 +239,11 @@ module Quicopt
     #   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.
+    #   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
@@ -361,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 +""+
@@ -413,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.
@@ -558,8 +578,9 @@ module Quicopt
 
     # 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
@@ -573,7 +594,7 @@ module Quicopt
     # @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
+    #   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

data/lib/quicopt/indicators.rb

@@ -37,8 +37,8 @@ module Quicopt
     # @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.
+    #   holding: +a >= b+ holds from +a = b − tol+ on, +a > b+ from
+    #   <tt>a > b + tol</tt>. 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
@@ -55,8 +55,8 @@ module Quicopt
     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.
+    # evaluates. <tt>fee * Quicopt.min(1, a.active + b.active)</tt> 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
@@ -101,7 +101,7 @@ module Quicopt
       end
     end
 
-    # Whether a comparison between two numbers (+value = lhs − rhs+) holds.
+    # Whether a comparison between two numbers (<tt>value = lhs − rhs</tt>) holds.
     def truth(value, sense, tol)
       case sense
       when :le then -value + tol >= 0
@@ -172,8 +172,8 @@ module Quicopt
       @argument.variables
     end
 
-    # @return [String] the term as sent, e.g. +step(x + y - 1)+; the indicator of
-    #   a bare variable reads +x.active+
+    # @return [String] the term as sent, e.g. <tt>step(x + y - 1)</tt>; 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
@@ -227,7 +227,8 @@ module Quicopt
       @args.flat_map(&:variables).uniq
     end
 
-    # @return [String] the term as written, e.g. +min(1, a.active + b.active)+
+    # @return [String] the term as written, e.g.
+    #   <tt>min(1, a.active + b.active)</tt>
     def to_s
       "#{@op}(#{@args.join(', ')})"
     end

data/lib/quicopt/model.rb

@@ -47,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
@@ -63,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
@@ -148,9 +148,10 @@ module Quicopt
     # 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)
@@ -171,7 +172,8 @@ module Quicopt
     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)]
@@ -272,11 +274,11 @@ module Quicopt
   end
 
   # A polynomial of degree ≤ 2 over a model's variables, always kept in collected
-  # form: +constant + Σ cᵢ·xᵢ + Σ qᵢⱼ·xᵢxⱼ+.
+  # form: <tt>constant + Σ cᵢ·xᵢ + Σ qᵢⱼ·xᵢxⱼ</tt>.
   #
-  # A value read from a permutation (+route.item_at(0)+) or a lookup table
-  # (+dist[i, j]+) counts as one factor, like a variable: +2 * dist[i, j]+ is
-  # linear, +x * dist[i, j]+ quadratic.
+  # 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.
@@ -335,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),
@@ -401,7 +403,7 @@ module Quicopt
       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?
@@ -614,10 +616,11 @@ module Quicopt
       @by_name[name.to_s]
     end
 
-    # Declare an order as a decision: +n+ items placed in +n+ 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.
+    # 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:
@@ -629,7 +632,7 @@ module Quicopt
     #   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.solve(m)
+    #   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
     #
@@ -639,31 +642,33 @@ module Quicopt
     # @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 [Integer] the number of items, at least 2
+    # @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+ once. Left out, item +i+ starts in slot +i+.
+    #   +0...n_items+ once. Left out, item +i+ starts in slot +i+.
     # @return [Permutation]
-    # @raise [TypeError] if +n+ is not an Integer
-    # @raise [ArgumentError] if +n+ is below 2, the name is taken, or +start+ is
-    #   not an arrangement of +0...n+
-    def permutation(name, n, start: nil)
-      raise TypeError, "a permutation's size is a whole number, got #{n.inspect}" unless n.is_a?(Integer)
-      raise ArgumentError, "a permutation has at least 2 items, got #{n}" if n < 2
+    # @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).to_a)
-        raise ArgumentError, "permutation #{nm.inspect}: start must hold each of 0 to #{n - 1} once " \
+      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, start&.dup)
+      permutation = Permutation.new(self, nm, n_items, start&.dup)
       @permutations << permutation
       @structured[nm] = permutation
     end
 
-    # Declare an assignment of +n+ items to +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.
+    # 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:
@@ -675,34 +680,39 @@ module Quicopt
     #   m.add(teams.size_of(0) == 4)                   # team 0 has four players
     #   m.minimize(Quicopt.max(total[0], total[1]))
     #
-    #   result = Quicopt::Client.new.solve(m)
+    #   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 [Integer] the number of items, at least 1
-    # @param parts [Integer] the number of parts, at least 2
+    # @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...parts+.
-    #   Left out, item +i+ starts in part +i % parts+.
+    #   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+ or +parts+ is not an Integer
-    # @raise [ArgumentError] if +n+ is below 1, +parts+ below 2, the name is
-    #   taken, or +start+ does not give each item a part
-    def partition(name, n, parts, start: nil)
-      raise TypeError, "a partition's number of items is a whole number, got #{n.inspect}" unless n.is_a?(Integer)
-      raise TypeError, "a partition's number of parts is a whole number, got #{parts.inspect}" unless parts.is_a?(Integer)
-      raise ArgumentError, "a partition has at least 1 item, got #{n}" if n < 1
-      raise ArgumentError, "a partition has at least 2 parts, got #{parts}" if parts < 2
+    # @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 && start.all? { |b| b.is_a?(Integer) && b >= 0 && b < parts })
-        raise ArgumentError, "partition #{nm.inspect}: start gives each of the #{n} items a part " \
-                             "from 0 to #{parts - 1}"
+      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, parts, start&.dup)
+      partition = Partition.new(self, nm, n_items, n_parts, start&.dup)
       @partitions << partition
       @structured[nm] = partition
     end
@@ -753,9 +763,9 @@ module Quicopt
 
     # 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 order 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.
+    # 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")
@@ -771,8 +781,8 @@ module Quicopt
     # @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 (+table[i, j]+, every row the same length) of
-    #   numbers, none of them NaN
+    #   +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
@@ -864,10 +874,11 @@ module Quicopt
         lines << "  #{v.name} in #{v.domain} #{range}"
       end
       @permutations.each do |p|
-        order = p.precedences.map { |a, b| ", #{a} before #{b}" }.join
-        lines << "  #{p.name} orders items 0 to #{p.size - 1}#{order}"
+        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.size - 1} in parts 0 to #{p.parts - 1}" }
+      @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")
@@ -918,9 +929,9 @@ module Quicopt
     end
 
     def auto_name
-      n = @variables.size + 1
-      n += 1 while @by_name.key?("x#{n}") || @structured.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,

data/lib/quicopt/structured.rb

@@ -2,7 +2,7 @@
 # SPDX-FileCopyrightText: (c) 2026 Tim Bode, PGI-12, Forschungszentrum Jülich
 # frozen_string_literal: true
 
-# quicopt/structured — orders as decisions (+Permutation+), assignments to
+# quicopt/structured — orderings as decisions (+Permutation+), assignments to
 # groups as decisions (+Partition+) and data read at decided positions
 # (+LookupTable+).
 #
@@ -44,9 +44,9 @@ module Quicopt
     end
   end
 
-  # A permutation declared by +Model#permutation+: +size+ items placed in +size+
-  # slots, one item per slot, both numbered from 0. Read it with +item_at+ and
-  # +slot_of+; constrain it with +precede+.
+  # A permutation declared by +Model#permutation+: +n_items+ items placed in as
+  # many slots, one item per slot, both numbered from 0. Read it with +item_at+
+  # and +slot_of+; constrain it with +precede+.
   #
   #   route = m.permutation("route", 5)
   #   route.item_at(0)     # the first stop visited
@@ -58,7 +58,7 @@ module Quicopt
     # @return [String] the permutation's name; its arrangement comes back keyed by it
     attr_reader :name
     # @return [Integer] the number of items, which is also the number of slots
-    attr_reader :size
+    attr_reader :n_items
     # @return [Array<Integer>, nil] the slot each item starts in, or +nil+ for the
     #   default (item +i+ in slot +i+)
     attr_reader :start
@@ -66,10 +66,10 @@ module Quicopt
     # Declared with +Model#permutation+, not built directly.
     #
     # @api private
-    def initialize(model, name, size, start)
+    def initialize(model, name, n_items, start)
       @model = model
       @name = name
-      @size = size
+      @n_items = n_items
       @start = start&.freeze
       @precedences = []
       @reads = {}
@@ -79,22 +79,22 @@ module Quicopt
     # a route whose items are stops, +route.item_at(0)+ is the first stop visited.
     # Index a +LookupTable+ with it to read data about that item.
     #
-    # @param slot [Integer] from 0 to +size - 1+
+    # @param slot [Integer] from 0 to +n_items - 1+
     # @return [Expression]
     # @raise [TypeError, ArgumentError] if +slot+ is not one of the slots
     def item_at(slot)
-      read(:item_at, Positions.check(slot, @size, "slot", owner))
+      read(:item_at, Positions.check(slot, @n_items, "slot", owner))
     end
 
     # The slot item +item+ is placed in, an expression whose value the service
     # chooses. For a route whose items are stops, +route.slot_of(3)+ is when stop 3
     # is visited.
     #
-    # @param item [Integer] from 0 to +size - 1+
+    # @param item [Integer] from 0 to +n_items - 1+
     # @return [Expression]
     # @raise [TypeError, ArgumentError] if +item+ is not one of the items
     def slot_of(item)
-      read(:slot_of, Positions.check(item, @size, "item", owner))
+      read(:slot_of, Positions.check(item, @n_items, "item", owner))
     end
 
     # Require item +before+ to be in an earlier slot than item +after+: a pickup
@@ -109,13 +109,13 @@ module Quicopt
     #   contradicts those already given (1 before 2 and 2 before 1), or if the
     #   +start+ places +before+ after +after+
     def precede(before, after)
-      a = Positions.check(before, @size, "item", owner)
-      b = Positions.check(after, @size, "item", owner)
+      a = Positions.check(before, @n_items, "item", owner)
+      b = Positions.check(after, @n_items, "item", owner)
       raise ArgumentError, "an item cannot precede itself" if a == b
       if @start && @start[a] > @start[b]
         raise ArgumentError, "#{owner}: the start places item #{a} after item #{b}, which it must precede"
       end
-      if Permutation.cycle?(@precedences + [[a, b]], @size)
+      if Permutation.cycle?(@precedences + [[a, b]], @n_items)
         raise ArgumentError, "requiring #{a} before #{b} contradicts the requirements already given for #{owner}"
       end
 
@@ -129,20 +129,20 @@ module Quicopt
       @precedences.dup.freeze
     end
 
-    # @return [String] name and size
+    # @return [String] name and number of items
     def inspect
-      "#<Quicopt::Permutation #{@name} (#{@size} items in #{@size} slots)>"
+      "#<Quicopt::Permutation #{@name} (#{@n_items} items in #{@n_items} slots)>"
     end
 
-    # Whether the +[before, after]+ requirements over items +0...n+ contradict
-    # each other: Kahn's algorithm leaves an item unplaced exactly when they
-    # contain a cycle.
+    # Whether the +[before, after]+ requirements over items +0...n_items+
+    # contradict each other: Kahn's algorithm leaves an item unplaced exactly
+    # when they contain a cycle.
     #
     # @api private
-    def self.cycle?(edges, n)
-      indegree = Array.new(n, 0)
+    def self.cycle?(edges, n_items)
+      indegree = Array.new(n_items, 0)
       edges.each { |_, b| indegree[b] += 1 }
-      ready = (0...n).select { |i| indegree[i].zero? }
+      ready = (0...n_items).select { |i| indegree[i].zero? }
       placed = 0
       until ready.empty?
         x = ready.pop
@@ -154,7 +154,7 @@ module Quicopt
           ready << b if indegree[b].zero?
         end
       end
-      placed < n
+      placed < n_items
     end
 
     private
@@ -169,8 +169,8 @@ module Quicopt
     end
   end
 
-  # A partition declared by +Model#partition+: +size+ items in +parts+ parts,
-  # both numbered from 0. Read it with +part_of+ and +size_of+.
+  # A partition declared by +Model#partition+: +n_items+ items in +n_parts+
+  # parts, both numbered from 0. Read it with +part_of+ and +size_of+.
   #
   #   teams = m.partition("teams", 6, 2)
   #   teams.part_of(4)     # the team person 4 joins
@@ -181,21 +181,21 @@ module Quicopt
     # @return [String] the partition's name; its assignment comes back keyed by it
     attr_reader :name
     # @return [Integer] the number of items
-    attr_reader :size
+    attr_reader :n_items
     # @return [Integer] the number of parts
-    attr_reader :parts
+    attr_reader :n_parts
     # @return [Array<Integer>, nil] the part each item starts in, or +nil+ for the
-    #   default (item +i+ in part +i % parts+)
+    #   default (item +i+ in part +i % n_parts+)
     attr_reader :start
 
     # Declared with +Model#partition+, not built directly.
     #
     # @api private
-    def initialize(model, name, size, parts, start)
+    def initialize(model, name, n_items, n_parts, start)
       @model = model
       @name = name
-      @size = size
-      @parts = parts
+      @n_items = n_items
+      @n_parts = n_parts
       @start = start&.freeze
       @reads = {}
     end
@@ -203,26 +203,26 @@ module Quicopt
     # The part item +item+ is in, an expression whose value the service
     # chooses. Index a +LookupTable+ with it to read data about that part.
     #
-    # @param item [Integer] from 0 to +size - 1+
+    # @param item [Integer] from 0 to +n_items - 1+
     # @return [Expression]
     # @raise [TypeError, ArgumentError] if +item+ is not one of the items
     def part_of(item)
-      read(:part_of, Positions.check(item, @size, "item", owner))
+      read(:part_of, Positions.check(item, @n_items, "item", owner))
     end
 
     # The number of items in part +part+, an expression whose value the service
-    # chooses: a count from 0 to +size+.
+    # chooses: a count from 0 to +n_items+.
     #
-    # @param part [Integer] from 0 to +parts - 1+
+    # @param part [Integer] from 0 to +n_parts - 1+
     # @return [Expression]
     # @raise [TypeError, ArgumentError] if +part+ is not one of the parts
     def size_of(part)
-      read(:size_of, Positions.check(part, @parts, "part", owner))
+      read(:size_of, Positions.check(part, @n_parts, "part", owner))
     end
 
-    # @return [String] name and sizes
+    # @return [String] name, number of items and number of parts
     def inspect
-      "#<Quicopt::Partition #{@name} (#{@size} items in #{@parts} parts)>"
+      "#<Quicopt::Partition #{@name} (#{@n_items} items in #{@n_parts} parts)>"
     end
 
     private
@@ -252,7 +252,8 @@ module Quicopt
     attr_reader :name
     # @return [Array<Float>, Array<Array<Float>>] the entries, as given
     attr_reader :values
-    # @return [Array<Integer>] the extent of each dimension: +[n]+ or +[rows, columns]+
+    # @return [Array<Integer>] the extent of each dimension: +[length]+ or
+    #   +[rows, columns]+
     attr_reader :shape
 
     # Declared with +Model#lookup_table+, not built directly.

data/lib/quicopt/version.rb

@@ -5,5 +5,5 @@
 module Quicopt
   # The gem version, tracking the client — not the wire schema, which is
   # versioned separately by its protobuf package (`quicopt.modeler.v1`).
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/quicopt/wire.rb

@@ -96,9 +96,10 @@ module Quicopt
       #
       # IEEE keeps +-0.0+ distinct from +0.0+ — a distinct bit pattern, and a
       # distinct protobuf value — and moving a bound across an inequality
-      # (+f ≤ 0+ ⇒ +0 − f ≥ 0+) produces one whenever that bound is zero. The
-      # Python and Julia clients send +0.0+ there, so collapse the sign here
-      # rather than sending bytes that differ from theirs by a sign bit.
+      # (<tt>f ≤ 0</tt> ⇒ <tt>0 − f ≥ 0</tt>) produces one whenever that bound
+      # is zero. The Python and Julia clients send +0.0+ there, so collapse the
+      # sign here rather than sending bytes that differ from theirs by a sign
+      # bit.
       def number(value)
         float = value.to_f
         float.zero? ? 0.0 : float
@@ -241,12 +242,12 @@ module Quicopt
       def structure_decl(structure)
         start = (structure.start || []).map { |k| k + 1 }
         if structure.is_a?(Partition)
-          return PB::StructureDecl.new(name: structure.name, kind: "partition", size: structure.size,
-                                       start: start, fixed: false, parts: structure.parts)
+          return PB::StructureDecl.new(name: structure.name, kind: "partition", size: structure.n_items,
+                                       start: start, fixed: false, parts: structure.n_parts)
         end
 
         PB::StructureDecl.new(
-          name: structure.name, kind: "permutation", size: structure.size, start: start, fixed: false,
+          name: structure.name, kind: "permutation", size: structure.n_items, start: start, fixed: false,
           precede: structure.precedences.map { |a, b| PB::Precedence.new(before: a + 1, after: b + 1) }
         )
       end

data/lib/quicopt.rb

@@ -22,7 +22,7 @@ require_relative "quicopt/client"
 #   m.maximize(3 * x + 2 * y + z)
 #   m.add(x + y <= 5)
 #
-#   result = Quicopt::Client.new.solve(m)
+#   result = Quicopt::Client.new(api_key: "…").solve(m)
 #   puts result.display
 #
 # Three pieces, nothing more: +Model+ authors, +Wire+ encodes, +Client+ ships.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quicopt
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Tim Bode