solver 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a7e3863747205d299960de14f4f6fb574d435661
-  data.tar.gz: 5d6eacf431b01313d025970c61b0d1dac0a16b13
+  metadata.gz: 494437a765172c4f950dc9f9b0d802b865bca747
+  data.tar.gz: 9f8454f7e3891a57cadd13eaba761cf4e13aeaf9
 SHA512:
-  metadata.gz: a0d8c29f097fee10546696c1ae8d992286dd96e1c892fec7acdb56a069660bd5c0b539ef04cbdb42e0a6d5c5fe43ca24c0792866604162ae170a6a4aed0c9ed8
-  data.tar.gz: 3778ce82d42956f7df0c02959e5e20264e6095881e480d617917ad53ff9e24d1f7491e4c54597936b99cb9adfc8f9cbffcba749a1834efda11abd64addb74d7f
+  metadata.gz: 9f152b61a7089fb97991f7624d97814f27a149b964f717e54ff397a942441beb0302d8dde8320015ee7445407ffaf6afbd3b45810a1f042bf0272372b3dc1f9b
+  data.tar.gz: 94b62848a1e693e6b2a51d55f8a29bf3c6835ccdc60ef131cc50cb537cbf07f3ae285e5c9ed875be7d9632456c77b2ecce38d6c7124be29438d27393231bdd0a

data/README.md

@@ -0,0 +1,88 @@
+# solver
+
+This numeric solver is an example of the use of Flt.
+
+## Examples
+
+Solve equation `2*exp(x)-10=0` using Float, with a tolerance of 10 decimal places,
+using the `SecantSolver` algorithm and with initial guesses of 0, 10:
+
+```ruby
+require 'solver'
+equation = ->(x){ 2*exp(x)-10 }
+algorithm = Flt::Solver::SecantSolver
+tolerance = Flt::Tolerance(10, :decimals)
+solver = algorithm.new(Float.context, tolerance, &equation)
+puts solver.root(0, 10) # => 1.6094379124341003
+```
+
+Now, solve the same equation, with the same algorithm, but requiring greater
+accuracy and using a higher precision numeric type:
+
+```ruby
+tolerance = Flt::Tolerance(25, :decimals)
+solver = algorithm.new(Flt::DecNum.context(precision: 30), tolerance, &equation)
+puts solver.root(0, 10) # => DecNum('1.609437912434100374600759333')
+```
+
+Let's compute the same using a different algorithm:
+
+```ruby
+algorithm = Flt::Solver::RFSecantSolver
+solver = algorithm.new(Flt::DecNum.context(precision: 30), tolerance, &equation)
+puts solver.root(0, 10) # => DecNum('1.609437912434100374600759333')
+```
+
+The `PSolver` class can be used to define an equation with multiple parameters, then
+solve for any of them.
+
+Let's define an equation to compute the *Time Value of Money* (i.e. compound interest):
+
+```ruby
+tvm_equation = ->(future_value, time, present_value, payment, interest, payments_per_year) {
+  i = interest/100/payments_per_year
+  n = -time
+  k = (i + 1)**n # not the right way to compute it!
+  present_value + payment*(1-k)/i + future_value*k
+}
+```
+
+Note that computing `(i + 1)**n` as in this example is not a good idea, see the `TVM`
+class for a better approach.
+
+Now let's use `PSolver` to solve this equation for any of its paramters:
+
+```ruby
+tvm_solver = Flt::Solver::PSolver.new(
+  Flt::DecNum.context,
+  Flt.Tolerance(2,:decimals),
+  &tvm_equation
+)
+```
+
+For example, let's compute the monthly payment of a loan of $150,000, to be paid in twenty years
+with a 7% interest rate:
+
+```ruby
+pmt = tvm_solver.root(
+  :payment,
+  present_value: 150000,
+  future_value: 0,
+  time: 20*12,
+  interest: 7,
+  payments_per_year: 12
+)
+puts s.round(2) # => -1162.95
+```
+
+A better (more accurate) financial solver is implemented by the `TVM` class:
+
+```ruby
+tvm = Flt::Solver::TVM.new(Flt.Tolerance(2,:decimals), Flt::DecNum.context)
+solution = tvm.solve(t: 20*12, m0: 150000, m: 0, i: 7, p: 12)
+puts solution[:pmt].round(2) # => -1162.95
+```
+
+# Licensing
+
+Copyright (c) 2010 Javier Goizueta. See LICENSE for details.

data/lib/solver.rb

@@ -1,4 +1,5 @@
 require 'flt/math'
+require 'flt/tolerance'
 
 require 'solver/version'
 require 'solver/function'

data/lib/solver/base.rb

@@ -6,13 +6,27 @@ module Flt::Solver
 
 class Base
 
+  # Admitted options:
+  #
+  # * :context : Numerical context (e.g. Flt::Decimal::Context) Float by default
+  # * :default_guesses : default initial guesses
+  # * :tolerance : numerical tolerance
+  # * :equation : equation to be solved; can also be passed as a block
+  #
   # default_guesses: nil for no pre-guess, or one or two guesses (use array for two)
