quaternion_c2 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 11a23c8bee71f2eac9cdd28569ddbd060e1c78d6
-  data.tar.gz: 2da47444cd5b3c7f50da7f9cb0dfc281dcd187a1
+SHA256:
+  metadata.gz: 2d786fc0057f8807e1a12a9c55c19e124fa7edd24eccf3d686c1a927685c01bc
+  data.tar.gz: a98e2aaed384903bff5a13b844b5097b88f360a1ed8a182b2a1a774b45e46d8e
 SHA512:
-  metadata.gz: 3504d452e7841683a890fb01c8ca3a82ce44c9c334aa3309b50329dd17415a99d021c6d2b56cf0358a5c04d9d09b1aaf44508d030cc75072a32626d4c1a8d1eb
-  data.tar.gz: 6348e89acb1f9a31923c03d9ea1fac21d10d2a849d55c198fd757021ad35243dce10c411502f4ea4b6e622d331e4e66dfd4b014e46c2774d290320a77507265b
+  metadata.gz: 45c7c781395f45cb8a0adc3acb2e2a6c0c6f7d58e03a14da74490080048146aee760a5835eb524f1c02a4dce77d3bfbc2f008aa88b89754394d57900c34eaca8
+  data.tar.gz: 3afc20e3e7b5fe2874343ade34e6550f862a1f21cb097ff3b403465f63b4364d1dc050748219fdac26b0328310eb995dd1fbf38598cd4d76cc12e5fb346ce92f

data/.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Test
+
+on:
+  push: {}
+  pull_request: {}
+  schedule:
+    - cron: '45 23 1 * *'  # Monthly check
+
+jobs:
+  unit-test:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [ '2.1', '2.2', '2.3', '2.4', '2.5', '2.6', '2.7',
+                '3.0', '3.1', '3.2',
+                head ]
+    runs-on: ubuntu-latest
+    name: Unit test with Ruby ${{ matrix.ruby }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run RSpec
+        run: |
+          bundle exec rake spec

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,10 +61,30 @@ 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)
-				self * other.conj.send(sym, other.abs2)
+				n = self * other.conj.send(sym, other.abs2)
+				__new__(n.a / 1, n.b / 1) # Canonicalize rationals as Complex does
 			elsif other.kind_of?(Numeric) && other.complex?
 				__new__(@a.send(sym, other), @b.send(sym, other.conj))
 			else
@@ -58,10 +96,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/comparison.rb

@@ -0,0 +1,55 @@
+require_relative 'base'
+require_relative 'arithmetic' # define Quaternion#coerce
+
+if Complex.public_method_defined?(:<=>)
+	class Quaternion
+		##
+		# Compare values if both are real numbers.
+		#
+		# @param other [Object]
+		# @return [-1, 0, 1, or nil]
+		#
+		def <=>(other)
+			if other.kind_of?(Quaternion)
+				(@b == 0 && other.b == 0) ? (@a <=> other.a) : nil
+			elsif other.kind_of?(Numeric) && other.complex?
+				(@b == 0) ? (@a <=> other) : nil
+			elsif other.respond_to?(:coerce)
+				n1, n2 = other.coerce(self)
+				n1 <=> n2
+			else
+				nil
+			end
+		end
+	end
+
+	# Check whether built-in Complex#<=> uses type coercions.
+	if (Complex.rect(0, 0) <=> Quaternion.send(:new, 0, 0)).nil?
+		warn "Redefine Complex#<=> to allow type coercions."
+
+		class Complex
+			##
+			# Compare values if both are real numbers.
+			#
+			# @param other [Object]
+			# @return [-1, 0, 1, or nil]
+			#
+			def <=>(other)
+				if other.kind_of?(Complex)
+					(imag == 0 && other.imag == 0) ? (real <=> other.real) : nil
+				elsif other.kind_of?(Numeric) && other.real?
+					(imag == 0) ? (real <=> other) : nil
+				elsif other.respond_to?(:coerce)
+					n1, n2 = other.coerce(self)
+					n1 <=> n2
+				else
+					nil
+				end
+			end
+		end
+	end
+else
+	class Quaternion
+		undef <=>
+	end
+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

