tuning-core 0.1.0

package/classes/IntervalSet.ts

@@ -0,0 +1,361 @@
+import Fraction, { type FractionInput } from 'fraction.js';
+import { Spectrum } from './Spectrum';
+
+/**
+ * Represents a set of frequency ratios (intervals).
+ * Uses Map to ensure no duplicate ratios.
+ * Useful for building tuning systems, scales, and analyzing interval collections.
+ */
+export class IntervalSet {
+  private ratios: Map<string, Fraction>;
+
+  constructor(ratios?: FractionInput[]) {
+    this.ratios = new Map();
+
+    if (!ratios) return
+
+    for (const r of ratios) {
+      this.add(r);
+    }
+  }
+
+  /**
+   * Add a ratio to the set.
+   * If ratio already exists, it replaces the existing one.
+   */
+  add(ratio: FractionInput): this {
+    const f = new Fraction(ratio);
+    this.ratios.set(f.toFraction(), f);
+    return this;
+  }
+
+  /**
+   * Check if the set contains this ratio
+   */
+  has(ratio: FractionInput): boolean {
+    const key = new Fraction(ratio).toFraction();
+    return this.ratios.has(key);
+  }
+
+  /**
+   * Remove a ratio from the set
+   * @returns true if ratio was removed, false if it didn't exist
+   */
+  delete(ratio: FractionInput): this {
+    const key = new Fraction(ratio).toFraction();
+    this.ratios.delete(key);
+    return this;
+  }
+
+  /**
+   * Get a ratio from the set
+   * @returns Fraction object or undefined if not found
+   */
+  get(ratio: FractionInput): Fraction | undefined {
+    const key = new Fraction(ratio).toFraction();
+    return this.ratios.get(key);
+  }
+
+  /**
+   * Number of ratios in the set
+   */
+  get size(): number {
+    return this.ratios.size;
+  }
+
+  /**
+   * Check if the set is empty
+   */
+  isEmpty(): boolean {
+    return this.ratios.size === 0;
+  }
+
+  /**
+   * Get all ratios as an array
+   */
+  getRatios(): Fraction[] {
+    return Array.from(this.ratios.values()).sort((a, b) => a.compare(b));
+  }
+
+  /**
+   * Get the smallest ratio in the set
+   */
+  min(): Fraction | undefined {
+    return this.getRatios().at(0);
+  }
+
+  /**
+   * Get the largest ratio in the set
+   */
+  max(): Fraction | undefined {
+    return this.getRatios().at(-1);
+  }
+
+  /**
+   * Clear all ratios from the set
+   */
+  clear(): this {
+    this.ratios.clear();
+    return this
+  }
+
+  /**
+   * Create a copy of this interval set
+   */
+  clone(): IntervalSet {
+    return new IntervalSet(Array.from(this.ratios.values()));
+  }
+
+  /**
+   * Iterate over all ratios
+   */
+  forEach(callback: (ratio: Fraction, key: string) => void): void {
+    this.ratios.forEach(callback);
+  }
+
+  /**
+   * Convert to Spectrum with equal amplitudes
+   * @param fundamentalHz - Optional fundamental frequency in Hz
+   * @param amplitude - Amplitude for all harmonics (default 1)
+   */
+  toSpectrum(amp: (ratio: Fraction, index: number) => number): Spectrum {
+    const spectrum = new Spectrum();
+
+    this.getRatios().forEach((ratio, index) => {
+      spectrum.add(ratio, amp(ratio, index));
+    });
+
+    return spectrum;
+  }
+
+  /**
+   * Get ratios as array of strings
+   */
+  toStrings(): string[] {
+    return this.getRatios().map(r => r.toFraction());
+  }
+
+  /**
+   * Get ratios as array of decimal numbers
+   */
+  toNumbers(): number[] {
+    return this.getRatios().map(r => r.valueOf());
+  }
+
+  /**
+   * Check if this set equals another set
+   */
+  equals(other: IntervalSet): boolean {
+    if (this.size !== other.size) return false;
+
+    for (const ratio of this.getRatios()) {
+      if (!other.has(ratio)) return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Calculate GCD of all ratios
+   */
+  private getGCD(): Fraction | undefined {
+    const ratios = this.getRatios();
+
+    if (ratios.length === 0) return undefined;
+
+    let gcd = ratios[0]!;
+    for (let i = 1; i < ratios.length; i++) {
+      gcd = gcd.gcd(ratios[i]!);
+    }
+
+    return gcd;
+  }
+
+  /**
+ * Convert an array of ratios to an array of intervals (differences between consecutive ratios).
+ * The first interval is always 1, and each subsequent interval is the current ratio divided by the previous ratio.
+ * 
+ * @param ratios - Array of Fraction objects representing ratios
+ * @returns Array of Fraction objects representing intervals, starting with 1
+ * 
+ * @example
+ * // If ratios are [1, 5/4, 3/2, 2], intervals will be [1, 5/4, 6/5, 4/3]
+ * const ratios = [new Fraction(1), new Fraction(5, 4), new Fraction(3, 2), new Fraction(2)];
+ * const intervals = getSweepIntervals(ratios);
+ */
+  toSweepIntervals(): Fraction[] {
+    const ratios = this.getRatios();
+    const intervals: Fraction[] = [];
+
+    if (ratios.length === 0) return intervals
+
+    intervals.push(new Fraction(1));
+
+    for (let i = 1; i < ratios.length; i++) {
+      intervals.push(ratios[i]!.div(ratios[i - 1]!));
+    }
+
+    return intervals;
+  }
+
+  minMax(min: FractionInput, max: FractionInput): this {
+    const minFraction = new Fraction(min);
+    const maxFraction = new Fraction(max);
+
+    if (minFraction.compare(maxFraction) > 0) {
+      throw new Error('min must be less than or equal to max');
+    }
+
+    for (const ratio of this.ratios.values()) {
+      if (ratio.compare(minFraction) < 0 || ratio.compare(maxFraction) > 0) {
+        this.ratios.delete(ratio.toFraction());
+      }
+    }
+
+    return this;
+  }
+
+  /**
+   * Generate all unique ratios between min and max with denominators up to maxDenominator.
+   * 
+   * This creates all possible fractions n/d where:
+   * - min <= n/d <= max
+   * - 1 <= d <= maxDenominator
+   * - 1 <= n
+   * - n and d are coprime (simplified fractions only)
+   * 
+   * The Map in IntervalSet automatically handles deduplication of equivalent fractions.
+   * 
+   * @param min - Minimum ratio (inclusive)
+   * @param max - Maximum ratio (inclusive)
+   * @param maxDenominator - Maximum denominator for generated fractions
+   * 
+   * @example
+   * // All simple ratios in one octave
+   * IntervalSetFactory.range(1, 2, 5)
+   * // Returns: 1/1, 6/5, 5/4, 4/3, 3/2, 8/5, 5/3, 2/1
+   * 
+   * @example
+   * // Fine divisions for analysis (100 steps per octave)
+   * IntervalSetFactory.range(1, 2, 100)
+   * 
+   * @example
+   * // Ratios across 1.5 octaves
+   * IntervalSetFactory.range(1, 3, 12)
+   */
+  static range(
+    min: FractionInput,
+    max: FractionInput,
+    maxDenominator: number
+  ): IntervalSet {
+    if (maxDenominator < 1) {
+      throw new Error('maxDenominator must be at least 1');
+    }
+
+    const minFraction = new Fraction(min);
+    const maxFraction = new Fraction(max);
+
+    if (minFraction.compare(maxFraction) > 0) {
+      throw new Error('min must be less than or equal to max');
+    }
+
+    const intervalSet = new IntervalSet();
+
+    for (let denominator = 1; denominator <= maxDenominator; denominator++) {
+      const minNumerator = Math.max(1, Math.ceil(minFraction.valueOf() * denominator));
+      const maxNumerator = Math.floor(maxFraction.valueOf() * denominator);
+
+      for (let numerator = minNumerator; numerator <= maxNumerator; numerator++) {
+        const fraction = new Fraction(numerator, denominator);
+
+        if (fraction.compare(minFraction) >= 0 && fraction.compare(maxFraction) <= 0) {
+          intervalSet.add(fraction);
+        }
+      }
+    }
+
+    return intervalSet;
+  }
+
+  /**
+ * Generate affinitive tuning intervals that contain all ratios between harmonics of two spectra.
+ * For each pair of harmonics (one from each spectrum), calculates the ratio between them.
+ * Useful for analyzing harmonic relationships and consonance between two sounds.
+ * 
+ * @param spectrum1 - First spectrum
+ * @param spectrum2 - Second spectrum
+ * @returns IntervalSet containing all unique ratios between the spectra's harmonics
+ */
+  static affinitive(context: Spectrum, complement: Spectrum): IntervalSet {
+    const intervalSet = new IntervalSet();
+
+    const harmonics1 = context.getHarmonics();
+    const harmonics2 = complement.getHarmonics();
+
+    // Calculate ratio between every pair of harmonics
+    for (const h1 of harmonics1) {
+      for (const h2 of harmonics2) {
+        const ratio = h2.frequency.div(h1.frequency);
+        intervalSet.add(ratio);
+      }
+    }
+
+    return intervalSet;
+  }
+
+  /**
+ * Add intermediate intervals between existing ratios to create a smooth curve.
+ * Uses logarithmic spacing to ensure perceptually uniform distribution.
+ * A gap of 1→2 gets the same density as 2→4 (both are octaves).
+ * 
+ * @param maxGapCents - Maximum allowed gap in cents (e.g., 10 for 10-cent steps)
+ *                      1200 cents = 1 octave, 100 cents ≈ 1 semitone
+ * @returns this (for chaining)
+ * 
+ * @example
+ * const intervals = new IntervalSet([1, 2, 4]);
+ * intervals.densify(100); // Max 100-cent (1 semitone) gaps
+ * // Adds same number of points between 1→2 as between 2→4
+ * 
+ * @example
+ * // For dissonance curves - logarithmic spacing
+ * const extrema = IntervalSet.affinitive(spectrum1, spectrum2);
+ * extrema.densify(10); // ~10-cent resolution for smooth curve
+ */
+  densify(maxGapCents: number): this {
+    if (maxGapCents <= 0) {
+      throw new Error('maxGapCents must be positive');
+    }
+
+    // Convert cents to ratio (1 cent = 2^(1/1200))
+    const maxGapRatio = Math.pow(2, maxGapCents / 1200);
+
+    // Keep adding intervals until all gaps are small enough
+    let needsMorePoints = true;
+
+    while (needsMorePoints) {
+      const sorted = this.getRatios();
+      needsMorePoints = false;
+
+      // Check each adjacent pair
+      for (let i = 0; i < sorted.length - 1; i++) {
+        const left = sorted[i]!;
+        const right = sorted[i + 1]!;
+
+        // Calculate logarithmic gap (ratio of ratios)
+        const gapRatio = right.div(left).valueOf();
+
+        // If gap is too large, add the geometric mean
+        if (gapRatio > maxGapRatio) {
+          // Geometric mean: sqrt(a * b) - the logarithmic midpoint
+          const geometricMean = Math.sqrt(left.valueOf() * right.valueOf());
+
+          this.add(geometricMean);
+          needsMorePoints = true;
+        }
+      }
+    }
+
+    return this;
+  }
+}

package/classes/README.md

@@ -0,0 +1,239 @@
+# New Tonality Tuning Core
+
+A set of primitive classes for representing harmonics, spectrum, and frequency ratios using exact rational number arithmetic. These classes are used across the New Tonality project ecosystem, including:
+
+- **[new-tonality-website-v3](https://github.com/new-tonality-project/new-tonality-website-v3)** - Main website and web tools
+- **[sethares-dissonance](https://github.com/new-tonality-project/sethares-dissonance)** - Dissonance curve calculations
+- **[set-consonance](https://github.com/new-tonality-project/set-consonance)** - Set-theorietic consonance analysis tools
+
+The primitives provide a foundation for precise tuning mathematics, avoiding floating-point errors through the use of `Fraction.js` for exact rational number representation.
+
+## Contributing
+
+Found a bug or have a feature request? Please don't hesitate to reach out!
+
+- **GitHub Issues**: Report bugs or request features by opening an issue on the [GitHub repository](https://github.com/new-tonality-project/tuning-core)
+- **Email**: Send feedback directly to [support@newtonality.net](mailto:support@newtonality.net)
+
+Your feedback helps improve the New Tonality Tuning Core for everyone!
+
+
+## Usage Examples
+
+### Frequency and Interval Representation
+
+All frequencies and intervals are handled as (Fraction.js)[https://www.npmjs.com/package/fraction.js?activeTab=readme] objects internally, which allows for exact representation of rational numbers. This is crucial for precise tuning mathematics and avoids floating-point errors. However that may lead to performance issues due to conversion of very percise floating point numbers like 1.0001230576.
+
+You can provide frequencies and intervals using any of the following `FractionInput` types,
+it will automatically be converted to Fraction object interanlly.
+
+```ts
+new Harmonic(100.25)                // 100.25 Hz
+new Harmonic("100.25")              // 100.25 Hz
+new Harmonic("100 1/4")             // 100.25 Hz
+new Harmonic(new Fraction(100.25))  // 100.25 Hz
+
+// working with intervals:
+
+const h = new Harmonic(100)
+
+const perfectFifth = h.toTransposed("3/2")          // 150 Hz
+const perfectFourth = h.toTransposed([4, 3])        // 133.33.. Hz
+const majorThird = h.toTransposed({ n: 5, d: 4 })   // 125 Hz
+const perfectOctave = h.toTransposed(2)             // 200 Hz
+```
+
+If you already have a Fraction object, it is also a valid input:
+
+```ts
+import Fraction from 'fraction.js';
+
+const f = new Fraction("4/3")
+const h = new Harmonic(440).transpose(f) // OK
+```
+
+**Note**: When using string fractions (e.g., `"3/2"`), the fraction is automatically simplified. For example, `"6/4"` becomes `"3/2"`.
+
+### Harmonic class
+
+```ts
+import { Harmonic } from 'tuning-core';
+
+// Create harmonic with individual parameters
+// Frequencies represent partials (e.g., from harmonic series: 110, 220, 330 Hz)
+const h1 = new Harmonic(220, 0.5, 0);     // 220 Hz, amplitude 0.5
+const h2 = new Harmonic("330", 0.8);      // 330 Hz, phase defaults to 0
+const h3 = new Harmonic("110 1/4");       // 110.25 Hz, amplitude defaults to 1
+
+// Access properties (read-only)
+console.log(h1.frequency);      // Fraction  obj
+console.log(h1.frequencyStr);   // "220"
+console.log(h1.frequencyNum);   // 220
+console.log(h1.amplitude);      // 0.5
+console.log(h1.phase);          // 0
+
+// Modify harmonic (methods can be chained)
+h1.setAmplitude(0.7).setPhase(Math.PI);
+h1.scale(0.5);  // Scale amplitude by 0.5
+
+// Transpose using musical intervals (ratios) in place
+h1.transpose('3/2');  // Transpose by perfect fifth (multiply frequency by 3/2)
+h1.transpose('4/3');  // Transpose by perfect fourth (multiply frequency by 4/3)
+
+// Create several harmonics using transposition
+const h2 = h1.toTransposed("3/2") // perfect fifth 
+const copy = h1.clone()
+
+// Serialization
+const h = new Harmonic(100, 0.5, Math.PI)
+const harmonicData: HarmonicData = h.toJSON()
+console.log(harmonicData)
+// Output: { frequency: '100', amplitude: 0.5, phase: 3.141592653589793 }
+
+// serialized data can be used to counstruct a new Harmonic
+const deserializedharmonic = new Harmonic(harmonicData)
+```
+
+### Spectrum class
+
+Spectrum is a collection of individual Harmonics. Under the hood it is a Map with keys that are frequency strings, that is done to avoid duplicates. Adding new harmonic with existing frequency will override the existing harmonic.
+
+```ts
+import { Spectrum } from 'tuning-core';
+
+// Create empty spectrum
+const s1 = new Spectrum();
+
+// Add harmonics using various methods
+// Frequencies represent partials (e.g., from harmonic series: 110, 220, 330 Hz)
+s1.add(110, 1.0);                                         // Add by frequency (Hz)
+s1.add(220, 0.5, Math.PI);                                // Add with phase
+s1.add(new Harmonic(330, 0.33));                          // Add Harmonic object
+s1.add({ frequency: '440', amplitude: 0.6, phase: 0 });   // Add HarmonicData
+
+// Query spectrum
+s1.has(220);           // Check if harmonic exists
+s1.get(220);           // Get harmonic (returns Harmonic | undefined)
+s1.size;               // Number of harmonics
+s1.isEmpty();          // Check if empty
+
+// Modify spectrum
+s1.remove(220);        // Remove harmonic
+s1.scaleAmplitudes(0.5);  // Scale all amplitudes
+s1.clear();            // Remove all harmonics
+s1.transposeHarmonic(220, "3/2");  // Transposes a single harmonic a fifth up
+
+// Transpose using musical intervals (ratios)
+s1.transpose('3/2');   // Transpose all harmonics by perfect fifth (mutable)
+s1.transpose('4/3');   // Transpose all harmonics by perfect fourth
+
+// Get harmonics
+const harmonics = s1.getHarmonics();  // Returns sorted array
+const lowest = s1.getLowestHarmonic();
+const highest = s1.getHighestHarmonic();
+
+// Clone and immutable operations
+const s3 = s1.clone();              // Create independent copy
+const s4 = s1.toTransposed('3/2');  // Create transposed copy (immutable) - perfect fifth
+
+// Serialization
+const spectrum = new Speacrum()
+
+spectrum.add(110, 1, 0)
+spectrum.add(220, 0.5, 1)
+
+const spectrumData: SpectrumData = spectrum.toJSON()
+console.log(spectrumData)
+// output: [
+//  { frequency: 110, amplitude: 1, phase: 0 },
+//  { frequency: 220, amplitude: 0.5, phase: 1 }
+// ]
+
+// Deserialisation
+const s2 = new Spectrum(spectrumData); // OK
+```
+
+### Spectrum static methods
+
+A set of convenience factory methods to create common spectra such as harmonic series and others
+
+```ts
+import { Spectrum } from 'tuning-core';
+
+// Create harmonic series (frequency ratios: 1, 2, 3, 4, ...)
+// These represent the harmonic series relative to a fundamental
+const harmonicSeries = Spectrum.harmonicSeries(8);
+// Creates spectrum with ratios 1, 2, 3, 4, 5, 6, 7, 8
+// Amplitudes follow natural decay: 1, 0.5, 0.333, 0.25, ...
+
+// Create spectrum from absolute frequencies (Hz)
+const spectrum = Spectrum.fromFrequencies(
+  [110, 220, 330, 440],   // Frequencies in Hz (harmonic series)
+  [1.0, 0.5, 0.33, 0.25], // Amplitudes
+  [0, 0, 0, 0]            // Phases
+);
+```
+
+### Performance Considerations
+
+The performance of `Fraction.js` constructor varies significantly depending on the input type and ratio complexity. Benchmarks show different characteristics for integers vs. simple vs. complex ratios:
+
+**Integers (e.g., `440`) measured for 100_000_000 iterations:**
+| Input Type | Time per Operation | Relative Speed |
+|------------|-------------------|----------------|
+| **Float** `440` | 88 ns | 1.00x (fastest) |
+| **Array** `[440, 1]` | 114 ns | 1.30x |
+| **Object** `{n: 440, d: 1}` | 114 ns | 1.30x |
+| **Fraction (copying)** | 143 ns | 1.63x |
+| **String** `"440"` | 237 ns | 2.70x (slowest) |
+
+**Simple Ratios (e.g., `3/2`) measured for 100_000_000 iterations:**
+| Input Type | Time per Operation | Relative Speed |
+|------------|-------------------|----------------|
+| **Object** `{n: 3, d: 2}` | 131 ns | 1.00x (fastest) |
+| **Array** `[3, 2]` | 132 ns | 1.01x |
+| **Fraction (copying)** | 160 ns | 1.22x |
+| **Float** `1.5` | 231 ns | 1.77x |
+| **String** `"3/2"` | 321 ns | 2.45x (slowest) |
+
+**Complex Ratios (e.g., `12345/6789`) measured for 10_000_000 iterations:**
+| Input Type | Time per Operation | Relative Speed |
+|------------|-------------------|----------------|
+| **Fraction (copying)** | 279 ns | 1.00x (fastest) |
+| **Object** `{n, d}` | 286 ns | 1.02x |
+| **Array** `[n, d]` | 287 ns | 1.03x |
+| **String** `"n/d"` | 506 ns | 1.81x |
+| **Float** `1.818...` | 2,826 ns | **10.12x** (slowest) |
+
+**Key Recommendations:**
+
+1. **For integers, floats are fastest**: When working with whole numbers (e.g., `440` Hz), using a float/number directly is the fastest option (~1.3x faster than array/object). However, arrays/objects are still very fast and provide consistency.
+
+2. **Use arrays or objects for ratios**: For both simple and complex ratios, array `[numerator, denominator]` or object `{n: numerator, d: denominator}` formats consistently provide the best performance. They are the fastest option for simple ratios and nearly as fast as copying for complex ratios.
+
+3. **Avoid floats for complex intervals**: Float input becomes **~10x slower** for complex ratios because `Fraction.js` must convert the decimal to a rational approximation. For simple ratios, floats are better than strings but still slower than array/object.
+
+4. **String parsing overhead**: String fractions add parsing overhead (~2.7x slower for integers, ~2.5x for simple ratios, ~1.8x for complex ratios). The overhead is not that great so they can be used for improved readability, but avoid them for performance-critical code.
+
+5. **Reuse Fraction objects when possible**: Copying an existing `Fraction` object has comparable performance to construction from array or object
+
+**Example - Performance Best Practices:**
+
+```ts
+// ✅ FASTEST FOR INTEGERS: Floats are fastest for whole numbers
+const fastestInt = new Harmonic(440);  // Float input is fastest for integers
+
+// ✅ FASTEST FOR RATIOS: Use array/object for best performance
+const fastest1 = new Harmonic(440).transpose([3, 2]);  // Simple ratio
+const fastest2 = new Harmonic(440).transpose({ n: 3, d: 2 });  // Simple ratio
+const fastest3 = new Harmonic(440).transpose([12345, 6789]);  // Complex ratio
+
+// ✅ GOOD: String fractions for readability (acceptable performance)
+const readable = new Harmonic(440).transpose("3/2");  // ~2.5x slower than array
+
+// ⚠️ AVOID: Floats for complex ratios (very slow)
+const slowComplex = new Harmonic(440).transpose(1.8181818181818182);  // ~10x slower
+
+// ⚠️ ACCEPTABLE: Floats for simple ratios (but array/object still faster)
+const acceptable = new Harmonic(440).transpose(1.5);  // ~1.8x slower than array
+```