lpsolver 0.2.0 → 0.3.0

data/lib/lpsolver/model.rb

@@ -1,93 +1,79 @@
 # frozen_string_literal: true
 
-require 'tempfile'
-
 module LpSolver
   # A high-level interface to HiGHS for building and solving LP/QP/MIP models.
   #
   # The Model class provides a Ruby DSL for defining variables, constraints,
-  # and objectives. Models are serialized to HiGHS LP format and solved via
-  # the HiGHS command-line interface.
-  #
-  # == Problem Types Supported
-  #
-  # * **Linear Programming (LP)**: Linear objective with linear constraints.
-  #   Example: maximize profit given resource constraints.
-  #
-  # * **Quadratic Programming (QP)**: Quadratic objective (convex) with
-  #   linear constraints. Example: minimize portfolio variance for a target return.
-  #
-  # * **Mixed Integer Programming (MIP)**: LP or QP with some or all variables
-  #   restricted to integer values. Example: coin change problem with integer counts.
-  #
-  # == Usage
-  #
-  # The DSL uses Ruby operators to build expressions naturally:
+  # and objectives. Models are solved via a pluggable driver.
   #
-  #   model = LpSolver::Model.new
-  #   x = model.add_variable(:x, lb: 0)
-  #   y = model.add_variable(:y, lb: 0)
-  #
-  #   # Constraints
-  #   model.add_constraint(:budget, (x * 2 + y) <= 100)
-  #   model.add_constraint(:demand, (x + y * 2) >= 50)
-  #
-  #   # Objective
-  #   model.minimize
-  #   model.set_objective(x * 3 + y * 5)
-  #
-  #   # Solve
-  #   solution = model.solve
-  #   puts solution[:x]  # => optimal value for x
-  #
-  # @example Linear Programming
-  #   model = LpSolver::Model.new
-  #   x = model.add_variable(:x, lb: 0)
-  #   y = model.add_variable(:y, lb: 0)
-  #   model.add_constraint(:c1, (x + y) >= 4)
-  #   model.minimize
-  #   model.set_objective(x * 3 + y * 5)
-  #   solution = model.solve
-  #   solution.objective_value  # => 12.0
-  #
-  # @example Quadratic Programming
-  #   model = LpSolver::Model.new
-  #   x = model.add_variable(:x, lb: 0)
-  #   y = model.add_variable(:y, lb: 0)
-  #   model.add_constraint(:c, (x + y) >= 2)
-  #   model.minimize
-  #   model.set_objective(x * x + y * y)
-  #   solution = model.solve
-  #   solution.objective_value  # => 2.0 (at x=1, y=1)
-  #
-  # @example Mixed Integer Programming
-  #   model = LpSolver::Model.new
-  #   x = model.add_variable(:x, lb: 0, integer: true)
-  #   y = model.add_variable(:y, lb: 0, integer: true)
-  #   model.add_constraint(:c, (x + y) == 10)
-  #   model.minimize
-  #   model.set_objective(x * 2 + y * 3)
-  #   solution = model.solve
-  #   solution[:x]  # => 10.0 (integer)
   class Model
-    # The path to the HiGHS binary.
+    # @return [Hash{Symbol => Variable}] All variables defined in this model.
+    attr_reader :variables
+    # @return [Integer] The next available variable index.
+    attr_reader :var_counter
+    # @return [Symbol] The current optimization heading.
+    attr_reader :heading
+    # @return [Array<Hash>] Constraint data as an array of {name, lb, ub, expr}.
+    def constraints
+      @constraints_data.values
+    end
+    # @return [Hash{Symbol => Hash}] Maps constraint names to their data.
+    attr_reader :constraints_data
+    # @return [Hash{Symbol => Symbol}] Maps variable names to their types.
+    attr_reader :var_types
+    # @return [Hash{Integer => Float}] Maps variable indices to coefficients.
+    attr_reader :objective
+    # @return [Array<[Integer, Integer, Float]>] Quadratic term entries.
+    attr_reader :quadratic_terms
+    # @return [Hash{Symbol => Array<Float>}] Maps variable names to [lb, ub] bounds.
+    attr_reader :var_bounds
+    # @return [String] The model name.
+    attr_reader :name
+    # @return [Drivers::CliDriver, Drivers::NativeDriver] The configured solver driver.
+    attr_reader :driver
+
+    # Returns the default solver driver.
+    #
+    # Tries CliDriver first (if HiGHS binary is available), then falls back
+    # to NativeDriver (if native extension is compiled), then raises an error.
+    #
+    # @return [Drivers::CliDriver, Drivers::NativeDriver] The default driver.
+    # @raise [RuntimeError] If neither CLI nor native driver is available.
+    def self.default_driver
+      begin
+        Drivers::CliDriver.new
+      rescue
+        begin
+          Drivers::NativeDriver.new
+        rescue LoadError
+          raise 'No solver available. Install HiGHS or compile the native extension with: rake compile'
+        end
+      end
+    end
+
+    # Solves the model using the configured driver, with automatic fallback.
     #
