From 60bf66e0cd2c9f519f7dfb27eca134b86ea5dd8b Mon Sep 17 00:00:00 2001 From: matz Date: Thu, 29 Jun 2006 09:09:33 +0000 Subject: * ext/bigdecimal/bigdecimal.c: add RDoc document. a patch from mathew . [ruby-core:07050] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@10428 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ext/bigdecimal/lib/bigdecimal/jacobian.rb | 26 ++++++++++++++++-- ext/bigdecimal/lib/bigdecimal/ludcmp.rb | 9 ++++++- ext/bigdecimal/lib/bigdecimal/math.rb | 45 ++++++++++++++++++++++++++++--- ext/bigdecimal/lib/bigdecimal/newton.rb | 30 +++++++++++---------- ext/bigdecimal/lib/bigdecimal/util.rb | 26 +++++++++--------- 5 files changed, 102 insertions(+), 34 deletions(-) (limited to 'ext/bigdecimal/lib') diff --git a/ext/bigdecimal/lib/bigdecimal/jacobian.rb b/ext/bigdecimal/lib/bigdecimal/jacobian.rb index 34a60ae67a..d80eeab901 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 1d5d3170cc..8f4888725e 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 7b3f46ed1a..f3248a3c5c 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 f1a55da789..59ac0f7f04 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 1f8d6c7a49..2c17aa6b8e 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 -- cgit v1.2.3