rical 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b1ce7f2b2a92c5a7b58a2328a98fcabfdc447efa
-  data.tar.gz: a26b4642e560f673200ed22f2e5d20de2dceb517
+  metadata.gz: 773c7c61e53f2619431d5434ee3454d966485e7a
+  data.tar.gz: 0864d8f3304f2b33347a67ac4aaaa93cee40439d
 SHA512:
-  metadata.gz: 4957d9249119585429d3c9ea2e331a73613898d50b2691c2d7dcb7b47ed55863526c8b295424296ccc5c901dbeb06d5d612fb956968239df7276b2a7016affec
-  data.tar.gz: 10a861d8159996d6dd080f69d549c03a8ed42bc2e8206fa511986c64df9fd24a3d34cf347b6042c32e52fe7b854a134989321e82931d55a188b5e6dceb0380e2
+  metadata.gz: 43242221a009ccb3d056639ac56e5edafdffd93ed9904f6775c11164429c5360073d2c9d27a9e49f8a582d87df0d4b12962f4da74f8d2ae68ea6965da563aa24
+  data.tar.gz: 9a003ea7281176124258f083c1a6ea0000bf228b80dc01b191c777caf61572f0be8604176a836c9251494a4300b305aff600999b205132a6a10f9da75db2a9c7

data/README.md

@@ -3,21 +3,26 @@
 
 Using Newton-Raphson or Secant methods, and within an arbitrary error:
 
-* Computes the values of a root of an arbitrary function _f(x)_
-* Computes the value of inverse function _f<sup>-1</sup>(y) = x_ at point _y_
+* Computes the values of a root of an arbitrary function _f(x, a, b, ...)_
+* Computes the value of inverse function _f<sup>-1</sup>(y, a, b, ...) = x_ at point _y_
+* Handles functions _f(x, a, b, ...)_, when fixed _f<sub>args</sub>_ = _a, b, ..._ are set
+* Handles additional function arguments either as Array or Hash (matching positional or named parameters)
 
 The Newton-Raphson requires:
 
 * one "close enough" estimate - _x<sub>0</sub>_ - of the root or inverse value
-* the derivative function _f'(x)_
+* the derivative function _f'(x, a, b, ...)_
+* _f<sub>args</sub>_ containing _a, b, ..._ when existing
+* _f'<sub>args</sub>_ containing _a, b, ..._ when existing (Note _f<sub>args</sub>_ are independent of _f'<sub>args</sub>_)
 
 The Secant method requires:
 
 * two "close enough" estimates - _x<sub>0</sub>_, _x<sub>1</sub>_ - of the root or inverse value
+* _f<sub>args</sub>_ containing _a, b, ..._ when existing
 
-If the estimates are not "close enough" (and what that means depends on _f(x)_), the methods may not converge to a solution.
+If the estimates are not "close enough" (and what that means depends on _f(x, a, b, ...)_), the methods may not converge to a solution.
 This may also happen for a "low" number of iterations and/or a "low" error limit.
-When no convergence is possible on the set conditions, a **`NoConvergenceError`** is raised.
+When no convergence is possible on the set conditions, a `NoConvergenceError` is raised.
 
 
 ## Installation
@@ -42,26 +47,30 @@ Or install it yourself as:
 1. Set function(s) as lambdas
 
 ```ruby
-fx  = -> (x) { x**2 - 1 }
-dfx = -> (x) { 2*x }
+fx1  = -> (x) { x**2 - 2 }
+dfx1 = -> (x) { 2*x }
 ```
 
 or set function(s) as Proc
 
 ```ruby
-fx = Proc.new do |x|
-  x**2 - 1
+fx2 = Proc.new do |x, a, b|
+  a*x**2 + b
+end
+
+dfx2 = Proc.new do |x, a|
+  2*a*x
 end
 ```
 
 or set function(s) as existing method(s)
 
 ```ruby
-def f(x)
-  x**2 - 1
+def f3(x, a:, b:)
+  a*x**2 + b
 end
 
-fx = method(:f)
+fx3 = method(:f3)
 ```
 
 2. Call `root_for` of `inverse_for` passing function(s) and estimate(s):
@@ -69,8 +78,12 @@ fx = method(:f)
 **Newton-Raphson's Method**
 
 ```ruby
-Rical.root_for f: fx, df: dfx, x0: 1.0, method: :newtonr_raphson    # :newton_raphson aliased to :n, :newton
-Rical.inverse_for f: fx, df: dfx, x0: 1.0, y: 2.0, method: :newton
+Rical.root_for f: fx1, df: dfx1, x0: 1.0, method: :newton_raphson    # :newton_raphson aliased to :n, :newton
+Rical.inverse_for f: fx1, df: dfx1, x0: 1.0, y: 2.0, method: :newton
+
+# with fargs and dfargs
+Rical.root_for f: fx2, fargs: [1, -2], df: dfx2, dfargs: 2, x0: 1.0, method: :newton
+Rical.root_for f: fx3, fargs: { a: 1, b: -2 }, df: dfx3, dfargs: { a: 2 }, x0: 1.0, method: :newton
 ```
 
 **Secant's Method**
@@ -78,6 +91,9 @@ Rical.inverse_for f: fx, df: dfx, x0: 1.0, y: 2.0, method: :newton
 ```ruby
 Rical.root_for f: fx, x0: 0.0, x1: 1.0, method: :secant              # :secant aliased to :sec, :s
 Rical.inverse_for f: fx, x0: 0.0, x1: 1.0, y: 2.0, method: :secant
+
+# with fargs and dfargs
+Rical.inverse_for f: fx, fargs: [1, -2], x0: 0.0, x1: 1.0, y: 2.0, method: :secant
 ```
 
 3. Change number of iterations - _num_ - or maximum allowable error - _err_ - if needed:

data/lib/rical.rb

@@ -4,16 +4,18 @@ require 'rical/errors'
 module Rical
   extend self
 
-  def root_for f:, df: nil, x0: 0.0, x1: 1.0, method:, num: 100, err: 1e-6
+  def root_for f:, fargs: nil,
+               df: nil, dfargs: nil,
+               x0: 0.0, x1: 1.0, method:, num: 100, err: 1e-6
     raise ArgumentError, 'f must respond_to call'    unless f.respond_to? :call
 
     case method
     when :n, :newton, :newton_raphson
       raise ArgumentError, 'df is required'          unless df
       raise ArgumentError, 'df must respond_to call' unless df.respond_to? :call
-      newton_raphson_root_for f, df, Float(x0), num, err
+      newton_raphson_root_for f, fargs, df, dfargs, Float(x0), num, err
     when :s, :sec, :secant
-      secant_root_for f, Float(x0), Float(x1), num, err
+      secant_root_for f, fargs, Float(x0), Float(x1), num, err
     else
       raise ArgumentError, 'unexpected method (allowed :newton, :secant)'
     end
@@ -26,24 +28,33 @@ module Rical
   alias_method :inv_for, :inverse_for
 
 private
-  def newton_raphson_root_for f, df, x, n, err
+  def newton_raphson_root_for f, fargs, df, dfargs, x, n, err
     n.times do
-      dfx = df.call x
+      fx  = compute  f, x, fargs
+      dfx = compute df, x, dfargs
       dfx = [1e-3, err * 1e3].max if dfx == 0.0
-      x = x - ( f.call(x) / dfx )
-      return x if f.call(x).abs < err
+      x = x - ( fx / dfx )
+      return x if compute(f, x, fargs).abs < err
     end
     raise NoConvergenceError
   end
 
-  def secant_root_for f, x0, x1, n, err
+  def secant_root_for f, fargs, x0, x1, n, err
     n.times do
-      delta = f.call(x1) - f.call(x0)
+      fx0 = compute f, x0, fargs
+      fx1 = compute f, x1, fargs
+      delta = fx1 - fx0
       delta = [1e-3, err * 1e3].max if delta == 0.0
-      x = x1 - (f.call(x1) * (x1 - x0)) / delta
-      return x if f.call(x).abs < err
+      x = x1 - (fx1 * (x1 - x0)) / delta
+      return x if compute(f, x, fargs).abs < err
       x0, x1 = x1, x
     end
     raise NoConvergenceError
   end
+
+  def compute f, x, fargs
+    return f.call x          unless fargs
+    return f.call x, **fargs if     fargs.is_a? Hash
+    return f.call x, *fargs
+  end
 end

data/lib/rical/version.rb

@@ -1,3 +1,3 @@
 module Rical
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/spec/rical_spec.rb

@@ -1,27 +1,45 @@
 require 'spec_helper'
 
 describe Rical do
-  f  = -> (x) { x**2 - 2 }
-  df = -> (x) { 2*x }
+  f1  = -> (x) { x**2 - 2 }
+  df1 = -> (x) { 2*x }
 
   context 'Newton-Raphson method' do
     context 'root computation' do
       it 'yields +√2 for f(x) = x²-2' do
-        expect(Rical.root_for f: f, df: df, x0: 10, method: :newton).to be_within(1e-6).of(2**0.5)
+        expect(Rical.root_for f: f1, df: df1, x0: 10, method: :newton).to be_within(1e-6).of(2**0.5)
       end
 
       it 'yields -√2 for f(x) = x²-2' do
-        expect(Rical.root_for f: f, df: df, x0: -10, method: :newton).to be_within(1e-6).of(-2**0.5)
+        expect(Rical.root_for f: f1, df: df1, x0: -10, method: :newton).to be_within(1e-6).of(-2**0.5)
       end
 
       it 'rescues when df(x0) = 0' do
