lpsolver 0.1.0

data/lib/lpsolver/solution.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module LpSolver
+  # Represents the solution returned by solving a model.
+  #
+  # The Solution object contains the optimal (or best-found) values for
+  # all decision variables, the optimal objective value, and metadata
+  # about the solver's execution.
+  #
+  # @example Accessing solution values
+  #   solution = model.solve
+  #   solution[:x]        # => 4.0 (value of variable x)
+  #   solution[:y]        # => 0.0 (value of variable y)
+  #   solution.objective_value  # => 12.0 (optimal objective)
+  #
+  # @example Checking solution status
+  #   solution.feasible?      # => true
+  #   solution.infeasible?    # => false
+  #   solution.unbounded?     # => false
+  class Solution
+    # @return [Hash{String => Float}] Maps variable names to their optimal values.
+    #   The keys are the variable names as strings (as produced by HiGHS),
+    #   and the values are the optimal decision variable values.
+    attr_reader :variables
+
+    # @return [Float] The optimal objective function value.
+    #   For minimization problems, this is the minimum value.
+    #   For maximization problems, this is the maximum value.
+    attr_reader :objective_value
+
+    # @return [String] The status of the model as reported by HiGHS.
+    #   Possible values include:
+    #   - "optimal": An optimal solution was found.
+    #   - "infeasible": No feasible solution exists.
+    #   - "unbounded": The objective can be improved without bound.
+    #   - "unknown": The solver could not determine the status.
+    attr_reader :model_status
+
+    # @return [Integer] The number of iterations the solver performed.
+    #   This is a diagnostic metric; may be 0 for some solver types.
+    attr_reader :iterations
+
+    # Creates a new Solution object.
+    #
+    # @param variables [Hash{String => Float}] Maps variable names to values.
+    # @param objective_value [Float] The optimal objective value.
+    # @param model_status [String] The solver-reported model status.
+    # @param iterations [Integer] The number of solver iterations.
+    def initialize(variables:, objective_value:, model_status:, iterations:)
+      @variables = variables
+      @objective_value = objective_value
+      @model_status = model_status
+      @iterations = iterations
+    end
+
+    # Retrieves the value of a variable by name.
+    #
+    # @param name [Symbol, String] The variable name.
+    # @return [Float] The optimal value of the variable.
+    # @raise [KeyError] If the variable name is not found in the solution.
+    # @example
+    #   solution[:x]  # => 4.0
+    def [](name)
+      variables[name.to_s]
+    end
+
+    # Retrieves values for multiple variables by name.
+    #
+    # @param *names [Symbol, String] The variable names to retrieve.
+    # @return [Array<Float>] An array of variable values in the same order.
+    # @example
+    #   solution.values_at(:x, :y)  # => [4.0, 0.0]
+    # @param [Array<Object>] names
+    def values_at(*names)
+      names.map { |name| variables[name.to_s] }
+    end
+
+    # Checks if the solution is feasible.
+    #
+    # A solution is feasible if the solver found a solution that satisfies
+    # all constraints and bounds.
+    #
+    # @return [Boolean] True if the model status is "optimal".
+    def feasible?
+      @model_status == 'optimal'
+    end
+
+    # Checks if the model is infeasible.
+    #
+    # A model is infeasible if no solution exists that satisfies all
+    # constraints simultaneously.
+    #
+    # @return [Boolean] True if the model status is "infeasible".
+    def infeasible?
+      @model_status == 'infeasible'
+    end
+
+    # Checks if the model is unbounded.
+    #
+    # A model is unbounded if the objective can be improved indefinitely
+    # without violating any constraints.
+    #
+    # @return [Boolean] True if the model status is "unbounded".
+    def unbounded?
+      @model_status == 'unbounded'
+    end
+
+    # Returns a string representation of the solution.
+    #
+    # @return [String] A formatted string showing variable values and
+    #   the objective value.
+    # @example
+    #   puts solution
+    #   # x = 4.0
+    #   # y = 0.0
+    #   # Objective: 12.0
+    def to_s
+      lines = variables.map { |name, value| "#{name} = #{value}" }
+      lines << "Objective: #{objective_value}"
+      lines.join("\n")
+    end
+  end
+end