-    # Resolution order:
-    #   1. HIGHS_PATH environment variable
-    #   2. Bundled binary at lib/lpsolver/highs (from rake compile)
-    #   3. 'highs' on system PATH
+    # If the configured driver is CliDriver and the HiGHS binary is not found,
+    # automatically falls back to NativeDriver. If NativeDriver is also not
+    # available, raises the original error.
     #
-    # @return [String] The path to the HiGHS executable.
-    HIGHS_PATH = begin
-      env_path = ENV.fetch('HIGHS_PATH', nil)
-      if env_path
-        env_path
-      else
-        bundled = File.expand_path('../../lib/lpsolver/highs', __dir__)
-        if File.exist?(bundled)
-          bundled
+    # @return [Solution] The solution object.
+    # @raise [SolverError] If the solver encounters an error.
+    # @raise [LoadError] If no driver is available.
+    def solve
+      begin
+        @driver.solve(self)
+      rescue SolverError, LoadError => e
+        # If CLI driver fails and native driver is available, try it
+        if @driver.class.name.end_with?('CliDriver')
+          begin
+            @driver = Drivers::NativeDriver.new
+            @driver.solve(self)
+          rescue LoadError
+            raise e
+          end
         else
-          'highs'
+          raise e
         end
       end
     end
@@ -102,37 +88,23 @@ module LpSolver
       @constraints = {}     # { symbol => index }
       @var_counter = 0
       @constr_counter = 0
-      @sense = :minimize
+      @heading = :minimize
       @solution = nil
       @objective = {}       # { var_index => coefficient }
       @quadratic_terms = [] # [[var1_idx, var2_idx, coefficient], ...]
       @var_types = {}       # { symbol => :continuous | :integer }
       @var_bounds = {}      # { symbol => [lb, ub] }
       @constraints_data = {} # { symbol => { lb:, ub:, expr: [[var_idx, coeff], ...] } }
+      @driver = self.class.default_driver
     end
 
     # Adds a variable to the model.
     #
-    # Variables represent the decision quantities to be determined by the
-    # solver. Each variable is assigned a unique internal index and can be
-    # used in expressions via arithmetic operators.
-    #
-    # @param name [Symbol, String] The name of the variable. This is used
-    #   for identification in the LP format output and solution results.
-    # @param lb [Float] The lower bound for the variable (default: 0.0).
-    #   Use -Float::INFINITY for no lower bound.
-    # @param ub [Float] The upper bound for the variable (default: Float::INFINITY).
-    #   Use Float::INFINITY for no upper bound. Setting lb == ub fixes the variable.
-    # @param integer [Boolean] Whether the variable must take integer values
-    #   (default: false). When true, the model becomes a MIP problem.
-    # @return [Variable] The variable object, which supports arithmetic and
-    #   comparison operators for building expressions and constraints.
-    # @example Adding a continuous variable
-    #   x = model.add_variable(:x, lb: 0)
-    # @example Adding an integer variable
-    #   count = model.add_variable(:count, lb: 0, integer: true)
-    # @example Adding a fixed variable
-    #   capacity = model.add_variable(:capacity, lb: 100, ub: 100)
+    # @param name [Symbol, String] The variable name.
+    # @param lb [Float] Lower bound (default: 0.0).
+    # @param ub [Float] Upper bound (default: +Inf).
+    # @param integer [Boolean] Whether the variable is integer (default: false).
+    # @return [Variable] The variable object.
     def add_variable(name, lb: 0.0, ub: Float::INFINITY, integer: false)
       name = name.to_sym
       idx = @var_counter
@@ -146,26 +118,12 @@ module LpSolver
 
     # Adds a constraint to the model.
     #
