sethares-dissonance 2.1.0 → 3.0.0

package/README.md

@@ -15,34 +15,40 @@ npm install sethares-dissonance
 ## Usage
 
 ```ts
-import { DissonanceCurve, Spectrum } from "sethares-dissonance";
+import { DissonanceCurve } from "sethares-dissonance";
+import { Spectrum } from "tuning-core";
 
-const context = Spectrum.harmonicSeries(10, 440);
-const complement = Spectrum.harmonicSeries(10, 440);
+const context = Spectrum.harmonic(10, 440);
+const complement = Spectrum.harmonic(10, 440);
 
 const curve = new DissonanceCurve({
     context,
     complement,
     start: 1,
     end: 2,
-    maxDenominator: 60,
+    maxGapCents: 20,
+    firstOrderContribution: 1,
+    secondOrderContribution: 0.25,
+    thirdOrderContribution: 0.1,
+    phantomHarmonicsNumber: 3,
 });
 
 const points = curve.points;
-const plotData = curve.plot();
+const plotData = curve.plot();        // [ratio, dissonance] tuples
+const plotDataCents = curve.plotCents();  // [cents, dissonance] tuples
 ```
 
 ## React
 
 Because DissonanceCurve class mutates data in place, it is not directly suited for React applications as reference to the instance does not change. React will not detect dissonance curve mutations in dependency arrays or state and thus will not rerender. You can solve it in two ways.
 
-### 1. Create new instances
+### Create new instances with useMemo hook
 
 Create a fresh `DissonanceCurve` whenever options change. `useMemo` ensures a new instance is created when dependencies change, so React detects the update and re-renders.
 
 ```tsx
 import { useMemo } from "react";
-import { DissonanceCurve, Spectrum } from "sethares-dissonance";
+import { DissonanceCurve } from "sethares-dissonance";
 
 function DissonanceChart({ context, complement, start = 1, end = 2 }) {
     const curve = useMemo(
@@ -52,7 +58,11 @@ function DissonanceChart({ context, complement, start = 1, end = 2 }) {
                 complement,
                 start,
                 end,
-                maxDenominator: 60,
+                maxGapCents: 20,
+                firstOrderContribution: 1,
+                secondOrderContribution: 0.25,
+                thirdOrderContribution: 0.1,
+                phantomHarmonicsNumber: 3,
             }),
         [context, complement, start, end],
     );
@@ -62,53 +72,4 @@ function DissonanceChart({ context, complement, start = 1, end = 2 }) {
 }
 ```
 
-This solution ok, but there is a downside that `curve` object contains methods that can mutate the internal state which will not be registered by React, thus leading to bugs.
-
-### 2. Use read-only wrappers (Recommended)
-
-This method relies on creating new instances of read-only objects rather than new DissonanceCurve instances. It is demonstrated in the following `useDissonanceCurve` hook. Memoize options with `useMemo` when they contain objects (e.g. `Spectrum`) to avoid recalculating on every render.
-
-```tsx
-"use client";
-
-import { useMemo, useState } from "react";
-import {
-    DissonanceCurve,
-    type DissonanceCurveOptions,
-} from "sethares-dissonance";
-import type { ReadOnlyDissonanceCurve } from "sethares-dissonance";
-
-/**
- * Read-only view of DissonanceCurve without the recalculate method.
- * Use this type when exposing the curve from hooks to prevent external mutation.
- */
-export type ReadOnlyDissonanceCurve = Partial<Omit<
-  DissonanceCurve,
-  "recalculate"
->>;
-
-function createReadOnlyWrapper(
-    curve: DissonanceCurve,
-): ReadOnlyDissonanceCurve {
-    
-    return {
-        get maxDissonance() {
-            return curve.maxDissonance;
-        },
-        plotCents: () => curve.plotCents(),
-        findNearestPoint: (ratio) => curve.findNearestPoint(ratio),
-        // .. can add more methods if needed, aboid those that cause mutations
-    };
-}
-
-export function useDissonanceCurve(
-    options: DissonanceCurveOptions,
-): ReadOnlyDissonanceCurve {
-    const [curve] = useState(() => new DissonanceCurve(options));
-
-    return useMemo(() => {
-        curve.recalculate(options);
-        return createReadOnlyWrapper(curve);
-    }, [options, curve]);
-}
-```
+**NOTE:** that `curve` object contains methods that can mutate the internal state of DissonanceCurve which will not be registered by React and will not cause a rerender.

package/dist/benches/dissonance-curve.bench.js

