quaternion_c2 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 11a23c8bee71f2eac9cdd28569ddbd060e1c78d6
-  data.tar.gz: 2da47444cd5b3c7f50da7f9cb0dfc281dcd187a1
+  metadata.gz: 6990b36ad863bcfeb0d147530f06461f634b13cc
+  data.tar.gz: 04be92b14b2149067953ac61c73151aafa42edea
 SHA512:
-  metadata.gz: 3504d452e7841683a890fb01c8ca3a82ce44c9c334aa3309b50329dd17415a99d021c6d2b56cf0358a5c04d9d09b1aaf44508d030cc75072a32626d4c1a8d1eb
-  data.tar.gz: 6348e89acb1f9a31923c03d9ea1fac21d10d2a849d55c198fd757021ad35243dce10c411502f4ea4b6e622d331e4e66dfd4b014e46c2774d290320a77507265b
+  metadata.gz: 4d62049c41e69f64f427932b91499399e122890472d963e2a2185959c197533f9fdac296301a8dd277866a74f710f6020b019fce30d584ae2f5c874b77c82593
+  data.tar.gz: b3dfa3a4691263ad104b5d9fc5669bd39708b1ad55ef680205f305f2012abc6512a6c93ebf93e9bb6ba660e1dc14b70a74b0e7f258da1aee3f02969ecfd4e9b2

data/README.md

@@ -1,5 +1,22 @@
 # Quaternion
 
