tonal-tools 2.0.1 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 340dc7220c5ab24c65486eefc2ebb457d76c7c1ac64fd91a428b94a4fd84cd7d
-  data.tar.gz: 5721937407c18951a5b72eb075ffdbbfe8765abb3ae98695fc2af40e55277c3a
+  metadata.gz: ed09e5cd360980028547160d80bf374eacc14df7596e7cdfa0034bc295de771a
+  data.tar.gz: 3f17b4accf20c651fb3f7e172d9e4e5c094eb62a1a5705274ef36b16577f8f4f
 SHA512:
-  metadata.gz: def0ab4830c3f5b3e82b919fcf8242899539a32e554acd2b260d3f37f87df6dbd7899cb8a6f9c045c98805bba69a10efc1f974d88e7f3107f641033c862acdc8
-  data.tar.gz: 72601d465253ab599188b0f15a241b30e9824754c076bf260f69d4fa5b92309ac85dbb677a1e9e03bff0c29b42302a064b8d73a14ac92e0c0f5f7c9c8c84af8c
+  metadata.gz: 22aef50e39cbc83f269fa1a326da40e1d8068b1ff965ffbbaeda8c82919aadce2d1ef11b6988f4c78f87321ddfa010fd07def250b597015bacb3dbf09accd94d
+  data.tar.gz: 186a12f240251e6a6f1a2f0142cfe3f800151f182827fa06f7f6c999d0e652277a4cbc473a3e0ae6838ff6d1786a7f4c5ce80a9de35a2fb5572d246b3d43e884

data/lib/tonal/attributions.rb

@@ -1,4 +1,4 @@
 module Tonal
   TOOLS_PRODUCER = "mTonal"
-  TOOLS_VERSION = "2.0.1"
+  TOOLS_VERSION = "3.0.1"
 end

data/lib/tonal/cents.rb

@@ -12,7 +12,7 @@ class Tonal::Cents
 
   attr_reader :log, :ratio
 
-  # @return [Cents]
+  # @return [Tonal::Cents]
   # @example
   #   Tonal::Cents.new(ratio: 2**(2.0/12)) => 200.0
   # @param cents [Numeric, Tonal::Log2]
@@ -40,7 +40,7 @@ class Tonal::Cents
     end
   end
 
-  # @return [Cents] the default cents tolerance
+  # @return [Tonal::Cents] the default cents tolerance
   # @example
   #   Tonal::Cents.default_tolerance => 5
   #
@@ -58,7 +58,7 @@ class Tonal::Cents
   alias :cents :value
 
   # @return
-  #   [Cents] nearest hundredth cent value
+  #   [Tonal::Cents] nearest hundredth cent value
   # @example
   #   Tonal::Cents.new(cents: 701.9550008653874).nearest_hundredth => 700.0
   #
@@ -85,7 +85,7 @@ class Tonal::Cents
   end
 
   # @return
-  #   [String] the string representation of Cents
+  #   [String] the string representation of Tonal::Cents
   # @example
   #   Tonal::Cents.new(100.0).inspect => "100.0"
   #

data/lib/tonal/extensions.rb

@@ -86,7 +86,7 @@ class Numeric
   def hz = Tonal::Hertz.new(self)
   alias :to_hz :hz
 
-  # @return [Step] the step of self in the given modulo
+  # @return [Tonal::Step] the step of self in the given modulo
   # @example
   #   (5/4r).step(12) => 4\12
   # @param modulo
@@ -131,7 +131,7 @@ class Numeric
   #
   def efficiency(modulo) = (Tonal::Cents::CENT_SCALE * step(modulo).step / modulo.to_f) - to_cents
 
-  # @return [Interval] beween self (upper) and ratio (lower)
+  # @return [Tonal::Interval] beween self (upper) and ratio (lower)
   # @example
   #   (133).interval_with(3/2r) => 133/96 (133/128 / 3/2)
   # @param ratio
