tonal-tools 7.3.0 → 7.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21362801eb7f0b63d3c05d4f694a4288bf3b2c0adf5cc3548953f25971a441d7
-  data.tar.gz: 6279ffac59c2af3bedcf794e945fbb4654599b87620df95badaa3431ee995f0a
+  metadata.gz: 769baf7d488e059f0f8072fdcf39dcf33567d14a631e6a55eece8c7c9ff864d1
+  data.tar.gz: 1e7ef0b95e95df63a2667ac04f2062ce0a62502ea577fd7c6d529e407ecc04da
 SHA512:
-  metadata.gz: b502514508150824355941fad9c009aef56f7edc8e4246963e151389ca60b3acaf56c90434b7a52a27af8633668b00c581ea335078f5356c2c3d319d5fd60470
-  data.tar.gz: f5e9614f05e070fe8642fdd7df7caacfde96b52f6963bc3c8a69c8821cc8b7bc61f84da613f877ddb3699acb5df6ac5b086d12eb6fe2ebf5a018df54f603179f
+  metadata.gz: 88ec036a5b4f17503d905c25bacf74a22d6d0c00b4a792d6196c5faecfcdebae3836711deb363a65863df4334a61f35d0b974de0fa42816390c0548e538a0a1f
+  data.tar.gz: 8f004f602f9e8780a7c0a64dbb1132ba323f7032411b8bd5617b89973c14047f5f607ea3c67d30287c29922719c3a3c580759463242fba73a3feac8280cee104

data/lib/tonal/attributions.rb

@@ -1,4 +1,4 @@
 module Tonal
   TOOLS_PRODUCER = "mTonal"
-  TOOLS_VERSION = "7.3.0"
+  TOOLS_VERSION = "7.4.0"
 end

data/lib/tonal/extended_ratio.rb

@@ -0,0 +1,131 @@
+module Tonal::ExtendableRatio
+  extend Forwardable
+  include Comparable
+  def_delegators :@partials, :size, :length, :each, :map, :select, :first, :last, :[], :count
+
+  attr_reader :partials
+
+  # @return [Tonal::ExtendedRatio, Tonal::SubharmonicExtendedRatio]
+  # @example
+  #   Tonal::ExtendedRatio.new(partials: [1, 2, 3])
+  #   Tonal::SubharmonicExtendedRatio.new(ratios: [Rational(1,1), Rational(1,2), Rational(1,3)])
+  # @param partials [Array<Numeric>] the partials to initialize the extended ratio
+  # @param ratios [Array<Rational>] the ratios to initialize the extended ratio
+  #
+  def initialize(partials: nil, ratios: nil)
+    raise(ArgumentError, "Provide either partials or ratios, not both", caller[0]) if !partials.nil? && !ratios.nil?
+    raise(ArgumentError, "Provide either partials or ratios", caller[0]) if partials.nil? && ratios.nil?
+
+    if partials
+      during_initialize(*partials)
+    elsif ratios
+      first = ratios.first
+      partials = ratios.map{|r| r * first}
+      during_initialize(*partials)
+    end
+  end
+
+  # @return [Tonal::Interval] the interval between two partials
+  # @example
+  #   er = Tonal::ExtendedRatio.new(partials: [1, 2, 3, 4])
+  #   er.interval_between(0, 2) => Tonal::Interval representing 3/2
+  #
+  def interval_between(index1, index2, reduced: true)
+    return nil if self[index1].nil? || self[index2].nil?
+    first = partials.first
+    r1 = reduced ? Tonal::ReducedRatio.new(self[index1], first) : Tonal::Ratio.new(self[index1], first)
+    r2 = reduced ? Tonal::ReducedRatio.new(self[index2], first) : Tonal::Ratio.new(self[index2], first)
+    Tonal::Interval.new(r1, r2, reduced:)
+  end
+
+  def inspect
+    display.join(":")
+  end
+
+  private
+  def switch_domain(domain)
+    case domain
+    when :harmonic
+      Tonal::ExtendedRatio
+    when :subharmonic
+      Tonal::SubharmonicExtendedRatio
+    else
+      raise(ArgumentError, "Unknown domain: #{domain}", caller[0])
+    end.new(ratios: ratios.map(&:to_r))
+  end
+  alias :switch_to :switch_domain
+end
+
+class Tonal::ExtendedRatio
+  include Tonal::ExtendableRatio
+
+  # @return [Array<Tonal::Ratio, Tonal::ReducedRatio>] the ratios of the extended ratio
+  # @example
+  #   er = Tonal::ExtendedRatio.new(partials: [4, 5, 6])
+  #   er.ratios => [1/1, 5/4, 3/2]
+  # @param reduced [Boolean] whether to return reduced ratios or not
+  #
+  def ratios(reduced: true)
+    first = partials.first
+    partials.map do |n|
+      reduced ? Tonal::ReducedRatio.new(n, first) : Tonal::Ratio.new(n, first)
+    end
+  end
+
+  # @return [Tonal::SubharmonicExtendedRatio] the subharmonic extended ratio
+  # @example
+  #   er = Tonal::ExtendedRatio.new(partials: [4, 5, 6])
+  #   er.to_subharmonic_extended_ratio => Tonal::SubharmonicExtendedRatio with partials [(1/15), (1/12), (1/10)]
+  #
+  def to_subharmonic_extended_ratio
+    switch_to(:subharmonic)
+  end
+  alias :to_sefr :to_subharmonic_extended_ratio
+
+  private
+  def during_initialize(*args)
+    lcm = args.denominators.lcm
+    @partials = Array.new(args.map{|n| n * lcm}.numerators).sort
+  end
+
+  def display
+    @display ||= partials.map{|r| r.round(2)}
+  end
+end
+
+class Tonal::SubharmonicExtendedRatio
+  include Tonal::ExtendableRatio
+
+  # @return [Array<Tonal::Ratio, Tonal::ReducedRatio>] the ratios of the subharmonic extended ratio
+  # @example
+  #   ser = Tonal::SubharmonicExtendedRatio.new(partials: [6,5,4])
+  #   ser.ratios => [1/1, 6/5, 3/2]
+  # @param reduced [Boolean] whether to return reduced ratios or not
+  #
+  def ratios(reduced: true)
+    first = partials.first
+    partials.map do |n|
+      reduced ? Tonal::ReducedRatio.new(n, first) : Tonal::Ratio.new(n, first)
+    end
+  end
+
+  # @return [Tonal::ExtendedRatio] the harmonic extended ratio
+  # @example
+  #   ser = Tonal::SubharmonicExtendedRatio.new(partials: [6,5,4])
+  #   ser.to_extended_ratio => Tonal::ExtendedRatio with partials [10, 12, 15]
+  #
+  def to_extended_ratio
+    switch_to(:harmonic)
+  end
+  alias :to_efr :to_extended_ratio
+
+  private
+  def during_initialize(*args)
+    lcm = args.numerators.lcm
+    @partials = args.map{|n| n.kind_of?(Rational) ? n / lcm : n.reciprocal}.sort
+  end
+
+  def display
+    @display ||= partials.map(&:reciprocal).map{|r| (r % 1).zero? ? r.to_i : r}.map{|r| r.round(2)}
+  end
+end