-        expect(Rical.root_for f: f, df: df, x0: 0.0, method: :newton).to be_within(1e-6).of(2**0.5)
+        expect(Rical.root_for f: f1, df: df1, x0: 0.0, method: :newton).to be_within(1e-6).of(2**0.5)
+      end
+
+      it 'passes extra arguments (array) to f' do
+        f2  = -> (x, a, b) { a*x**2 + b }    # f2  = f1  for a=1, b=-2
+        df2 = -> (x, a)    { a*x }           # df2 = df1 for a=2
+        expect(Rical.root_for f:  f2,  fargs:  [1, -2],
+                              df: df2, dfargs: 2,
+                              x0: 10,
+                              method: :newton).to be_within(1e-6).of(2**0.5)
+      end
+
+      it 'passes extra arguments (hash) to f' do
+        f3  = -> (x, a:, b:) { a*x**2 + b }   # f3  = f1  for { a: 1, b: -2 }
+        df3 = -> (x, a:)    { a*x }           # df3 = df1 for { a: 2 }
+        expect(Rical.root_for f:  f3,  fargs:  { a: 1, b: -2 },
+                              df: df3, dfargs: { a: 2 },
+                              x0: 10,
+                              method: :newton).to be_within(1e-6).of(2**0.5)
       end
     end
 
     context 'inverse computation' do
       it 'yields +2.0 for y=2, f(x)=y=x²-2' do
-        expect(Rical.inverse_for f: f, df: df, y: 2, x0: 0, method: :newton).to be_within(1e-6).of(2.0)
+        expect(Rical.inverse_for f: f1, df: df1, y: 2, x0: 0, method: :newton).to be_within(1e-6).of(2.0)
       end
     end
 
@@ -30,48 +48,53 @@ describe Rical do
   context 'Secant method' do
     context 'root computation' do
       it 'yields +√2 for f(x) = x²-2' do
-        expect(Rical.root_for f: f, x0: 10, x1: 9, method: :secant).to be_within(1e-6).of(2**0.5)
+        expect(Rical.root_for f: f1, x0: 10, x1: 9, method: :secant).to be_within(1e-6).of(2**0.5)
       end
 
       it 'yields -√2 for f(x) = x²-2' do
-        expect(Rical.root_for f: f, x0: -10, x1: -9, method: :secant).to be_within(1e-6).of(-2**0.5)
+        expect(Rical.root_for f: f1, x0: -10, x1: -9, method: :secant).to be_within(1e-6).of(-2**0.5)
       end
 
       it 'rescues when f(x1) - f(x0) = 0' do
-        # converges but to either one of the roots
-        expect(Rical.root_for(f: f, x0: 9, x1: -9, method: :secant).abs).to be_within(1e-6).of(2**0.5)
+        # converges to either one of the roots
+        expect(Rical.root_for(f: f1, x0: 9, x1: -9, method: :secant).abs).to be_within(1e-6).of(2**0.5)
+      end
+
+      it 'passes extra arguments (array) to f' do
+        f2  = -> (x, a, b) { a*x**2 + b }    # f2  = f1  for a=1, b=-2
+        expect(Rical.root_for f: f2, fargs: [1, -2], x0: 10, x1: 9, method: :secant).to be_within(1e-6).of(2**0.5)
       end
     end
 
     context 'inverse computation' do
       it 'yields +2.0 for y=2, f(x)=y=x²-2' do
-        expect(Rical.inverse_for f: f, y: 2, x0: 0, x1: 1, method: :secant).to be_within(1e-6).of(2.0)
+        expect(Rical.inverse_for f: f1, y: 2, x0: 0, x1: 1, method: :secant).to be_within(1e-6).of(2.0)
       end
     end
   end
 
   context 'error handling' do
     it 'raises ArgumentError when f is not callable' do
-      expect{ Rical.root_for f: :dummy, df: df, method: :newton  }.to raise_error ArgumentError
+      expect{ Rical.root_for f: :dummy, df: df1, method: :newton  }.to raise_error ArgumentError
       expect{ Rical.root_for f: :dummy, x0: 0, x1: 1, method: :secant }.to raise_error ArgumentError
     end
 
     it 'raises ArgumentError when no df given and method is Newton-Raphson' do
-      expect{ Rical.root_for f: f, method: :newton    }.to raise_error ArgumentError
-      expect{ Rical.inverse_for f: f, method: :newton }.to raise_error ArgumentError
+      expect{ Rical.root_for f: f1, method: :newton    }.to raise_error ArgumentError
+      expect{ Rical.inverse_for f: f1, method: :newton }.to raise_error ArgumentError
     end
 
     it 'raises ArgumentError when df is not callable and method is Newton-Raphson' do
-      expect{ Rical.root_for f: f, df: :dummy, method: :newton }.to raise_error ArgumentError
+      expect{ Rical.root_for f: f1, df: :dummy, method: :newton }.to raise_error ArgumentError
     end
 
     it 'raises NoConvergenceError when Newton-Raphson does not converge' do
-      expect{ Rical.root_for f: f, df: df, x0: 1e32, method: :newton, num: 10 
+      expect{ Rical.root_for f: f1, df: df1, x0: 1e32, method: :newton, num: 10
       }.to raise_error Rical::NoConvergenceError
     end
 
     it 'raises NoConvergenceError when Secant does not converge' do
-      expect{ Rical.root_for f: f, x0: 1e32, x1: 1.1e32, method: :secant, num: 10 
+      expect{ Rical.root_for f: f1, x0: 1e32, x1: 1.1e32, method: :secant, num: 10
       }.to raise_error Rical::NoConvergenceError
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rical
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Luis Bacelar