data/lib/lpsolver/variable.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module LpSolver
+  # Represents a decision variable in an LP/MIP/QP model.
+  #
+  # Variables are the building blocks of optimization models. Each variable
+  # represents a quantity to be determined by the solver (e.g., production
+  # levels, investment amounts, resource allocations).
+  #
+  # Variables support arithmetic operators for building expressions and
+  # comparison operators for creating constraints. The operator overloading
+  # enables a natural, mathematical DSL:
+  #
+  #   x = model.add_variable(:x, lb: 0)
+  #   model.add_constraint(:budget, (x * 2 + y) <= 100)
+  #
+  # @note Variable * Variable produces a QuadraticExpression (for QP).
+  #   Variable * Scalar produces a LinearExpression (for LP).
+  #
+  # @example Creating a variable
+  #   x = model.add_variable(:x, lb: 0, ub: 100, integer: false)
+  #   x.index    # => 0
+  #   x.name     # => :x
+  #
+  # @example Using in expressions
+  #   expr = x * 2 + y * 3          # LinearExpression
+  #   quad = x * x + y * y          # QuadraticExpression
+  #   spec = (x * 2 + y) <= 100     # ConstraintSpec
+  class Variable
+    # @return [Integer] The internal index of this variable in the model.
+    #   This is used internally to map the variable to a column in the
+    #   solver's constraint matrix.
+    attr_reader :index
+
+    # @return [Symbol] The human-readable name of this variable.
+    attr_reader :name
+
+    # Creates a new Variable instance.
+    #
+    # @param index [Integer] The internal index assigned by the model.
+    # @param name [Symbol] The human-readable name of this variable.
+    def initialize(index, name)
+      @index = index
+      @name = name
+    end
+
+    # Multiplies this variable by a scalar or another variable.
+    #
+    # When multiplied by a Numeric, returns a LinearExpression with this
+    # variable scaled by the given coefficient. When multiplied by another
+    # Variable, returns a QuadraticExpression representing the product term
+    # (used for quadratic objectives in QP).
+    #
+    # @param other [Numeric, Variable] The multiplier.
+    # @return [LinearExpression] When +other+ is a Numeric.
+    #   Example: `x * 2` → LinearExpression with terms {0 => 2.0}
+    # @return [QuadraticExpression] When +other+ is a Variable.
+    #   Example: `x * y` → QuadraticExpression with terms [[0, 1, 1.0]]
+    def *(other)
+      if other.is_a?(Variable)
+        QuadraticExpression.new({}, [[@index, other.index, 1.0]])
+      else
+        LinearExpression.new({ @index => other.to_f })
+      end
+    end
+
+    # Adds another variable, expression, or constant to this variable.
+    #
+    # Creates a new LinearExpression containing the sum of this variable
+    # and the other operand.
+    #
+    # @param other [Variable, LinearExpression, Numeric] The operand to add.
+    # @return [LinearExpression] A new expression representing the sum.
+    # @example Adding two variables
+    #   (x + y).terms  # => {0 => 1.0, 1 => 1.0}
+    # @example Adding a constant
+    #   (x + 5).constant  # => 5.0
+    def +(other)
+      if other.is_a?(Variable)
+        LinearExpression.new({ @index => 1.0, other.index => 1.0 })
+      elsif other.is_a?(LinearExpression)
+        LinearExpression.new(merge_terms({ @index => 1.0 }, other.terms), other.constant)
+      else
+        LinearExpression.new({ @index => 1.0 }, other.to_f)
+      end
+    end
+
+    # Subtracts another variable, expression, or constant from this variable.
+    #
+    # Creates a new LinearExpression containing the difference between this
+    # variable and the other operand.
+    #
+    # @param other [Variable, LinearExpression, Numeric] The operand to subtract.
+    # @return [LinearExpression] A new expression representing the difference.
+    # @example Subtracting two variables
+    #   (x - y).terms  # => {0 => 1.0, 1 => -1.0}
+    # @example Subtracting a constant
+    #   (x - 5).constant  # => -5.0
+    def -(other)
+      if other.is_a?(Variable)
+        LinearExpression.new({ @index => 1.0, other.index => -1.0 })
+      elsif other.is_a?(LinearExpression)
+        LinearExpression.new(negate_add_terms({ @index => 1.0 }, other.terms), -other.constant)
+      else
+        LinearExpression.new({ @index => 1.0 }, -other.to_f)
+      end
+    end
+
+    # Returns a LinearExpression with this variable negated.
+    #
+    # @return [LinearExpression] A new expression with negated coefficients.
+    # @example
+    #   (-x).terms  # => {0 => -1.0}
+    def -@
+      LinearExpression.new({ @index => -1.0 })
+    end
+
+    # Creates a less-than-or-equal-to constraint specification.
+    #
+    # This is used with Model#add_constraint to define upper bounds on
+    # linear expressions. The constraint represents: expression <= value.
+    #
+    # @param value [Numeric] The right-hand side upper bound.
+    # @return [ConstraintSpec] A constraint specification with operator :le.
+    # @example
+    #   model.add_constraint(:budget, (x * 2 + y) <= 100)
+    # @param [Object] other
+    def <=(other)
+      ConstraintSpec.new(:le, { @index => 1.0 }, 0, other.to_f)
+    end
+
+    # Creates a greater-than-or-equal-to constraint specification.
+    #
+    # This is used with Model#add_constraint to define lower bounds on
+    # linear expressions. The constraint represents: expression >= value.
+    #
+    # @param value [Numeric] The right-hand side lower bound.
+    # @return [ConstraintSpec] A constraint specification with operator :ge.
+    # @example
+    #   model.add_constraint(:demand, (x + y * 2) >= 50)
+    # @param [Object] other
+    def >=(other)
+      ConstraintSpec.new(:ge, { @index => 1.0 }, 0, other.to_f)
+    end
+
+    # Creates an equality constraint specification.
+    #
+    # This is used with Model#add_constraint to define exact values for
+    # linear expressions. The constraint represents: expression == value.
+    #
+    # @param value [Numeric] The exact value the expression must equal.
+    # @return [ConstraintSpec] A constraint specification with operator :eq.
+    # @example
+    #   model.add_constraint(:weights, (x + y + z) == 1)
+    # @param [Object] other
+    def ==(other)
+      ConstraintSpec.new(:eq, { @index => 1.0 }, 0, other.to_f)
+    end
+
+    # Checks if two variables refer to the same underlying variable.
+    #
+    # @param other [Object] The object to compare against.
+    # @return [Boolean] True if +other+ is a Variable with the same index.
+    def equals?(other)
+      other.is_a?(Variable) && other.index == @index
+    end
+
+    # Returns a string representation of this variable.
+    #
+    # @return [String] A string in the format "@name(index)".
+    # @example
+    #   x.to_s  # => "@x(0)"
+    def to_s
+      "@#{@name}(#{@index})"
+    end
+
+    # Converts this variable's name to a Symbol.
+    #
+    # @return [Symbol] The variable's name.
+    # @example
+    #   x.to_sym  # => :x
+    def to_sym
+      @name
+    end
+
+    # Returns the hash code based on this variable's index.
+    #
+    # @return [Integer] The hash code of the variable's index.
+    def hash
+      @index.hash
+    end
+
+    alias eql? equals?
+
+    private
+
+    # Merges two term hashes, combining coefficients for duplicate indices.
+    #
+    # @param a [Hash{Integer => Float}] First term hash.
+    # @param b [Hash{Integer => Float}] Second term hash.
+    # @return [Hash{Integer => Float}] The merged term hash with zero coefficients removed.
+    def merge_terms(a, b)
+      merged = a.dup
+      b.each { |idx, coeff| merged[idx] = (merged[idx] || 0) + coeff }
+      merged.reject! { |_, v| v.zero? }
+      merged
+    end
+
+    # Merges two term hashes with subtraction (a - b).
+    #
+    # @param a [Hash{Integer => Float}] First term hash.
+    # @param b [Hash{Integer => Float}] Second term hash to subtract.
+    # @return [Hash{Integer => Float}] The difference term hash with zero coefficients removed.
+    def negate_add_terms(a, b)
+      merged = a.dup
+      b.each { |idx, coeff| merged[idx] = (merged[idx] || 0) - coeff }
+      merged.reject! { |_, v| v.zero? }
+      merged
+    end
+  end
+end

