xen-dev-utils/dist/monzo.d.ts

Utility functions used by the Scale Workshop ecosystem

import { Fraction, FractionValue } from './fraction';
/**
 * Array of integers representing the exponents of prime numbers in the unique factorization of a rational number.
 */
export type Monzo = number[];
/**
 * Array of rational numbers representing the exponents of prime numbers in the unique factorization of a radical number i.e. n-th root.
 */
export type FractionalMonzo = Fraction[];
/**
 * Array of rational-looking numbers suitable as arguments for methods that work with fractional monzos.
 */
export type ProtoFractionalMonzo = FractionValue[];
/**
 * Calculate the absolute value of a BigInt.
 * @param n Integer to measure.
 * @returns Size of the integer as a BigInt.
 */
export declare function bigAbs(n: bigint): bigint;
/**
 * Check if two monzos are equal.
 * @param a The first monzo.
 * @param b The second monzo.
 * @returns `true` if the two values are equal when interpreted as fractions.
 */
export declare function monzosEqual(a: Monzo, b: Monzo): boolean;
/**
 * Check if two fractional monzos are equal.
 * @param a The first monzo.
 * @param b The second monzo.
 * @returns `true` if the two values are equal.
 */
export declare function fractionalMonzosEqual(a: ProtoFractionalMonzo, b: ProtoFractionalMonzo): boolean;
/**
 * Add two monzos.
 * @param a The first monzo.
 * @param b The second monzo.
 * @returns A monzo that represents the product of the two numbers represented by `a` and `b`.
 */
export declare function add(a: Monzo, b: Monzo): Monzo;
/**
 * Add two fractional monzos.
 * @param a The first monzo.
 * @param b The second monzo.
 * @returns A monzo that represents the product of the two numbers represented by `a` and `b`.
 */
export declare function fractionalAdd(a: ProtoFractionalMonzo, b: ProtoFractionalMonzo): FractionalMonzo;
/**
 * Subtract two monzos.
 * @param a The first monzo.
 * @param b The second monzo.
 * @returns A monzo that represents the division of the two numbers represented by `a` and `b`.
 */
export declare function sub(a: Monzo, b: Monzo): Monzo;
/**
 * Subtract two fractional monzos.
 * @param a The first monzo.
 * @param b The second monzo.
 * @returns A monzo that represents the division of the two numbers represented by `a` and `b`.
 */
export declare function fractionalSub(a: ProtoFractionalMonzo, b: ProtoFractionalMonzo): FractionalMonzo;
/**
 * Scale a monzo by a scalar.
 * @param monzo The monzo to scale.
 * @param amount The amount to scale by.
 * @returns The scalar multiple.
 */
export declare function scale(monzo: Monzo, amount: number): number[];
/**
 * Scale a monzo by a scalar.
 * @param monzo The monzo to scale.
 * @param amount The amount to scale by.
 * @returns The scalar multiple.
 */
export declare function fractionalScale(monzo: ProtoFractionalMonzo, amount: FractionValue): FractionalMonzo;
/**
 * Calculate the inner (dot) product of two arrays of rational numbers.
 * @param a The first array of numbers.
 * @param b The second array of numbers.
 * @returns The dot product.
 */
export declare function fractionalDot(a: ProtoFractionalMonzo, b: ProtoFractionalMonzo): Fraction;
/**
 * Calculate the norm (vector length) of an array of rational numbers.
 * @param array The array to measure.
 * @param type Type of measurement. (Euclidean norm can be obtained using L2 and calling .sqrt() on the result.)
 * @returns The length of the vector.
 */
export declare function fractionalNorm(array: ProtoFractionalMonzo, type?: 'L2' | 'taxicab' | 'maximum'): Fraction;
/**
 * Multiply two monzos component-wise.
 * @param monzo The first monzo.
 * @param weights The second monzo. Missing values interpreted as 1 (no change).
 * @returns The first monzo weighted by the second.
 */
export declare function applyWeights(monzo: Monzo, weights: Monzo): number[];
/**
 * Divide two monzos component-wise.
 * @param monzo The first monzo.
 * @param weights The second monzo. Missing values interpreted as 1 (no change).
 * @returns The first monzo unweighted by the second.
 */
export declare function unapplyWeights(monzo: Monzo, weights: Monzo): number[];
/**
 * Accumulate a monzo into the first one.
 * @param target The monzo to accumulate into.
 * @param source The monzo to add.
 * @returns The (modified) target monzo.
 */
export declare function accumulate(target: Monzo, source: Monzo): Monzo;
/**
 * Decumulate a monzo into the first one.
 * @param target The monzo to decumulate into.
 * @param source The monzo to subtract.
 * @returns The (modified) target monzo.
 */
export declare function decumulate(target: Monzo, source: Monzo): Monzo;
/**
 * Rescale a monzo by a scalar.
 * @param target The monzo to rescale.
 * @param amount The amount to scale by.
 * @returns The (modified) target monzo.
 */
export declare function rescale(target: Monzo, amount: number): Monzo;
/**
 * Extract the exponents of the prime factors of a rational number.
 * @param n Rational number to convert to a monzo.
 * @returns The monzo representing `n`.
 */
export declare function toMonzo(n: FractionValue | bigint): Monzo;
/**
 * Convert a monzo to the fraction it represents.
 * @param monzo Iterable of prime exponents.
 * @returns Fractional representation of the monzo.
 */
export declare function monzoToFraction(monzo: Iterable<number>): Fraction;
/**
 * Convert a monzo to the BigInt it represents.
 * @param monzo Iterable of prime exponents.
 * @returns BigInt representation of the monzo.
 */
export declare function monzoToBigInt(monzo: Iterable<number>): bigint;
/**
 * Convert a monzo to the BigInt fraction it represents.
 * @param monzo Iterable of prime exponents.
 * @returns Record with keys 'numerator' and 'denominator containing BigInts.
 */
export declare function monzoToBigNumeratorDenominator(monzo: Iterable<number>): {
    numerator: bigint;
    denominator: bigint;
};
/**
 * Calculate the prime limit of an integer or a fraction.
 * @param n Integer or fraction to calculate prime limit for.
 * @param asOrdinal Return the limit as an ordinal instead of a prime. (1 is #0, 2 is #1, 3 is #2, 5 is #3, etc.)
 * @param maxLimit Maximum prime limit to consider.
 * @returns The largest prime in the factorization of the input. `Infinity` if above the maximum limit. `NaN` if not applicable.
 */
export declare function primeLimit(n: FractionValue | bigint, asOrdinal?: boolean, maxLimit?: number): number;
/**
 * Extract the exponents of the prime factors of a rational number.
 * @param n Rational number to convert to a monzo.
 * @param numberOfComponents Number of components in the result.
 * @returns The monzo representing `n` and a multiplicative residue that cannot be represented in the given limit.
 */
export declare function toMonzoAndResidual(n: bigint, numberOfComponents: number): [Monzo, bigint];
export declare function toMonzoAndResidual(n: FractionValue, numberOfComponents: number): [Monzo, Fraction];
/**
 * Factorize a number into a `Map` instace with prime numbers as keys and their multiplicity as values.
 * @param value Rational number to factorize.
 * @returns A sparse monzo.
 */
export declare function primeFactorize(value: FractionValue): Map<number, number>;