summaryrefslogtreecommitdiff
path: root/ext/bigdecimal/lib
diff options
context:
space:
mode:
authormatz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2006-06-29 09:09:33 +0000
committermatz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2006-06-29 09:09:33 +0000
commit60bf66e0cd2c9f519f7dfb27eca134b86ea5dd8b (patch)
treedcc53a834964d3813864acd28a1cecd6777d74d2 /ext/bigdecimal/lib
parent0c11152794d4f07970a5c36981e95eb176d5fdc8 (diff)
* ext/bigdecimal/bigdecimal.c: add RDoc document. a patch from
mathew <meta at pobox.com>. [ruby-core:07050] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@10428 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/bigdecimal/lib')
-rw-r--r--ext/bigdecimal/lib/bigdecimal/jacobian.rb26
-rw-r--r--ext/bigdecimal/lib/bigdecimal/ludcmp.rb9
-rw-r--r--ext/bigdecimal/lib/bigdecimal/math.rb45
-rw-r--r--ext/bigdecimal/lib/bigdecimal/newton.rb30
-rw-r--r--ext/bigdecimal/lib/bigdecimal/util.rb26
5 files changed, 102 insertions, 34 deletions
diff --git a/ext/bigdecimal/lib/bigdecimal/jacobian.rb b/ext/bigdecimal/lib/bigdecimal/jacobian.rb
index 34a60ae..d80eeab 100644
--- a/ext/bigdecimal/lib/bigdecimal/jacobian.rb
+++ b/ext/bigdecimal/lib/bigdecimal/jacobian.rb
@@ -1,9 +1,27 @@
#
-# jacobian.rb
+# require 'bigdecimal/jacobian'
#
-# Computes Jacobian matrix of f at x
+# Provides methods to compute the Jacobian matrix of a set of equations at a
+# point x. In the methods below:
+#
+# f is an Object which is used to compute the Jacobian matrix of the equations.
+# It must provide the following methods:
+#
+# f.values(x):: returns the values of all functions at x
+#
+# f.zero:: returns 0.0
+# f.one:: returns 1.0
+# f.two:: returns 1.0
+# f.ten:: returns 10.0
+#
+# f.eps:: returns the convergence criterion (epsilon value) used to determine whether two values are considered equal. If |a-b| < epsilon, the two values are considered equal.
+#
+# x is the point at which to compute the Jacobian.
+#
+# fx is f.values(x).
#
module Jacobian
+ #--
def isEqual(a,b,zero=0.0,e=1.0e-8)
aa = a.abs
bb = b.abs
@@ -17,7 +35,10 @@ module Jacobian
end
end
end
+ #++
+ # Computes the derivative of f[i] at x[i].
+ # fx is the value of f at x.
def dfdxi(f,fx,x,i)
nRetry = 0
n = x.size
@@ -49,6 +70,7 @@ module Jacobian
deriv
end
+ # Computes the Jacobian of f at x. fx is the value of f at x.
def jacobian(f,fx,x)
n = x.size
dfdx = Array::new(n*n)
diff --git a/ext/bigdecimal/lib/bigdecimal/ludcmp.rb b/ext/bigdecimal/lib/bigdecimal/ludcmp.rb
index 1d5d317..8f48887 100644
--- a/ext/bigdecimal/lib/bigdecimal/ludcmp.rb
+++ b/ext/bigdecimal/lib/bigdecimal/ludcmp.rb
@@ -1,7 +1,8 @@
#
-# ludcmp.rb
+# Solves a*x = b for x, using LU decomposition.
#
module LUSolve
+ # Performs LU decomposition of the n by n matrix a.
def ludecomp(a,n,zero=0,one=1)
prec = BigDecimal.limit(nil)
ps = []
@@ -52,6 +53,12 @@ module LUSolve
ps
end
+ # Solves a*x = b for x, using LU decomposition.
+ #
+ # a is a matrix, b is a constant vector, x is the solution vector.
+ #
+ # ps is the pivot, a vector which indicates the permutation of rows performed
+ # during LU decomposition.
def lusolve(a,b,ps,zero=0.0)
prec = BigDecimal.limit(nil)
n = ps.size
diff --git a/ext/bigdecimal/lib/bigdecimal/math.rb b/ext/bigdecimal/lib/bigdecimal/math.rb
index 7b3f46e..f3248a3 100644
--- a/ext/bigdecimal/lib/bigdecimal/math.rb
+++ b/ext/bigdecimal/lib/bigdecimal/math.rb
@@ -1,4 +1,5 @@
#
+#--
# Contents:
# sqrt(x, prec)
# sin (x, prec)
@@ -13,19 +14,35 @@
# x ... BigDecimal number to be computed.
# |x| must be small enough to get convergence.
# prec ... Number of digits to be obtained.
+#++
+#
+# Provides mathematical functions.
+#
+# Example:
#
-# Usage:
# require "bigdecimal"
-# require "bigdecimal/math.rb"
+# require "bigdecimal/math"
+#
# include BigMath
+#
# a = BigDecimal((PI(100)/2).to_s)
-# puts sin(a,100) # => 0.10000000000000000000......E1
+# puts sin(a,100) # -> 0.10000000000000000000......E1
#
module BigMath
+
+ # Computes the square root of x to the specified number of digits of
+ # precision.
+ #
+ # BigDecimal.new('2').sqrt(16).to_s
+ # -> "0.14142135623730950488016887242096975E1"
+ #
def sqrt(x,prec)
x.sqrt(prec)
end
+ # Computes the sine of x to the specified number of digits of precision.
+ #
+ # If x is infinite or NaN, returns NaN.
def sin(x, prec)
raise ArgumentError, "Zero or negative precision for sin" if prec <= 0
return BigDecimal("NaN") if x.infinite? || x.nan?
@@ -51,6 +68,9 @@ module BigMath
y
end
+ # Computes the cosine of x to the specified number of digits of precision.
+ #
+ # If x is infinite or NaN, returns NaN.
def cos(x, prec)
raise ArgumentError, "Zero or negative precision for cos" if prec <= 0
return BigDecimal("NaN") if x.infinite? || x.nan?
@@ -76,6 +96,10 @@ module BigMath
y
end
+ # Computes the arctangent of x to the specified number of digits of precision.
+ #
+ # If x is infinite or NaN, returns NaN.
+ # Raises an argument error if x > 1.
def atan(x, prec)
raise ArgumentError, "Zero or negative precision for atan" if prec <= 0
return BigDecimal("NaN") if x.infinite? || x.nan?
@@ -96,6 +120,13 @@ module BigMath
y
end
+ # Computes the value of e (the base of natural logarithms) raised to the
+ # power of x, to the specified number of digits of precision.
+ #
+ # If x is infinite or NaN, returns NaN.
+ #
+ # BigMath::exp(BigDecimal.new('1'), 10).to_s
+ # -> "0.271828182845904523536028752390026306410273E1"
def exp(x, prec)
raise ArgumentError, "Zero or negative precision for exp" if prec <= 0
return BigDecimal("NaN") if x.infinite? || x.nan?
@@ -117,6 +148,11 @@ module BigMath
y
end
+ # Computes the natural logarithm of x to the specified number of digits
+ # of precision.
+ #
+ # Returns x if x is infinite or NaN.
+ #
def log(x, prec)
raise ArgumentError, "Zero or negative argument for log" if x <= 0 || prec <= 0
return x if x.infinite? || x.nan?
@@ -138,6 +174,7 @@ module BigMath
y*two
end
+ # Computes the value of pi to the specified number of digits of precision.
def PI(prec)
raise ArgumentError, "Zero or negative argument for PI" if prec <= 0
n = prec + BigDecimal.double_fig
@@ -176,6 +213,8 @@ module BigMath
pi
end
+ # Computes e (the base of natural logarithms) to the specified number of
+ # digits of precision.
def E(prec)
raise ArgumentError, "Zero or negative precision for E" if prec <= 0
n = prec + BigDecimal.double_fig
diff --git a/ext/bigdecimal/lib/bigdecimal/newton.rb b/ext/bigdecimal/lib/bigdecimal/newton.rb
index f1a55da..59ac0f7 100644
--- a/ext/bigdecimal/lib/bigdecimal/newton.rb
+++ b/ext/bigdecimal/lib/bigdecimal/newton.rb
@@ -1,24 +1,26 @@
#
# newton.rb
#
-# Solves nonlinear algebraic equation system f = 0 by Newton's method.
-# (This program is not dependent on BigDecimal)
+# Solves the nonlinear algebraic equation system f = 0 by Newton's method.
+# This program is not dependent on BigDecimal.
#
# To call:
# n = nlsolve(f,x)
-# where n is the number of iterations required.
-# x is the solution vector.
-# f is the object to be solved which must have following methods.
+# where n is the number of iterations required,
+# x is the initial value vector
+# f is an Object which is used to compute the values of the equations to be solved.
+# It must provide the following methods:
#
-# f ... Object to compute Jacobian matrix of the equation systems.
-# [Methods required for f]
-# f.values(x) returns values of all functions at x.
-# f.zero returns 0.0
-# f.one returns 1.0
-# f.two returns 1.0
-# f.ten returns 10.0
-# f.eps convergence criterion
-# x ... initial values
+# f.values(x):: returns the values of all functions at x
+#
+# f.zero:: returns 0.0
+# f.one:: returns 1.0
+# f.two:: returns 1.0
+# f.ten:: returns 10.0
+#
+# f.eps:: returns the convergence criterion (epsilon value) used to determine whether two values are considered equal. If |a-b| < epsilon, the two values are considered equal.
+#
+# On exit, x is the solution vector.
#
require "bigdecimal/ludcmp"
require "bigdecimal/jacobian"
diff --git a/ext/bigdecimal/lib/bigdecimal/util.rb b/ext/bigdecimal/lib/bigdecimal/util.rb
index 1f8d6c7..2c17aa6 100644
--- a/ext/bigdecimal/lib/bigdecimal/util.rb
+++ b/ext/bigdecimal/lib/bigdecimal/util.rb
@@ -1,19 +1,17 @@
#
# BigDecimal utility library.
-# ----------------------------------------------------------------------
-# Contents:
#
-# String#
-# to_d ... to BigDecimal
+# To use these functions, require 'bigdecimal/util'
+#
+# The following methods are provided to convert other types to BigDecimals:
#
-# Float#
-# to_d ... to BigDecimal
+# String#to_d -> BigDecimal
+# Float#to_d -> BigDecimal
+# Rational#to_d -> BigDecimal
#
-# BigDecimal#
-# to_r ... to Rational
+# The following method is provided to convert BigDecimals to other types:
#
-# Rational#
-# to_d ... to BigDecimal
+# BigDecimal#to_r -> Rational
#
# ----------------------------------------------------------------------
#
@@ -30,8 +28,8 @@ class String
end
class BigDecimal < Numeric
- # to "nnnnnn.mmm" form digit string
- # Use BigDecimal#to_s("F") instead.
+ # Converts a BigDecimal to a String of the form "nnnnnn.mmm".
+ # This method is deprecated; use BigDecimal#to_s("F") instead.
def to_digits
if self.nan? || self.infinite? || self.zero?
self.to_s
@@ -42,7 +40,7 @@ class BigDecimal < Numeric
end
end
- # Convert BigDecimal to Rational
+ # Converts a BigDecimal to a Rational.
def to_r
sign,digits,base,power = self.split
numerator = sign*digits.to_i
@@ -57,7 +55,7 @@ class BigDecimal < Numeric
end
class Rational < Numeric
- # Convert Rational to BigDecimal
+ # Converts a Rational to a BigDecimal
def to_d(nFig=0)
num = self.numerator.to_s
if nFig<=0