-  def initialize(context, default_guesses, tol, eqn=nil, &blk)
-    @context = context
-    @default_guesses = Array(default_guesses)
+  #
+  # The values of any of the parameters can also be passed as arguments
+  # (not in the options Hash, if present) in any order, e.g.:
+  #
+  #   Solver::Base.new Flt::DecNum.context, tolerance: Flt::Tolerance(3, :decimals)
+  #
+  def initialize(*args, &blk)
+    options = Base.extract_options(*args, &blk)
+    @context = options[:context] || Float.context
+    @default_guesses = Array(options[:default_guesses])
     @x = @default_guesses.first
-    @f = eqn || blk
-    @tol = tol # user-requested tolerance
+    @f = options[:equation]
+    @tol = options[:tolerance] # user-requested tolerance
     @max_it = 8192
     reset
   end
@@ -25,8 +39,6 @@ class Base
     @conv = false
   end
 
-  # value of parameters[var] is used as a guess in precedence to the pre-guesses if not nil
-  # use Array for two guesses
   def root(*guesses)
     @guess = (guesses + @default_guesses).map{|g| num(g)}
     reset
@@ -36,7 +48,7 @@ class Base
     @conv = false
 
     # Minimum tolerance of the numeric type used
-    @numeric_tol = Tolerance(1,:ulps) # Tolerance(@context.epsilon, :floating)
+    @numeric_tol = Flt::Tolerance(1,:ulps) # Tolerance(@context.epsilon, :floating)
 
     raise "Invalid parameters" unless validate
 
@@ -107,6 +119,30 @@ class Base
     true
   end
 
+  def self.extract_options(*args, &blk)
+    options = {}
+    args.each do |arg|
+      case arg
+      when Hash
+        options.merge! arg
+      when Flt::Num::ContextBase, Flt::FloatContext
+        options.merge! context: arg
+      when Array, Numeric
+        options.merge! default_guesses: Array(arg)
+      when Proc
+        options.merge! equation: arg
+      when Flt::Tolerance
+        options.merge! tolerance: arg
+      when Base
+        options.merge! solver_class: arg
+      else
+        raise "Invalid Argument #{arg.inspect}"
+      end
+    end
+    options[:equation] ||= blk
+    options
+  end
+
 end # Base
 
 end # Flt::Solve

data/lib/solver/psolver.rb

@@ -1,7 +1,7 @@
 module Flt::Solver
-  
+
   # Solver with equation parameters passed in a hash
-  # 
+  #
   # Example: a simple TVM (Time Value of Money) solver
   #
   #   # ln(x+1)
@@ -9,7 +9,7 @@ module Flt::Solver
   #     v = x + 1
   #     (v == 1) ? x : (x*ln(v) / (v - 1))
   #   end
-  # 
+  #
   #   tvm = Flt::Solver::PSolver.new(Float.context, Flt.Tolerance(3,:decimals)) do |m, t, m0, pmt, i, p|
   #     i /= 100
   #     i /= p
@@ -23,20 +23,20 @@ module Flt::Solver
   #   puts sol.inspect # => -55.45975978539105
   #
   class PSolver
-    
-    def initialize(context, tol, solver_class=nil, &blk)
 
-      @solver_class = solver_class || RFSecantSolver
-      @eqn = blk
+    def initialize(*args, &blk)
+      options = Base.extract_options(*args, &blk)
+
+      @solver_class = options[:solver_class] || RFSecantSolver
+      @eqn = options[:equation]
       @vars = Function.parameters(@eqn)
       # alternatively, we could keep @eqn = Function[@eqn] and dispense with @vars
 
-      @default_guesses = nil
+      @default_guesses = options[:default_guesses]
 
-      @context = context
-      @tol = tol
+      @context = options[:context]
+      @tol = options[:tolerance]
       @solver = nil
-
     end
 
     def default_guesses=(*g)
@@ -55,16 +55,20 @@ module Flt::Solver
     def equation_value(v)
       values = @parameters.merge(@var=>v)
       #@context.math(*values.values_at(*@vars).map{|v| @context.Num(v)}, &@eqn)
-      @context.math(*@vars.map{|v| @context.Num(values[v])}, &@eqn)
+      @context.math(*@vars.map{|v| values[v] && @context.Num(values[v])}.compact, &@eqn)
       # equivalent to: @context.math(values, &Function[@eqn]) # which doesn't need @vars
     end
 
     private
     def init_solver
       this = self
-      @solver ||= @solver_class.new(@context, @default_guesses, @tol){|v| this.equation_value(v)}
+      @solver ||= @solver_class.new(
+                    context: @context,
+                    default_guesses: @default_guesses,
+                    tolerance: @tol
+                  ) { |v| this.equation_value(v) }
     end
 
   end
 
-end # Flt::PSolver
+end # Flt::PSolver

data/lib/solver/rfsecant.rb

@@ -1,8 +1,8 @@
 module Flt::Solver
-  
+
   # Regula-Falsi/Secant method solver
   # Secant is used if no bracketing is available