@@ -2,9 +2,14 @@ require_relative 'base'
 require_relative 'classification'
 
 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 +20,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 +34,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,8 +121,8 @@ class Quaternion
 	end
 
 	class << self
-		def parse(str, strict = false)
-			regexp = %r{
+		RE, RE_STRICT = [false, true].collect do |strict|
+			%r{
 				\A
 				\s*+
 				(?:(?'real'   [+-]?+           \g'rational'  ) (?![ijk]))?+
@@ -62,19 +130,30 @@ class Quaternion
 				(?:(?'imag_j' \g'head_or_sign' \g'rational'?+) j        )?+
 				(?:(?'imag_k' \g'head_or_sign' \g'rational'?+) k        )?+
 				\s*+
-				|\z
-				(?'head_or_sign' (?<=^|\s) [+-]?+ | [+-])
+				|(?!)
+				(?'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
+		end
+		private_constant :RE, :RE_STRICT
+
+		private
 
-			match_data = regexp.match(str)
-			if strict && (!$'.empty? || match_data.captures[0,4].all?(&:nil?))
-				raise ArgumentError, "invalid value for convert(): #{str.inspect}"
+		def parse(str, strict = false)
+			regexp = strict ? RE_STRICT : RE
+
+			# 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 +163,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,59 @@
 require_relative 'base'
 
-#
-# Unary operations
-#
-
 class Quaternion
+	##
+	# Unary operations
+	#
+
 	# defined by Numeric:
 	# * +@ #=> self
 	# * -@ #=> 0 - self
 
+	##
+	# Returns negation of the value.
+	#
+	# @return [Quaternion]
+	#
+	# @example
+	#   -Quaternion(1, 2, 3, 4) #=> (-1-2i-3j-4k)
+	#
+	def -@
+		__new__(-@a, -@b)
+	end
+
+	##
+	# 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 +76,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/lib/quaternion_c2.rb

@@ -8,3 +8,4 @@ require "quaternion_c2/arithmetic"
 require "quaternion_c2/to_type"
 require "quaternion_c2/conversion"
 require "quaternion_c2/utils"
+require "quaternion_c2/comparison"

data/quaternion_c2.gemspec

@@ -3,14 +3,15 @@ $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       = "1.0.0"
   spec.authors       = ["Masahiro Nomoto"]
   spec.email         = ["hmmnrst@users.noreply.github.com"]
 
   spec.summary       = %q{Quaternion class}
-  spec.description   = %q{This provides a numeric class Quaternion which is similar to a built-in class Complex.}
+  spec.description   = %q{Provides a numeric class Quaternion which is similar to a built-in class Complex.}
   spec.homepage      = "https://github.com/hmmnrst/quaternion_c2"
   spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.1"  # matrix:0.1.0 does not support ruby 2.0
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
@@ -19,7 +20,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.14"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_dependency "matrix"  # Vector
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 3.0"
 end

metadata

@@ -1,68 +1,83 @@
 --- !ruby/object:Gem::Specification
 name: quaternion_c2
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Masahiro Nomoto
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2017-03-31 00:00:00.000000000 Z
+date: 2022-09-12 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: matrix
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.14'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.14'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '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
-  class Complex.
+description: Provides a numeric class Quaternion which is similar to a built-in class
+  Complex.
 email:
 - hmmnrst@users.noreply.github.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
+- ".github/workflows/test.yml"
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -74,6 +89,7 @@ files:
 - lib/quaternion_c2/attributes.rb
 - lib/quaternion_c2/base.rb
 - lib/quaternion_c2/classification.rb
+- lib/quaternion_c2/comparison.rb
 - lib/quaternion_c2/conversion.rb
 - lib/quaternion_c2/equality.rb
 - lib/quaternion_c2/to_type.rb
@@ -85,24 +101,23 @@ homepage: https://github.com/hmmnrst/quaternion_c2
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.0
-signing_key: 
+rubygems_version: 3.3.7
+signing_key:
 specification_version: 4
 summary: Quaternion class
 test_files: []