@@ -0,0 +1,71 @@
+import { Spectrum } from "tuning-core";
+import { DissonanceCurve } from "../classes";
+/**
+ * Performance benchmark for DissonanceCurve creation.
+ * Tests creating a dissonance curve with harmonic spectra (6 harmonics, 440 Hz),
+ * range 0.25–4, and Sethares parameters.
+ */
+const ITERATIONS = 100;
+function benchmark(name, fn) {
+    // Warmup
+    for (let i = 0; i < 10; i++) {
+        fn();
+    }
+    // Actual benchmark
+    const start = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        fn();
+    }
+    const end = performance.now();
+    const timeMs = end - start;
+    const timePerOpMs = timeMs / ITERATIONS;
+    return {
+        operation: name,
+        timeMs,
+        timePerOpMs,
+        iterations: ITERATIONS,
+    };
+}
+function runBenchmarks() {
+    const results = [];
+    const options = {
+        context: Spectrum.harmonic(6, 440),
+        complement: Spectrum.harmonic(6, 440),
+        start: 1,
+        end: 2,
+        firstOrderContribution: 1,
+        secondOrderContribution: 0.25,
+        thirdOrderContribution: 0.1,
+        phantomHarmonicsNumber: 3,
+        maxGapCents: 30,
+    };
+    const sampleCurve = new DissonanceCurve(options);
+    console.log(`Test setup: Spectrum.harmonic(6, 440), range 0.25–4, curve points: ${sampleCurve.points.length}\n`);
+    results.push(benchmark("DissonanceCurve creation", () => {
+        new DissonanceCurve(options);
+    }));
+    return results;
+}
+function formatResults(results) {
+    console.log("=".repeat(80));
+    console.log("DissonanceCurve Creation Performance Benchmark");
+    console.log(`Iterations per test: ${ITERATIONS.toLocaleString()}`);
+    console.log("=".repeat(80));
+    console.log("\n");
+    const fastest = results.reduce((min, r) => (r.timeMs < min.timeMs ? r : min), results[0]);
+    console.log("Results:");
+    console.log("-".repeat(80));
+    console.log(`${"Operation".padEnd(45)} ${"Total Time (ms)".padEnd(18)} ${"Time per Op (ms)".padEnd(18)} ${"Relative Speed".padEnd(15)}`);
+    console.log("-".repeat(80));
+    for (const result of results) {
+        const relativeSpeed = (result.timeMs / fastest.timeMs).toFixed(2) + "x";
+        const timeMsStr = result.timeMs.toFixed(2);
+        const timePerOpStr = result.timePerOpMs.toFixed(4);
+        console.log(`${result.operation.padEnd(45)} ${timeMsStr.padEnd(18)} ${timePerOpStr.padEnd(18)} ${relativeSpeed.padEnd(15)}`);
+    }
+    console.log("-".repeat(80));
+    console.log(`\nFastest: ${fastest.operation} (${fastest.timeMs.toFixed(2)} ms)`);
+    console.log("=".repeat(80) + "\n");
+}
+const results = runBenchmarks();
+formatResults(results);

package/dist/classes/DissonanceCurve.d.ts

@@ -1,12 +1,13 @@
 import { Fraction, type FractionInput } from "fraction.js";
 import { Spectrum } from "tuning-core";
 import type { DissonanceParams, DissonanceCurvePoint, DissonanceCurveData } from "../lib";
+import { SpectrumWithLoudness } from "./private/SpectrumWithLoudness";
 export type DissonanceCurveOptions = DissonanceParams & {
     context: Spectrum;
     complement: Spectrum;
-    maxDenominator?: number;
     start?: FractionInput;
     end?: FractionInput;
+    maxGapCents?: number;
 };
 /**
  * Represents a dissonance curve calculated using Sethares' sensory dissonance model.
@@ -43,8 +44,9 @@ export declare class DissonanceCurve {
     private _data;
     start: Fraction;
     end: Fraction;
-    context: Spectrum;
-    complement: Spectrum;
+    context: SpectrumWithLoudness;
+    complement: SpectrumWithLoudness;
+    maxGapCents: number;
     maxDissonance: number;
     constructor(opts: DissonanceCurveOptions);
     /**
@@ -52,6 +54,7 @@ export declare class DissonanceCurve {
      * Updates the curve in place.
      */
     recalculate(opts: DissonanceCurveOptions): void;
+    private getIntervals;
     /**
      * Build _data from public props (context, complement, start, end).
      */

package/dist/classes/DissonanceCurve.js

@@ -1,6 +1,7 @@
 import { Fraction } from "fraction.js";
 import { ratioToCents, Spectrum, IntervalSet } from "tuning-core";
-import { getSetharesDissonance } from "../lib";
+import { getSetharesDissonance, getIntrinsicDissonance } from "../lib";
+import { SpectrumWithLoudness } from "./private/SpectrumWithLoudness";
 const DEFAULT_COLUMN_DELIMITER = ",";
 const DEFAULT_ROW_DELIMITER = "\n";
 /**
@@ -40,13 +41,16 @@ export class DissonanceCurve {
     end;
     context;
     complement;
+    maxGapCents;
     maxDissonance = 0;
     constructor(opts) {
-        const { context, complement, start, end, maxDenominator, ...dissonanceParams } = opts;
-        this.context = context;
-        this.complement = complement;
+        const { context, complement, start, end, maxGapCents = 20, ...dissonanceParams } = opts;
+        const phantomHarmonics = SpectrumWithLoudness.harmonic(dissonanceParams.phantomHarmonicsNumber + 1, 1, true);
+        this.context = new SpectrumWithLoudness(context).mul(phantomHarmonics);
+        this.complement = new SpectrumWithLoudness(complement).mul(phantomHarmonics);
         this.start = new Fraction(start ?? 1);
         this.end = new Fraction(end ?? 2);
+        this.maxGapCents = maxGapCents;
         if (this.start.compare(this.end) > 0)
             throw Error("startCents should be less or equal to endCents");
         this.build(dissonanceParams);
@@ -56,26 +60,36 @@ export class DissonanceCurve {
      * Updates the curve in place.
      */
     recalculate(opts) {
-        const { context, complement, start, end, maxDenominator, ...dissonanceParams } = opts;
-        this.context = context;
-        this.complement = complement;
+        const { context, complement, start, end, maxGapCents = 20, ...dissonanceParams } = opts;
+        const phantomHarmonics = SpectrumWithLoudness.harmonic(dissonanceParams.phantomHarmonicsNumber + 1, 1, true);
+        this.context = new SpectrumWithLoudness(context).mul(phantomHarmonics);
+        this.complement = new SpectrumWithLoudness(complement).mul(phantomHarmonics);
         this.start = new Fraction(start ?? 1);
         this.end = new Fraction(end ?? 2);
+        this.maxGapCents = maxGapCents;
         if (this.start.compare(this.end) > 0)
             throw Error("startCents should be less or equal to endCents");
         this.build(dissonanceParams);
     }
