From f7652b1c52f4b45fbfecd4b1335f75528f3b091b Mon Sep 17 00:00:00 2001 From: Anton Davydov Date: Tue, 19 May 2015 20:35:52 +0300 Subject: [PATCH] Update documentation for CMath library --- ChangeLog | 5 ++++ lib/cmath.rb | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 79 insertions(+), 12 deletions(-) diff --git a/ChangeLog b/ChangeLog index 0e3ba2e..35539aa 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2015-05-20 Anton Davydov + + * lib/cmath.rb: [DOC] update documentation for CMath library + [ci skip] + Mon May 18 15:31:31 2015 Nobuyoshi Nakada * include/ruby/intern.h (rb_f_notimplement): should not respond to diff --git a/lib/cmath.rb b/lib/cmath.rb index e0c9139..9ce161c 100644 --- a/lib/cmath.rb +++ b/lib/cmath.rb @@ -1,16 +1,48 @@ ## +# = Trigonometric and transcendental functions for complex numbers. +# # CMath is a library that provides trigonometric and transcendental -# functions for complex numbers. +# functions for complex numbers. The functions in this module accept +# integers, floating-point numbers or complex numbers as arguments. +# +# Note that the selection of functions is similar, but not identical, +# to that in module math. The reason for having two modules is that +# some users aren’t interested in complex numbers, and perhaps don’t +# even know what they are. They would rather have Math.sqrt(-1) raise +# an exception than return a complex number. +# +# == Brief overview of complex numbers +# +# A complex number is a number that can be expressed in the form +# a + bi, where a and b are real numbers and i is the imaginary unit, +# that satisfies the equation x**2 = −1, that is, i**2 = −1. In this +# expression, a is the real part and b is the imaginary part of the +# complex number. +# +# In ruby, you can create complex object with Complex, ::rect, ::polar +# or #to_c method. +# +# Complex(1) #=> (1+0i) +# Complex.polar(2, 3) #=> (-1.9799849932008908+0.2822400161197344i) +# 3.to_c #=> (3+0i) # # == Usage # -# To start using this library, simply: +# To start using this library, simply require cmath library: # # require "cmath" # -# Square root of a negative number is a complex number. +# And after call any CMath function. For example: +# +# CMath.sqrt(-9) #=> 0+3.0i +# CMath.exp(Complex(0,0)) #=> 1.0+0.0i +# CMath.log10(-5.to_c) #=> (0.6989700043360187+1.3643763538418412i) # -# CMath.sqrt(-9) #=> 0+3.0i +# == References +# +# Kahan, W: Branch cuts for complex elementary functions +# Solomentsev, E.D. (2001), "Complex number", in Hazewinkel, Michiel, +# Encyclopedia of Mathematics, Springer, ISBN 978-1-55608-010-4 # module CMath @@ -44,9 +76,7 @@ module CMath ## # Math::E raised to the +z+ power # - # exp(Complex(0,0)) #=> 1.0+0.0i - # exp(Complex(0,PI)) #=> -1.0+1.2246467991473532e-16i - # exp(Complex(0,PI/2.0)) #=> 6.123233995736766e-17+1.0i + # CMath.exp(Complex(0,PI)) #=> -1.0+1.2246467991473532e-16i def exp(z) begin if z.real? @@ -62,10 +92,11 @@ module CMath end ## - # Returns the natural logarithm of Complex. If a second argument is given, + # Returns the natural logarithm of Complex. If a second argument is given, # it will be the base of logarithm. # - # log(Complex(0,0)) #=> -Infinity+0.0i + # CMath.log(Complex(1,4)) #=> (1.416606672028108+1.3258176636680326i) + # CMath.log(Complex(1,4), 10) #=> (0.6152244606891369+0.5757952953408879i) def log(z, b=::Math::E) begin if z.real? && z >= 0 && b >= 0 @@ -80,6 +111,8 @@ module CMath ## # returns the base 2 logarithm of +z+ + # + # CMath.log2(-1) => (0.0+4.532360141827194i) def log2(z) begin if z.real? and z >= 0 @@ -94,6 +127,8 @@ module CMath ## # returns the base 10 logarithm of +z+ + # + # CMath.log10(-1) #=> (0.0+1.3643763538418412i) def log10(z) begin if z.real? and z >= 0 @@ -108,9 +143,8 @@ module CMath ## # Returns the non-negative square root of Complex. - # sqrt(-1) #=> 0+1.0i - # sqrt(Complex(-1,0)) #=> 0.0+1.0i - # sqrt(Complex(0,8)) #=> 2.0+2.0i + # + # CMath.sqrt(Complex(-1,0)) #=> 0.0+1.0i def sqrt(z) begin if z.real? @@ -136,12 +170,16 @@ module CMath ## # returns the principal value of the cube root of +z+ + # + # CMath.cbrt(Complex(1,4)) #=> (1.449461632813119+0.6858152562177092i) def cbrt(z) z ** (1.0/3) end ## # returns the sine of +z+, where +z+ is given in radians + # + # CMath.sin(Complex(Math::PI)) #=> (1.2246467991473532e-16-0.0i) def sin(z) begin if z.real? @@ -157,6 +195,8 @@ module CMath ## # returns the cosine of +z+, where +z+ is given in radians + # + # CMath.cos(Complex(Math::PI)) #=> (-1.0-0.0i) def cos(z) begin if z.real? @@ -172,6 +212,8 @@ module CMath ## # returns the tangent of +z+, where +z+ is given in radians + # + # CMath.tan(Complex(Math::PI)) #=> (-1.2246467991473532e-16+0.0i) def tan(z) begin if z.real? @@ -186,6 +228,8 @@ module CMath ## # returns the hyperbolic sine of +z+, where +z+ is given in radians + # + # CMath.sinh(Complex(Math::PI)) #=> (11.548739357257746+0.0i) def sinh(z) begin if z.real? @@ -201,6 +245,8 @@ module CMath ## # returns the hyperbolic cosine of +z+, where +z+ is given in radians + # + # CMath.cosh(Complex(Math::PI)) #=> (11.591953275521519+0.0i) def cosh(z) begin if z.real? @@ -216,6 +262,8 @@ module CMath ## # returns the hyperbolic tangent of +z+, where +z+ is given in radians + # + # CMath.tanh(Complex(Math::PI)) #=> (0.99627207622075+0.0i) def tanh(z) begin if z.real? @@ -230,6 +278,8 @@ module CMath ## # returns the arc sine of +z+ + # + # CMath.asin(Complex(Math::PI)) #=> (1.5707963267948966-1.8115262724608532i) def asin(z) begin if z.real? and z >= -1 and z <= 1 @@ -244,6 +294,8 @@ module CMath ## # returns the arc cosine of +z+ + # + # CMath.acos(Complex(Math::PI)) #=> (0.0+1.8115262724608536i) def acos(z) begin if z.real? and z >= -1 and z <= 1 @@ -258,6 +310,8 @@ module CMath ## # returns the arc tangent of +z+ + # + # CMath.atan(Complex(Math::PI)) #=> (1.2626272556789118+0.0i) def atan(z) begin if z.real? @@ -273,6 +327,8 @@ module CMath ## # returns the arc tangent of +y+ divided by +x+ using the signs of +y+ and # +x+ to determine the quadrant + # + # CMath.atan2(Complex(Math::PI), 0) #=> (1.5707963267948966+0.0i) def atan2(y,x) begin if y.real? and x.real? @@ -287,6 +343,8 @@ module CMath ## # returns the inverse hyperbolic sine of +z+ + # + # CMath.asinh(Complex(Math::PI)) #=> (1.8622957433108482+0.0i) def asinh(z) begin if z.real? @@ -301,6 +359,8 @@ module CMath ## # returns the inverse hyperbolic cosine of +z+ + # + # CMath.acosh(Complex(Math::PI)) #=> (1.8115262724608532+0.0i) def acosh(z) begin if z.real? and z >= 1 @@ -315,6 +375,8 @@ module CMath ## # returns the inverse hyperbolic tangent of +z+ + # + # CMath.atanh(Complex(Math::PI)) #=> (0.32976531495669914-1.5707963267948966i) def atanh(z) begin if z.real? and z >= -1 and z <= 1 -- 2.3.0