quicopt 0.1.0

data/lib/quicopt/wire.rb

@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: (c) 2026 Tim Bode, PGI-12, Forschungszentrum Jülich
+# frozen_string_literal: true
+
+require "google/protobuf"
+require_relative "modeler/v1/program_pb"
+
+# quicopt/wire — a +Model+ → the wire IR +Program+ → protobuf bytes.
+#
+# The generated codec (+lib/quicopt/modeler/+, regenerated by +gen/gen.sh+ from
+# the vendored +program.proto+) does the serialization; this file supplies the
+# node constructors on top of it and the lowering from the DSL's normalised
+# polynomials into the IR's expression trees.
+#
+# The canonical forms below are shared with the other clients, so the same model
+# authored in Ruby, Python or Julia reaches the service as the same IR:
+#
+#   f = c   ⇒  f − c = 0   (Zero)
+#   f ≥ l   ⇒  f − l ≥ 0   (Nonneg)
+#   f ≤ u   ⇒  u − f ≥ 0   (Nonneg)
+#
+# A unit coefficient is dropped rather than emitted as +1 * e+, an additive zero
+# constant is dropped from a sum, and a sum of one term is that term.
+#
+# Note on byte-level comparison: proto3 omits zero-valued scalars (+start: 0.0+)
+# and does not canonicalize field order, so these bytes are *decode-equivalent*
+# to the service's reference codec, not byte-identical — the same position the
+# Julia client is in. Compare decoded +Program+ values in tests, never hex.
+module Quicopt
+  # Node constructors over the generated codec, and the lowering from the DSL's
+  # normalised polynomials into the IR's expression trees.
+  module Wire
+    # The generated wire schema — +Program+, +Expression+, +Constraint+, … — as
+    # the client's IR. Aliased for brevity throughout the codec.
+    PB = Quicopt::Modeler::V1
+
+    class << self
+      # Lower +model+ to the wire IR.
+      #
+      # @param model [Quicopt::Model]
+      # @return [PB::Program]
+      def program(model)
+        PB::Program.new(
+          vars: model.variables.map { |v| var_decl(v) },
+          objective: expression(model.objective),
+          sense: model.sense,
+          constraints: model.constraints.map { |c| constraint(c) }
+        )
+      end
+
+      # Serialize a model (or an already-lowered +Program+) to wire bytes.
+      #
+      # @param model [Quicopt::Model, PB::Program]
+      # @return [String] binary protobuf bytes
+      def encode(model)
+        PB::Program.encode(model.is_a?(PB::Program) ? model : program(model))
+      end
+
+      # Parse wire bytes back into a +Program+ — the inverse of +encode+, and the
+      # only sound way to compare two encodings.
+      #
+      # @param bytes [String]
+      # @return [PB::Program]
+      def decode(bytes)
+        PB::Program.decode(bytes)
+      end
+
+      # ── node constructors ──────────────────────────────────────────────────
+
+      # A constant expression node. Always a set +oneof+ case, so +Const(0.0)+
+      # survives the round-trip rather than vanishing as a proto3 default.
+      def const(value)
+        PB::Expression.new(constant: number(value))
+      end
+
+      # Normalise negative zero on its way to the wire.
+      #
+      # 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
+      # sibling clients emit +0.0+ there, so collapse the sign here rather than
+      # shipping bytes that differ from theirs by a sign bit.
+      def number(value)
+        float = value.to_f
+        float.zero? ? 0.0 : float
+      end
+
+      # A reference to a flat (unindexed) variable. The +Index+ message is emitted
+      # present-but-empty, matching the reference codec.
+      def var(name)
+        PB::Expression.new(var: PB::VarRef.new(name: name, index: PB::Index.new))
+      end
+
+      # An operator application: +op+ applied to child expressions.
+      def apply(op, args)
+        PB::Expression.new(apply: PB::Apply.new(op: op, args: args))
+      end
+
+      # +coef · expr+, dropping a unit coefficient.
+      def scaled(coef, expr)
+        coef == 1.0 ? expr : apply("*", [const(coef), expr])
+      end
+
+      # Fold terms into an n-ary sum, dropping additive-zero constants. No terms
+      # is the zero constant; one term is itself.
+      def sum(terms)
+        surviving = terms.reject { |t| t.node == :constant && t.constant.zero? }
+        return const(0.0) if surviving.empty?
+        return surviving.first if surviving.size == 1
+
+        apply("+", surviving)
+      end
+
+      # ── lowering ───────────────────────────────────────────────────────────
+
+      # A normalised DSL expression → an IR expression tree: the constant (when
+      # nonzero), then the linear terms, then the quadratic ones — the term order
+      # the sibling front-ends emit.
+      #
+      # @param expr [Quicopt::Expression]
+      # @return [PB::Expression]
+      def expression(expr)
+        terms = []
+        terms << const(expr.constant) unless expr.constant.zero?
+        expr.linear.each { |v, c| terms << scaled(c, var(v.name)) }
+        expr.quadratic.each { |(a, b), c| terms << scaled(c, apply("*", [var(a.name), var(b.name)])) }
+        sum(terms)
+      end
+
+      # One DSL constraint row → an IR function-in-set row.
+      #
+      # @param con [Quicopt::Constraint]
+      # @return [PB::Constraint]
+      def constraint(con)
+        f = expression(con.body)
+        c = con.bound
+        case con.sense
+        when :eq then PB::Constraint.new(f: minus(f, c), set: con_set(:zero))
+        when :ge then PB::Constraint.new(f: minus(f, c), set: con_set(:nonneg))
+        when :le then PB::Constraint.new(f: geq(c, f), set: con_set(:nonneg))
+        else raise Error, "unknown constraint sense #{con.sense.inspect}"
+        end
+      end
+
+      # A variable declaration → +VarDecl+. Bounds are scalars (a Param-table
+      # bound needs indexed variables, which the DSL does not have); ±Inf passes
+      # straight through as a free direction.
+      #
+      # @param variable [Quicopt::Variable]
+      # @return [PB::VarDecl]
+      def var_decl(variable)
+        PB::VarDecl.new(name: variable.name,
+                        domain: variable.domain,
+                        lower: PB::Bound.new(scalar: number(variable.lower)),
+                        upper: PB::Bound.new(scalar: number(variable.upper)),
+                        start: number(variable.start))
+      end
+
+      private
+
+      # +f − c+, dropping the additive zero.
+      def minus(f, c)
+        c.zero? ? f : apply("-", [f, const(c)])
+      end
+
+      # +u − f+ — the body of +f ≤ u+ written as +u − f ≥ 0+.
+      def geq(u, f)
+        apply("-", [const(u), f])
+      end
+
+      def con_set(kind)
+        case kind
+        when :zero then PB::ConSet.new(zero: PB::Zero.new)
+        when :nonneg then PB::ConSet.new(nonneg: PB::Nonneg.new)
+        end
+      end
+    end
+  end
+end