data/lib/tonal/extensions.rb

@@ -158,7 +158,7 @@ class Numeric
   # @example
   #   (3/2r).to_interval => 3/2 (3/2 / 1/1)
   #
-  def to_interval = Tonal::Interval.new(1/1r, self)
+  def to_interval = Tonal::Interval.new(self)
 
   # @return [Tonal::Cents] difference between ratio (upper) and self (lower)
   # @example
@@ -221,6 +221,12 @@ class Numeric
   # @param base of the log
   #
   def log_floor(base=10) = Math.log(self, base).floor
+
+  # @return [Rational] the reciprocal of self
+  # @example
+  #   (3/2r).reciprocal => (2/3)
+  #
+  def reciprocal = Rational(1,self)
 end
 
 class Integer
@@ -398,6 +404,16 @@ class Array
   def to_cents = self.map{|r| r.to_cents}
   alias :cents :to_cents
 
+  # @return [Tonal::Interval]
+  # @example
+  #   [3/2r, 4/3r].to_interval => 16/9 (4/3 / 3/2)
+  # @example
+  #   [5].to_interval => 5/4 (5/4 / 1/1)
+  # @example
+  #   [2,3,3,4].to_interval => 9/8 (3/2 / 4/3)
+  #
+  def to_interval = Tonal::Interval.new(*self)
+
   # @return [Float] the mean of the elements of self
   # @example
   #   [1, 2].mean => 1.5
@@ -474,6 +490,34 @@ class Array
   #   [4,3].to_r => (4/3)
   #
   def to_r = Rational(numerator, denominator)
+
+  # @return [Tonal::ExtendedRatio]
+  # @example
+  #   [4/1r, 5/1r, 6/1r].to_efr => ExtendedRatio "4:5:6"
+  # @param as :ratios or :partials
+  #
+  def to_efr(as: :ratios) = as == :ratios ? Tonal::ExtendedRatio.new(ratios: self) : Tonal::ExtendedRatio.new(partials: self)
+
+  # @return [Tonal::SubharmonicExtendedRatio]
+  # @example
+  #   [4,5,6].to_sefr => SubharmonicExtendedRatio "4:5:6"
+  # @param as :ratios or :partials
+  #
+  def to_sefr(as: :ratios) = as == :ratios ? Tonal::SubharmonicExtendedRatio.new(ratios: self) : Tonal::SubharmonicExtendedRatio.new(partials: self)
+end
+
+class Range
+  # @return [Tonal::ExtendedRatio]
+  # @example
+  #   (4..7).to_efr => 4:5:6:7
+  #
+  def to_efr = Tonal::ExtendedRatio.new(partials: self)
+
+  # @return [Tonal::SubharmonicExtendedRatio]
+  # @example
+  #   (4..7).to_sefr => 7:6:5:4
+  #
+  def to_sefr = Tonal::SubharmonicExtendedRatio.new(partials: self)
 end
 
 class Vector