+    getIntervals() {
+        return IntervalSet.affinitive(this.context, this.complement)
+            .minMax(this.start, this.end)
+            .add(this.start)
+            .add(this.end)
+            .interpolateLog(this.maxGapCents);
+    }
     /**
      * Build _data from public props (context, complement, start, end).
      */
     build(dissonanceParams) {
         this._data.clear();
         let maxDissonance = 0;
-        const intervals = IntervalSet.affinitive(this.context.size > 1 ? this.context : Spectrum.harmonic(2, 1), this.complement.size > 1 ? this.complement : Spectrum.harmonic(2, 1)).densify(20);
+        const intervals = this.getIntervals();
         const ratios = intervals.getRatios();
+        const contextIntrinsic = getIntrinsicDissonance(this.context, dissonanceParams);
         for (let i = 0; i < ratios.length; i++) {
             const interval = ratios[i];
-            const dissonance = getSetharesDissonance(this.context, this.complement.toTransposed(interval), dissonanceParams);
+            const dissonance = getSetharesDissonance(this.context, this.complement.toTransposed(interval), dissonanceParams, contextIntrinsic);
             if (dissonance > maxDissonance)
                 maxDissonance = dissonance;
             this._data.set(interval.toFraction(), { interval, dissonance });

package/dist/classes/private/HarmonicWithLoudness.d.ts

@@ -0,0 +1,21 @@
+import type { FractionInput } from "fraction.js";
+import { Harmonic } from "tuning-core";
+import type { HarmonicData } from "tuning-core";
+type HarmonicWithLoudnessOptions = {
+    harmonic: Harmonic;
+    phantom: boolean;
+};
+export type HarmonicWithLoudnessData = HarmonicData & {
+    phantom?: boolean;
+};
+export declare class HarmonicWithLoudness extends Harmonic {
+    phantom: boolean;
+    loudness: number;
+    constructor(options: HarmonicWithLoudnessOptions);
+    constructor(data: HarmonicWithLoudnessData);
+    constructor(frequency: FractionInput, amplitude?: number, phase?: number, phantom?: boolean);
+    clone(): HarmonicWithLoudness;
+    toTransposed(ratio: FractionInput): HarmonicWithLoudness;
+    toJSON(): HarmonicWithLoudnessData;
+}
+export {};

package/dist/classes/private/HarmonicWithLoudness.js

@@ -0,0 +1,42 @@
+import { Harmonic, isHarmonicData } from "tuning-core";
+import { getLoudness } from "../../lib/loudness";
+export class HarmonicWithLoudness extends Harmonic {
+    phantom = false;
+    loudness;
+    constructor(optionsOrDataOrFreq, amplitudeOrPhantom, phase, phantom) {
+        if (typeof optionsOrDataOrFreq === "object" &&
+            "harmonic" in optionsOrDataOrFreq &&
+            optionsOrDataOrFreq.harmonic instanceof Harmonic) {
+            const opts = optionsOrDataOrFreq;
+            super(opts.harmonic.frequency, opts.harmonic.amplitude, opts.harmonic.phase);
+            this.phantom = opts.phantom;
+            this.loudness = getLoudness(opts.harmonic.amplitude);
+        }
+        else if (isHarmonicData(optionsOrDataOrFreq)) {
+            const data = optionsOrDataOrFreq;
+            super(data);
+            this.phantom = data.phantom ?? false;
+            this.loudness = getLoudness(data.amplitude ?? 1);
+        }
+        else {
+            super(optionsOrDataOrFreq, amplitudeOrPhantom ?? 1, phase ?? 0);
+            this.phantom = phantom ?? false;
+            this.loudness = getLoudness(amplitudeOrPhantom ?? 1);
+        }
+    }
+    clone() {
+        return new HarmonicWithLoudness({
+            harmonic: new Harmonic(this.frequency, this.amplitude, this.phase),
+            phantom: this.phantom,
+        });
+    }
+    toTransposed(ratio) {
+        return new HarmonicWithLoudness({
+            harmonic: super.toTransposed(ratio),
+            phantom: this.phantom,
+        });
+    }
+    toJSON() {
+        return { ...super.toJSON(), phantom: this.phantom };
+    }
+}

package/dist/classes/private/SpectrumWithLoudness.d.ts

@@ -0,0 +1,31 @@
+import type { FractionInput } from "fraction.js";
+import { Spectrum } from "tuning-core";
+import { HarmonicWithLoudness, type HarmonicWithLoudnessData } from "./HarmonicWithLoudness";
+export type SpectrumWithLoudnessData = HarmonicWithLoudnessData[];
+export declare class SpectrumWithLoudness extends Spectrum {
+    constructor(data?: SpectrumWithLoudnessData | Spectrum);
+    add(harmonic: HarmonicWithLoudness): this;
+    add(data: HarmonicWithLoudnessData): this;
+    add(frequency: FractionInput, amplitude?: number, phase?: number, phantom?: boolean): this;
+    getHarmonics(): HarmonicWithLoudness[];
+    getLowestHarmonic(): HarmonicWithLoudness | undefined;
+    getHighestHarmonic(): HarmonicWithLoudness | undefined;
+    clone(): SpectrumWithLoudness;
+    toTransposed(ratio: FractionInput): SpectrumWithLoudness;
+    toJSON(): SpectrumWithLoudnessData;
+    get(frequency: FractionInput): HarmonicWithLoudness | undefined;
+    /**
+   * Multiply this spectrum by another spectrum.
+   * Each harmonic of this spectrum is multiplied by each harmonic of the other
+   * (as interval relative to the other's fundamental), and added to the output.
+   *
+   * Phantom logic:
+   * - Result is phantom if either operand harmonic is phantom.
+   * - Exception: when multiplying by the fundamental (interval 1), preserve
+   *   harmonic_1's phantom status—a real harmonic from "this" is never
+   *   overridden by phantom.
+   * - When frequencies collide: non-phantom wins (replaces phantom).
+   */
+    mul(other: SpectrumWithLoudness): SpectrumWithLoudness;
+    static harmonic(count: number, fundamentalHz: FractionInput, phantom?: boolean): SpectrumWithLoudness;
+}

package/dist/classes/private/SpectrumWithLoudness.js

@@ -0,0 +1,105 @@
+import { Spectrum, isHarmonicData } from "tuning-core";
+import { HarmonicWithLoudness } from "./HarmonicWithLoudness";
+export class SpectrumWithLoudness extends Spectrum {
+    constructor(data) {
+        super();
+        if (data instanceof Spectrum) {
+            for (const harmonic of data.getHarmonics()) {
+                this.add(new HarmonicWithLoudness({ harmonic, phantom: false }));
+            }
+        }
+        else if (data) {
+            for (const harmonicData of data) {
+                this.add(harmonicData);
+            }
+        }
+    }
+    add(harmonicOrDataOrFreq, amplitude, phase, phantom) {
+        if (harmonicOrDataOrFreq instanceof HarmonicWithLoudness) {
+            super.add(harmonicOrDataOrFreq);
+        }
+        else if (isHarmonicData(harmonicOrDataOrFreq)) {
+            super.add(new HarmonicWithLoudness(harmonicOrDataOrFreq));
+        }
+        else {
+            super.add(new HarmonicWithLoudness(harmonicOrDataOrFreq, amplitude ?? 1, phase ?? 0, phantom ?? false));
+        }
+        return this;
+    }
+    getHarmonics() {
+        return super.getHarmonics();
+    }
+    getLowestHarmonic() {
+        return super.getLowestHarmonic();
+    }
+    getHighestHarmonic() {
+        return super.getHighestHarmonic();
+    }
+    clone() {
+        const copy = new SpectrumWithLoudness();
+        for (const harmonic of this.getHarmonics()) {
+            copy.add(harmonic.clone());
+        }
+        return copy;
+    }
+    toTransposed(ratio) {
+        return this.clone().transpose(ratio);
+    }
+    toJSON() {
+        return this.getHarmonics().map((h) => h.toJSON());
+    }
+    get(frequency) {
+        return super.get(frequency);
+    }
+    /**
+   * Multiply this spectrum by another spectrum.
+   * Each harmonic of this spectrum is multiplied by each harmonic of the other
+   * (as interval relative to the other's fundamental), and added to the output.
+   *
+   * Phantom logic:
+   * - Result is phantom if either operand harmonic is phantom.
+   * - Exception: when multiplying by the fundamental (interval 1), preserve
+   *   harmonic_1's phantom status—a real harmonic from "this" is never
+   *   overridden by phantom.
+   * - When frequencies collide: non-phantom wins (replaces phantom).
+   */
+    mul(other) {
+        const fundamental = other.getLowestHarmonic();
+        if (!fundamental) {
+            throw new Error("Other spectrum has no fundamental (empty or not computable). Provide spectrum with harmonics.");
+        }
+        const result = new SpectrumWithLoudness();
+        for (const harmonic_1 of this.getHarmonics()) {
+            for (const harmonic_2 of other.getHarmonics()) {
+                const interval = harmonic_2.frequency.div(fundamental.frequency);
+                const ampRatio = harmonic_2.amplitude / fundamental.amplitude;
+                const newFreq = harmonic_1.frequency.mul(interval);
+                const newAmp = harmonic_1.amplitude * ampRatio;
+                const newPhase = harmonic_2.phase;
+                const isFundamental = harmonic_2 === fundamental;
+                const newPhantom = isFundamental
+                    ? harmonic_1.phantom
+                    : harmonic_1.phantom || harmonic_2.phantom;
+                const existing = result.get(newFreq);
+                if (existing !== undefined) {
+                    const existingPhantom = existing.phantom;
+                    if (existingPhantom && !newPhantom) {
+                        result.remove(newFreq);
+                        result.add(newFreq, newAmp, newPhase, newPhantom);
+                    }
+                    continue;
+                }
+                result.add(newFreq, newAmp, newPhase, newPhantom);
+            }
+        }
+        return result;
+    }
+    static harmonic(count, fundamentalHz, phantom) {
+        const spectrum = super.harmonic(count, fundamentalHz);
+        const result = new SpectrumWithLoudness();
+        for (const harmonic of spectrum.getHarmonics()) {
+            result.add(new HarmonicWithLoudness({ harmonic, phantom: phantom ?? false }));
+        }
+        return result;
+    }
+}

package/dist/lib/const.d.ts

@@ -1,10 +1,4 @@
-import type { SecondOrderBeatingTerm } from "./types";
 export declare const NORMALISATION_PRESSURE_UNIT = 2.8284271247461903;
-export declare const SECOND_ORDER_BEATING_PARAMS: {
-    terms: SecondOrderBeatingTerm[];
-    widthMagnitudeRelationship: number;
-    totalContribution: number;
-};
 /** Fitting parameters proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
 export declare const SETHARES_DISSONANCE_PARAMS: {
     s1: number;
@@ -12,18 +6,4 @@ export declare const SETHARES_DISSONANCE_PARAMS: {
     b1: number;
     b2: number;
     x_star: number;
-    totalContribution: number;
-};
-export declare const DEFAULT_DISSONANCE_PARAMS: {
-    secondOrderBeating: {
-        terms: SecondOrderBeatingTerm[];
-        widthMagnitudeRelationship: number;
-        totalContribution: number;
-    };
-    s1: number;
-    s2: number;
-    b1: number;
-    b2: number;
-    x_star: number;
-    totalContribution: number;
 };

package/dist/lib/const.js

@@ -1,9 +1,4 @@
 export const NORMALISATION_PRESSURE_UNIT = 2.8284271247461905;
-export const SECOND_ORDER_BEATING_PARAMS = {
-    terms: [],
-    widthMagnitudeRelationship: 0,
-    totalContribution: 1,
-};
 /** Fitting parameters proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
 export const SETHARES_DISSONANCE_PARAMS = {
     s1: 0.021,
@@ -11,9 +6,4 @@ export const SETHARES_DISSONANCE_PARAMS = {
     b1: 3.5,
     b2: 5.75,
     x_star: 0.24,
-    totalContribution: 1,
-};
-export const DEFAULT_DISSONANCE_PARAMS = {
-    ...SETHARES_DISSONANCE_PARAMS,
-    secondOrderBeating: SECOND_ORDER_BEATING_PARAMS,
 };

package/dist/lib/loudness.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The formula to calculate loudness from amplitude. The converstion to SPL (phons) is done according to Sethares in the appendix "How to Draw Dissonance Curves". The converstion to loudness is done according to https://sengpielaudio.com/calculatorSonephon.htm
+ * @param {number} amplitude - the normalized peak value where 0.001 corresponds to SPL of 40 db or 1 sone and 1 to SPL of 100db and 64 sones. Normalisation is done for the simplicity of providing harmonic spectrum with amplitudes 1, 1/2, 1/3, ...
+ */
+export declare function getLoudness(amplitude: number): number;

package/dist/lib/loudness.js

@@ -0,0 +1,16 @@
+import { NORMALISATION_PRESSURE_UNIT } from "./const";
+/**
+ * The formula to calculate loudness from amplitude. The converstion to SPL (phons) is done according to Sethares in the appendix "How to Draw Dissonance Curves". The converstion to loudness is done according to https://sengpielaudio.com/calculatorSonephon.htm
+ * @param {number} amplitude - the normalized peak value where 0.001 corresponds to SPL of 40 db or 1 sone and 1 to SPL of 100db and 64 sones. Normalisation is done for the simplicity of providing harmonic spectrum with amplitudes 1, 1/2, 1/3, ...
+ */
+export function getLoudness(amplitude) {
+    const rms = amplitude / Math.SQRT2;
+    const pressure = rms * NORMALISATION_PRESSURE_UNIT;
+    const referencePressure = 2e-5;
+    const phons = 20 * Math.log10(pressure / referencePressure);
+    if (phons < 8)
+        return 0;
+    if (phons < 40)
+        return Math.pow(phons / 40, 2.86) - 0.005;
+    return Math.pow(2, (phons - 40) / 10);
+}

package/dist/lib/types.d.ts

@@ -1,13 +1,11 @@
 import type Fraction from "fraction.js";
-import type { SECOND_ORDER_BEATING_PARAMS, SETHARES_DISSONANCE_PARAMS } from "./const";
-export type SecondOrderBeatingTerm = {
-    ratio: number;
-    magnitude: number;
-};
+import type { SETHARES_DISSONANCE_PARAMS } from "./const";
 export type SetharesDissonanceParams = Partial<typeof SETHARES_DISSONANCE_PARAMS>;
-export type SecondOrderBeatingParams = Partial<typeof SECOND_ORDER_BEATING_PARAMS>;
 export type DissonanceParams = SetharesDissonanceParams & {
-    secondOrderBeating?: SecondOrderBeatingParams;
+    firstOrderContribution: number;
+    secondOrderContribution: number;
+    thirdOrderContribution: number;
+    phantomHarmonicsNumber: number;
 };
 export type DissonanceCurvePoint = {
     interval: Fraction;

package/dist/lib/utils.d.ts

@@ -1,16 +1,23 @@
-import type { Harmonic, Spectrum } from "tuning-core";
-import type { DissonanceParams } from "./types";
+import type { Harmonic } from "tuning-core";
+import type { DissonanceParams, SetharesDissonanceParams } from "./types";
+import type { HarmonicWithLoudness } from "../classes/private/HarmonicWithLoudness";
+import { SpectrumWithLoudness } from "../classes/private/SpectrumWithLoudness";
+export { getLoudness } from "./loudness";
+/** The formula to calculate sensory dissoannce proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
+export declare function getPlompLeveltDissonance(h1: Harmonic, h2: Harmonic, params?: SetharesDissonanceParams & {
+    contribution?: number;
+}): number;
 /**
- * The formula to calculate loudness from amplitude. The converstion to SPL (phons) is done according to Sethares in the appendix "How to Draw Dissonance Curves". The converstion to loudness is done according to https://sengpielaudio.com/calculatorSonephon.htm
- * @param {number} amplitude - the normalized peak value where 0.001 corresponds to SPL of 40 db or 1 sone and 1 to SPL of 100db and 64 sones. Normalisation is done for the simplicity of providing harmonic spectrum with amplitudes 1, 1/2, 1/3, ...
+ * Find dissonance between two harmonics based on phantom status.
+ * - Both non-phantom: firstOrderDissonance
+ * - One phantom, one non-phantom: secondOrderDissonance
+ * - Both phantom: thirdOrderDissonance
  */
-export declare function getLoudness(amplitude: number): number;
-/** The formula to calculate sensory dissoannce proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
-export declare function getPlompLeveltDissonance(h1: Harmonic, h2: Harmonic, params?: DissonanceParams): number;
+export declare function getSensoryDissonance(h1: HarmonicWithLoudness, h2: HarmonicWithLoudness, params?: DissonanceParams): number;
 /**
  * Calculate the intrinsic dissonance of a spectrum.
  */
-export declare function getIntrinsicDissonance(spectrum: Spectrum, params?: DissonanceParams): number;
+export declare function getIntrinsicDissonance(spectrum: SpectrumWithLoudness, params?: DissonanceParams): number;
 /**
  * Calculate the dissonance between two spectra.
  * This is the sum of the intrinsic dissonance of each spectrum
@@ -18,9 +25,7 @@ export declare function getIntrinsicDissonance(spectrum: Spectrum, params?: Diss
  *
  * Note: If not proviing secondOrderBeating params is yield the same result as Sethares' TTSS formula.
  * However secondOrderBeating params can be used to finetune the dissoannce perception and account for harmonicity.
+ *
+ * @param precomputedSpectrum1Intrinsic - When provided, use this instead of computing spectrum1's intrinsic dissonance (for performance when spectrum1 is constant across many calls).
  */
-export declare function getSetharesDissonance(spectrum1: Spectrum, spectrum2: Spectrum, params?: DissonanceParams): number;
-/**
- * Helper function to calculate the second order beating dissonance between two harmonics.
- */
-export declare function getSecondOrderBeatingDissonance(h1: Harmonic, h2: Harmonic, params?: DissonanceParams): number;
+export declare function getSetharesDissonance(spectrum1: SpectrumWithLoudness, spectrum2: SpectrumWithLoudness, params?: DissonanceParams, precomputedSpectrum1Intrinsic?: number): number;

package/dist/lib/utils.js

@@ -1,29 +1,20 @@
-import { DEFAULT_DISSONANCE_PARAMS, NORMALISATION_PRESSURE_UNIT } from "./const";
-/**
- * The formula to calculate loudness from amplitude. The converstion to SPL (phons) is done according to Sethares in the appendix "How to Draw Dissonance Curves". The converstion to loudness is done according to https://sengpielaudio.com/calculatorSonephon.htm
- * @param {number} amplitude - the normalized peak value where 0.001 corresponds to SPL of 40 db or 1 sone and 1 to SPL of 100db and 64 sones. Normalisation is done for the simplicity of providing harmonic spectrum with amplitudes 1, 1/2, 1/3, ...
- */
-export function getLoudness(amplitude) {
-    const rms = amplitude / Math.SQRT2;
-    const pressure = rms * NORMALISATION_PRESSURE_UNIT;
-    const referencePressure = 2e-5;
-    const phons = 20 * Math.log10(pressure / referencePressure);
-    if (phons < 8)
-        return 0;
-    if (phons < 40)
-        return Math.pow(phons / 40, 2.86) - 0.005;
-    return Math.pow(2, (phons - 40) / 10);
-}
+import { SETHARES_DISSONANCE_PARAMS } from "./const";
+import { getLoudness } from "./loudness";
+import { SpectrumWithLoudness } from "../classes/private/SpectrumWithLoudness";
+export { getLoudness } from "./loudness";
 /** The formula to calculate sensory dissoannce proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
 export function getPlompLeveltDissonance(h1, h2, params) {
-    const x_star = params?.x_star ?? DEFAULT_DISSONANCE_PARAMS.x_star;
-    const s1 = params?.s1 ?? DEFAULT_DISSONANCE_PARAMS.s1;
-    const s2 = params?.s2 ?? DEFAULT_DISSONANCE_PARAMS.s2;
-    const b1 = params?.b1 ?? DEFAULT_DISSONANCE_PARAMS.b1;
-    const b2 = params?.b2 ?? DEFAULT_DISSONANCE_PARAMS.b2;
+    const contribution = params?.contribution ?? 1;
+    if (contribution <= 0)
+        return 0;
+    const x_star = params?.x_star ?? SETHARES_DISSONANCE_PARAMS.x_star;
+    const s1 = params?.s1 ?? SETHARES_DISSONANCE_PARAMS.s1;
+    const s2 = params?.s2 ?? SETHARES_DISSONANCE_PARAMS.s2;
+    const b1 = params?.b1 ?? SETHARES_DISSONANCE_PARAMS.b1;
+    const b2 = params?.b2 ?? SETHARES_DISSONANCE_PARAMS.b2;
     if (h1.frequency.equals(h2.frequency))
         return 0;
-    const minLoudness = Math.min(getLoudness(h1.amplitude), getLoudness(h2.amplitude));
+    const minLoudness = Math.min("loudness" in h1 ? h1.loudness : getLoudness(h1.amplitude), "loudness" in h2 ? h2.loudness : getLoudness(h2.amplitude));
     if (minLoudness <= 0)
         return 0;
     const minFrequency = Math.min(h1.frequencyNum, h2.frequencyNum);
@@ -31,35 +22,50 @@ export function getPlompLeveltDissonance(h1, h2, params) {
         return 0;
     const frequencyDifference = Math.abs(h1.frequencyNum - h2.frequencyNum);
     const s = x_star / (s1 * minFrequency + s2);
-    return (minLoudness *
+    return (contribution *
+        minLoudness *
         (Math.exp(-1 * b1 * s * frequencyDifference) -
             Math.exp(-1 * b2 * s * frequencyDifference)));
 }
+/** For now identical to getPlompLeveltDissonance */
+function firstOrderDissonance(h1, h2, params) {
+    return getPlompLeveltDissonance(h1, h2, { ...params, contribution: params?.firstOrderContribution });
+}
+/** For now identical to getPlompLeveltDissonance */
+function secondOrderDissonance(h1, h2, params) {
+    return getPlompLeveltDissonance(h1, h2, { ...params, contribution: params?.secondOrderContribution });
+}
+/** For now identical to getPlompLeveltDissonance */
+function thirdOrderDissonance(h1, h2, params) {
+    return getPlompLeveltDissonance(h1, h2, { ...params, contribution: params?.thirdOrderContribution });
+}
+/**
+ * Find dissonance between two harmonics based on phantom status.
+ * - Both non-phantom: firstOrderDissonance
+ * - One phantom, one non-phantom: secondOrderDissonance
+ * - Both phantom: thirdOrderDissonance
+ */
+export function getSensoryDissonance(h1, h2, params) {
+    if (!h1.phantom && !h2.phantom) {
+        return firstOrderDissonance(h1, h2, params);
+    }
+    if (h1.phantom !== h2.phantom) {
+        return secondOrderDissonance(h1, h2, params);
+    }
+    return thirdOrderDissonance(h1, h2, params);
+}
 /**
  * Calculate the intrinsic dissonance of a spectrum.
  */
 export function getIntrinsicDissonance(spectrum, params) {
-    const totalContribution = params?.totalContribution ??
-        DEFAULT_DISSONANCE_PARAMS.totalContribution;
-    const secondOrderBeatingContribution = params?.secondOrderBeating?.totalContribution ??
-        DEFAULT_DISSONANCE_PARAMS.secondOrderBeating?.totalContribution;
     let dissonance = 0;
-    const frequencies = spectrum.getKeys();
+    const harmonics = spectrum.getHarmonics();
     // loop over all pairs of harmonics within the spectrum (not including reversed pairs)
-    for (let i = 0; i < frequencies.length; i++) {
-        for (let j = i + 1; j < frequencies.length; j++) {
-            const h1 = spectrum.get(frequencies[i]);
-            const h2 = spectrum.get(frequencies[j]);
-            if (totalContribution) {
-                dissonance +=
-                    totalContribution *
-                        getPlompLeveltDissonance(h1, h2, params);
-            }
-            if (secondOrderBeatingContribution) {
-                dissonance +=
-                    secondOrderBeatingContribution *
-                        getSecondOrderBeatingDissonance(h1, h2, params);
-            }
+    for (let i = 0; i < harmonics.length; i++) {
+        for (let j = i + 1; j < harmonics.length; j++) {
+            const h1 = harmonics[i];
+            const h2 = harmonics[j];
+            dissonance += getSensoryDissonance(h1, h2, params);
         }
     }
     return dissonance;
@@ -71,65 +77,17 @@ export function getIntrinsicDissonance(spectrum, params) {
  *
  * Note: If not proviing secondOrderBeating params is yield the same result as Sethares' TTSS formula.
  * However secondOrderBeating params can be used to finetune the dissoannce perception and account for harmonicity.
+ *
+ * @param precomputedSpectrum1Intrinsic - When provided, use this instead of computing spectrum1's intrinsic dissonance (for performance when spectrum1 is constant across many calls).
  */
-export function getSetharesDissonance(spectrum1, spectrum2, params) {
-    const totalContribution = params?.totalContribution ??
-        DEFAULT_DISSONANCE_PARAMS.totalContribution;
-    const secondOrderBeatingContribution = params?.secondOrderBeating?.totalContribution ??
-        DEFAULT_DISSONANCE_PARAMS.secondOrderBeating?.totalContribution;
-    let dissonance = getIntrinsicDissonance(spectrum1, params) +
-        getIntrinsicDissonance(spectrum2, params);
-    const frequencies1 = spectrum1.getKeys();
-    const frequencies2 = spectrum2.getKeys();
+export function getSetharesDissonance(spectrum1, spectrum2, params, precomputedSpectrum1Intrinsic) {
+    const spectrum1Intrinsic = precomputedSpectrum1Intrinsic ?? getIntrinsicDissonance(spectrum1, params);
+    let dissonance = spectrum1Intrinsic + getIntrinsicDissonance(spectrum2, params);
     // loop over all pairs of harmonics between the two spectra (not including reversed pairs)
-    for (let i = 0; i < frequencies1.length; i++) {
-        for (let j = 0; j < frequencies2.length; j++) {
-            const h1 = spectrum1.get(frequencies1[i]);
-            const h2 = spectrum2.get(frequencies2[j]);
-            if (totalContribution) {
-                dissonance +=
-                    totalContribution *
-                        getPlompLeveltDissonance(h1, h2, params);
-            }
-            if (secondOrderBeatingContribution) {
-                dissonance +=
-                    secondOrderBeatingContribution *
-                        getSecondOrderBeatingDissonance(h1, h2, params);
-            }
+    for (const h1 of spectrum1.getHarmonics()) {
+        for (const h2 of spectrum2.getHarmonics()) {
+            dissonance += getSensoryDissonance(h1, h2, params);
         }
     }
     return dissonance;
 }
-/**
- * Helper function to calculate the second order beating dissonance between two harmonics.
- */
-export function getSecondOrderBeatingDissonance(h1, h2, params) {
-    const x_star = params?.x_star ?? DEFAULT_DISSONANCE_PARAMS.x_star;
-    const s1 = params?.s1 ?? DEFAULT_DISSONANCE_PARAMS.s1;
-    const s2 = params?.s2 ?? DEFAULT_DISSONANCE_PARAMS.s2;
-    const b1 = params?.b1 ?? DEFAULT_DISSONANCE_PARAMS.b1;
-    const b2 = params?.b2 ?? DEFAULT_DISSONANCE_PARAMS.b2;
-    const widthMagnitudeRelationship = params?.secondOrderBeating?.widthMagnitudeRelationship ??
-        DEFAULT_DISSONANCE_PARAMS.secondOrderBeating.widthMagnitudeRelationship;
-    const terms = params?.secondOrderBeating?.terms ??
-        DEFAULT_DISSONANCE_PARAMS.secondOrderBeating.terms;
-    let dissonance = 0;
-    const minLoudness = Math.min(getLoudness(h1.amplitude), getLoudness(h2.amplitude));
-    const minFrequency = Math.min(h1.frequencyNum, h2.frequencyNum);
-    if (minFrequency <= 0)
-        return 0;
-    const maxFrequency = Math.max(h1.frequencyNum, h2.frequencyNum);
-    for (const term of terms) {
-        if (term.ratio === 1 || term.ratio <= 0)
-            continue;
-        const difference = Math.abs(minFrequency * term.ratio - maxFrequency);
-        const s = x_star / (s1 * minFrequency + s2);
-        const widthModifier = 1 - widthMagnitudeRelationship * term.magnitude;
-        dissonance +=
-            term.magnitude *
-                minLoudness *
-                (Math.exp((-1 * b1 * s * difference) / widthModifier) -
-                    Math.exp((-1 * b2 * s * difference) / widthModifier));
-    }
-    return dissonance;
-}

package/dist/manual-testing/index.js

@@ -0,0 +1,16 @@
+import { Spectrum } from "tuning-core";
+import { DissonanceCurve } from "../classes";
+const context = Spectrum.harmonic(6, 440);
+const complement = Spectrum.harmonic(6, 440);
+const curve = new DissonanceCurve({
+    context,
+    complement,
+    start: 1,
+    end: 2,
+    firstOrderContribution: 1,
+    secondOrderContribution: 0.3,
+    thirdOrderContribution: 0.1,
+    phantomHarmonicsNumber: 2,
+    maxGapCents: 20,
+});
+Bun.write("./manual-testing/curve.csv", curve.toCsvFileBuffer());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sethares-dissonance",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "type": "module",
   "devDependencies": {
     "@types/bun": "latest"
@@ -16,10 +16,11 @@
   ],
   "scripts": {
     "build": "npx tsc",
-    "release": "./release.sh"
+    "release": "./release.sh",
+    "bench": "bun run benches/dissonance-curve.bench.ts"
   },
   "dependencies": {
     "fraction.js": "^5.3.4",
-    "tuning-core": "^1.1.0"
+    "tuning-core": "^1.2.0"
   }
 }

package/dist/tests/DissonanceCurve.test.js

@@ -1,127 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import Fraction from "fraction.js";
-import { DissonanceCurve } from "../classes";
-import { Spectrum } from "tuning-core";
-function createTestCurve() {
-    const context = Spectrum.harmonic(6, 440);
-    const complement = Spectrum.harmonic(6, 440);
-    return new DissonanceCurve({
-        context,
-        complement,
-        start: 1,
-        end: 2,
-        maxDenominator: 60,
-    });
-}
-describe("DissonanceCurve", () => {
-    describe("findNearestPoint", () => {
-        describe("ratios that exist in the curve", () => {
-            test("returns exact point when ratio is in curve (number)", () => {
-                const curve = createTestCurve();
-                const points = curve.points;
-                const firstPoint = points[0];
-                const result = curve.findNearestPoint(firstPoint.interval.valueOf());
-                expect(result).toBeDefined();
-                expect(result?.interval.compare(firstPoint.interval)).toBe(0);
-                expect(result?.dissonance).toBe(firstPoint.dissonance);
-            });
-            test("returns exact point when ratio is in curve (string)", () => {
-                const curve = createTestCurve();
-                const points = curve.points;
-                const midPoint = points[Math.floor(points.length / 2)];
-                const result = curve.findNearestPoint(midPoint.interval.toFraction());
-                expect(result).toBeDefined();
-                expect(result?.interval.compare(midPoint.interval)).toBe(0);
-            });
-            test("returns exact point when ratio is in curve (Fraction)", () => {
-                const curve = createTestCurve();
-                const points = curve.points;
-                const lastPoint = points[points.length - 1];
-                const result = curve.findNearestPoint(new Fraction(lastPoint.interval));
-                expect(result).toBeDefined();
-                expect(result?.interval.compare(lastPoint.interval)).toBe(0);
-            });
-            test("returns exact point for ratio 1 (unison)", () => {
-                const curve = createTestCurve();
-                const result = curve.findNearestPoint(1);
-                expect(result).toBeDefined();
-                expect(result?.interval.compare(1)).toBe(0);
-            });
-            test("returns exact point for ratio 2 (octave)", () => {
-                const curve = createTestCurve();
-                const result = curve.findNearestPoint(2);
-                expect(result).toBeDefined();
-                expect(result?.interval.compare(2)).toBe(0);
-            });
-        });
-        describe("ratios that do not exist in the curve", () => {
-            test("returns ceiling point when ratio is between two calculated points", () => {
-                const curve = createTestCurve();
-                const points = curve.points;
-                if (points.length < 2)
-                    return;
-                const left = points[0];
-                const right = points[1];
-                const between = Math.sqrt(left.interval.valueOf() * right.interval.valueOf());
-                const result = curve.findNearestPoint(between);
-                expect(result).toBeDefined();
-                expect(result?.interval.compare(right.interval)).toBe(0);
-            });
-            test("returns first point when ratio is below curve range", () => {
-                const curve = createTestCurve();
-                const points = curve.points;
-                const minRatio = points[0].interval.valueOf();
-                const result = curve.findNearestPoint(minRatio * 0.5);
-                expect(result).toBeDefined();
-                expect(result?.interval.compare(points[0].interval)).toBe(0);
-            });
-            test("returns last point when ratio is above curve range", () => {
-                const curve = createTestCurve();
-                const points = curve.points;
-                const lastPoint = points[points.length - 1];
-                const result = curve.findNearestPoint(lastPoint.interval.valueOf() * 2);
-                expect(result).toBeDefined();
-                expect(result?.interval.compare(lastPoint.interval)).toBe(0);
-            });
-            test("returns correct point for ratio just below an existing point", () => {
-                const curve = createTestCurve();
-                const points = curve.points;
-                if (points.length < 2)
-                    return;
-                const target = points[1];
-                const justBelow = target.interval.valueOf() - 0.001;
-                const result = curve.findNearestPoint(justBelow);
-                expect(result).toBeDefined();
-                expect(result?.interval.compare(target.interval)).toBe(0);
-            });
-            test("returns ceiling point when ratio is just above an existing point", () => {
-                const curve = createTestCurve();
-                const points = curve.points;
-                if (points.length < 2)
-                    return;
-                const current = points[1];
-                const justAboveCurrent = current.interval.valueOf() + 0.001;
-                const result = curve.findNearestPoint(justAboveCurrent);
-                expect(result).toBeDefined();
-                expect(result.interval.compare(justAboveCurrent)).toBeGreaterThanOrEqual(0);
-            });
-        });
-        describe("FractionInput types", () => {
-            test("accepts number input", () => {
-                const curve = createTestCurve();
-                const result = curve.findNearestPoint(1.5);
-                expect(result).toBeDefined();
-            });
-            test("accepts string fraction input", () => {
-                const curve = createTestCurve();
-                const result = curve.findNearestPoint("3/2");
-                expect(result).toBeDefined();
-            });
-            test("accepts Fraction object input", () => {
-                const curve = createTestCurve();
-                const result = curve.findNearestPoint(new Fraction(5, 4));
-                expect(result).toBeDefined();
-            });
-        });
-    });
-});

package/dist/tests/utils.test.js

@@ -1,9 +0,0 @@
-import { expect, test, describe } from "bun:test";
-import * as Utils from "../lib/utils";
-describe("lib/utils", () => {
-    test("Should calculate loudness", () => {
-        const amplitudes = [1, 0.001, 0.000025];
-        const expectedOutcome = [64, 1, 0];
-        expect(amplitudes.map(Utils.getLoudness)).toEqual(expectedOutcome);
-    });
-});