data/lib/lpsolver/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LpSolver
+  # The current version of the LpSolver gem.
+  #
+  # @return [String] The version string (e.g., "0.1.0").
+  VERSION = '0.1.0'
+end

data/lib/lpsolver.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# LpSolver - A Ruby gem for solving Linear Programming (LP), Quadratic
+# Programming (QP), and Mixed Integer Programming (MIP) problems.
+#
+# This gem provides a Ruby DSL for building optimization models and
+# interfaces with the HiGHS solver via its command-line interface.
+#
+# == Quick Start
+#
+#   require 'lpsolver'
+#
+#   model = LpSolver::Model.new
+#   x = model.add_variable(:x, lb: 0)
+#   y = model.add_variable(:y, lb: 0)
+#
+#   model.add_constraint(:budget, (x * 2 + y) <= 100)
+#   model.minimize
+#   model.set_objective(x * 3 + y * 5)
+#
+#   solution = model.solve
+#   puts solution.objective_value  # => 12.0
+#
+# @see LpSolver::Model
+# @see LpSolver::Variable
+# @see LpSolver::Solution
+module LpSolver
+end
+
+require_relative 'lpsolver/version'
+require_relative 'lpsolver/exception'
+
+# Core DSL classes (loaded in dependency order)
+require_relative 'lpsolver/constraint_spec'
+require_relative 'lpsolver/variable'
+require_relative 'lpsolver/linear_expression'
+require_relative 'lpsolver/quadratic_expression'
+
+# Solvers and data classes
+require_relative 'lpsolver/solution'
+require_relative 'lpsolver/model'