@@ -149,7 +149,7 @@ class Numeric
   # @example
   #   (31/30r).prime_divisions => [[[31, 1]], [[2, 1], [3, 1], [5, 1]]]
   #
-  def prime_divisions = self.ratio.prime_divisions
+  def prime_divisions = [self.numerator.prime_division, self.denominator.prime_division]
 
   # @return [Integer] the maximum prime factor of self
   # @example
@@ -163,20 +163,6 @@ class Numeric
   #
   def min_prime = prime_divisions.flatten(1).map(&:first).min
 
-  # @return [Tonal::ReducedRatio], the Ernst Levy negative of self
-  # @example
-  #  (7/4r).negative => (12/7)
-  #
-  def negative = self.ratio.negative
-
-  # @return [Tonal::ReducedRatio], the ratio rotated on the given axis, default 1/1
-  # @example
-  #   (3/2r).mirror => (4/3)
-  #
-  def mirror(axis=1/1r) = self.ratio.mirror(axis)
-end
-
-class Rational
   # @return [Vector], self expressed as a Vector
   # @example
   #   (3/2r).to_vector => Vector[3, 2]
@@ -184,23 +170,17 @@ class Rational
   def to_vector = Vector[self.numerator, self.denominator]
   alias :vector :to_vector
 
-  # @return [Array], self decomposed into its prime factors
-  # @example
-  #   (31/30r).prime_divisions => [[[31, 1]], [[2, 1], [3, 1], [5, 1]]]
-  #
-  def prime_divisions = self.ratio.prime_divisions
-
-  # @return [Integer] the maximum prime factor of self
+  # @return [Tonal::ReducedRatio], the Ernst Levy negative of self
   # @example
-  #   (31/30r).max_prime => 31
+  #  (7/4r).negative => (12/7)
   #
-  def max_prime = self.ratio.max_prime
+  def negative = self.ratio.negative
 
-  # @return [Integer] the minimum prime factor of self
+  # @return [Tonal::ReducedRatio], the ratio rotated on the given axis, default 1/1
   # @example
-  #   (31/30r).min_prime => 2
+  #   (3/2r).mirror => (4/3)
   #
-  def min_prime = self.ratio.min_prime
+  def mirror(axis=1/1r) = self.ratio.mirror(axis)
 end
 
 class Integer

data/lib/tonal/hertz.rb

@@ -3,9 +3,9 @@ class Tonal::Hertz
 
   attr_reader :value
 
-  # @return [Hertz]
+  # @return [Tonal::Hertz]
   # @example
-  #   Hertz.new(1000.0) => 1000.0
+  #   Tonal::Hertz.new(1000.0) => 1000.0
   # @param arg [Numeric, Tonal::Hertz]
   #
   def initialize(arg)
@@ -13,7 +13,7 @@ class Tonal::Hertz
     @value = arg.kind_of?(self.class) ? arg.inspect : arg
   end
 
-  # @return [Hertz] 440 Hz
+  # @return [Tonal::Hertz] 440 Hz
   # @example
   #   Tonal::Hertz.a440 => 440.0
   #
@@ -38,9 +38,9 @@ class Tonal::Hertz
     value.to_f
   end
 
-  # @return [String] the string representation of Hertz
+  # @return [String] the string representation of Tonal::Hertz
   # @example
-  #   Hertz(1000.0).inspect => "1000.0"
+  #   Tonal::Hertz(1000.0).inspect => "1000.0"
   #
   def inspect
     "#{value}"

data/lib/tonal/log.rb

@@ -53,13 +53,13 @@ class Tonal::Log
   # @return [Tonal::Cents] the cents scale logarithm
   # @example
   #   Tonal::Log.new(logarithmand: 3/2r, base: 2).to_cents => 701.9550008653874
-  # @see Cents
+  # @see Tonal::Cents
   #
   def to_cents(precision: Tonal::Cents::PRECISION)
     Tonal::Cents.new(log: self, precision: precision)
   end
 