-  # 
+  #
   # Example of use:
   #   require 'solver'
   #   include Flt
@@ -21,12 +21,12 @@ module Flt::Solver
   #
   class RFSecantSolver < Base
 
-    def initialize(context, default_guesses, tol, eqn=nil, &blk)
-      super context, default_guesses, tol, eqn, &blk
+    def initialize(*args, &blk)
+      super
       @half = num(Rational(1,2))
       reset
     end
-    
+
     def reset
       super
       @a = @b = @fa = @fb = nil
@@ -85,5 +85,5 @@ module Flt::Solver
     end
 
   end  # RFSecantSolver
-  
-end # Flt::Solver
+
+end # Flt::Solver

data/lib/solver/secant.rb

@@ -1,11 +1,10 @@
 module Flt::Solver
-  
+
   # Secant method solver
   # Bisect method is used is bracketing found (sign(f(a)) != sign(f(b)))
-  # 
+  #
   # Example of use:
   #   require 'solver'
-  #   require 'flt/tolerance'
   #   include Flt
   #   solver = Solver::SecantSolver.new(Float.context, [0.0, 100.0], Tolerance(3, :decimals)) do |x|
   #     2*x+11.0
@@ -22,12 +21,12 @@ module Flt::Solver
   #
   class SecantSolver < Base
 
-    def initialize(context, default_guesses, tol, eqn=nil, &blk)
-      super context, default_guesses, tol, eqn, &blk
+    def initialize(*args, &blk)
+      super
       @half = num(Rational(1,2))
       reset
     end
-    
+
     def reset
       super
       @a = @b = @fa = @fb = nil
@@ -85,5 +84,5 @@ module Flt::Solver
     end
 
   end # SecantSolver
-  
-end # Flt::Solver
+
+end # Flt::Solver

data/lib/solver/tvm.rb

@@ -1,11 +1,11 @@
 module Flt::Solver
 
   # A Time-Value-of-Money solver
-  # 
+  #
   # Example:
   #   tvm = TVM.new(Tolerance(3, :decimals), Float.context)
   #   puts tvm.solve(:t=>240, :m0=>10000, :m=>0, :i=>3, :p=>12).inspect # => {:pmt=>-55.45975978539105}
-  #   
+  #
   class TVM
 
     def initialize(tol, context=Float.context)
@@ -69,4 +69,4 @@ module Flt::Solver
 
   end # TVM
 
-end # Flt::Solver
+end # Flt::Solver

data/lib/solver/version.rb

@@ -1,5 +1,5 @@
 module Flt
   module Solver
-    VERSION = "0.1.2"
+    VERSION = "0.2.0"
   end
 end

data/solver.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "flt", '~> 1.3.1'
+  spec.add_runtime_dependency "flt", '~> 1.5'
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "minitest"

data/test/test_secant.rb

@@ -32,6 +32,32 @@ class TestSecant < MiniTest::Unit::TestCase
         assert_in_delta 1.6094389956808506, solver.root(1.0), @delta
         assert_in_delta 1.6094389956808506, solver.root(2.0), @delta
       end
+
+      should "be flexible with the solver parameters" do
+        solver = Flt::Solver::SecantSolver.new(@context, default_guesses: [0.0, 10.0], tolerance: @tolerance) do |x|
+          y = 2
+          y*exp(x)-10
+        end
+        assert_in_delta 1.6094389956808506, solver.root, @delta
+        assert_in_delta 1.6094389956808506, solver.root(1.0), @delta
+        assert_in_delta 1.6094389956808506, solver.root(2.0), @delta
+
+        solver = Flt::Solver::SecantSolver.new(context: @context, default_guesses: [0.0, 10.0], tolerance: @tolerance) do |x|
+          y = 2
+          y*exp(x)-10
+        end
+        assert_in_delta 1.6094389956808506, solver.root, @delta
+        assert_in_delta 1.6094389956808506, solver.root(1.0), @delta
+        assert_in_delta 1.6094389956808506, solver.root(2.0), @delta
+
+        solver = Flt::Solver::SecantSolver.new(@tolerance, @context, [0.0, 10.0]) do |x|
+          y = 2
+          y*exp(x)-10
+        end
+        assert_in_delta 1.6094389956808506, solver.root, @delta
+        assert_in_delta 1.6094389956808506, solver.root(1.0), @delta
+        assert_in_delta 1.6094389956808506, solver.root(2.0), @delta
+      end
     end
 
     context "using DecNum arithmetic" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solver
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Javier Goizueta
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-21 00:00:00.000000000 Z
+date: 2015-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: flt
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.3.1
+        version: '1.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.3.1
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -91,7 +91,7 @@ files:
 - ".gitignore"
 - Gemfile
 - LICENSE
-- README.rdoc
+- README.md
 - Rakefile
 - lib/solver.rb
 - lib/solver/base.rb

data/README.rdoc

@@ -1,5 +0,0 @@
-= solver
-
-This numeric solver is an example of the use of Flt.
-
-Copyright (c) 2010 Javier Goizueta. See LICENSE for details.