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

Utility functions used by the Scale Workshop ecosystem

import { Fraction, FractionValue } from './fraction';
import { FractionalMonzo, Monzo, ProtoFractionalMonzo } from './monzo';
/**
 * Result of Gram–Schmidt process without normalization.
 */
export type GramResult = {
    /** Orthogonal basis with the leading basis element intact. */
    ortho: number[][];
    /** Squared lengths of the orthogonal basis. */
    squaredLengths: number[];
    /** Geometric duals of the orthogonal basis. */
    dual: number[][];
};
/**
 * Result of Gram–Schmidt process without normalization.
 */
export type FractionalGramResult = {
    /** Orthogonal basis with the leading basis element intact. */
    ortho: FractionalMonzo[];
    /** Squared lengths of the orthogonal basis. */
    squaredLengths: Fraction[];
    /** Geometric duals of the orthogonal basis. */
    dual: FractionalMonzo[];
};
/**
 * Result of Lenstra-Lenstra-Lovász basis reduction.
 */
export type LLLResult = {
    /** Basis that's short and nearly orthogonal. */
    basis: number[][];
    /** Gram-Schmidt process results. */
    gram: GramResult;
};
/**
 * Result of Lenstra-Lenstra-Lovász basis reduction.
 */
export type FractionalLLLResult = {
    /** Basis that's short and nearly orthogonal. */
    basis: FractionalMonzo[];
    /** Gram-Schmidt process results. */
    gram: FractionalGramResult;
};
/**
 * Perform Gram–Schmidt process without normalization.
 * @param basis Array of basis elements.
 * @param epsilon Threshold for zero.
 * @returns The orthogonalized basis and its dual (duals of near-zero basis elements are coerced to zero).
 */
export declare function gram(basis: number[][], epsilon?: number): GramResult;
/**
 * Perform Gram–Schmidt process without normalization.
 * @param basis Array of rational basis elements.
 * @returns The orthogonalized basis and its dual as arrays of fractions (duals of zero basis elements are coerced to zero).
 */
export declare function fractionalGram(basis: ProtoFractionalMonzo[]): FractionalGramResult;
/**
 * Preform Lenstra-Lenstra-Lovász basis reduction.
 * @param basis Array of basis elements.
 * @param delta Lovász coefficient.
 * @param epsilon Threshold for zero.
 * @param maxIterations Maximum number of iterations to perform.
 * @returns The basis processed to be short and nearly orthogonal alongside Gram-Schmidt coefficients.
 */
export declare function lenstraLenstraLovasz(basis: number[][], delta?: number, epsilon?: number, maxIterations?: number): LLLResult;
/**
 * Preform Lenstra-Lenstra-Lovász basis reduction using rational numbers.
 * @param basis Array of rational basis elements.
 * @param delta Lovász coefficient.
 * @param maxIterations Maximum number of iterations to perform.
 * @returns The basis processed to be short and nearly orthogonal alongside Gram-Schmidt coefficients.
 */
export declare function fractionalLenstraLenstraLovasz(basis: ProtoFractionalMonzo[], delta?: FractionValue, maxIterations?: number): FractionalLLLResult;
/**
 * Return a 2-D array with ones on the diagonal and zeros elsewhere.
 * @param N Number of rows in the output.
 * @param M Number of columns in the output.
 * @param k Index of the diagonal.
 * @returns An array where all elements are equal to zero, except for the `k`-th diagonal, whose values are equal to one.
 */
export declare function eye(N: number, M?: number, k?: number): number[][];
/**
 * Return a 2-D array with ones on the diagonal and zeros elsewhere.
 * @param N Number of rows in the output.
 * @param M Number of columns in the output.
 * @param k Index of the diagonal.
 * @returns An array where all elements are equal to zero, except for the `k`-th diagonal, whose values are equal to one.
 */
export declare function fractionalEye(N: number, M?: number, k?: number): FractionalMonzo[];
/**
 * Compute the (multiplicative) inverse of a matrix.
 * @param matrix Matrix to be inverted.
 * @returns The multiplicative inverse.
 * @throws An error if the matrix is not square or not invertible.
 */
export declare function inv(matrix: number[][]): number[][];
/**
 * Compute the (multiplicative) inverse of a matrix.
 * @param matrix Matrix to be inverted.
 * @returns The multiplicative inverse.
 * @throws An error if the matrix is not square or not invertible.
 */
export declare function fractionalInv(matrix: ProtoFractionalMonzo[]): FractionalMonzo[];
/**
 * Compute the matrix product of two matrices or vectors.
 * @param A The left operand.
 * @param B The right operand.
 * @returns The matrix product of the operands.
 */
export declare function matmul(A: number[], B: number[]): number;
export declare function matmul(A: number[], B: number[][]): number[];
export declare function matmul(A: number[][], B: number[]): number[];
export declare function matmul(A: number[][], B: number[][]): number[][];
/**
 * Compute the matrix product of two matrices or vectors.
 * @param A The left operand.
 * @param B The right operand.
 * @returns The matrix product of the operands.
 */