-    # Constraints define the feasible region of the optimization problem.
-    # They can be specified using the DSL (comparison operators) or the
-    # legacy array format.
-    #
-    # @param name [Symbol, String] The name of the constraint.
+    # @param name [Symbol, String] The constraint name.
     # @param expr [ConstraintSpec, Array<[Integer, Float]>] The constraint
-    #   specification. Can be either:
-    #   - A ConstraintSpec from comparison operators: (x * 2 + y) <= 100
-    #   - An array of [var_index, coefficient] pairs with explicit bounds
-    # @param lb [Float] Lower bound for the constraint (used with array-style expr).
-    #   Default: -Float::INFINITY.
-    # @param ub [Float] Upper bound for the constraint (used with array-style expr).
-    #   Default: Float::INFINITY.
+    #   specification (DSL expression or legacy array format).
+    # @param lb [Float] Lower bound (default: -Inf).
+    # @param ub [Float] Upper bound (default: +Inf).
     # @return [Symbol] The constraint name.
-    # @example Using DSL comparison operators
-    #   model.add_constraint(:budget, (x * 2 + y) <= 100)
-    #   model.add_constraint(:demand, (x + y * 2) >= 50)
-    #   model.add_constraint(:balance, (x + y) == 10)
-    # @example Using legacy array format
-    #   model.add_constraint(:budget, [[x.index, 2], [y.index, 1]], ub: 100)
     def add_constraint(name, expr, lb: -Float::INFINITY, ub: Float::INFINITY)
       name = name.to_sym
 
@@ -189,39 +147,34 @@ module LpSolver
       name
     end
 
-    # Sets the optimization sense to minimization.
+    # Sets heading to minimize, sets the objective, and solves.
     #
-    # @return [void]
-    # @see #maximize
-    def minimize
-      @sense = :minimize
+    # @param objective [LinearExpression, QuadraticExpression, Hash{Integer => Float}] The objective.
+    # @return [Solution] The solution object.
+    # @raise [SolverError] If the solver encounters an error.
+    def minimize!(objective)
+      @heading = :minimize
+      set_objective_internal(objective)
+      solve
     end
 
-    # Sets the optimization sense to maximization.
+    # Sets heading to maximize, sets the objective, and solves.
     #
-    # @return [void]
-    # @see #minimize
-    def maximize
-      @sense = :maximize
+    # @param objective [LinearExpression, QuadraticExpression, Hash{Integer => Float}] The objective.
+    # @return [Solution] The solution object.
+    # @raise [SolverError] If the solver encounters an error.
+    def maximize!(objective)
+      @heading = :maximize
+      set_objective_internal(objective)
+      solve
     end
 
-    # Sets the objective function for the model.
-    #
-    # The objective function defines what the solver should optimize.
-    # It can be a linear expression (for LP), a quadratic expression
-    # (for QP), or a hash of coefficients (legacy format).
+    private
+
+    # Sets the objective function internally.
     #
-    # @param objective [LinearExpression, QuadraticExpression, Hash{Variable|Integer => Float}]
-    #   The objective function. Can be:
-    #   - A LinearExpression: `x * 3 + y * 5`
-    #   - A QuadraticExpression: `x * x + y * y + (x * y) * 2`
-    #   - A Hash mapping variable indices to coefficients: `{ x.index => 3.0, y.index => 5.0 }`
-    # @return [void]
-    # @example Linear objective
-    #   model.set_objective(x * 3 + y * 5)
-    # @example Quadratic objective (QP)
-    #   model.set_objective(x * x + y * y)
-    def set_objective(objective)
+    # @param objective [LinearExpression, QuadraticExpression, Hash{Integer => Float}] The objective.
+    def set_objective_internal(objective)
       if objective.is_a?(QuadraticExpression)
         @objective = objective.linear_terms.transform_values(&:to_f)
         @quadratic_terms = objective.hessian_entries
@@ -234,101 +187,11 @@ module LpSolver
       end
     end
 
