harmonic-entropy
Version:
Compute harmonic entropy of a musical interval
109 lines (108 loc) • 4.16 kB
TypeScript
import { FractionValue } from 'xen-dev-utils';
/**
* Options for configuring harmonic entropy calculation.
*/
export type HarmonicEntropyOptions = {
/** Max height of rationals (Benedetti (default 10k) or Wilson (default 1000) depending on series) */
N?: number;
/** Gaussian frequency deviation (default 0.01) */
s?: number;
/** Rényi order (default 1.0 i.e Shanon entropy) */
a?: number;
/** Series of rationals to use (default 'tenney') */
series?: 'tenney' | 'farey';
/** Lower bound of tabulation (default 0) */
minCents?: number;
/** Upper bound of tabulation (default 2400) */
maxCents?: number;
/** Tabulation delta in cents (default 1) */
res?: number;
/** Boolean flag to normalize the result by Hartley entropy (default false) */
normalize?: boolean;
};
/**
* Calculate a harmonic entropy table.
* @param options Parameters for calculating the table.
* @param ratios Ratios precalculated using {@link precalculateRatios}.
* @returns Array of [cents, entropy (in natural units)].
*/
export declare function harmonicEntropy(options: HarmonicEntropyOptions, ratios: number[][]): [number, number][];
/**
* Precalculate the set of ratios considered when calculating {@link harmonicEntropy}.
* @param options Parameters for calculating the table.
* @returns Array of [numerator, denominator] pairs.
*/
export declare function precalculateRatios(options: HarmonicEntropyOptions): [number, number][];
/**
* Construct a harmonic entropy calculator for individual musical intervals.
*/
export declare class EntropyCalculator {
private options_;
private ratios?;
table: [number, number][];
constructor(options?: HarmonicEntropyOptions);
/**
* Revive a {@link EntropyCalculator} instance produced by `EntropyCalculator.toJSON()`. Return everything else as is.
*
* Intended usage:
* ```ts
* const data = JSON.parse(serializedData, EntropyCalculator.reviver);
* ```
*
* @param key Property name.
* @param value Property value.
* @returns Deserialized {@link EntropyCalculator} instance or other data without modifications.
*/
static reviver(key: string, value: any): any;
/**
* Serialize the entropy calculator to a JSON compatible object.
* @returns The serialized object with property `type` set to `'EntropyCalculator'`.
*/
toJSON(): {
type: string;
options: HarmonicEntropyOptions;
tableY: number[];
};
private recalculate;
/** Options associated with this harmonic entropy calculator. */
get options(): HarmonicEntropyOptions;
set options(value: HarmonicEntropyOptions);
/** Max height of rationals (Benedetti or Wilson depending on series) */
get N(): number;
set N(value: number);
/** Gaussian frequency deviation (default 0.01) */
get s(): number;
set s(value: number);
/** Rényi order */
get a(): number;
set a(value: number);
/** Series of rationals to use */
get series(): 'tenney' | 'farey';
set series(value: 'tenney' | 'farey');
/** Lower bound of tabulation */
get minCents(): number;
set minCents(value: number);
/** Upper bound of tabulation */
get maxCents(): number;
set maxCents(value: number);
/** Tabulation delta in cents */
get res(): number;
set res(value: number);
/** Boolean flag to normalize the result by Hartley entropy */
get normalize(): boolean;
set normalize(value: boolean);
/**
* Calculate the harmonic entropy of a rational number.
* @param value Fractional value.
* @returns The harmonic entropy of the input in natural units.
* @throws An error if the input is outside of the tablated range.
*/
ofFraction(value: FractionValue): number;
/**
* Calculate the harmonic entropy of a musical interval measured in cents.
* @param cents Width of the interval.
* @returns The harmonic entropy of the input in natural units.
* @throws An error if the input is outside the range of `.minCents` and `.maxCents`.
*/
ofCents(cents: number): number;
}