data/lpsolver.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/lpsolver/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lpsolver'
+  spec.version       = LpSolver::VERSION
+  spec.authors       = ['David Siaw']
+  spec.email         = ['874280+davidsiaw@users.noreply.github.com']
+
+  spec.summary       = 'HiGHS LP/MIP/QP solver for Ruby'
+  spec.description   = 'A Ruby gem providing access to the HiGHS linear, quadratic, and mixed-integer programming solver via CLI.'
+  spec.homepage      = 'https://github.com/davidsiaw/lpsolver'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.0')
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/davidsiaw/lpsolver'
+  spec.metadata['changelog_uri'] = 'https://github.com/davidsiaw/lpsolver'
+  spec.metadata['documentation_uri'] = 'https://davidsiaw.github.io/lpsolver'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files         = Dir['{exe,data,lib}/**/*'] + %w[Gemfile lpsolver.gemspec README.md LICENSE.txt]
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: lpsolver
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Siaw
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-22 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby gem providing access to the HiGHS linear, quadratic, and mixed-integer
+  programming solver via CLI.
+email:
+- 874280+davidsiaw@users.noreply.github.com
+executables:
+- README.md
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE.txt
+- README.md
+- exe/README.md
+- lib/lpsolver.rb
+- lib/lpsolver/constraint_spec.rb
+- lib/lpsolver/exception.rb
+- lib/lpsolver/linear_expression.rb
+- lib/lpsolver/model.rb
+- lib/lpsolver/quadratic_expression.rb
+- lib/lpsolver/solution.rb
+- lib/lpsolver/variable.rb
+- lib/lpsolver/version.rb
+- lpsolver.gemspec
+homepage: https://github.com/davidsiaw/lpsolver
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/davidsiaw/lpsolver
+  source_code_uri: https://github.com/davidsiaw/lpsolver
+  changelog_uri: https://github.com/davidsiaw/lpsolver
+  documentation_uri: https://davidsiaw.github.io/lpsolver
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: HiGHS LP/MIP/QP solver for Ruby
+test_files: []