data/lib/tonal/interval.rb

@@ -11,10 +11,15 @@ class Tonal::Interval
   # @return [Tonal::Interval] the interval of the given ratios
   # @example
   #   Tonal::Interval.new(2,3) => (3/2) ((3/2) / (1/1))
+  # @example
+  #   Tonal::Interval.new(2,3,3,4) => (9/8) ((3/2) / (4/3))
+  # @example
+  #   Tonal::Interval.new(3) => (3/1) ((3/1) / (1/1))
   # @param args two arguments representing ratios or four arguments representing two pairs of numerator/denominator
   # @param reduced boolean determining whether to use Tonal::ReducedRatio or Tonal::Ratio
   #
   def initialize(*args, reduced: true)
+    args = [1/1r, args[0]] if args.length == 1
     klass = reduced ? Tonal::ReducedRatio : Tonal::Ratio
     raise(ArgumentError, "Two or four arguments required. Either two ratios, or two pairs of numerator, denominator", caller[0]) unless [2, 4].include?(args.size)
     @lower_ratio, @upper_ratio = case args.size
@@ -42,7 +47,7 @@ class Tonal::Interval
   end
 
   def inspect
-    "#{interval} (#{upper} / #{lower})"
+    "#{interval.label} (#{upper.label} / #{lower.label})"
   end
 
   def <=>(rhs)

data/lib/tonal/irb_helpers.rb

@@ -23,6 +23,10 @@ module Tonal
     # @return [Tonal::Interval] the interval between the given args
     # @example
     #   i(2,3) => (3/2) ((3/2) / (1/1))
+    # @example
+    #  i(2,3,3,4) => (9/8) ((3/2) / (4/3))
+    # @example
+    #   i(3) => (3/1) ((3/1) / (1/1))
     # @param args two arguments representing ratios or four arguments representing two pairs of numerator/denominator
     # @param reduced boolean determining whether to use Tonal::ReducedRatio or Tonal::Ratio
     #

data/lib/tonal/ratio.rb

@@ -233,7 +233,7 @@ class Tonal::Ratio
   # @return [Tonal::ReducedRatio] of self
   # @example
   #   Tonal::Ratio.new(1,9).to_reduced_ratio => (16/9)
-  # 
+  #
   def to_reduced_ratio
     Tonal::ReducedRatio.new(reduced_antecedent, reduced_consequent, equave: equave)
   end
@@ -247,6 +247,7 @@ class Tonal::Ratio
     self.class.new(consequent, antecedent)
   end
   alias :reflect :invert
+  alias :reciprocal :invert
 
   # @return [Tonal::Ratio] with antecedent and precedent switched
   # @example
@@ -472,10 +473,8 @@ class Tonal::Ratio
   # @return [String] symbolic representation of Tonal::Ratio
   #
   def label
-    # Return label, if defined; or,
-    # Return the "antecedent/consequent", if antecedent is less than 7 digits long; or
-    # Return the floating point representation rounded to 2 digits of precision
-    (@label || ((Math.log10(antecedent).to_i + 1) <= 6 ? "#{antecedent}/#{consequent}" : to_f.round(PRECISION))).to_s
+    # Return label, if defined; or see inspect
+    @label || inspect
   end
 
   # @return [String] the string representation of Tonal::Ratio
@@ -483,7 +482,9 @@ class Tonal::Ratio
   #   Tonal::Ratio.new(3, 2).inspect => "(3/2)"
   #
   def inspect
-    "(#{antecedent}/#{consequent})"
+    # Return the "antecedent/consequent", if antecedent is less than 7 digits long; or
+    # Return the floating point representation rounded to PRECISION digits
+    ((Math.log10(antecedent).to_i + 1) <= 6 ? "#{antecedent}/#{consequent}" : "#{to_f.round(PRECISION)}")
   end
   alias :to_s :inspect
 
@@ -642,4 +643,3 @@ module Ratio
     Tonal::Ratio.new(u, l)
   end
 end
-

data/lib/tonal/tools.rb

@@ -14,6 +14,7 @@ module Tonal
   require "tonal/approximation"
   require "tonal/ratio"
   require "tonal/reduced_ratio"
+  require "tonal/extended_ratio"
   require "tonal/interval"
   require "tonal/step"
   require "tonal/extensions"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: tonal-tools
 version: !ruby/object:Gem::Version
-  version: 7.3.0
+  version: 7.4.0
 platform: ruby
 authors:
 - Jose Hales-Garcia
 bindir: bin
 cert_chain: []
-date: 2025-12-04 00:00:00.000000000 Z
+date: 2025-12-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yaml
@@ -161,6 +161,7 @@ files:
 - lib/tonal/attributions.rb
 - lib/tonal/cents.rb
 - lib/tonal/comma.rb
+- lib/tonal/extended_ratio.rb
 - lib/tonal/extensions.rb
 - lib/tonal/hertz.rb
 - lib/tonal/interval.rb