data/lib/quicopt.rb

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: (c) 2026 Tim Bode, PGI-12, Forschungszentrum Jülich
+# frozen_string_literal: true
+
+require_relative "quicopt/version"
+require_relative "quicopt/model"
+require_relative "quicopt/wire"
+require_relative "quicopt/client"
+
+# Quicopt — a Ruby client for the Quicopt optimization service.
+#
+# Author a model in the native DSL, encode it to the versioned wire IR, and let
+# the service solve it:
+#
+#   require "quicopt"
+#
+#   m = Quicopt::Model.new
+#   x = m.int_var(0, 4, "x")
+#   y = m.bin_var("y")
+#   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)
+#   puts result.display
+#
+# Three pieces, nothing more: +Model+ authors, +Wire+ encodes, +Client+ ships.
+module Quicopt
+  # The wire IR container, re-exported so callers can inspect or route the bytes
+  # themselves rather than going through +Client+.
+  Program = Wire::PB::Program
+
+  class << self
+    # Lower a model to wire bytes.
+    #
+    # @param model [Model, Program]
+    # @return [String] binary protobuf bytes
+    def encode(model)
+      Wire.encode(model)
+    end
+
+    # Parse wire bytes back into a +Program+.
+    #
+    # @param bytes [String]
+    # @return [Program]
+    def decode(bytes)
+      Wire.decode(bytes)
+    end
+  end
+end