-    # Solves the model and returns the solution.
-    #
-    # Serializes the model to HiGHS LP format, invokes the HiGHS solver,
-    # and parses the solution file to return a Solution object.
-    #
-    # @return [Solution] The solution object containing variable values,
-    #   objective value, and model status.
-    # @raise [SolverError] If the HiGHS solver encounters an error.
-    # @example
-    #   solution = model.solve
-    #   solution[:x]        # => optimal value for variable x
-    #   solution.objective_value  # => optimal objective value
-    #   solution.feasible?  # => true
-    def solve
-      lp_content = to_lp
-      lp_file = Tempfile.new(['model', '.lp'])
-      lp_file.write(lp_content)
-      lp_file.close
-
-      solution_file = Tempfile.new(['solution', '.sol'])
-      opts_file = Tempfile.new(['highs_opts', '.txt'])
-      opts_file.write("log_to_console = false\noutput_flag = false\n")
-      opts_file.close
-
-      cmd = "#{self.class::HIGHS_PATH} " \
-            "--model_file #{lp_file.path} " \
-            "--options_file #{opts_file.path} " \
-            "--solution_file #{solution_file.path}"
-
-      output = `#{cmd} 2>&1`
-      status = $?.success?
-
-      lp_file.unlink
-      opts_file.unlink
-
-      raise SolverError, "HiGHS solver failed:\n#{output}" unless status
-
-      @solution = parse_solution_file(solution_file.path)
-      solution_file.unlink
-      @solution
-    end
-
-    # Sets the optimization sense to minimization, sets the objective,
-    # and solves the model in a single call.
-    #
-    # This is a convenience method that combines #minimize, #set_objective,
-    # and #solve into one step.
-    #
-    # @param objective [LinearExpression, QuadraticExpression, Hash{Variable|Integer => Float}]
-    #   The objective function to minimize. Can be:
-    #   - A LinearExpression: `x * 3 + y * 5`
-    #   - A QuadraticExpression: `x * x + y * y + (x * y) * 2`
-    #   - A Hash mapping variable indices to coefficients: `{ x.index => 3.0, y.index => 5.0 }`
-    # @return [Solution] The solution object containing variable values,
-    #   objective value, and model status.
-    # @raise [SolverError] If the HiGHS solver encounters an error.
-    # @example
-    #   solution = model.minimize!(x * 3 + y * 5)
-    #   puts solution.objective_value  # => optimal (minimum) value
-    # @example Quadratic minimization (QP)
-    #   solution = model.minimize!(x * x + y * y)
-    def minimize!(objective)
-      @sense = :minimize
-      set_objective(objective)
-      solve
-    end
-
-    # Sets the optimization sense to maximization, sets the objective,
-    # and solves the model in a single call.
-    #
-    # This is a convenience method that combines #maximize, #set_objective,
-    # and #solve into one step.
-    #
-    # @param objective [LinearExpression, QuadraticExpression, Hash{Variable|Integer => Float}]
-    #   The objective function to maximize. Can be:
-    #   - A LinearExpression: `x * 3 + y * 5`
-    #   - A QuadraticExpression: `x * x + y * y + (x * y) * 2`
-    #   - A Hash mapping variable indices to coefficients: `{ x.index => 3.0, y.index => 5.0 }`
-    # @return [Solution] The solution object containing variable values,
-    #   objective value, and model status.
-    # @raise [SolverError] If the HiGHS solver encounters an error.
-    # @example
-    #   solution = model.maximize!(x * 3 + y * 5)
-    #   puts solution.objective_value  # => optimal (maximum) value
-    def maximize!(objective)
-      @sense = :maximize
-      set_objective(objective)
-      solve
-    end
+    public
 
     # Converts the model to HiGHS LP format string.
     #
-    # The LP format is a text-based representation of the optimization
-    # problem that HiGHS can read. It includes the objective function,
-    # constraints, variable bounds, and integer declarations.
+    # Delegates to LpGenerator for serialization.
     #
     # @return [String] The LP format content.
     # @example
@@ -343,84 +206,7 @@ module LpSolver
     #   #  0 <= y <= +Inf
     #   # End
     def to_lp