-  # @return [Step] the nearest step in the given modulo
+  # @return [Tonal::Step] the nearest step in the given modulo
   # @example
   #   Tonal::Log.new(3/2r, base: 2).step(12) => 7\12
   #

data/lib/tonal/ratio.rb

@@ -16,18 +16,7 @@ class Tonal::Ratio
     raise ArgumentError, "Antecedent must be Numeric" unless antecedent.kind_of?(Numeric)
     raise ArgumentError, "Consequent must be Numeric or nil" unless (consequent.kind_of?(Numeric) || consequent.nil?)
 
-    if consequent
-      @antecedent = antecedent.abs
-      @consequent = consequent.abs
-    else
-      antecedent = antecedent.abs
-      @antecedent = antecedent.numerator
-      @consequent = antecedent.denominator
-    end
-    @equave = equave
-    @reduced_antecedent, @reduced_consequent = _equave_reduce(equave)
-    @label = label
-    @approximation = Approximation.new(ratio: self)
+    _initialize(antecedent, consequent, label:, equave:)
   end
 
   alias :numerator :antecedent
@@ -183,7 +172,7 @@ class Tonal::Ratio
   #   Tonal::ReducedRatio.new(3,2).step(12) => 7
   #
   def step(modulo=12)
-    to_log2.step(modulo)
+    Tonal::Step.new(ratio: to_r, modulo: modulo)
   end
 
   # @return [Float] degrees
@@ -254,13 +243,12 @@ class Tonal::Ratio
   end
   alias :reflect :invert
 
-  # @return [self] with antecedent and precedent switched
+  # @return [Tonal::Ratio] with antecedent and precedent switched
   # @example
   #   Tonal::Ratio.new(3,2).invert! => (2/3)
   #
   def invert!
-    tmp = antecedent
-    @antecedent, @consequent = consequent, tmp
+    _initialize(consequent, antecedent, label: label, equave: equave)
     self
   end
 
@@ -273,7 +261,7 @@ class Tonal::Ratio
     (self.class.new(axis) ** 2) / self
   end
 
-  # @return Tonal::ReducedRatio the Ernst Levy negative of self
+  # @return [Tonal::ReducedRatio] the Ernst Levy negative of self
   # @example
   #   Tonal::ReducedRatio.new(7/4r).negative => (12/7)
   #
@@ -428,13 +416,15 @@ class Tonal::Ratio
     benedetti_height.prime_division.reject{|p| prime_rejects.include?(p.first) }.sum{|p| p.first * p.last }
   end
 
-  # @return [Float] the cents difference between self and its step in the given modulo
+  # @return [Tonal::Cents] the cents difference between self and its step in the given modulo
   # @example
   #   Tonal::ReducedRatio.new(3,2).efficiency(12) => -1.955000865387433
   # @param modulo
   #
   def efficiency(modulo)
-    ((Tonal::Cents::CENT_SCALE * step(modulo).step / modulo.to_f) - to_cents).round(Tonal::Cents::PRECISION)
+    # We want the efficiency from the ratio, instead of from the step.
+    # If step efficiency is X cents, then ratio efficiency is -X cents.
+    step(modulo).efficiency * -1.0
   end
 
   # @return [Array] the results of ratio dividing and multiplying self
@@ -458,7 +448,7 @@ class Tonal::Ratio
   end
   alias :min_plus :plus_minus
 
-  # @return [Cents] cent difference between self and other ratio
+  # @return [Tonal::Cents] cent difference between self and other ratio
   # @example
   #   Tonal::ReducedRatio.new(3,2).cent_diff(4/3r) => 203.92
   # @param other_ratio [Tonal::ReducedRatio, Numeric] from which self's cents is measured
@@ -554,6 +544,21 @@ class Tonal::Ratio
   end
 
   private