export declare function fractionalMatmul(A: ProtoFractionalMonzo, B: ProtoFractionalMonzo): Fraction;
export declare function fractionalMatmul(A: ProtoFractionalMonzo, B: ProtoFractionalMonzo[]): FractionalMonzo;
export declare function fractionalMatmul(A: ProtoFractionalMonzo[], B: ProtoFractionalMonzo): FractionalMonzo;
export declare function fractionalMatmul(A: ProtoFractionalMonzo[], B: ProtoFractionalMonzo[]): FractionalMonzo[];
export declare function fractionalMatmul_(A: ProtoFractionalMonzo[], B: ProtoFractionalMonzo[]): FractionalMonzo[];
/**
 * Compute the determinant of a matrix.
 * @param matrix Array of arrays of numbers to calculate determinant for.
 * @returns The determinant.
 */
export declare function det(matrix: number[][]): number;
/**
 * Compute the determinant of a matrix with rational entries.
 * @param matrix Array of arrays of fractions to calculate determinant for.
 * @returns The determinant.
 */
export declare function fractionalDet(matrix: ProtoFractionalMonzo[]): Fraction;
/**
 * Transpose a 2-D matrix with rational entries (swap rows and columns).
 * @param matrix Matrix to transpose.
 * @returns The transpose.
 */
export declare function fractionalTranspose(matrix: ProtoFractionalMonzo[]): FractionalMonzo[];
/**
 * Obtain the minor a matrix.
 * @param matrix The input matrix.
 * @param i The row to remove.
 * @param j The column to remove.
 * @returns The spliced matrix.
 */
export declare function minor(matrix: any[][], i: number, j: number): any[][];
/**
 * Scale a matrix by a scalar.
 * @param matrix The matrix to scale.
 * @param amount The amount to scale by.
 * @returns The scalar multiple.
 */
export declare function matscale(matrix: number[][], amount: number): number[][];
/**
 * Add two matrices.
 * @param A The first matrix.
 * @param B The second matrix.
 * @returns The sum.
 */
export declare function matadd(A: number[][], B: number[][]): number[][];
/**
 * Subtract two matrices.
 * @param A The matrix to subtract from.
 * @param B The matrix to subtract by.
 * @returns The difference.
 */
export declare function matsub(A: number[][], B: number[][]): number[][];
/**
 * Scale a matrix by a scalar.
 * @param matrix The matrix to scale.
 * @param amount The amount to scale by.
 * @returns The scalar multiple.
 */
export declare function fractionalMatscale(matrix: ProtoFractionalMonzo[], amount: FractionValue): FractionalMonzo[];
/**
 * Add two matrices.
 * @param A The first matrix.
 * @param B The second matrix.
 * @returns The sum.
 */
export declare function fractionalMatadd(A: ProtoFractionalMonzo[], B: ProtoFractionalMonzo[]): FractionalMonzo[];
/**
 * Subtract two matrices.
 * @param A The matrix to subtract from.
 * @param B The matrix to subtract by.
 * @returns The difference.
 */
export declare function fractionalMatsub(A: ProtoFractionalMonzo[], B: ProtoFractionalMonzo[]): FractionalMonzo[];
/**
 * Compute the Hermite normal form with torsion removed.
 * @param M The input matrix.
 * @returns The defactored Hermite normal form.
 */
export declare function defactoredHnf(M: number[][]): number[][];
/**
 * Compute the canonical form of the input.
 * @param M Input maps.
 * @returns Defactored Hermite normal form or the antitranspose sandwich for commas bases.
 */
export declare function canonical(M: number[][]): number[][];
/**
 * Solve approximate CVP using Babai's nearest plane algorithm.
 * @param v Vector to reduce.
 * @param basis LLL basis to reduce with.
 * @param dual Optional precalculated geometric duals of the orthogonalized basis.
 * @returns The reduced vector.
 */
export declare function nearestPlane(v: number[], basis: number[][], dual?: number[][]): Monzo;
/**
 * Respell a monzo represting a rational number to a simpler form.
 * @param monzo Array of prime exponents to simplify.
 * @param commas Monzos representing near-unisons to simplify by. Should be LLL reduced to work properly.
 * @param commaOrthoDuals Optional precalculated geometric duals of the orthogonalized comma basis.
 * @returns An array of prime exponents representing a simpler rational number.
 */
export declare function respell(monzo: Monzo, commas: Monzo[], commaOrthoDuals?: Monzo[]): Monzo;
/**
 * Solve Ax = b in the integers.
 * @param A Coefficients of unknowns.
 * @param b Target vector or a matrix of column vectors.
 * @returns A vector mapped to the target vector by A or a matrix of row vectors.
 */
export declare function solveDiophantine(A: number[][], b: number[][]): number[][];
export declare function solveDiophantine(A: number[][], b: number[]): number[];