-      lines = []
-
-      # Objective
-      lines << (@sense == :minimize ? 'Minimize' : 'Maximize')
-
-      obj_terms = @objective.map do |var_idx, coeff|
-        var_name = find_var_name(var_idx)
-        "#{format_coeff(coeff)} #{sanitize_name(var_name)}"
-      end.join(' + ')
-
-      if @quadratic_terms.any?
-        quad_parts = @quadratic_terms.map do |i1, i2, coeff|
-          n1 = sanitize_name(find_var_name(i1))
-          n2 = sanitize_name(find_var_name(i2))
-          if i1 == i2
-            "#{format_coeff(coeff)} #{n1} ^ 2"
-          else
-            "#{format_coeff(coeff)} #{n1} * #{n2}"
-          end
-        end.join(' + ')
-        lines << " obj: #{obj_terms} + [ #{quad_parts} ] / 2"
-      else
-        lines << " obj: #{obj_terms}"
-      end
-
-      # Constraints
-      if @constraints.any?
-        lines << 'Subject To'
-        @constraints.each do |name, _idx|
-          data = @constraints_data[name]
-          terms = data[:expr].map do |var_idx, coeff|
-            var_name = find_var_name(var_idx)
-            "#{format_coeff(coeff)} #{sanitize_name(var_name)}"
-          end.join(' + ')
-
-          if data[:lb] == -Float::INFINITY && data[:ub] == Float::INFINITY
-            lines << " #{sanitize_name(name)}: #{terms} free"
-          elsif data[:lb] == -Float::INFINITY
-            lines << " #{sanitize_name(name)}: #{terms} <= #{format_bound(data[:ub])}"
-          elsif data[:ub] == Float::INFINITY
-            lines << " #{sanitize_name(name)}: #{terms} >= #{format_bound(data[:lb])}"
-          elsif (data[:ub] - data[:lb]).abs < 1e-12
-            lines << " #{sanitize_name(name)}: #{terms} = #{format_bound(data[:lb])}"
-          else
-            lines << " #{sanitize_name(name)}: #{terms} >= #{format_bound(data[:lb])}"
-            lines << " #{sanitize_name(name)}_ub: #{terms} <= #{format_bound(data[:ub])}"
-          end
-        end
-      end
-
-      # Bounds
-      if @var_bounds.any?
-        lines << 'Bounds'
-        @variables.each do |name, _var|
-          lb, ub = @var_bounds[name]
-          sname = sanitize_name(name)
-
-          if lb == ub
-            lines << " #{sname} = #{format_bound(lb)}"
-          elsif lb > -Float::INFINITY && ub < Float::INFINITY
-            lines << " #{lb} <= #{sname} <= #{format_bound(ub)}"
-          elsif lb > -Float::INFINITY
-            lines << " #{sname} >= #{format_bound(lb)}"
-          elsif ub < Float::INFINITY
-            lines << " #{sname} <= #{format_bound(ub)}"
-          end
-        end
-      end
-
-      # Integer variables
-      int_vars = @variables.select { |sym, _| @var_types[sym] == :integer }
-      if int_vars.any?
-        lines << 'Integers'
-        int_vars.each { |name, _| lines << " #{sanitize_name(name)}" }
-      end
-
-      lines << 'End'
-      lines.join("\n")
+      LpGenerator.new(self).generate
     end
 
     # Writes the model to an LP file.
@@ -433,28 +219,16 @@ module LpSolver
       File.write(filename, to_lp)
     end
 
-    # Returns all variables defined in this model.
+    # Sets the solver driver.
     #
-    # @return [Hash{Symbol => Variable}] Maps variable names (Symbols) to
-    #   their Variable objects.
-    # @example
-    #   model.variables
-    #   # => { :x => @x(0), :y => @y(1) }
-    def variables
-      @variables
+    # @param driver [Drivers::CliDriver, Drivers::NativeDriver] The driver to use for solving.
+    def driver=(driver)
+      @driver = driver
     end
 
     private
 
-    # Looks up a variable name by its internal index.
-    #
-    # @param idx [Integer] The internal variable index.
-    # @return [String] The variable name, or "v#{idx}" if not found.
-    def find_var_name(idx)
-      @variables.find { |_, var| var.index == idx }&.first || "v#{idx}"
-    end
-
-    # Normalizes bound values for LP format output.
+    # Normalizes bound values for internal storage.
     #
     # Converts special infinity values to their canonical forms.
     #
@@ -463,82 +237,7 @@ module LpSolver
     def normalize_bound(val)
       return -Float::INFINITY if val == -Float::INFINITY || val == -1.0 / 0.0
       return Float::INFINITY if val == Float::INFINITY || val == 1.0 / 0.0
-
       val.to_f
     end