+This gem provides a `Quaternion` class highly compatible with other numeric classes.
+
+The [quaternions](https://en.wikipedia.org/wiki/Quaternion) are an extension of complex numbers.
+They have an important application to calculations of spatial rotations, such as in 3DCG.
+
+A quaternion can be represented in several forms:
+
+* Four real numbers: `$w + xi + yj + zk$`
+* Two complex numbers: `$a + bj$`
+* Scalar and 3-D vector: `$s + \vec{v}$`
+* Polar form: `$r \exp{(\vec{n} \theta)}$`
+
+where i, j, and k are imaginary units which satisfy $i^2 = j^2 = k^2 = ijk = -1$.
+A scalar is a real quaternion and a vector is a pure imaginary quaternion.
+
+The multiplication of quaternions is noncommutative unlike complex numbers.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -45,6 +62,32 @@ Complex::I * Quaternion::J  #=> (0+0i+0j+1k)
 Quaternion(1, 1, 1, 1) ** 6 #=> (64+0i+0j+0k)
 ```
 
+### Spatial rotations
+
+Unit quaternions are often used to calculate 3-D rotations around arbitrary axes.
+They have a compact form, avoid gimbal lock, and easily interpolate between themselves (see [Slerp](https://en.wikipedia.org/wiki/Slerp)).
+
+```ruby
+# theta = 120 * (Math::PI / 180)
+# axis = Vector[1, 1, 1].normalize
+# q = Quaternion.polar(1, theta / 2, axis)
+q = Quaternion(0.5, 0.5, 0.5, 0.5)
+r = Quaternion('2i+3j+4k')
+
+r_new = q * r / q      #=> (0.0+4.0i+2.0j+3.0k)
+r_new = q * r * q.conj #=> (0.0+4.0i+2.0j+3.0k) # q.abs must be 1
+```
+
+More generally, a pair of unit quaternions represents a [4-D rotation](https://en.wikipedia.org/wiki/Rotations_in_4-dimensional_Euclidean_space).
+
+```ruby
+ql = Quaternion(0.5,  0.5, -0.5, 0.5)
+qr = Quaternion(0.5, -0.5,  0.5, 0.5)
+r = Quaternion('1+2i+3j+4k')
+
+r_new = ql * r * qr #=> (-4.0-3.0i-2.0j+1.0k)
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/quaternion_c2/arithmetic.rb

@@ -2,12 +2,18 @@ require_relative 'base'
 require_relative 'classification'
 require_relative 'unary'
 
-#
-# Basic arithmetic operators (#+, #-, #*, #/)
-# and related methods
-#
-
 class Quaternion
+	##
+	# Basic arithmetic operators (#+, #-, #*, #/)
+	# and related methods
+	#
+
+	##
+	# Performs addition.
+	#
+	# @param other [Numeric]
+	# @return [Quaternion]
+	#
 	def +(other)
 		if other.kind_of?(Quaternion)
 			__new__(@a + other.a, @b + other.b)
@@ -19,6 +25,12 @@ class Quaternion
 		end
 	end
 
+	##
+	# Performs subtraction.
+	#
+	# @param other [Numeric]
+	# @return [Quaternion]
+	#
 	def -(other)
 		if other.kind_of?(Quaternion)
 			__new__(@a - other.a, @b - other.b)
@@ -30,6 +42,12 @@ class Quaternion
 		end
 	end
 
+	##
+	# Performs multiplication.
+	#
+	# @param other [Numeric]
+	# @return [Quaternion]
+	#
 	def *(other)
 		if other.kind_of?(Quaternion)
 			_a = other.a
@@ -43,6 +61,25 @@ class Quaternion
 		end
 	end
 
+	##
+	# @!method quo(other)
+	#
+	# Performs division.
+	#
+	# @param other [Numeric]
+	# @return [Quaternion]
+	# @raise [ZeroDivisionError] if +other+ is exactly zero.
+	#
+
+	##
+	# @!method fdiv(other)
+	#
+	# Performs division as each part is a float, never returns a float.
+	#
+	# @param other [Numeric]
+	# @return [Quaternion]
+	#
+
 	[:quo, :fdiv].each do |sym|
 		define_method(sym) do |other|
 			if other.kind_of?(Quaternion)
@@ -58,10 +95,17 @@ class Quaternion
 	alias / quo
 	undef div, %, modulo, remainder, divmod
 
-	#
+	##
 	# Conversion
 	#
 
+	##
+	# Performs type conversion.
+	#
+	# @param other [Numeric]
+	# @return [[Quaternion, self]]
+	# @raise [TypeError]
+	#
 	def coerce(other)
 		if other.kind_of?(Quaternion)
 			[other, self]

data/lib/quaternion_c2/attributes.rb

@@ -9,12 +9,23 @@ class Quaternion
 	defined_methods = public_instance_methods
 
 	if defined_methods.include?(:finite?)
+		##
+		# Returns true if its magnitude is finite, oterwise returns false.
+		#
+		# @return [Boolean]
+		#
 		def finite?
 			abs.finite?
 		end
 	end
 
 	if defined_methods.include?(:infinite?)
+		##
+		# Returns values corresponding to the value of its magnitude.
+		#
+		# @return [nil] if finite.
+		# @return [+1]  if positive infinity.
+		#
 		def infinite?
 			abs.infinite?
 		end

data/lib/quaternion_c2/base.rb

@@ -1,7 +1,23 @@
+##
+# This class +Quaternion+ is an analogue of +Complex+.
+# * A subclass of +Numeric+
+# * Immutable instances
+# * Common / extended methods
+# Please +require 'quaternion_c2'+ to load all functions.
+#
+# +Quaternion+ has many constructors to accept
+# the various representations of a quaternion.
+# It is recommended to use +Kernel.#Quaternion+ and +Quaternion.polar+.
+#
+# @see https://ruby-doc.org/core/Complex.html
+#
 class Quaternion < Numeric
 	attr_reader :a, :b
 	protected   :a, :b
 
+	##
+	# @!visibility private
+	#
 	def initialize(a, b)
 		@a = a.to_c
 		@b = b.to_c

data/lib/quaternion_c2/classification.rb

@@ -1,31 +1,43 @@
 require_relative 'base'
 
-#
-# Number system classification
-# (N <) Z < Q < R < C < H (< ...)
-#
-# * quaternion?  : [H] Quaternion (*undefined*)
-# * && complex?  : [C] Complex
-# * && real?     : [R] Float, BigDecimal, Numeric
-# * && rational? : [Q] Rational (*undefined*)
-# * && integer?  : [Z] Fixnum, Bignum, Integer
-#
-
 class Numeric
+	##
+	# Number system classification
+	# (N <) Z < Q < R < C < H (< ...)
+	#
+	# * quaternion?  : [H] Quaternion (*undefined*)
+	# * && complex?  : [C] Complex
+	# * && real?     : [R] Float, BigDecimal, Numeric
+	# * && rational? : [Q] Rational (*undefined*)
+	# * && integer?  : [Z] Fixnum, Bignum, Integer
+	#
+
 	# defined:
 	# * integer? #=> false
 	# * real?    #=> true
 
+	##
+	# Returns true.
+	#
 	def complex?
 		true
 	end
 end
 
 class Quaternion
+	# defined by Numeric:
+	# * integer? #=> false
+
+	##
+	# Returns false.
+	#
 	def real?
 		false
 	end
 
+	##
+	# Returns false.
+	#
 	def complex?
 		false
 	end

data/lib/quaternion_c2/conversion.rb

@@ -8,11 +8,22 @@ require_relative 'to_type'
 require 'matrix'
 
 class Quaternion
-	#
+	##
 	# Constructors
 	#
 
 	class << self
+		##
+		# Returns a quaternion object a+bj, where both a and b are complex (or real).
+		#
+		# @param a [Complex]
+		# @param b [Complex]
+		# @return [Quaternion]
+		# @raise [TypeError]
+		#
+		# @example
+		#   Quaternion.rect(1, Complex::I) #=> (1+0i+0j+1k)
+		#
 		def rect(a, b = 0)
 			unless [a, b].all? { |c| c.kind_of?(Numeric) && c.complex? }
 				raise TypeError, 'not a complex'
@@ -21,6 +32,19 @@ class Quaternion
 		end
 		alias rectangular rect
 
+		##
+		# Returns a quaternion object w+xi+yj+zk, where all of w, x, y, and z are real.
+		#
+		# @param w [Real]
+		# @param x [Real]
+		# @param y [Real]
+		# @param z [Real]
+		# @return [Quaternion]
+		# @raise [TypeError]
+		#
+		# @example
+		#   Quaternion.hrect(1, 2, 3, 4) #=> (1+2i+3j+4k)
+		#
 		def hrect(w, x = 0, y = 0, z = 0)
 			a = Complex.rect(w, x)
 			b = Complex.rect(y, z)
@@ -28,8 +52,26 @@ class Quaternion
 		end
 		alias hyperrectangular hrect
 
-		# Quaternion.polar(r) == r
-		# Quaternion.polar(r, theta) == Complex.polar(r, theta)
+		##
+		# Returns a quaternion object which denotes the given polar form.
+		# The actual angle is recognized as +theta * vector.norm+.
+		#
+		# @param r      [Real]       absolute value
+		# @param theta  [Real]       angle in radians
+		# @param vector [Enumerable] 3-D vector
+		# @return [Quaternion]
+		# @raise [TypeError]
+		#
+		# @example
+		#   Quaternion.polar(1, Math::PI/3, Vector[1,1,1].normalize)
+		#   #=> (0.5000000000000001+0.5i+0.5j+0.5k)
+		#   Quaternion.polar(1, 1, Math::PI/3 * Vector[1,1,1].normalize)
+		#   #=> (0.4999999999999999+0.5i+0.5j+0.5k)
+		#
+		#   r, theta = -3, -1
+		#   Quaternion.polar(r)        == r                       #=> true
+		#   Quaternion.polar(r, theta) == Complex.polar(r, theta) #=> true
+		#
 		def polar(r, theta = 0, vector = Vector[1, 0, 0])
 			unless vector.kind_of?(Enumerable) && vector.size == 3
 				raise TypeError, 'not a 3-D vector'
@@ -49,25 +91,57 @@ class Quaternion
 		end
 	end
 
-	#
+	##
 	# Accessors
 	#
 
+	##
+	# Returns an array of two complex numbers.
+	#
+	# @return [[Complex, Complex]]
+	#
+	# @example
+	#   Quaternion('1+2i+3j+4k').rect #=> [(1+2i), (3+4i)]
+	#
 	def rect
 		[@a, @b]
 	end
 	alias rectangular rect
 
+	##
+	# Returns an array of four real numbers.
+	#
+	# @return [[Real, Real, Real, Real]]
+	#
+	# @example
+	#   Quaternion('1+2i+3j+4k').hrect #=> [1, 2, 3, 4]
+	#
 	def hrect
 		rect.flat_map(&:rect)
 	end
 	alias hyperrectangular hrect
 
+	##
+	# Returns the real part.
+	#
+	# @return [Real]
+	#
+	# @example
+	#   Quaternion('1+2i+3j+4k').real #=> 1
+	#
 	def real
 		@a.real
 	end
 	alias scalar real
 
+	##
+	# Returns the imaginary part as a 3-D vector.
+	#
+	# @return [Vector] 3-D vector
+	#
+	# @example
+	#   Quaternion('1+2i+3j+4k').imag #=> Vector[2, 3, 4]
+	#
 	def imag
 		Vector[*hrect.drop(1)]
 	end
@@ -78,6 +152,14 @@ class Quaternion
 	# * abs
 	# * magnitude
 
+	##
+	# Returns the angle part of its polar form.
+	#
+	# @return [Real]
+	#
+	# @example
+	#   Quaternion('1+i+j+k').arg #=> Math::PI/3
+	#
 	def arg
 		r_cos = real
 		r_sin = imag.norm
@@ -86,6 +168,14 @@ class Quaternion
 	alias angle arg
 	alias phase arg
 
+	##
+	# Returns the axis part of its polar form.
+	#
+	# @return [Vector] normalized 3-D vector
+	#
+	# @example
+	#   Quaternion('1+i+j+k').axis #=> Vector[1,1,1].normalize
+	#
 	def axis
 		v = imag
 		norm = v.norm
@@ -100,24 +190,55 @@ class Quaternion
 		end
 	end
 
+	##
+	# Returns an array; +[q.abs, q.arg, q.axis]+.
+	#
+	# @return [[Real, Real, Vector]]
+	#
+	# @example
+	#   Quaternion('1+i+j+k').polar
+	#   #=> [2.0, Math::PI/3, Vector[1,1,1].normalize]
+	#
 	def polar
 		[abs, arg, axis]
 	end
 end
 
-#
-# Generic constructor
-#
-# This accepts various arguments:
-# * (Numeric)          -> real quaternion
-# * (Numeric, Numeric) -> a+bj
-# * (Numeric, Vector)  -> scalar and 3-D vector
-# * (Numeric, Numeric, Numeric[, Numeric]) -> w+xi+yj+zk
-# and String instead of Numeric.
-#
 module Kernel
 	module_function
 
+	##
+	# Returns a quaternion.
+	#
+	# This function accepts various arguments except polar form.
+	# Strings are parsed to +Numeric+.
+	#
+	# @overload Quaternion(w, x, y, z)
+	#   @param w [Numeric]
+	#   @param x [Numeric]
+	#   @param y [Numeric]
+	#   @param z [Numeric]
+	#   @return [Quaternion] w+xi+yj+zk
+	# @overload Quaternion(a, b)
+	#   @param a [Numeric]
+	#   @param b [Numeric]
+	#   @return [Quaternion] a+bj
+	# @overload Quaternion(s, v)
+	#   @param s [Numeric]    scalar part
+	#   @param v [Enumerable] vector part
+	#   @return [Quaternion] $s+\\vec!{v}$
+	# @overload Quaternion(str)
+	#   @param str [String]
+	#   @return [Quaternion] +str.to_q+
+	#   @raise [ArgumentError] if its format is inexact.
+	#
+	# @example
+	#   Quaternion(1)            #=> (1+0i+0j+0k)
+	#   Quaternion(1, 2)         #=> (1+0i+2j+0k) # not (1+2i+0j+0k)
+	#   Quaternion(1, 2, 3, 4)   #=> (1+2i+3j+4k)
+	#   Quaternion(1, [2, 3, 4]) #=> (1+2i+3j+4k)
+	#   Quaternion('1+2i+3j+4k') #=> (1+2i+3j+4k)
+	#
 	def Quaternion(*args)
 		argc = args.size
 
@@ -141,26 +262,45 @@ module Kernel
 		end
 
 		case argc
+		when 1
+			arg = args[0]
+			if arg.kind_of?(Numeric)
+				# a quaternion (or an octonion, etc.)
+				return arg.complex? ? arg.to_q : arg
+			else
+				raise TypeError,
+				      "can't convert #{arg.class} into Quaternion"
+			end
 		when 2
 			if args[1].kind_of?(Enumerable)
-				# scalar and 3-D vector
+				# scalar and 3-D vector -> expand
 				if args[1].size != 3
 					raise TypeError, "not a 3-D vector"
 				end
-				args = [args[0], *args[1]]
-			else
+				args.flatten!(1)
+			elsif args.all? { |x| x.kind_of?(Numeric) && x.complex? }
 				# a pair of complex numbers
+				return Quaternion.send(:new, *args)
+			else
 				return args[0] + args[1] * Quaternion::J
 			end
 		end
 
-		# maximum four real numbers
-		i = Quaternion::I
-		j = Quaternion::J
-		k = Quaternion::K
-		zero = Quaternion.send(:new, 0, 0)
-		args.zip([1, i, j, k]).inject(zero) do |sum,(num,base)|
-			sum + num * base
+		w, x, y, z = args
+		z ||= 0
+		if args.all? { |x| x.kind_of?(Numeric) && x.real? }
+			# 3 or 4 real numbers
+			a = Complex.rect(w, x)
+			b = Complex.rect(y, z)
+			Quaternion.send(:new, a, b)
+		else
+			a = Complex(w, x)
+			b = Complex(y, z)
+			if [a, b].all? { |x| x.kind_of?(Numeric) && x.complex? }
+				Quaternion.send(:new, a, b)
+			else
+				a + b * Quaternion::J
+			end
 		end
 	end
 end

data/lib/quaternion_c2/equality.rb

@@ -5,6 +5,12 @@ class Quaternion
 	undef <=>
 	undef_method(*Comparable.instance_methods)
 
+	##
+	# Returns true if it equals to the other numerically.
+	#
+	# @param other [Object]
+	# @return [Boolean]
+	#
 	def ==(other)
 		if other.kind_of?(Quaternion)
 			@a == other.a && @b == other.b
@@ -15,6 +21,12 @@ class Quaternion
 		end
 	end
 
+	##
+	# Returns true if two quaternions have same reals.
+	#
+	# @param other [Object]
+	# @return [Boolean]
+	#
 	def eql?(other)
 		if other.kind_of?(Quaternion)
 			@a.eql?(other.a) && @b.eql?(other.b)
@@ -23,8 +35,13 @@ class Quaternion
 		end
 	end
 
-	# q1.eql?(q2) => q1.hash == q2.hash
+	##
+	# Returns a hash.
+	#
+	# @return [Integer]
+	#
 	def hash
+		# q1.eql?(q2) -> q1.hash == q2.hash
 		[@a, @b].hash
 	end
 end

data/lib/quaternion_c2/to_type.rb

@@ -1,18 +1,29 @@
 require_relative 'base'
 require_relative 'unary'
 
-#
-# to_xxx
-#
-
 class Quaternion
+	##
+	# to_xxx
+	#
+
 	# defined by Numeric:
 	# * to_int #=> to_i
 
+	##
+	# Returns self.
+	#
+	# @return [self]
+	#
 	def to_q
 		self
 	end
 
+	##
+	# Returns the value as a complex if possible (the discarded part should be exactly zero).
+	#
+	# @return [Complex]
+	# @raise [RangeError] if its yj+zk part is not exactly zero.
+	#
 	def to_c
 		unless __exact_zero__(@b)
 			raise RangeError, "can't convert #{self} into Complex"
@@ -20,14 +31,71 @@ class Quaternion
 		@a
 	end
 
+	##
+	# @!method to_f
+	#
+	# Returns the value as a float if possible (the imaginary part should be exactly zero).
+	#
+	# @return [Float]
+	# @raise [RangeError] if its imaginary part is not exactly zero.
+	#
+
+	##
+	# @!method to_r
+	#
+	# Returns the value as a rational if possible (the imaginary part should be exactly zero).
+	#
+	# @return [Rational]
+	# @raise [RangeError] if its imaginary part is not exactly zero.
+	#
+
+	##
+	# @!method to_i
+	#
+	# Returns the value as an integer if possible (the imaginary part should be exactly zero).
+	#
+	# @return [Integer]
+	# @raise [RangeError] if its imaginary part is not exactly zero.
+	#
+
+	##
+	# @!method rationalize(eps = 0)
+	#
+	# Returns the value as a rational if possible (the imaginary part should be exactly zero).
+	#
+	# @param eps [Real]
+	# @return [Rational]
+	# @raise [RangeError] if its imaginary part is not exactly zero.
+	#
+
 	[:to_f, :to_r, :to_i, :rationalize].each do |sym|
 		define_method(sym) { |*args| to_c.send(sym, *args) }
 	end
 
+	##
+	# Returns the value as a string.
+	#
+	# @return [String]
+	#
+	# @example
+	#   str = '1-2i-3/4j+0.56k'
+	#   q = str.to_q #=> (1-2i-(3/4)*j+0.56k)
+	#   q.to_s       #=> "1-2i-3/4j+0.56k"
+	#
 	def to_s
 		__format__(:to_s)
 	end
 
+	##
+	# Returns the value as a string for inspection.
+	#
+	# @return [String]
+	#
+	# @example
+	#   str = '1-2i-3/4j+0.56k'
+	#   q = str.to_q #=>  (1-2i-(3/4)*j+0.56k)
+	#   q.inspect    #=> "(1-2i-(3/4)*j+0.56k)"
+	#
 	def inspect
 		"(#{__format__(:inspect)})"
 	end
@@ -53,6 +121,9 @@ class Quaternion
 	end
 
 	class << self
+		##
+		# @!visibility private
+		#
 		def parse(str, strict = false)
 			regexp = %r{
 				\A
@@ -65,16 +136,20 @@ class Quaternion
 				|\z
 				(?'head_or_sign' (?<=^|\s) [+-]?+ | [+-])
 				(?'digits'       \d++ (?:#{strict ? "_" : "_++"} \d++)*+)
-				(?'int_or_float' (?:\g'digits')?+ (?:\. \g'digits')?+ (?<=\d) (?:e [+-]?+ \g'digits')?+)
+				(?'int_or_float' (?:\g'digits')?+ (?:\. \g'digits')?+
+				                 (?<=\d) (?:e [+-]?+ \g'digits')?+)
 				(?'rational'     \g'int_or_float' (?:/ \g'digits')?+)
 			}xi
 
-			match_data = regexp.match(str)
-			if strict && (!$'.empty? || match_data.captures[0,4].all?(&:nil?))
-				raise ArgumentError, "invalid value for convert(): #{str.inspect}"
+			# regexp.match(str) always succeeds (even if str is empty)
+			components = regexp.match(str).captures[0,4]
+			components = components.reverse.drop_while(&:nil?).reverse
+			if strict && (!$'.empty? || components.empty?)
+				raise ArgumentError,
+				      "invalid value for convert(): #{str.inspect}"
 			end
 
-			w, x, y, z = match_data.captures[0,4].collect do |s|
+			components.collect! do |s|
 				case s
 				when %r{/}     then s.to_r
 				when %r{[.eE]} then s.to_f
@@ -84,24 +159,57 @@ class Quaternion
 				end
 			end
 
-			new(Complex.rect(w, x), Complex.rect(y, z))
+			# returns the parsed number as a preferred type
+			case components.size
+			when 0
+				0
+			when 1
+				components[0]
+			when 2
+				Complex.rect(*components)
+			else # 3 or 4
+				w, x, y, z = components
+				new(Complex.rect(w, x), Complex.rect(y, z || 0))
+			end
 		end
 	end
 end
 
 class Numeric
+	##
+	# Returns the value as a quaternion.
+	#
+	# @return [Quaternion]
+	#
 	def to_q
 		Quaternion.send(:new, self, 0)
 	end
 end
 
 class String
+	##
+	# Returns a quaternion which denotes the string form.
+	# The parser ignores leading whitespaces and trailing garbage.
+	# Any digit sequences can be separated by an underscore.
+	# Returns zero for null or garbage string.
+	#
+	# @return [Quaternion]
+	#
+	# @example
+	#   "1-2i-3/4j+0.56k".to_q #=> (1-2i-(3/4)*j+0.56k)
+	#   "foobarbaz".to_q       #=> (0+0i+0j+0k)
+	#
 	def to_q
-		Quaternion.send(:parse, self, false)
+		Quaternion.send(:parse, self, false).to_q
 	end
 end
 
 class NilClass
+	##
+	# Returns zero as a quaternion.
+	#
+	# @return [Quaternion]
+	#
 	def to_q
 		Quaternion.send(:new, 0, 0)
 	end

data/lib/quaternion_c2/unary.rb

@@ -1,23 +1,47 @@
 require_relative 'base'
 
-#
-# Unary operations
-#
-
 class Quaternion
+	##
+	# Unary operations
+	#
+
 	# defined by Numeric:
 	# * +@ #=> self
 	# * -@ #=> 0 - self
 
+	##
+	# Returns its conjugate.
+	#
+	# @return [Quaternion]
+	#
+	# @example
+	#   Quaternion(1, 2, 3, 4).conj #=> (1-2i-3j-4k)
+	#
 	def conj
 		__new__(@a.conj, -@b)
 	end
 	alias conjugate conj
 
+	##
+	# Returns square of the absolute value.
+	#
+	# @return [Real]
+	#
+	# @example
+	#   Quaternion(-1, 1, -1, 1).abs2 #=> 4
+	#
 	def abs2
 		@a.abs2 + @b.abs2
 	end
 
+	##
+	# Returns the absolute part of its polar form.
+	#
+	# @return [Real]
+	#
+	# @example
+	#   Quaternion(-1, 1, -1, 1).abs #=> 2.0
+	#
 	def abs
 		a_abs = @a.abs
 		b_abs = @b.abs
@@ -40,4 +64,9 @@ class Quaternion
 	else
 		false
 	end
+
+	def __reciprocal__
+		d2 = abs2
+		__new__(@a.conj.quo(d2), @b.quo(-d2))
+	end
 end

data/lib/quaternion_c2/units.rb

@@ -1,33 +1,57 @@
 require_relative 'base'
 
-#
-# Fundamental quaternion units
-#
-
 class Quaternion
+	##
+	# Fundamental quaternion units
+	#
+
 	i = Complex::I
 	I = new(i, 0)
 	J = new(0, 1)
 	K = new(0, i)
 end
 
-#
-# Convert to an imaginary part
-#
-
 class Numeric
+	##
+	# Convert to an imaginary part
+	#
+
 	# defined:
-	# * #i #=> Complex.rect(0, self)
+	# * i #=> Complex.rect(0, self)
 
+	##
+	# Returns the corresponding imaginary number.
+	# Not available for quaternions.
+	#
+	# @return [Quaternion] +self * Quaternion::J+
+	# @raise [NoMethodError] if +self+ is not a complex.
+	#
+	# @example
+	#   3.j             #=> (0+0i+3j+0k)
+	#   Complex(3, 4).j #=> (0+0i+3j+4k)
+	#
 	def j
 		Quaternion.send(:new, 0, self)
 	end
 
+	##
+	# Returns the corresponding imaginary number.
+	# Not available for complex numbers.
+	#
+	# @return [Quaternion] +self * Quaternion::K+
+	# @raise [NoMethodError] if +self+ is not a real.
+	#
+	# @example
+	#   4.k #=> (0+0i+0j+4k)
+	#
 	def k
 		Quaternion.send(:new, 0, self.i)
 	end
 end
 
+##
+# @!parse class Complex < Numeric; end
+#
 class Complex
 	# undefined:
 	# * #i

data/lib/quaternion_c2/utils.rb

@@ -5,58 +5,98 @@ require_relative 'arithmetic'
 require_relative 'conversion'
 
 class Quaternion
+	##
+	# Performs exponentiation.
+	#
+	# @param index [Numeric]
+	# @return [Quaternion]
+	#
+	# @example
+	#   Quaternion(1, 1, 1, 1) ** 6 #=> (64+0i+0j+0k)
+	#   Math::E.to_q ** Quaternion(Math.log(2), [Math::PI/3 / Math.sqrt(3)] * 3)
+	#   #=> (1.0000000000000002+1.0i+1.0j+1.0k)
+	#
 	def **(index)
-		if index.kind_of?(Numeric)
-			if __exact_zero__(index)
-				return __new__(1, 0)
-			end
+		unless index.kind_of?(Numeric)
+			num1, num2 = index.coerce(self)
+			return num1 ** num2
+		end
+
+		if __exact_zero__(index)
+			return __new__(1, 0)
+		end
 
-			# complex -> real
+		# complex -> real
+		# (only if the imaginary part is exactly zero)
+		unless index.real?
 			begin
 				index.to_f
 			rescue
 			else
 				index = index.real
 			end
+		end
 
-			# rational -> integer
-			if index.kind_of?(Rational) && index.denominator == 1
-				index = index.numerator
-			end
+		# rational -> integer
+		if index.kind_of?(Rational) && index.denominator == 1
+			index = index.numerator
+		end
 
-			if index.integer?
-				# binary method
-				x = (index >= 0) ? self : 1 / self
-				n = index.abs
+		# calc and return
+		if index.integer?
+			# exponentiation by squaring
+			x = (index >= 0) ? self : __reciprocal__
+			n = index.abs
 
-				z = __new__(1, 0)
-				while true
-					n, i = n.divmod(2)
-					z *= x if i == 1
-					return z if n == 0
-					x *= x
-				end
-			elsif index.real?
-				r, theta, vector = polar
-				return Quaternion.polar(r ** index, theta * index, vector)
-			elsif index.complex? || index.kind_of?(Quaternion)
-				r, theta, vector = polar
-				q = Math.log(r) + Quaternion.hrect(0, *(theta * vector))
-				q *= index
-				return Quaternion.polar(Math.exp(q.real), 1, q.imag)
+			z = __new__(1, 0)
+			while true
+				z *= x if n.odd?
+				n >>= 1
+				return z if n.zero?
+				x *= x
 			end
+		elsif index.real?
+			r, theta, vector = polar
+			Quaternion.polar(r ** index, theta * index, vector)
+		elsif index.complex? || index.kind_of?(Quaternion)
+			# assume that log(self) commutes with index under multiplication
+			r, theta, vector = polar
+			q = Quaternion.hrect(Math.log(r), *(theta * vector))
+			q *= index
+			Quaternion.polar(Math.exp(q.real), 1, q.imag)
+		else
+			num1, num2 = index.coerce(self)
+			num1 ** num2
 		end
-
-		num1, num2 = other.coerce(self)
-		num1 ** num2
 	end
 
+	##
+	# Returns the denominator (lcm of all components' denominators).
+	# @see numerator
+	#
+	# @return [Integer]
+	#
 	def denominator
 		ad = @a.denominator
 		bd = @b.denominator
 		ad.lcm(bd)
 	end
 
+	##
+	# Returns the numerator.
+	#
+	#   1   1    1    3     4-6i-12j+9k <- numerator
+	#   - - -i - -j + -k -> -----------
+	#   3   2    1    4         12      <- denominator
+	#
+	# @return [Quaternion]
+	#
+	# @example
+	#   q = Quaternion('1/3-1/2i-j+3/4k') #=> ((1/3)-(1/2)*i-1j+(3/4)*k)
+	#   n = q.numerator                   #=> (4-6i-12j+9k)
+	#   d = q.denominator                 #=> 12
+	#   n / d == q                        #=> true
+	#
 	def numerator
 		an = @a.numerator
 		bn = @b.numerator

data/quaternion_c2.gemspec

@@ -3,7 +3,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "quaternion_c2"
-  spec.version       = "0.1.1"
+  spec.version       = "0.1.2"
   spec.authors       = ["Masahiro Nomoto"]
   spec.email         = ["hmmnrst@users.noreply.github.com"]
 

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: quaternion_c2
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Masahiro Nomoto
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-31 00:00:00.000000000 Z
+date: 2017-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.14'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
 description: This provides a numeric class Quaternion which is similar to a built-in
@@ -60,9 +60,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -91,17 +91,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.0
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Quaternion class