lpsolver 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ff84f9d0bcf181ac202f5f25cf5754e04319e1bf459ab830af40f8e91c42bc7
+  data.tar.gz: f51148b23deca2cd3070726c78fc505d07bc3d9c3594e386cfbba4048e68187c
+SHA512:
+  metadata.gz: 827cfb4a818544a8a90a47231ec46de845b973c4522f4e3496ce9c85d4b55f01fd9cfed0eaf206d93757db09208e61047b8106519b38285ce789940518cb8e11
+  data.tar.gz: 253710d8517bbbc6fd817cb15ad630b8d9949c89ea08f6c3a9b0f71d08e1abf627b2739ceca7f133904ddc310a5925073475a2cfdfcaac0c921db782cfa49820

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in lpsolver.gemspec
+gemspec
+
+# Specify development dependencies here and not in the gemspec
+gem 'rake'
+gem 'rspec'
+gem 'rubocop'
+gem 'rubocop-rake'
+gem 'rubocop-rspec'
+gem 'rubocop-yard'
+gem 'yard'
+gem 'yard-rspec'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 You
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,345 @@
+# LpSolver
+
+A Ruby gem for solving optimization problems using the [HiGHS](https://github.com/ERGO-Code/HiGHS) solver.
+
+## What is this for?
+
+Imagine you want to **maximize profit** or **minimize cost** while following certain rules (like a budget limit or a minimum requirement). This gem helps you find the best answer.
+
+You describe your problem in simple math, and the solver finds the optimal solution.
+
+### Real-world examples
+
+- **Coin change**: You need exactly $9.99 in coins. Which combination uses the least weight?
+- **Diet plan**: You need 2000 calories, 50g protein, and 100g carbs per day. What combination of foods costs the least?
+- **Factory**: You have limited materials and labor. How many of each product should you make to maximize profit?
+- **Investment**: You want to split money across stocks, bonds, and gold. How do you minimize risk while earning a target return?
+
+## Linear Programming (LP)
+
+**LP** is for problems where everything scales in a straight line. If making one widget earns $5, making two earns $10. There are no "bulk discounts" or "diminishing returns" — just simple multiplication.
+
+**Use LP when:**
+- Your goal is a simple sum: `total_cost = price_a * qty_a + price_b * qty_b`
+- Your rules are simple: `total_cost <= budget`, `qty_a + qty_b >= 100`
+
+### LP Example: Diet Problem
+
+```ruby
+require 'lpsolver'
+
+model = LpSolver::Model.new
+
+bread = model.add_variable(:bread, lb: 0)   # how many slices
+milk = model.add_variable(:milk, lb: 0)      # how many liters
+
+# Rules first
+model.add_constraint(:calories, (bread * 80 + milk * 60) >= 2000)
+model.add_constraint(:protein, (bread * 3 + milk * 3.2) >= 50)
+
+# Then solve
+solution = model.minimize!(bread * 0.50 + milk * 1.20)
+
+puts solution.objective_value  # minimum cost
+```
+
+## Quadratic Programming (QP)
+
+**QP** is like LP, but your goal can involve multiplying variables together. This is useful when the "cost" or "risk" depends on how things interact, not just their individual values.
+
+The most common use: **minimizing variance** (risk) in a portfolio. If Stock A and Stock B tend to move together, the combined risk isn't just the sum of their individual risks — it also depends on how they correlate.
+
+**Use QP when:**
+- Your goal involves squares or products: `risk = x² + y² + 2xy`
+- You need to minimize deviation: `(actual - target)²`
+
+### QP Example: Portfolio Optimization
+
+```ruby
+require 'lpsolver'
+
+model = LpSolver::Model.new
+
+tech = model.add_variable(:tech, lb: 0)
+bonds = model.add_variable(:bonds, lb: 0)
+gold = model.add_variable(:gold, lb: 0)
+
+# Rules first
+model.add_constraint(:all_money, (tech + bonds + gold) == 1)
+model.add_constraint(:target_return, (tech * 0.15 + bonds * 0.05 + gold * 0.08) >= 0.10)
+
+# Then solve — minimize portfolio variance (risk)
+solution = model.minimize!(
+  tech * tech * 0.04 +       # tech variance
+  bonds * bonds * 0.0025 +   # bonds variance
+  gold * gold * 0.01 +       # gold variance
+  (tech * bonds) * 0.002 +   # tech-bonds interaction
+  (tech * gold) * (-0.004)   # tech-gold interaction (negative = they move apart)
+)
+
+puts "Std dev: #{(Math.sqrt(solution.objective_value) * 100).round(2)}%"
+```
+
+## LP vs QP: Quick Comparison
+
+| | LP | QP |
+|---|---|---|
+| **Goal** | Simple sum: `2x + 3y` | Includes products: `x² + 2xy + y²` |
+| **Best for** | Cost, profit, weight, time | Risk, variance, error, deviation |
+| **Speed** | Very fast | Fast |
+| **Example** | "Minimize shipping cost" | "Minimize investment risk" |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lpsolver'
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+Or run directly from source:
+
+```bash
+ruby -Ilib examples/coin_purse.rb
+```
+
+## Prerequisites
+
+HiGHS must be installed:
+
+```bash
+# Ubuntu/Debian
+sudo apt install highs
+
+# macOS
+brew install highs
+
+# Or from source
+git clone https://github.com/ERGO-Code/HiGHS.git
+cd HiGHS && mkdir build && cd build
+cmake .. -DCMAKE_BUILD_TYPE=Release
+make -j$(nproc)
+sudo make install
+```
+
+Or set a custom path:
+
+```bash
+export HIGHS_PATH=/path/to/highs
+```
+
+## Usage
+
+### Simple Example (Operator DSL)
+
+The recommended approach uses Ruby operators for natural, readable code. Build the model first, then call `minimize!` or `maximize!` at the end — it sets the objective, picks the direction, and solves in one call:
+
+```ruby
+require 'lpsolver'
+
+model = LpSolver::Model.new
+
+# 1. Add variables
+x = model.add_variable(:x, lb: 0)
+y = model.add_variable(:y, lb: 0)
+
+# 2. Add constraints
+model.add_constraint(:budget, (x * 2 + y) <= 100)
+model.add_constraint(:demand, (x + y * 2) >= 50)
+
+# 3. Solve
+solution = model.minimize!(x * 3 + y * 5)
+
+puts "Cost: $#{solution.objective_value}"
+puts "x = #{solution[:x]}"
+puts "y = #{solution[:y]}"
+```
+
+### Integer (MIP) Example
+
+Some problems require whole numbers only (you can't make half a car):
+
+```ruby
+model = LpSolver::Model.new
+
+# integer: true means the value must be a whole number
+car = model.add_variable(:car, lb: 0, integer: true)
+bike = model.add_variable(:bike, lb: 0, integer: true)
+
+model.add_constraint(:vehicles, (car + bike) >= 10)
+model.add_constraint(:wheels, (car * 4 + bike * 2) >= 24)
+
+solution = model.minimize!(car * 30 + bike * 5)  # minimize cost
+puts solution
+```
+
+### Maximization
+
+```ruby
+model = LpSolver::Model.new
+x = model.add_variable(:x, lb: 0)
+y = model.add_variable(:y, lb: 0)
+
+model.add_constraint(:c1, (x + y) <= 10)
+solution = model.maximize!(x * 3 + y * 5)
+puts solution.objective_value  # => 50.0
+```
+
+### Complex Expressions
+
+You can chain operators with constants and unary minus:
+
+```ruby
+x = model.add_variable(:x, lb: 0)
+y = model.add_variable(:y, lb: 0)
+
+# Arithmetic
+expr = x * 2 + y * 3           # LinearExpression
+expr = x * 2 + y * 3 + 5       # add constant
+expr = x * 2 - y * 3 - 5       # subtract
+expr = -(x * 2 + y * 3)        # negate
+
+# Constraints
+model.add_constraint(:c, (x * 2 + y * 3 + 5) <= 100)
+model.add_constraint(:c, (x * 2 + y * 3 + 5) >= 100)
+model.add_constraint(:c, (x * 2 + y * 3 + 5) == 100)
+```
+
+### Export LP Format
+
+```ruby
+model = LpSolver::Model.new
+x = model.add_variable(:x, lb: 0)
+y = model.add_variable(:y, lb: 0)
+
+model.add_constraint(:c1, (x * 2 + y) <= 10)
+model.set_objective(x + y)
+
+# Print the LP file format
+puts model.to_lp
+
+# Or write to a file
+model.write_lp('model.lp')
+```
+
+## DSL Quick Reference
+
+### Variable (from `model.add_variable`)
+
+| Operator | Example | Result |
+|----------|---------|--------|
+| `*` | `x * 2` | Linear expression (2x) |
+| `*` | `x * y` | Quadratic term (xy) |
+| `+` | `x + y`, `x + 5` | Sum or constant offset |
+| `-` | `x - y`, `x - 5` | Difference or negative constant |
+| `-` | `-x` | Negated expression |
+| `<=` | `x + y <= 10` | Upper bound constraint |
+| `>=` | `x + y >= 5` | Lower bound constraint |
+| `==` | `x + y == 10` | Exact equality constraint |
+
+### LinearExpression (from arithmetic)
+
+| Operator | Example | Result |
+|----------|---------|--------|
+| `*` | `expr * 2` | Scaled expression |
+| `+` | `expr + y`, `expr + 5` | Combined expression |
+| `-` | `expr - y`, `expr - 5` | Difference expression |
+| `-` | `-expr` | Negated expression |
+| `<=`, `>=`, `==` | `expr <= 10` | Constraint |
+
+### QuadraticExpression (from `Variable * Variable`)
+
+| Operator | Example | Result |
+|----------|---------|--------|
+| `*` | `quad * 2` | Scaled expression |
+| `+` | `quad + expr`, `quad + 5` | Combined expression |
+| `-` | `quad - expr`, `quad - 5` | Difference expression |
+| `-` | `-quad` | Negated expression |
+
+> **Note:** `Variable * Variable` creates a quadratic term. `Variable * Scalar` creates a linear term. To scale a quadratic term, use `(x * y) * 2` (not `2 * (x * y)`).
+
+## API Reference
+
+### `Model#add_variable(name, lb: 0, ub: Float::INFINITY, integer: false)`
+Add a variable. Returns a `Variable` object.
+- `name` — variable name (Symbol or String)
+- `lb` — lower bound (default: 0)
+- `ub` — upper bound (default: no limit)
+- `integer` — set to `true` for whole-number-only variables
+
+### `Model#add_constraint(name, expr, lb: -Float::INFINITY, ub: Float::INFINITY)`
+Add a constraint. `expr` can be:
+- A `ConstraintSpec` from comparison operators: `(x * 2 + y) <= 100`
+- An array of `[variable_index, coefficient]` pairs (legacy format)
+
+### `Model#minimize!(objective)`
+Set the objective to minimize and solve in one call.
+
+### `Model#maximize!(objective)`
+Set the objective to maximize and solve in one call.
+
+### `Model#minimize`
+Set the optimization sense to minimization (legacy, use `minimize!` instead).
+
+### `Model#maximize`
+Set the optimization sense to maximization (legacy, use `maximize!` instead).
+
+### `Model#set_objective(objective)`
+Set the objective function without solving (legacy, use `minimize!`/`maximize!` instead).
+- `objective` can be a `LinearExpression`, `QuadraticExpression`, or Hash.
+
+### `Model#to_lp`
+Returns the model as a HiGHS LP format string.
+
+### `Model#write_lp(filename)`
+Writes the model to an LP file.
+
+### `Model#solve`
+Solves the model without setting an objective (legacy).
+
+### `Solution#[]`
+Get a variable's value: `solution[:x]`
+
+### `Solution#values_at(*names)`
+Get multiple values: `solution.values_at(:x, :y)`
+
+### `Solution#objective_value`
+The optimal (best) objective value.
+
+### `Solution#feasible?`
+True if a valid solution was found.
+
+### `Solution#infeasible?`
+True if no solution satisfies all constraints.
+
+### `Solution#unbounded?`
+True if the objective can improve without limit.
+
+## Examples
+
+- `examples/coin_purse.rb` — Minimize coin weight for exactly $9.99 (MIP)
+- `examples/diet_problem.rb` — Minimize food cost while meeting nutrition (LP)
+- `examples/factory.rb` — Maximize factory profit (LP)
+- `examples/portfolio.rb` — Minimize investment risk (QP)
+
+## Supported Problem Types
+
+| Type | Goal | Constraints | Whole Numbers? |
+|------|------|-------------|----------------|
+| LP | Linear sum | Linear | No |
+| QP | Quadratic (squares/products) | Linear | No |
+| MIP | Linear | Linear | Yes |
+
+## License
+
+[MIT License](https://opensource.org/licenses/MIT)
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)

data/exe/README.md

@@ -0,0 +1 @@
+# Executables go here

data/lib/lpsolver/constraint_spec.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module LpSolver
+  # Represents a constraint specification derived from comparing an expression with a value.
+  #
+  # ConstraintSpec objects are created when comparison operators (<=, >=, ==) are
+  # applied to LinearExpression or Variable objects. They encode the constraint's
+  # operator type, variable coefficients, and bounds.
+  #
+  # A constraint specification has the form:
+  #   operator: sum(coeff_i * x_i) + constant_offset compared to rhs
+  #
+  # The bounds are computed by rearranging the expression to isolate the
+  # variables on the left-hand side:
+  #   sum(coeff_i * x_i) <= (rhs - constant_offset)  for <= constraints
+  #   sum(coeff_i * x_i) >= (rhs - constant_offset)  for >= constraints
+  #   sum(coeff_i * x_i) == (rhs - constant_offset)  for == constraints
+  #
+  # @example Creating a constraint specification
+  #   x = model.add_variable(:x, lb: 0)
+  #   y = model.add_variable(:y, lb: 0)
+  #   spec = (x * 2 + y * 3 + 5) <= 100
+  #   spec.operator    # => :le
+  #   spec.terms       # => {x_idx => 2.0, y_idx => 3.0}
+  #   spec.lhs_constant # => 5.0
+  #   spec.rhs         # => 100.0
+  #   spec.bounds      # => [-Infinity, 95.0]
+  #
+  # @example Using in a model
+  #   model.add_constraint(:budget, (x * 2 + y * 3 + 5) <= 100)
+  class ConstraintSpec
+    # @return [Symbol] The constraint operator: :le (<=), :ge (>=), or :eq (==).
+    attr_reader :operator
+
+    # @return [Hash{Integer => Float}] Maps variable indices to their coefficients
+    #   in the expression (excluding the constant offset).
+    attr_reader :terms
+
+    # @return [Float] The constant offset on the left-hand side of the comparison.
+    #   For example, in `(x * 2 + y * 3 + 5) <= 100`, this is 5.0.
+    attr_reader :lhs_constant
+
+    # @return [Float] The right-hand side value of the comparison.
+    #   For example, in `(x * 2 + y * 3 + 5) <= 100`, this is 100.0.
+    attr_reader :rhs
+
+    # Creates a new ConstraintSpec.
+    #
+    # @param operator [Symbol] The constraint operator: :le, :ge, or :eq.
+    # @param terms [Hash{Integer => Float}] Maps variable indices to coefficients.
+    # @param lhs_constant [Float] The constant offset on the left-hand side.
+    # @param rhs [Float] The right-hand side value.
+    def initialize(operator, terms, lhs_constant, rhs)
+      @operator = operator
+      @terms = terms
+      @lhs_constant = lhs_constant
+      @rhs = rhs
+    end
+
+    # Converts this constraint specification to lower and upper bounds.
+    #
+    # Rearranges the constraint expression to isolate the variable terms,
+    # computing the effective bounds for the expression.
+    #
+    # @return [Array<Float, Float>] An array [lb, ub] representing the
+    #   lower and upper bounds for the variable terms.
+    # @example For (x * 2 + y * 3 + 5) <= 100
+    #   spec.bounds  # => [-Infinity, 95.0]
+    # @example For (x * 2 + y * 3 + 5) >= 50
+    #   spec.bounds  # => [45.0, Infinity]
+    # @example For (x * 2 + y * 3 + 5) == 75
+    #   spec.bounds  # => [70.0, 70.0]
+    def bounds
+      case @operator
+      when :le
+        [-Float::INFINITY, @rhs - @lhs_constant]
+      when :ge
+        [@rhs - @lhs_constant, Float::INFINITY]
+      when :eq
+        v = @rhs - @lhs_constant
+        [v, v]
+      end
+    end
+
+    # Returns the expression terms as an array of [variable_index, coefficient] pairs.
+    #
+    # This format is used internally when serializing the model to HiGHS LP format.
+    #
+    # @return [Array<[Integer, Float]>] Array of [var_index, coefficient] pairs.
+    # @example
+    #   spec.expr  # => [[0, 2.0], [1, 3.0]]
+    def expr
+      @terms.map { |idx, coeff| [idx, coeff] }
+    end
+  end
+end

data/lib/lpsolver/exception.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module LpSolver
+  # The base exception class for all LpSolver errors.
+  #
+  # All LpSolver-specific exceptions inherit from this class.
+  #
+  # @example Rescuing LpSolver errors
+  #   begin
+  #     model.solve
+  #   rescue LpSolver::Error => e
+  #     puts "Solver error: #{e.message}"
+  #   end
+  class Error < StandardError; end
+
+  # Raised when the HiGHS solver encounters an error.
+  #
+  # This exception is raised when the HiGHS command-line tool exits
+  # with a non-zero status, indicating a problem with the model
+  # (e.g., syntax error, infeasibility not handled, etc.).
+  #
+  # @example
+  #   begin
+  #     model.solve
+  #   rescue LpSolver::SolverError => e
+  #     puts "HiGHS error: #{e.message}"
+  #     puts "Stderr: #{e.stderr}" if e.stderr
+  #   end
+  class SolverError < Error
+    # @return [String, nil] The stderr output from the HiGHS solver.
+    attr_reader :stderr
+
+    # Creates a new SolverError.
+    #
+    # @param message [String] The error message.
+    # @param stderr [String, nil] The stderr output from HiGHS.
+    def initialize(message, stderr: nil)
+      @stderr = stderr
+      super(message)
+    end
+  end
+
+  # Raised when the HiGHS binary cannot be found.
+  #
+  # This exception is raised when the HIGHS_PATH environment variable
+  # is not set and 'highs' is not on the system PATH.
+  #
+  # @example
+  #   begin
+  #     model.solve
+  #   rescue LpSolver::NotFoundError => e
+  #     puts "HiGHS not found. Install it or set HIGHS_PATH."
+  #   end
+  class NotFoundError < Error; end
+end