-
-    # Formats a coefficient for LP output.
-    #
-    # Integers are output without decimal points for readability.
-    #
-    # @param value [Float] The coefficient value.
-    # @return [String] The formatted coefficient string.
-    def format_coeff(value)
-      if value == value.to_i && value.abs < 1e15
-        value.to_i.to_s
-      else
-        format('%.6g', value)
-      end
-    end
-
-    # Formats a bound value for LP output.
-    #
-    # @param value [Float] The bound value.
-    # @return [String] The formatted bound string (+Inf, -Inf, or numeric).
-    def format_bound(value)
-      return '+Inf' if value == Float::INFINITY
-      return '-Inf' if value == -Float::INFINITY
-
-      format_coeff(value)
-    end
-
-    # Sanitizes a name for LP format (no spaces, special characters).
-    #
-    # @param name [String, Symbol] The name to sanitize.
-    # @return [String] The sanitized name (max 32 characters).
-    def sanitize_name(name)
-      name.to_s.gsub(/[^a-zA-Z0-9_]/, '_')[0, 32]
-    end
-
-    # Parses the HiGHS solution file.
-    #
-    # Extracts variable values, objective value, and model status from
-    # the solution file format produced by HiGHS.
-    #
-    # @param path [String] The path to the HiGHS solution file.
-    # @return [Solution] The parsed solution object.
-    def parse_solution_file(path)
-      content = File.read(path)
-      variables = {}
-      objective_value = 0.0
-      model_status = 'unknown'
-      iterations = 0
-
-      status_match = content.match(/Model status\s*\n\s*(\S+)/i)
-      model_status = status_match[1].downcase.gsub('_', ' ') if status_match
-
-      obj_match = content.match(/Objective\s+(\S+)/i)
-      objective_value = obj_match[1].to_f if obj_match
-
-      in_columns = false
-      content.each_line do |line|
-        if line =~ /# Columns/i
-          in_columns = true
-          next
-        end
-        next unless in_columns
-        break if line.strip.empty? || line.start_with?('#')
-
-        parts = line.strip.split(/\s+/, 2)
-        variables[parts[0]] = parts[1].to_f if parts.length == 2
-      end
-
-      Solution.new(
-        variables: variables,
-        objective_value: objective_value,
-        model_status: model_status,
-        iterations: iterations
-      )
-    end
   end
 end

data/lib/lpsolver/solution.rb

@@ -21,11 +21,15 @@ module LpSolver
     # @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.
+    #   When the solution is infeasible, this hash is empty.
+    #   Always check `infeasible?` or `unbounded?` before reading 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.
+    #   When the solution is infeasible, this returns `0.0`.
+    #   Always check `infeasible?` or `unbounded?` before reading this value.
     attr_reader :objective_value
 
     # @return [String] The status of the model as reported by HiGHS.
@@ -40,6 +44,19 @@ module LpSolver
     #   This is a diagnostic metric; may be 0 for some solver types.
     attr_reader :iterations
 
+    # Returns the model status as a Symbol.
+    #
+    # @return [Symbol] The solver status as a Ruby symbol:
+    #   - :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.
+    # @example
+    #   solution.status  # => :optimal
+    def status
+      @model_status.to_sym
+    end
+
     # Creates a new Solution object.
     #
     # @param variables [Hash{String => Float}] Maps variable names to values.
@@ -57,12 +74,15 @@ module LpSolver
     #
     # @param name [Symbol, String, Variable] The variable name (Symbol, String,
     #   or Variable object).
-    # @return [Float] The optimal value of the variable.
+    # @return [Float] The optimal value of the variable, or `nil` if the
+    #   solution is infeasible or unbounded.
     # @raise [KeyError] If the variable name is not found in the solution.
     # @example
     #   solution[:x]        # => 4.0 (by symbol)
     #   solution['x']       # => 4.0 (by string)
     #   solution[x]         # => 4.0 (by Variable object)
+    # @note When the solution is infeasible, all variables are empty.
+    #   Check `infeasible?` first before accessing variable values.
     def [](name)
       key = if name.is_a?(Variable)
         name.name.to_s

data/lib/lpsolver/version.rb

@@ -4,5 +4,5 @@ module LpSolver
   # The current version of the LpSolver gem.
   #
   # @return [String] The version string (e.g., "0.1.0").
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/lpsolver.rb

@@ -15,10 +15,7 @@
 #   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
+#   solution = model.minimize!(x * 3 + y * 5)
 #   puts solution.objective_value  # => 12.0
 #
 # @see LpSolver::Model
@@ -39,3 +36,12 @@ require_relative 'lpsolver/quadratic_expression'
 # Solvers and data classes
 require_relative 'lpsolver/solution'
 require_relative 'lpsolver/model'
+require_relative 'lpsolver/lp_generator'
+require_relative 'lpsolver/drivers'
+
+# Native extension (optional — only available if compiled)
+begin
+  require_relative 'lpsolver/native'
+rescue LoadError
+  # Native extension not compiled — NativeDriver will raise LoadError at runtime
+end