roots 1.0.0

data/lib/roots.rb

@@ -0,0 +1,166 @@
+=begin
+Author: Jabari Zakiya,   Original: 2009-12-25
+Revision-2: 2009-12-31
+Revision-3: 2010-6-2
+Revision-4: 2010-12-15
+
+Module 'Roots' provides two methods 'root' and 'roots'
+which will find all the nth roots of real and complex
+numerical values.
+
+---------------
+Install process:
+Place module file 'roots.rb' into 'lib' directory of ruby
+version. Then from irb session, or a source code file, do:
+
+require 'roots'
+#For extended math features also do: require 'mathn'
+#Mixin 'Roots' into class Numeric
+Rev-4 Add line 'class Numeric; include Roots end'
+to end of file to automatically add root/s methods in
+all class Numeric types.
+---------------
+
+Use syntax:  val.root(n,{k})
+root(n,k=0) n is root 1/n exponent,  integer > 0 
+            k is nth ccw root 1..n , integer >=0
+If k not given default root returned, which are:
+for +val => real root  |val**(1.0/n)|
+for -val => real root -|val**(1.0/n)| when n is odd
+for -val => first ccw complex root    when n is even
+
+9.root(2); -32.root(5,3), -100.43.root 6,6
+
+Use syntax:  val.roots(n,{opt})
+roots(n,opt=0) n is root 1/n exponent, integer > 0
+               opt, optional string input, are:
+   0   : default (no input), return array of n ccw roots
+'c'|'C': complex, return array of complex roots
+'e'|'E': even, return array even numbered roots
+'o'|'O': odd , return array odd  numbered roots
+'i'|'I': imag, return array of imaginary roots
+'r'|'R': real, return array of real roots
+An empty array is returned for an opt with no members.
+
+9348134943.roots(9); -89.roots(4,'real'); 2.2.roots 3,'Im'
+
+Can ask: How many real roots of x: x.roots(n,'real').size
+What's the 3rd 5th root of (4+9i): Complex(4,9).root(5,3)
+
+---------------
+Mathematical foundations
+
+1) i = (-1)^(1/2)
+2) i^1 =  i
+3) i^2 = -1
+4) i^3 = -i
+5) i^4 =  1
+6) Then it repeats, e.g.: i^5 = i*(i^4) = i
+7) e^(i*x) = cos(x) + i*sin(x)
+8) when x = PI/2 then  e^(PI*i/2) = i
+
+For roots (-a)^(1/n) of negative real values:
+
+x = |a^(1/n)|*(-1)^(1/n)
+from 2) above
+x = |a^(1/n)|*(i^2)^(1/n)
+x = |a^(1/n)|*(i)^(2/n)
+apply 8) from above
+x = |a^{1/n)|*e^(PI*i/2)^(2/n)
+x = |a^(1/n)|*e^(PI*i/n)
+9) x = |a^(1/n)|*(cos(PI/n) + i*sin(PI/n))
+
+For roots (a)^(1/n) of positive real values:
+
+x = (a)^(1/n)
+x = (a*1)^(1/n)
+x = |a^(1/n)|*(1)^(1/n)
+from 5) above
+x = |a^(1/n)|*(i^4))^(1/n)
+x = |a^(1/n)|*(i)^(4/n)
+apply 8) from above
+x = |a^{1/n)|*e^(PI*i/2)^(4/n)
+x = |a^(1/n)|*e^(2*PI*i/n)
+10) x = |a^(1/n)|*(cos(2*PI/n) + i*sin(2*PI/n))
+
+There are n distinct roots (values): 
+---------------
+
+Ruby currently gives incorrect values for x|y axis angles
+cos PI/2   =>  6.12303176911189e-17 
+sin PI     =>  1.22460635382238e-16
+cos 3*PI/2 => -1.83690953073357e-16  
+sin 2*PI   => -2.44921970764475e-16
+
+These all should be 0.0, which causes incorrect root values there.
+I 'fix' these errors by clipping absolute values less than a value
+I call TRIG-EPSILON so they produces the correct results.
+
+Extract this code into separate file and 'require' into your apps
+to get correct|exact results for x|y axis angles and still get same
+accuracy for extremely small delta angles to the x|y axis.
+cosine(89.9999999999*PI/180) =>  1.74534333112399e-11
+cosine(90.0*PI/180)          =>  0.0
+cosine(90.0000000001*PI/180) => -1.74543140899798e-12
+=end
+
+# file roots.rb
+
+module Roots
+  require 'complex'
+  include Math
+
+  def root(n,k=0) # return nth root k=1..n;, or default for k=0
+    raise "Root n not an integer > 0" unless n.kind_of?(Integer) && n>0
+    raise "Index k not an integer >= 0" unless k.kind_of?(Integer) && k>=0
+    return self if n == 1 || self == 0
+    mag = abs**n**-1
+    return rootn(mag,arg/n,k>0 ? k-1:0,n) if kind_of?(Complex)
+    return rootn(mag,PI/n,k-1) if k>0 # nth root any real
+    return  mag if self > 0    # pos real default
+    return -mag if n&1 == 1    # neg real default, n odd
+    return rootn(mag,PI/n)     # neg real default, n even
+  end
+
+  def roots(n,opt=0) #  returns array of roots, [] option not valid
+    raise "Root n not an integer > 0" unless n.kind_of?(Integer) && n>0
+    raise "Invalid option" unless opt == 0 || opt =~ /^(c|e|i|o|r|C|E|I|O|R)/
+    return [self] if n == 1 || self == 0
+    mag = abs**n**-1
+    theta = kind_of?(Complex) ? arg/n : PI/n
+    roots = []
+    case opt
+    when /^(o|O)/  # odd  roots 1,3,5...
+      0.step(n-1,2) {|k| roots << rootn(mag,theta,k,n)}
+    when /^(e|E)/  # even roots 2,4,6...
+      1.step(n-1,2) {|k| roots << rootn(mag,theta,k,n)}
+    when /^(r|R)/  # real roots     Complex(x,0) = (x+i0)
+      n.times {|k|
+        x=rootn(mag,theta,k,n); roots << x if x.imag == 0}
+    when /^(i|I)/  # imaginry roots Complex(0,y) = (0+iy)
+      n.times {|k|
+        x=rootn(mag,theta,k,n); roots << x if x.real == 0}
+    when /^(c|C)/  # complex roots  Complex(x,y) = (x+iy)
+      n.times {|k|
+        x=rootn(mag,theta,k,n); roots << x unless 
+        x.imag == 0 || x.real == 0}
+    else           # all n roots
+      n.times {|k| roots << rootn(mag,theta,k,n)}
+    end
+    return roots
+  end
+
+  private # don't show as methods in mixin class
+  TRIG_EPSILON = 2.5e-16
+  def sine(x);   y=sin(x); y.abs < TRIG_EPSILON ? 0.0:y end
+  def cosine(x); y=cos(x); y.abs < TRIG_EPSILON ? 0.0:y end
+  def tangent(x); sine(x)/cosine(x) end # more accurate tan
+
+  def rootn(mag,theta,k=0,n=1) # nth root of a real|complex
+    angle_n = kind_of?(Complex) ? theta+(2*k*PI)/n :
+              self > 0 ? 2*(k+1)*theta : (2*k+1)*theta
+    mag*Complex(cosine(angle_n),sine(angle_n))
+  end
+end
+
+class Numeric; include Roots end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: roots
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Jabari Zakiya
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-27 00:00:00.000000000 Z
+dependencies: []
+description: ! 'For val (real/complex) and root n: val.root(n,[1-n]) and val.roots(n,
+  [opt]) '
+email:
+- jzakiya@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/roots.rb
+homepage: http://www.scribd.com/doc/60067570/Roots-in-Ruby
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: two methods 'root' and 'roots' to compute all n roots of real/complex numbers
+test_files: []
+has_rdoc: