Class: Tonal::Ratio

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Comparable
Defined in:
lib/tonal/approximation.rb,
lib/tonal/ratio.rb

Direct Known Subclasses

ReducedRatio

Defined Under Namespace

Classes: Approximation

Constant Summary collapse

PRECISION = 
2
DEFAULT_EQUAVE = 
2
PRIME_LIMIT = 
10_000

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(antecedent, consequent = nil, label: nil, equave: DEFAULT_EQUAVE) ⇒ Tonal::Ratio

Examples:

Tonal::Ratio.new(3,2) => 3/2

Parameters:

Raises:

  • (ArgumentError) 


21
22
23
24
25
26
 
# File 'lib/tonal/ratio.rb', line 21

def initialize(antecedent, consequent=nil, label: nil, equave: DEFAULT_EQUAVE)
  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?)

  _initialize(antecedent, consequent, label:, equave:)
end

Instance Attribute Details

#antecedent ⇒ Object (readonly) Also known as: numerator

Returns the value of attribute antecedent.



11
12
13
 
# File 'lib/tonal/ratio.rb', line 11

def antecedent
  @antecedent
end

#consequent ⇒ Object (readonly) Also known as: denominator

Returns the value of attribute consequent.



11
12
13
 
# File 'lib/tonal/ratio.rb', line 11

def consequent
  @consequent
end

#equave ⇒ Object (readonly)

Returns the value of attribute equave.



11
12
13
 
# File 'lib/tonal/ratio.rb', line 11

def equave
  @equave
end

#label ⇒ String

Returns symbolic representation of Tonal::Ratio.

Returns:

  • (String) —

    symbolic representation of Tonal::Ratio



582
583
584
 
# File 'lib/tonal/ratio.rb', line 582

def label
  @label
end

#reduced_antecedent ⇒ Object (readonly)

Returns the value of attribute reduced_antecedent.



11
12
13
 
# File 'lib/tonal/ratio.rb', line 11

def reduced_antecedent
  @reduced_antecedent
end

#reduced_consequent ⇒ Object (readonly)

Returns the value of attribute reduced_consequent.



11
12
13
 
# File 'lib/tonal/ratio.rb', line 11

def reduced_consequent
  @reduced_consequent
end

Class Method Details

.ed(step, modulo, equave: DEFAULT_EQUAVE) ⇒ Tonal::Ratio

Returns the ratio of step in the modulo.

Examples:

Tonal::Ratio.ed(12, 7) => 1.5

Parameters:

  • modulo —

    the number of steps in the equal division

  • step —

    the step number in the equal division of the equave

  • equave (defaults to: DEFAULT_EQUAVE) —

    the interval of equivalence, default 2/1

Returns:



84
85
86
 
# File 'lib/tonal/ratio.rb', line 84

def self.ed(step, modulo, equave: DEFAULT_EQUAVE)
  self.new(2**(step.to_f/modulo), equave:)
end

.random_ratio(number_of_factors = 2, within: 100, reduced: (self == Tonal::ReducedRatio) ? true : false) ⇒ Tonal::Ratio

Returns a randomly generated ratio.

Examples:

Tonal::Ratio.random_ratio => 169/1

Parameters:

  • number_of_factors (defaults to: 2) —

    the number of prime factors to include in the ratio

  • within (defaults to: 100) —

    the upper limit for prime factors

  • reduced (defaults to: (self == Tonal::ReducedRatio) ? true : false) —

    boolean determining whether to use Tonal::ReducedRatio or Tonal::Ratio

Returns:



66
67
68
69
70
71
72
73
74
75
 
# File 'lib/tonal/ratio.rb', line 66

def self.random_ratio(number_of_factors = 2, within: 100, reduced: (self == Tonal::ReducedRatio) ? true : false)
  primes = Prime.each(within).to_a
  nums = []
  dens = []
  1.upto(number_of_factors) do
    nums << [primes[rand(10)], rand(3)]
    dens << [primes[rand(10)], rand(3)]
  end
  [nums, dens].ratio_from_prime_divisions(reduced:)
end

.superparticular(n, factor: 1, superpart: :upper) ⇒ Tonal::Ratio

Returns ratio who's numerator and denominator are seperated by a difference of 1.

Examples:

Tonal::Ratio.superparticular(100) = 101/100

Parameters:

  • n (Integer) —

    number from which the superior part is calculated

  • factor (Rational) (defaults to: 1) —

    multiplied into the resulting ratio, default 1/1

  • superpart (Symbol) (defaults to: :upper) —

    assigning the superior part to the antecedent or consequent

Returns:

  • (Tonal::Ratio) —

    ratio who's numerator and denominator are seperated by a difference of 1



38
39
40
 
# File 'lib/tonal/ratio.rb', line 38

def self.superparticular(n, factor: 1/1r, superpart: :upper)
  superpartient(n, summand: 1, factor:, superpart:)
end

.superpartient(n, summand:, factor: 1, superpart: :upper) ⇒ Tonal::Ratio

Returns ratio who's numerator and denominator are separated by a summand difference.

Examples:

Tonal::Ratio.superpartient(23, summand: 3) => 26/23

Parameters:

  • n (Integer) —

    number from which the superior part is calculated

  • summand (Integer) —

    term added to the superior part

  • factor (Rational) (defaults to: 1) —

    multiplied into the resulting ratio, default 1/1

  • superpart (Symbol) (defaults to: :upper) —

    assigning the superior part to the antecedent or consequent

Returns:

  • (Tonal::Ratio) —

    ratio who's numerator and denominator are separated by a summand difference



50
51
52
53
54
55
56
57
 
# File 'lib/tonal/ratio.rb', line 50

def self.superpartient(n, summand:, factor: 1/1r, superpart: :upper)
  case superpart.to_sym.downcase
  when :lower, :consequent, :denominator
    self.new(n*factor.numerator, (n+summand)*factor.denominator)
  else
    self.new((n+summand)*factor.numerator, n*factor.denominator)
  end
end

.within_cents?(cents1, cents2, within) ⇒ Boolean

Returns if pair of ratios are within the given cents limit.

Examples:

Tonal::Ratio.within_cents?(100, 105, 2) => false

Parameters:

  • cents1
  • cents2
  • within

Returns:

  • (Boolean) —

    if pair of ratios are within the given cents limit



95
96
97
 
# File 'lib/tonal/ratio.rb', line 95

def self.within_cents?(cents1, cents2, within)
  (cents1 - cents2).abs <= within
end

Instance Method Details

#*(rhs) ⇒ Tonal::Ratio

Returns result of multiplying self and rhs.

Examples:

Tonal::Ratio.new(3,2) * Tonal::Ratio.new(4,3) => (2/1)

Parameters:

Returns:



626
627
628
 
# File 'lib/tonal/ratio.rb', line 626

def *(rhs)
  operate(rhs, :*)
end

#**(rhs) ⇒ Tonal::Ratio

Returns result of raising self to the rhs power.

Examples:

Tonal::Ratio.new(3,2) ** 2 => (9/4)

Parameters:

Returns:

  • (Tonal::Ratio) —

    result of raising self to the rhs power



644
645
646
 
# File 'lib/tonal/ratio.rb', line 644

def **(rhs)
  operate(rhs, :**)
end

#+(rhs) ⇒ Tonal::Ratio

Returns result of adding self and rhs.

Examples:

Tonal::Ratio.new(3,2) + Tonal::Ratio.new(4,3) => (17/12)

Parameters:

Returns:



608
609
610
 
# File 'lib/tonal/ratio.rb', line 608

def +(rhs)
  operate(rhs, :+)
end

#-(rhs) ⇒ Tonal::Ratio

Returns result of subtracting rhs from self.

Examples:

Tonal::Ratio.new(3,2) - Tonal::Ratio.new(4,3) => (1/6)

Parameters:

Returns:



617
618
619
 
# File 'lib/tonal/ratio.rb', line 617

def -(rhs)
  operate(rhs, :-)
end

#/(rhs) ⇒ Tonal::Ratio

Returns result of dividing self by rhs.

Examples:

Tonal::Ratio.new(3,2) / Tonal::Ratio.new(4,3) => (9/8)

Parameters:

Returns:



635
636
637
 
# File 'lib/tonal/ratio.rb', line 635

def /(rhs)
  operate(rhs, :/)
end

#<=>(rhs) ⇒ Integer

Returns comparison of self to rhs.

Examples:

Tonal::Ratio.new(3,2) <=> Tonal::Ratio.new(4,3) => 1

Parameters:

Returns:

  • (Integer) —

    comparison of self to rhs



664
665
666
667
668
 
# File 'lib/tonal/ratio.rb', line 664

def <=>(rhs)
  left = consequent == 0 ? Float::INFINITY : Rational(antecedent, consequent)
  right = rhs.denominator == 0 ? Float::INFINITY : Rational(rhs.numerator, rhs.denominator)
  left <=> right
end

#approximate ⇒ Tonal::Ratio::Approximation

Returns self's approximation instance.

Returns:



108
109
110
 
# File 'lib/tonal/ratio.rb', line 108

def approximate
  @approximation
end

#benedetti_height ⇒ Integer Also known as: product_complexity

=================================

Measures of complexity

Examples:

Tonal::ReducedRatio.new(3/2r).benedetti_height => 6

Returns:

  • (Integer) —

    the product complexity of self



418
419
420
 
# File 'lib/tonal/ratio.rb', line 418

def benedetti_height
  reduced_antecedent * reduced_consequent
end

#cent_diff ⇒ Tonal::Cents

Returns cent difference between self and other ratio.

Examples:

Tonal::ReducedRatio.new(3,2).cents_difference_with(4/3r) => 203.92

Parameters:

Returns:

  • (Tonal::Cents) —

    cent difference between self and other ratio



498
499
500
 
# File 'lib/tonal/ratio.rb', line 498

def cents_difference_with(other_ratio)
  to_cents - other_ratio.ratio.to_cents
end

#cents_difference_with(other_ratio, is_lower: true) ⇒ Tonal::Cents

Returns difference between ratio (upper) and self (lower).

Examples:

Tonal::ReducedRatio.new(3,2).cents_difference_with(4/3r) => 203.91
Tonal::ReducedRatio.new(3,2).cents_difference_with(4/3r, is_lower: false) => 996.09

Parameters:

Returns:

  • (Tonal::Cents) —

    difference between ratio (upper) and self (lower)



495
496
497
 
# File 'lib/tonal/ratio.rb', line 495

def cents_difference_with(other_ratio)
  to_cents - other_ratio.ratio.to_cents
end

#combination ⇒ Integer Also known as: comb

Returns the sum of antecedent and consequent.

Examples:

Tonal::ReducedRatio.new(3,2).combination => 5

Returns:

  • (Integer) —

    the sum of antecedent and consequent



558
559
560
 
# File 'lib/tonal/ratio.rb', line 558

def combination
  antecedent + consequent
end

#difference ⇒ Integer Also known as: diff

Returns the difference between antecedent and consequent.

Examples:

Tonal::ReducedRatio.new(3,2).difference => 1

Returns:

  • (Integer) —

    the difference between antecedent and consequent



549
550
551
 
# File 'lib/tonal/ratio.rb', line 549

def difference
  antecedent - consequent
end

#div_times(other_ratio) ⇒ Array

Returns the results of ratio dividing and multiplying self.

Examples:

Tonal::ReducedRatio.new(3/2r).div_times(5/4r) => [(6/5), (15/8)]

Parameters:

  • other_ratio —

    to divide and multiple on self

Returns:

  • (Array) —

    the results of ratio dividing and multiplying self



474
475
476
477
 
# File 'lib/tonal/ratio.rb', line 474

def div_times(other_ratio)
  other_ratio = self.class.new(other_ratio)
  [self / other_ratio, self * other_ratio]
end

#efficiency(modulo, is_step_efficiency: false) ⇒ Tonal::Cents

Returns the cents difference between self and its step in the given modulo.

Examples:

Tonal::ReducedRatio.new(3,2).efficiency(12) => -1.96

Parameters:

  • modulo —

    against which the difference of self is compared

Returns:

  • (Tonal::Cents) —

    the cents difference between self and its step in the given modulo



463
464
465
466
467
 
# File 'lib/tonal/ratio.rb', line 463

def efficiency(modulo, is_step_efficiency: false)
  # For single ratios, we normally want the efficiency from the ratio (self).
  # If the step efficiency is X cents, then the ratio efficiency is -X cents.
  step(modulo).efficiency * (is_step_efficiency ? 1.0 : -1.0)
end

#eql?(other) ⇒ Boolean

Set uses Hash as storage and equality of elements is determined according to Object#eql? and Object#hash.

Returns:

  • (Boolean) 


672
673
674
 
# File 'lib/tonal/ratio.rb', line 672

def eql?(other)
   other.instance_of?(self.class) && to_r == other.to_r
end

#equave_reduce(equave = DEFAULT_EQUAVE) ⇒ Tonal::Ratio Also known as: reduce, reduced

Returns copy of self reduced to the given equave.

Examples:

Tonal::Ratio.new(48,14).equave_reduce(3) => 8/7

Parameters:

  • equave (defaults to: DEFAULT_EQUAVE) —

    Numeric

Returns:

  • (Tonal::Ratio) —

    copy of self reduced to the given equave



240
241
242
 
# File 'lib/tonal/ratio.rb', line 240

def equave_reduce(equave=DEFAULT_EQUAVE)
  self.class.new(*_equave_reduce(equave))
end

#equave_reduce!(equave = DEFAULT_EQUAVE) ⇒ Tonal::Ratio Also known as: reduce!, reduced!

Returns self reduced to the given equave.

Examples:

Tonal::Ratio.new(48,14).equave_reduce!(3) => 8/7

Parameters:

  • equave (defaults to: DEFAULT_EQUAVE) —

    Numeric

Returns:



251
252
253
254
 
# File 'lib/tonal/ratio.rb', line 251

def equave_reduce!(equave=DEFAULT_EQUAVE)
  @antecedent, @consequent = _equave_reduce(equave)
  self
end

#fraction_reduce ⇒ Tonal::Ratio

Returns copy of self rationally reduced.

Examples:

Tonal::Ratio.new(16,14).fraction_reduce => 8/7

Returns:

See Also:



231
232
233
 
# File 'lib/tonal/ratio.rb', line 231

def fraction_reduce
  self.class.new(to_r)
end

#hash ⇒ Object 



676
 
# File 'lib/tonal/ratio.rb', line 676

def hash = [self.class, to_r].hash

#inspect ⇒ String Also known as: to_s

Returns the string representation of Tonal::Ratio.

Examples:

Tonal::Ratio.new(3, 2).inspect => "3/2"

Returns:

  • (String) —

    the string representation of Tonal::Ratio



591
592
593
594
595
596
 
# File 'lib/tonal/ratio.rb', line 591

def inspect
  # Return the "antecedent/consequent", if antecedent is less than 7 digits long; or
  # Return the floating point representation rounded to PRECISION digits
  func = -> (n) { n.zero? ? n : Math.log10(n).to_i + 1 }
  ((func.call(antecedent)) <= 6 ? "#{antecedent}/#{consequent}" : "#{to_f.round(PRECISION)}")
end

#interval_with(other_ratio, is_lower: true) ⇒ Tonal::Interval

Returns between self and another ratio.

Examples:

Tonal::ReducedRatio.new(3,2).interval_with(4/3r)
=> 9/8 (3/2 / 4/3)
Tonal::ReducedRatio.new(3,2).interval_with(4/3r, is_lower: false)
=> 16/9 (4/3 / 3/2)

Parameters:

  • other_ratio (Tonal::ReducedRatio, Numeric) —

    the ratio to form the interval with

  • is_lower (Boolean) (defaults to: true) —

    whether other_ratio is the lower ratio of the interval

Returns:



519
520
521
522
523
 
# File 'lib/tonal/ratio.rb', line 519

def interval_with(other_ratio, is_lower: true)
  other_ratio = self.class.new(other_ratio)
  args = is_lower ? [self, other_ratio] : [other_ratio, self]
  Tonal::Interval.new(*args)
end

#invert ⇒ Tonal::Ratio Also known as: reflect, reciprocal

Returns copy of self with the antecedent and precedent switched.

Examples:

Tonal::Ratio.new(3,2).invert => 2/3

Returns:

  • (Tonal::Ratio) —

    copy of self with the antecedent and precedent switched



271
272
273
 
# File 'lib/tonal/ratio.rb', line 271

def invert
  self.class.new(consequent, antecedent)
end

#invert! ⇒ Tonal::Ratio

Returns with antecedent and precedent switched.

Examples:

Tonal::Ratio.new(3,2).invert! => 2/3

Returns:



281
282
283
284
 
# File 'lib/tonal/ratio.rb', line 281

def invert!
  _initialize(consequent, antecedent, label: label, equave: equave)
  self
end

#lcm(lhs) ⇒ Integer

Returns the least common multiple with self's denominator and the given number's denominator.

Examples:

Tonal::Ratio.new(3/2r).lcm(5/4r) => 4

Parameters:

Returns:

  • (Integer) —

    the least common multiple with self's denominator and the given number's denominator



505
506
507
 
# File 'lib/tonal/ratio.rb', line 505

def lcm(lhs)
  [self.denominator, lhs.denominator].lcm
end

#log_weil_height ⇒ Tonal::Log2

Returns the log of Weil height.

Examples:

Tonal::ReducedRatio.new(3/2r).log_weil_height => 1.58

Returns:



446
447
448
 
# File 'lib/tonal/ratio.rb', line 446

def log_weil_height
  Tonal::Log2.new(logarithmand: weil_height)
end

#max_prime(limit: PRIME_LIMIT) ⇒ Integer?

Returns the maximum prime factor of self, or nil if self has a prime factor above limit.

Examples:

Tonal::Ratio.new(31/30r).max_prime => 31

Parameters:

  • limit (Integer) (defaults to: PRIME_LIMIT) —

    the largest prime to factor by

Returns:

  • (Integer, nil) —

    the maximum prime factor of self, or nil if self has a prime factor above limit



397
398
399
 
# File 'lib/tonal/ratio.rb', line 397

def max_prime(limit: PRIME_LIMIT)
  prime_divisions(limit:)&.flatten(1)&.map(&:first)&.max
end

#mediant_sum(number) ⇒ Tonal::Ratio Also known as: mediant, farey_sum

Returns the mediant (Farey) sum of self and another number.

Examples:

Tonal::Ratio.new(3,2).mediant_sum(4/3r) => (7/5)

Parameters:

Returns:

  • (Tonal::Ratio) —

    the mediant (Farey) sum of self and another number



653
654
655
 
# File 'lib/tonal/ratio.rb', line 653

def mediant_sum(number)
  self.class.new(antecedent + number.numerator, consequent + number.denominator)
end

#min_prime(limit: PRIME_LIMIT) ⇒ Integer?

Returns the minimum prime factor of self, or nil if self has a prime factor above limit.

Examples:

Tonal::Ratio.new(31/30r).min_prime => 2

Parameters:

  • limit (Integer) (defaults to: PRIME_LIMIT) —

    the largest prime to factor by

Returns:

  • (Integer, nil) —

    the minimum prime factor of self, or nil if self has a prime factor above limit



406
407
408
 
# File 'lib/tonal/ratio.rb', line 406

def min_prime(limit: PRIME_LIMIT)
  prime_divisions(limit:)&.flatten(1)&.map(&:first)&.min
end

#mirror(axis = 1) ⇒ Tonal::Ratio

Returns the mirror of self along the axis (default 1/1).

Examples:

Tonal::ReducedRatio.new(4,3).mirror => 3/2

Parameters:

  • axis (defaults to: 1)

Returns:

  • (Tonal::Ratio) —

    the mirror of self along the axis (default 1/1)



291
292
293
 
# File 'lib/tonal/ratio.rb', line 291

def mirror(axis=1/1r)
  (self.class.new(axis) ** 2) / self
end

#negative ⇒ Tonal::ReducedRatio

Returns the Ernst Levy negative of self.

Examples:

Tonal::ReducedRatio.new(7/4r).negative => 12/7

Returns:



299
300
301
 
# File 'lib/tonal/ratio.rb', line 299

def negative
  self.class.new(3/2r) / self
end

#period_degrees(round: PRECISION) ⇒ Float

Returns degrees.

Examples:

Tonal::Ratio.new(3,2).period_degrees => 210.59

Parameters:

  • round (defaults to: PRECISION)

Returns:

  • (Float) —

    degrees



213
214
215
 
# File 'lib/tonal/ratio.rb', line 213

def period_degrees(round: PRECISION)
  (360.0 * Math.log(to_f, equave)).round(round)
end

#period_radians(round: PRECISION) ⇒ Float

Returns radians.

Examples:

Tonal::Ratio.new(3,2).period_radians => 3.68

Parameters:

  • round (defaults to: PRECISION)

Returns:

  • (Float) —

    radians



222
223
224
 
# File 'lib/tonal/ratio.rb', line 222

def period_radians(round: PRECISION)
  (2 * Math::PI * Math.log(to_f, equave)).round(round)
end

#planar_degrees(round: PRECISION) ⇒ Float

Returns degrees of antecedent (x) and consequent (y) on a 2D plane.

Examples:

Tonal::Ratio.new(3,2).planar_degrees => 33.69

Parameters:

  • round (defaults to: PRECISION)

Returns:

  • (Float) —

    degrees of antecedent (x) and consequent (y) on a 2D plane



347
348
349
 
# File 'lib/tonal/ratio.rb', line 347

def planar_degrees(round: PRECISION)
  (Math.atan2(consequent, antecedent) * 180/Math::PI).round(round)
end

#planar_radians(round: PRECISION) ⇒ Float

Returns radians.

Examples:

Tonal::Ratio.new(3,2).planar_radians => 0.59

Parameters:

  • round (defaults to: PRECISION)

Returns:

  • (Float) —

    radians



356
357
358
 
# File 'lib/tonal/ratio.rb', line 356

def planar_radians(round: PRECISION)
  Math.atan2(consequent, antecedent).round(round)
end

#plus_minus(other_ratio) ⇒ Array Also known as: min_plus

Returns the results of ratio subtracted and added to self.

Examples:

Tonal::ReducedRatio.new(3/2r).plus_minus(5/4r) => [(1/1), (11/8)]

Parameters:

  • other_ratio —

    to add and subtract from self

Returns:

  • (Array) —

    the results of ratio subtracted and added to self



484
485
486
487
 
# File 'lib/tonal/ratio.rb', line 484

def plus_minus(other_ratio)
  other_ratio = self.class.new(other_ratio)
  [self - other_ratio, self + other_ratio]
end

#power(power, root = nil, approximant: 0, by_method: :continued_fraction, from: :lower_ratio) ⇒ Tonal::Ratio

Returns self raised to the given power and root.

Examples:

Tonal::ReducedRatio.new(3,2).power(2) => 9/8

Parameters:

  • power (Numeric)
  • root (Numeric, nil) (defaults to: nil)
  • approximant (Integer) (defaults to: 0) —

    the index of the approximant to use

  • by_method (Symbol) (defaults to: :continued_fraction) —

    the method used to calculate approximation of the root intervalic ratio

  • from (Symbol) (defaults to: :lower_ratio) —

    whether to calculate the root interval from the lower or upper ratio of the interval

Returns:

  • (Tonal::Ratio) —

    self raised to the given power and root



572
573
574
 
# File 'lib/tonal/ratio.rb', line 572

def power(power, root=nil, approximant: 0, by_method: :continued_fraction, from: :lower_ratio)
  to_interval.root_interval(power:, root:, approximant:, by_method:, from:).intervalic_ratio
end

#prime_divisions(limit: PRIME_LIMIT) ⇒ Array?

Returns , self decomposed into its prime factors, or nil if self has a prime factor above limit (e.g. an irrational ratio built from a Float).

Examples:

Tonal::Ratio.new(31/30r).prime_divisions => [[[31, 1]], [[2, 1], [3, 1], [5, 1]]]

Parameters:

  • limit (Integer) (defaults to: PRIME_LIMIT) —

    the largest prime to factor by

Returns:

  • (Array, nil) —

    , self decomposed into its prime factors, or nil if self has a prime factor above limit (e.g. an irrational ratio built from a Float)



365
366
367
368
369
 
# File 'lib/tonal/ratio.rb', line 365

def prime_divisions(limit: PRIME_LIMIT)
  ante = prime_division_within(antecedent, limit)
  cons = prime_division_within(consequent, limit)
  [ante, cons] if ante && cons
end

#prime_vector(limit: PRIME_LIMIT) ⇒ Vector? Also known as: monzo, prime_exponent_vector

Returns , self represented as a prime vector, or nil if self is 1/1 or has a prime factor above limit.

Examples:

Tonal::Ratio.new(3/2r).prime_vector => Vector[-1, 1]

Parameters:

  • limit (Integer) (defaults to: PRIME_LIMIT) —

    the largest prime to factor by

Returns:

  • (Vector, nil) —

    , self represented as a prime vector, or nil if self is 1/1 or has a prime factor above limit



376
377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/tonal/ratio.rb', line 376

def prime_vector(limit: PRIME_LIMIT)
  pds = prime_divisions(limit:)
  return nil if pds.nil? || pds.all?(&:empty?)

  max = [pds.first.max{|p| p.first}, pds.last.max{|p| p.first}].compact.max.first

  pds.last.collect!{|i| [i.first, -i.last]}

  p_arr = Prime.each(max).to_a
  Array.new(p_arr.count, 0).tap do |arr|
    pds.flatten(1).each{|e| arr[p_arr.find_index(e.first)] = e.last}
  end.to_vector
end

#ratio ⇒ Tonal::Ratio Also known as: to_ratio

Returns convenience method returning self.

Returns:



101
102
103
 
# File 'lib/tonal/ratio.rb', line 101

def ratio
  self
end

#scale(a, b = a) ⇒ Tonal::Ratio

Returns self scaled by given arguments.

Examples:

Tonal::Ratio.new(3,2).scale(2**5) => 96/64

Parameters:

Returns:



326
327
328
329
 
# File 'lib/tonal/ratio.rb', line 326

def scale(a, b=a)
  raise_if_negative(a,b)
  self.class.new(*(Matrix[[a, 0],[0, b]] * Vector[antecedent, consequent]))
end

#shear(a, b = a) ⇒ Tonal::Ratio

Returns self sheared by given arguments.

Examples:

Tonal::Ratio.new(3,2).shear(1, 3) => 14/11

Parameters:

Returns:



337
338
339
340
 
# File 'lib/tonal/ratio.rb', line 337

def shear(a, b=a)
  raise_if_negative(a,b)
  self.class.new(*((Matrix[[1,a],[0,1]] * Matrix[[1,0], [b,1]]) * Vector[antecedent, consequent]))
end

#step(modulo = 12) ⇒ Integer

Returns the step of self in the given modulo.

Examples:

Tonal::ReducedRatio.new(3,2).step(12) => 7\12

Returns:

  • (Integer) —

    the step of self in the given modulo



204
205
206
 
# File 'lib/tonal/ratio.rb', line 204

def step(modulo=12)
  Tonal::Scale::Step.new(ratio: to_r, modulo: modulo)
end

#tenney_height ⇒ Tonal::Log2 Also known as: log_product_complexity, harmonic_distance

Returns the log product complexity of self.

Examples:

Tonal::ReducedRatio.new(3/2r).tenney_height => 2.58

Returns:



427
428
429
 
# File 'lib/tonal/ratio.rb', line 427

def tenney_height
  Tonal::Log2.new(logarithmand: benedetti_height)
end

#to_a ⇒ Array

Returns antecedent and consequent as elements of Array.

Examples:

Tonal::Ratio.new(3,2).to_a => [3, 2]

Returns:

  • (Array) —

    antecedent and consequent as elements of Array



120
121
122
 
# File 'lib/tonal/ratio.rb', line 120

def to_a
  [antecedent, consequent]
end

#to_cents ⇒ Tonal::Cents Also known as: cents

Returns cents value of self.

Examples:

Tonal::Ratio.new(3,2).to_cents => 701.96

Returns:



173
174
175
 
# File 'lib/tonal/ratio.rb', line 173

def to_cents
  Tonal::Cents.new(ratio: to_r)
end

#to_f ⇒ Float Also known as: number

Returns self as a Float.

Examples:

Tonal::Ratio.new(3,2).to_f => 1.5

Returns:

  • (Float) —

    self as a Float



145
146
147
 
# File 'lib/tonal/ratio.rb', line 145

def to_f
  antecedent.to_f / consequent.to_f
end

#to_hertz(reference: Tonal::Hertz.reference) ⇒ Tonal::Hertz

Returns the hertz of self with respect to a reference frequency.

Examples:

Tonal::Ratio.new(3,2).to_hertz => 660.0

Parameters:

  • reference (Numeric) (defaults to: Tonal::Hertz.reference) —

    the reference frequency

Returns:

  • (Tonal::Hertz) —

    the hertz of self with respect to a reference frequency



183
184
185
 
# File 'lib/tonal/ratio.rb', line 183

def to_hertz(reference: Tonal::Hertz.reference)
  Tonal::Hertz.new(reference.to_f * to_f)
end

#to_interval ⇒ Tonal::Interval

Returns between 1/1 and self.

Examples:

Tonal::ReducedRatio.new(3,2).to_interval
=> (3/2) ((3/2) / (1/1))

Returns:



530
531
532
 
# File 'lib/tonal/ratio.rb', line 530

def to_interval
  interval_with(1/1r)
end

#to_log(base = 2) ⇒ Tonal::Log Also known as: log

Returns Math.log of self in given base.

Examples:

Tonal::Ratio.new(3,2).log(3) => 0.37

Parameters:

  • base (defaults to: 2)

Returns:



155
156
157
 
# File 'lib/tonal/ratio.rb', line 155

def to_log(base=2)
  Tonal::Log.new(logarithmand: to_r, base: base)
end

#to_log2 ⇒ Tonal::Log2 Also known as: log2

Returns Math.log2 of self.

Examples:

Tonal::ReducedRatio.new(3,2).to_log2 => 0.58

Returns:



164
165
166
 
# File 'lib/tonal/ratio.rb', line 164

def to_log2
  Tonal::Log2.new(logarithmand: to_r)
end

#to_midi(reference: Tonal::Hertz.reference, modulo: Tonal::Midi::Note::DEFAULT_MODULO) ⇒ Tonal::Midi::Note

Returns the midi representation of self with respect to a reference frequency.

Examples:

Tonal::Ratio.new(3,2).to_midi => 76 MIDI

Parameters:

  • reference (Numeric) (defaults to: Tonal::Hertz.reference) —

    the reference frequency

  • modulo (Integer) (defaults to: Tonal::Midi::Note::DEFAULT_MODULO) —

    the number of steps per octave used to scale self's offset from reference. The reference frequency's own MIDI note number is always computed independently of modulo.

Returns:

  • (Tonal::Midi::Note) —

    the midi representation of self with respect to a reference frequency



194
195
196
197
198
 
# File 'lib/tonal/ratio.rb', line 194

def to_midi(reference: Tonal::Hertz.reference, modulo: Tonal::Midi::Note::DEFAULT_MODULO)
  reference_hertz = Tonal::Hertz.new(reference)
  reference_number = reference_hertz.to_midi_note.number
  to_hertz(reference: reference_hertz).to_midi_note(modulo: modulo, reference_number: reference_number, reference_frequency: reference_hertz.to_f)
end

#to_r ⇒ Rational

Returns self as a Rational.

Examples:

Tonal::Ratio.new(3,2).to_r => (3/2)

Returns:

  • (Rational) —

    self as a Rational



136
137
138
139
 
# File 'lib/tonal/ratio.rb', line 136

def to_r
  return Float::INFINITY if consequent.zero? || !antecedent.finite?
  Rational(antecedent, consequent)
end

#to_reduced_ratio ⇒ Tonal::ReducedRatio Also known as: reduced_ratio

Returns of self.

Examples:

Tonal::Ratio.new(1,9).to_reduced_ratio => 16/9

Returns:



262
263
264
 
# File 'lib/tonal/ratio.rb', line 262

def to_reduced_ratio
  Tonal::ReducedRatio.new(reduced_antecedent, reduced_consequent, equave: equave)
end

#to_v ⇒ Vector

Returns antecedent and consequent as elements of Vector.

Examples:

Tonal::Ratio.new(3,2).to_v => Vector[3, 2]

Returns:

  • (Vector) —

    antecedent and consequent as elements of Vector



128
129
130
 
# File 'lib/tonal/ratio.rb', line 128

def to_v
  Vector[antecedent, consequent]
end

#translate(x = 1, y = 0) ⇒ Tonal::Ratio

==================================

Ratio grid transformations numerator mapped on x-axis, denominator mapped on y-axis

Examples:

Tonal::Ratio.new(3,2).translate(3,3) => 6/5

Parameters:

Returns:

  • (Tonal::Ratio) —

    with the antecedent and consequent translated by x and y



315
316
317
318
 
# File 'lib/tonal/ratio.rb', line 315

def translate(x=1, y=0)
  raise_if_negative(x,y)
  self.class.new(*(Vector[antecedent, consequent] + Vector[x, y]))
end

#weil_height ⇒ Integer

Returns the Weil height.

Examples:

Tonal::ReducedRatio.new(3/2r).weil_height => 3

Returns:



437
438
439
 
# File 'lib/tonal/ratio.rb', line 437

def weil_height
  [reduced_antecedent, reduced_consequent].max
end

#wilson_height(prime_rejects: [2]) ⇒ Integer

Returns the Wilson height. The sum of self's prime factors (greater than 2) times the absolute values of their exponents.

Examples:

Tonal::ReducedRatio.new(14/9r).wilson_height => 13

Returns:

  • (Integer) —

    the Wilson height. The sum of self's prime factors (greater than 2) times the absolute values of their exponents



454
455
456
 
# File 'lib/tonal/ratio.rb', line 454

def wilson_height(prime_rejects: [2])
  benedetti_height.prime_division.reject{|p| prime_rejects.include?(p.first) }.sum{|p| p.first * p.last }
end