data/proto/quicopt/modeler/v1/program.proto

@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: (c) 2026 Tim Bode, PGI-12, Forschungszentrum Jülich
+// ===========================================================================
+//  Quicopt wire schema — v1
+//
+//  The language-neutral API contract of the Quicopt service. A client authors a
+//  model in a front-end (JuMP, Pyomo, …), lowers it to the structured `Program`
+//  below, and serializes it to protobuf bytes; the service decodes and solves it.
+//  This file is the source of truth clients compile against.
+//  ---------------------------------------------------------------------------
+//  Schema evolution (v1):
+//    - Field numbers are permanent. Never reuse a number; `reserved` removed
+//      ones. Additive-only: new optional fields/messages may be appended.
+//    - `oneof` cases are append-only.
+//    - Breaking changes bump the package to `quicopt.modeler.v2` in a new file;
+//      v1 stays frozen.
+//
+//  Conventions:
+//    - IR names (`x`, `i`, `S`, `+`, `min`) are `string` here; a client maps them
+//      to its own symbol type at the boundary. Data is never carried as a bare
+//      string, so the mapping is lossless.
+//    - Tuple-keyed tables (params, indexed_sets, fix) cannot be protobuf `map`
+//      (keys aren't scalar) — each is a `repeated Entry { key, value }`.
+// ===========================================================================
+
+syntax = "proto3";
+
+package quicopt.modeler.v1;
+
+// ---------------------------------------------------------------------------
+// Index machinery
+// ---------------------------------------------------------------------------
+
+// One entry of an index tuple: a concrete coordinate (`3`) or a bound index
+// name (`i`).
+message IndexElem {
+  oneof kind {
+    int64  int  = 1;  // a concrete coordinate
+    string name = 2;  // a bound index name, e.g. i
+  }
+}
+
+// An index tuple: () scalar, (i,), (3,), (i, j) …
+message Index {
+  repeated IndexElem elems = 1;
+}
+
+// ---------------------------------------------------------------------------
+// Expression tree  (e ::= c │ p[idx] │ x[idx] │ op(e…) │ ⊕_{k∈S} e(k))
+//
+// Serialized as a tree — each node stands alone, so the structure is acyclic by
+// construction.
+// ---------------------------------------------------------------------------
+
+message Expression {
+  oneof node {
+    double   constant = 1;  // Const(value) — always emitted (a set oneof case),
+                            //                so Const(0.0) survives the round-trip
+    ParamRef param    = 2;  // Param(name, index)
+    VarRef   var      = 3;  // Var(name, index)
+    Apply    apply    = 4;  // Apply(op, args)
+    Reduce   reduce   = 5;  // Reduce(op, idx, over, body, cond)
+  }
+}
+
+message ParamRef {
+  string name  = 1;
+  Index  index = 2;
+}
+
+message VarRef {
+  string name  = 1;
+  Index  index = 2;
+}
+
+// Operator application. `op` is a key into the operator catalog (see Catalog),
+// not code; an unknown op or an arity mismatch is rejected.
+message Apply {
+  string     op   = 1;
+  repeated Expression args = 2;
+}
+
+// A reference to an index set, possibly applied to enclosing bound indices.
+// args = () → a flat set (resolved against IndexSet); args = (i,) → a dependent
+// set "S(i)" (resolved against IndexedSet once i is bound).
+message SetRef {
+  string name = 1;
+  Index  args = 2;
+}
+
+// Aggregation  ⊕_{idx ∈ over} body, optionally filtered by `cond` (keep a term
+// only where cond ≠ 0). `cond` absent (message not set) ⇒ no filter.
+message Reduce {
+  string     op   = 1;  // the fold operator key (+, *, …)
+  string     idx  = 2;  // the bound dummy index name
+  SetRef     over = 3;
+  Expression body = 4;
+  Expression cond = 5;  // optional
+}
+
+// ---------------------------------------------------------------------------
+// Constraints — function-in-set, both sides open
+// ---------------------------------------------------------------------------
+
+message Zero   {}                 // f = 0
+message Nonneg {}                 // f ≥ 0
+
+// Indicator: the binary `bin` being active implies f lies in `inner`. Kept
+// first-class on the wire (not desugared); the service decides how it is realized.
+message Indicator {
+  VarRef bin   = 1;
+  ConSet inner = 2;
+}
+
+message ConSet {
+  oneof kind {
+    Zero      zero      = 1;
+    Nonneg    nonneg    = 2;
+    Indicator indicator = 3;
+  }
+}
+
+// One (index symbol => set) binding of a constraint's quantifier.
+message QuantBinding {
+  string idx = 1;
+  SetRef set = 2;
+}
+
+// f ∈ set, quantified over `over` (∅ over ⇒ a single flat constraint).
+message Constraint {
+  Expression   f    = 1;
+  ConSet       set  = 2;
+  repeated QuantBinding over = 3;
+}
+
+// ---------------------------------------------------------------------------
+// Variables, sets, data
+// ---------------------------------------------------------------------------
+
+enum Domain {
+  DOMAIN_UNSPECIFIED = 0;  // invalid on the wire; rejected on decode
+  CONTINUOUS         = 1;
+  INTEGER            = 2;
+  BINARY             = 3;
+}
+
+// A per-variable bound: a scalar, or the name of a per-index Param table to look
+// the bound up in (so a bound may vary by index).
+message Bound {
+  oneof kind {
+    double scalar = 1;
+    string param  = 2;  // name of a Param table
+  }
+}
+
+// A variable *family* indexed over `axes` (set names; empty ⇒ scalar).
+message VarDecl {
+  string          name   = 1;
+  repeated string axes   = 2;
+  Domain          domain = 3;
+  Bound           lower  = 4;
+  Bound           upper  = 5;
+  double          start  = 6;
+}
+
+// A flat index set: name + concrete elements.
+message IndexSet {
+  string             name     = 1;
+  repeated IndexElem elements = 2;
+}
+
+// A dependent set carried as data: one fibre per key tuple, e.g. S[(i,)] → [j…].
+message IndexedSetFibre {
+  Index              key   = 1;
+  repeated IndexElem value = 2;
+}
+message IndexedSet {
+  string                   name   = 1;
+  repeated IndexedSetFibre fibres = 2;
+}
+
+// A named indexed data table: one entry per key tuple, e.g. p[(i,)], A[(i,j)].
+message ParamEntry {
+  Index  key   = 1;
+  double value = 2;
+}
+message ParamTable {
+  string              name    = 1;
+  repeated ParamEntry entries = 2;
+}
+
+// A per-index pin: fix variable `var` at `index` to `value` (e.g. x[1] = 0).
+message FixEntry {
+  string var   = 1;
+  Index  index = 2;
+  double value = 3;
+}
+
+// ---------------------------------------------------------------------------
+// Program — the structured authoring container (what crosses the wire)
+// ---------------------------------------------------------------------------
+
+message Program {
+  repeated IndexSet   sets         = 1;
+  repeated IndexedSet indexed_sets = 2;
+  repeated ParamTable params       = 3;
+  repeated VarDecl    vars         = 4;
+  Expression          objective    = 5;
+  string              sense        = 6;  // "min" | "max"
+  repeated Constraint constraints  = 7;
+  repeated FixEntry   fix          = 8;
+}
+
+// ---------------------------------------------------------------------------
+// Rebinding — graph once, data per instance
+//
+// A client sends the Program (the graph) once, then a ParamData per instance to
+// re-solve the same structure on new data without re-sending the expression trees.
+// ---------------------------------------------------------------------------
+
+message ParamData {
+  repeated ParamTable params = 1;
+}
+
+// ---------------------------------------------------------------------------
+// Operator catalog — the versioned set of operators a client may emit
+//
+// Clients fetch the Catalog to discover the supported ops; `version` co-versions
+// with the schema. arity = -1 ≡ variadic.
+// ---------------------------------------------------------------------------
+
+message OpDef {
+  string          op    = 1;
+  int32           arity = 2;
+  repeated string tags  = 3;
+}
+message Catalog {
+  uint32           version = 1;
+  repeated OpDef   ops     = 2;
+}