+  def _initialize(antecedent, consequent=nil, label: nil, equave: 2/1r)
+    if consequent
+      @antecedent = antecedent.abs
+      @consequent = consequent.abs
+    else
+      antecedent = antecedent.abs
+      @antecedent = antecedent.numerator
+      @consequent = antecedent.denominator
+    end
+    @equave = equave
+    @reduced_antecedent, @reduced_consequent = _equave_reduce(equave)
+    @label = label
+    @approximation = Approximation.new(ratio: self)
+  end
+
   def raise_if_negative(*args)
     raise ArgumentError, "Arguments must be greater than zero" if args.any?{|i| i < 0 }
   end

data/lib/tonal/reduced_ratio.rb

@@ -25,7 +25,7 @@ class Tonal::ReducedRatio < Tonal::Ratio
     Tonal::Ratio.new(antecedent, consequent)
   end
 
-  # @return [Interval] between self (upper) and ratio (lower)
+  # @return [Tonal::Interval] between self (upper) and ratio (lower)
   # @example
   #   Tonal::ReducedRatio.new(133).interval_with(3/2r) => 133/96 (133/128 / 3/2)
   # @param ratio
@@ -34,4 +34,14 @@ class Tonal::ReducedRatio < Tonal::Ratio
     r = ratio.is_a?(self.class) ? ratio : self.class.new(ratio)
     Tonal::Interval.new(self, r)
   end
+
+  # @return [Tonal::ReducedRatio] with antecedent and precedent switched
+  # @example
+  #   Tonal::ReducedRatio.new(3,2).invert! => (4/3)
+  #
+  def invert!
+    super
+    @antecedent, @consequent = @reduced_antecedent, @reduced_consequent
+    self
+  end
 end

data/lib/tonal/step.rb

@@ -28,18 +28,62 @@ class Tonal::Step
   end
   alias :to_s :inspect
 
+  # @return [Tonal::Step] new step with the ratio mapped to the new modulo
+  # @example
+  #   Tonal::Step.new(ratio: 3/2r, modulo: 31).convert(12)
+  #   => 7\12
+  #
   def convert(new_modulo)
     self.class.new(log: log, modulo: new_modulo)
   end
 
-  def to_r
+  # @return [Rational] of the step
+  # @example
+  #   Tonal::Step.new(ratio: 3/2r, modulo: 31).step_to_r
+  #   => 6735213777669305/4503599627370496
+  #
+  def step_to_r
+    tempered.to_r
+  end
+  alias :to_r :step_to_r
+
+  # @return [Rational] of the ratio
+  # @example
+  #   Tonal::Step.new(ratio: 3/2r, modulo: 31).ratio_to_r
+  #   => 3/2
+  #
+  def ratio_to_r
     ratio.to_r
   end
 
-  def to_cents
+  # @return [Tonal::Cents] measure of step in cents
+  # @example
+  #   Tonal::Step.new(ratio: 3/2r, modulo: 31).step_to_cents
+  #   => 696.77
+  #
+  def step_to_cents
+    tempered.to_cents
+  end
+  alias :to_cents :step_to_cents
+
+  # @return [Tonal::Cents] measure of ratio in cents
+  # @example
+  #   Tonal::Step.new(ratio: 3/2r, modulo: 31).ratio_to_cents
+  #   => 701.96
+  #
+  def ratio_to_cents
     ratio.to_cents
   end
 
+  # @return [Tonal::Cents] the difference between the step and the ratio
+  # @example
+  #   Tonal::Step.new(ratio: 3/2r, modulo: 31).efficiency
+  #   => 5.19
+  #
+  def efficiency
+    ratio_to_cents - step_to_cents
+  end
+
   def +(rhs)
     self.class.new(step: (rhs % modulo), modulo: modulo)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tonal-tools
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 3.0.1
 platform: ruby
 authors:
 - Jose Hales-Garcia
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-13 00:00:00.000000000 Z
+date: 2024-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yaml
@@ -192,7 +192,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '3.1'
 requirements: []
-rubygems_version: 3.5.5
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: Tonal tools