@lakutata/math 0.0.0-stage → 3.1.5

package/dist/cjs/lib/Native.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.native = void 0;
+exports.toException = toException;
+exports.nativeCall = nativeCall;
+const MathArgumentException_js_1 = require("../exceptions/MathArgumentException.js");
+const MathCancelledException_js_1 = require("../exceptions/MathCancelledException.js");
+const MathDefinitionException_js_1 = require("../exceptions/MathDefinitionException.js");
+const MathDivisionByZeroException_js_1 = require("../exceptions/MathDivisionByZeroException.js");
+const MathDomainException_js_1 = require("../exceptions/MathDomainException.js");
+const MathException_js_1 = require("../exceptions/MathException.js");
+const MathNotSupportedException_js_1 = require("../exceptions/MathNotSupportedException.js");
+const MathSyntaxException_js_1 = require("../exceptions/MathSyntaxException.js");
+const MathTimeoutException_js_1 = require("../exceptions/MathTimeoutException.js");
+const MathUnitException_js_1 = require("../exceptions/MathUnitException.js");
+const MathUnknownFunctionException_js_1 = require("../exceptions/MathUnknownFunctionException.js");
+const Addon_js_1 = require("./Addon.js");
+const EXCEPTIONS = {
+    E_MATH_SYNTAX: MathSyntaxException_js_1.MathSyntaxException,
+    E_MATH_UNKNOWN_FUNCTION: MathUnknownFunctionException_js_1.MathUnknownFunctionException,
+    E_MATH_DEFINITION: MathDefinitionException_js_1.MathDefinitionException,
+    E_MATH_DOMAIN: MathDomainException_js_1.MathDomainException,
+    E_MATH_DIVISION_BY_ZERO: MathDivisionByZeroException_js_1.MathDivisionByZeroException,
+    E_MATH_NOT_SUPPORTED: MathNotSupportedException_js_1.MathNotSupportedException,
+    E_MATH_UNIT: MathUnitException_js_1.MathUnitException,
+    E_MATH_CANCELLED: MathCancelledException_js_1.MathCancelledException,
+    E_MATH_TIMEOUT: MathTimeoutException_js_1.MathTimeoutException,
+    E_MATH_ARGUMENT: MathArgumentException_js_1.MathArgumentException
+};
+/**
+ * The exception of an error of the addon (its code), the error itself otherwise
+ * @param error
+ */
+function toException(error) {
+    if (!(error instanceof Error) || error instanceof MathException_js_1.MathException)
+        return error;
+    const code = error.code;
+    if (typeof code !== 'string' || !code.startsWith('E_MATH_'))
+        return error;
+    const exception = new (EXCEPTIONS[code] ?? MathException_js_1.MathException)(error.message);
+    const position = error.position;
+    if (typeof position === 'number')
+        exception.position = position;
+    return exception;
+}
+/**
+ * Call a function of the addon, its errors thrown as the exceptions of the package
+ * @param call
+ */
+function nativeCall(call) {
+    try {
+        return call(Addon_js_1.addon);
+    }
+    catch (error) {
+        throw toException(error);
+    }
+}
+/**
+ * The addon, for the calls that cannot fail (its versions)
+ */
+exports.native = Addon_js_1.addon;

package/dist/cjs/lib/NumberTheory.d.ts

@@ -0,0 +1,356 @@
+import { type AsyncOptions, type Context } from './Context.js';
+import { Expression, type Value } from './Expression.js';
+/**
+ * An integer: a bigint, or a number that is a safe integer (`Number.isSafeInteger()`); any other value throws
+ * `MathArgumentException`.
+ */
+export type IntegerValue = bigint | number;
+/**
+ * A prime factor and its exponent.
+ */
+export interface PrimeFactor {
+    /**
+     * The prime (-1 for the sign of a negative number).
+     */
+    prime: bigint;
+    /**
+     * Its exponent.
+     */
+    exponent: number;
+}
+/**
+ * The greatest common divisor of two integers and the coefficients of Bézout's identity: `a*x + b*y = gcd`.
+ */
+export interface ExtendedGcd {
+    /**
+     * The greatest common divisor, 0 or positive.
+     */
+    gcd: bigint;
+    /**
+     * The coefficient of `a`.
+     */
+    x: bigint;
+    /**
+     * The coefficient of `b`.
+     */
+    y: bigint;
+}
+/**
+ * The solutions of a system of congruences: the integers equal to `remainder` modulo `modulus`.
+ */
+export interface Congruence {
+    /**
+     * The smallest solution that is 0 or positive.
+     */
+    remainder: bigint;
+    /**
+     * The modulus of the solutions: the least common multiple of the moduli.
+     */
+    modulus: bigint;
+}
+/**
+ * The options of a continued fraction
+ */
+export interface ContinuedFractionOptions {
+    /**
+     * The largest number of terms, from 1 to 10000: 20 by default. A rational number has all its terms, up to it.
+     */
+    terms?: number;
+}
+/**
+ * The number theory of the integers: divisibility, modular arithmetic, primes, factorization, integer sequences,
+ * combinatorial numbers and continued fractions. It is `MathScope.ntheory`; the package exports the one of `math` as
+ * `ntheory`. The integers are bigints, or numbers that are safe integers; the integer results are bigints, of any size
+ * up to 2^20 bits (about 315000 digits).
+ *
+ * When a result does not exist (`modInverse()` of a number with no inverse, `primitiveRoot()` of a number with none,
+ * `crt()` of congruences with no common solution), it is `undefined`. An argument outside the domain of a function
+ * (`totient(0)`, `legendre(a, 9)`, `factorial(-1)`) throws `MathDomainException`, a modulus of 0
+ * `MathDivisionByZeroException`. The results modulo `m` have the sign of `m`, as `mod()`.
+ *
+ * Testing primality is deterministic below 2^64. Above, it is the Baillie-PSW test, which no known composite number
+ * passes. Factorization uses trial division, then Pollard's p - 1 and rho methods: quick up to about 20 digits, or when
+ * all the prime factors but one are small. A number with two large prime factors (two primes of 25 digits) can take
+ * days: factor it with `factorAsync()` and a time limit.
+ * @example
+ * ```typescript
+ * import {math} from '@lakutata/math'
+ *
+ * math.ntheory.factor(360)                  //[{prime: 2n, exponent: 3}, {prime: 3n, exponent: 2}, {prime: 5n, exponent: 1}]
+ * math.ntheory.isPrime(2n ** 127n - 1n)     //true
+ * math.ntheory.powMod(4, 13, 497)           //445n
+ * math.ntheory.crt([2, 3, 2], [3, 5, 7])    //{remainder: 23n, modulus: 105n}
+ * math.ntheory.bernoulli(12).toString()     //'-691/2730'
+ * ```
+ */
+export declare class NumberTheory {
+    #private;
+    protected readonly context: Context;
+    constructor(context: Context);
+    /**
+     * The greatest common divisor of integers, 0 or positive: `gcd(12, -18, 30)` is 6n, `gcd()` is 0n.
+     * @param values The integers.
+     */
+    gcd(...values: IntegerValue[]): bigint;
+    /**
+     * The least common multiple of integers, 0 or positive: `lcm(4, 6, -10)` is 60n, `lcm()` is 1n.
+     * @param values The integers.
+     */
+    lcm(...values: IntegerValue[]): bigint;
+    /**
+     * The greatest common divisor of two integers and the coefficients `x`, `y` of `a*x + b*y = gcd`, the ones of the
+     * extended Euclidean algorithm (as SymPy's `igcdex`): `extendedGcd(240, 46)` is `{gcd: 2n, x: -9n, y: 47n}`.
+     * @param a The first integer.
+     * @param b The second integer.
+     */
+    extendedGcd(a: IntegerValue, b: IntegerValue): ExtendedGcd;
+    /**
+     * The remainder of `a` divided by `m`, of the sign of `m`: `mod(-7, 3)` is 2n, `mod(7, -3)` is -2n (JavaScript's
+     * `%` keeps the sign of `a`).
+     * @param a The dividend.
+     * @param m The modulus, not 0.
+     */
+    mod(a: IntegerValue, m: IntegerValue): bigint;
+    /**
+     * The inverse of `a` modulo `m`: the `x` of `a*x = 1` modulo `m`, `undefined` when `a` and `m` have a common
+     * factor. `modInverse(3, 7)` is 5n.
+     * @param a The integer.
+     * @param m The modulus, not 0.
+     */
+    modInverse(a: IntegerValue, m: IntegerValue): bigint | undefined;
+    /**
+     * `base^exponent` modulo `m`, without computing the power: `powMod(4, 13, 497)` is 445n. A negative exponent is
+     * a power of the inverse of `base`; when it has none, `MathDomainException` is thrown.
+     * @param base The base.
+     * @param exponent The exponent.
+     * @param m The modulus, not 0.
+     */
+    powMod(base: IntegerValue, exponent: IntegerValue, m: IntegerValue): bigint;
+    /**
+     * Whether an integer is a prime: deterministic below 2^64, by the Baillie-PSW test above.
+     * @param n The integer.
+     */
+    isPrime(n: IntegerValue): boolean;
+    /**
+     * `isPrime()` in the threads of the addon, for integers of thousands of digits.
+     * @param n The integer.
+     * @param options Its cancellation, its time limit.
+     */
+    isPrimeAsync(n: IntegerValue, options?: AsyncOptions): Promise<boolean>;
+    /**
+     * The smallest prime larger than `n`: `nextPrime(1000000)` is 1000003n.
+     * @param n The integer.
+     */
+    nextPrime(n: IntegerValue): bigint;
+    /**
+     * `nextPrime()` in the threads of the addon.
+     * @param n The integer.
+     * @param options Its cancellation, its time limit.
+     */
+    nextPrimeAsync(n: IntegerValue, options?: AsyncOptions): Promise<bigint>;
+    /**
+     * The prime factors of an integer and their exponents, from the smallest prime: -1 first for a negative integer
+     * (`factor(-12)` is -1, 2^2, 3), none for 1, `-1` alone for -1; 0 throws `MathDomainException`. A number with two large prime
+     * factors can take very long: use `factorAsync()` with a time limit.
+     * @param n The integer.
+     */
+    factor(n: IntegerValue): PrimeFactor[];
+    /**
+     * `factor()` in the threads of the addon: stopped by the time limit or the cancellation.
+     * @param n The integer.
+     * @param options Its cancellation, its time limit.
+     */
+    factorAsync(n: IntegerValue, options?: AsyncOptions): Promise<PrimeFactor[]>;
+    /**
+     * Euler's totient: the count of the integers from 1 to `n` coprime with `n`, for `n >= 1` (it factors `n`).
+     * @param n The integer.
+     */
+    totient(n: IntegerValue): bigint;
+    /**
+     * `totient()` in the threads of the addon.
+     * @param n The integer.
+     * @param options Its cancellation, its time limit.
+     */
+    totientAsync(n: IntegerValue, options?: AsyncOptions): Promise<bigint>;
+    /**
+     * The Möbius function, for `n >= 1`: 0 when a square divides `n`, else 1 or -1 for an even or odd count of prime
+     * factors (it factors `n`).
+     * @param n The integer.
+     */
+    mobius(n: IntegerValue): -1 | 0 | 1;
+    /**
+     * `mobius()` in the threads of the addon.
+     * @param n The integer.
+     * @param options Its cancellation, its time limit.
+     */
+    mobiusAsync(n: IntegerValue, options?: AsyncOptions): Promise<-1 | 0 | 1>;
+    /**
+     * The smallest primitive root modulo `n`, for `n >= 2`: a number whose powers give every integer coprime with `n`.
+     * `undefined` when there is none (only 2, 4, the powers of an odd prime and their doubles have one).
+     * `primitiveRoot(23)` is 5n.
+     * @param n The modulus.
+     */
+    primitiveRoot(n: IntegerValue): bigint | undefined;
+    /**
+     * `primitiveRoot()` in the threads of the addon.
+     * @param n The modulus.
+     * @param options Its cancellation, its time limit.
+     */
+    primitiveRootAsync(n: IntegerValue, options?: AsyncOptions): Promise<bigint | undefined>;
+    /**
+     * The Legendre symbol `(a/p)`, for an odd prime `p`: 0 when `p` divides `a`, 1 when `a` is a square modulo `p`,
+     * -1 otherwise.
+     * @param a The integer.
+     * @param p The odd prime.
+     */
+    legendre(a: IntegerValue, p: IntegerValue): -1 | 0 | 1;
+    /**
+     * The Jacobi symbol `(a/n)`, for an odd positive `n`: the product of the Legendre symbols of `a` and the prime
+     * factors of `n`.
+     * @param a The integer.
+     * @param n The odd positive integer.
+     */
+    jacobi(a: IntegerValue, n: IntegerValue): -1 | 0 | 1;
+    /**
+     * The common solutions of the congruences `x = remainders[i]` modulo `moduli[i]` (the Chinese remainder theorem):
+     * the moduli need not be coprime. `undefined` when there is none. `crt([2, 3, 2], [3, 5, 7])` is
+     * `{remainder: 23n, modulus: 105n}`.
+     * @param remainders The remainders.
+     * @param moduli The moduli, as many as the remainders, none of them 0.
+     */
+    crt(remainders: IntegerValue[], moduli: IntegerValue[]): Congruence | undefined;
+    /**
+     * The Fibonacci number `F(n)`: F(0) = 0, F(1) = 1, F(n) = F(n - 1) + F(n - 2); for a negative `n`,
+     * F(-n) = (-1)^(n + 1) F(n).
+     * @param n The index.
+     */
+    fibonacci(n: IntegerValue): bigint;
+    /**
+     * The Lucas number `L(n)`: L(0) = 2, L(1) = 1, L(n) = L(n - 1) + L(n - 2); for a negative `n`,
+     * L(-n) = (-1)^n L(n).
+     * @param n The index.
+     */
+    lucas(n: IntegerValue): bigint;
+    /**
+     * The binomial coefficient `C(n, k)`: 0 for a negative `k`, or `k > n >= 0`; for a negative `n`,
+     * `(-1)^k C(k - n - 1, k)` (as SymPy). `n` may be large: `binomial(10n ** 100n, 2)` is computed.
+     * @param n The integer.
+     * @param k The count.
+     */
+    binomial(n: IntegerValue, k: IntegerValue): bigint;
+    /**
+     * The number of arrangements of k of n items, `n! / (n - k)!`; without `k`, of all of them, `n!`. 0 for `k > n`
+     * (mathjs throws).
+     * @param n The number of items, 0 or more.
+     * @param k The number arranged, 0 or more: `n` by default.
+     */
+    permutations(n: IntegerValue, k?: IntegerValue): bigint;
+    /**
+     * The number of combinations with repetition of k items of n kinds (the multisets of k items of n kinds),
+     * `C(n + k - 1, k)`: 1 for `n = k = 0`.
+     * @param n The number of kinds, 0 or more.
+     * @param k The number chosen, 0 or more.
+     */
+    combinationsWithRepetition(n: IntegerValue, k: IntegerValue): bigint;
+    /**
+     * The multinomial coefficient `(k1 + k2 + …)! / (k1! k2! …)`: the ways to split items into groups of these sizes
+     * (a count may be 0; of no counts, 1).
+     * @param counts The sizes of the groups, 0 or more.
+     */
+    multinomial(counts: IntegerValue[]): bigint;
+    /**
+     * The Bell number `B(n)`: the number of partitions of a set of n items, for `n` from 0 to 2000.
+     * @param n The number of items.
+     */
+    bell(n: IntegerValue): bigint;
+    /**
+     * The Catalan number `C(2n, n) / (n + 1)`, for `n >= 0`.
+     * @param n The index.
+     */
+    catalan(n: IntegerValue): bigint;
+    /**
+     * The Stirling number of the second kind `S(n, k)`: the number of partitions of a set of n items into k nonempty
+     * blocks (0 for `k > n`; mathjs's `stirlingS2`), for `n` up to 50000 and `n k` up to 6250000.
+     * @param n The number of items, 0 or more.
+     * @param k The number of blocks, 0 or more.
+     */
+    stirlingSecondKind(n: IntegerValue, k: IntegerValue): bigint;
+    /**
+     * The number of compositions of n into k parts: the ways to write n as an ordered sum of k positive integers,
+     * `C(n - 1, k - 1)` (mathjs's `composition`); 1 for `n = k = 0`, 0 for `k > n`.
+     * @param n The integer, 0 or more.
+     * @param k The number of parts, 0 or more.
+     */
+    compositions(n: IntegerValue, k: IntegerValue): bigint;
+    /**
+     * The factorial `n!`, for `n >= 0`, up to about 71000 (a result of 2^20 bits). A formula's `factorial(n)` (or
+     * `n!`) stays `gamma(n + 1)` above 20000, so that an expression holding it stays printable; this one is computed.
+     * @param n The integer.
+     */
+    factorial(n: IntegerValue): bigint;
+    /**
+     * The double factorial `n!! = n (n - 2) (n - 4)…`, down to 1 or 2, for `n >= -1` (`0!!` and `(-1)!!` are 1).
+     * @param n The integer.
+     */
+    doubleFactorial(n: IntegerValue): bigint;
+    /**
+     * The Bernoulli number `B(n)`, an exact fraction, for `n` from 0 to 2000. `B(1)` is +1/2, as SymPy (some books,
+     * and mathjs, give -1/2).
+     * @param n The index.
+     */
+    bernoulli(n: IntegerValue): Expression;
+    /**
+     * The harmonic number `H(n) = 1 + 1/2 + … + 1/n`, an exact fraction, for `n` from 0 to 50000.
+     * @param n The index.
+     */
+    harmonic(n: IntegerValue): Expression;
+    /**
+     * The continued fraction of a real number, `a0 + 1/(a1 + 1/(a2 + …))`: its terms, `a0` an integer, the others
+     * positive. Of a rational number (a number of JavaScript is the decimal it prints as: `0.1` is 1/10), all its
+     * terms, by Euclid's algorithm, the last one above 1 (as SymPy); of another value (`sqrt(2)`, `pi`), its first
+     * terms, as many as `terms` asks (20 by default), each one certain: computed from decimals of the value, with more
+     * digits until they settle each term. A remainder that cannot be told from 0, or a value that cannot be told from
+     * an integer, even with thousands of digits, ends the continued fraction there.
+     * @param value The number: a number, a bigint, a decimal, an expression without variables or a formula.
+     * @param options The largest number of terms.
+     * @example
+     * ```typescript
+     * import {ntheory} from '@lakutata/math'
+     *
+     * console.log(ntheory.continuedFraction('415/93'))                    //[4n, 2n, 6n, 7n]
+     * console.log(ntheory.continuedFraction('sqrt(2)', {terms: 5}))       //[1n, 2n, 2n, 2n, 2n]
+     * console.log(ntheory.continuedFraction('pi', {terms: 6}))            //[3n, 7n, 15n, 1n, 292n, 1n]
+     * ```
+     */
+    continuedFraction(value: Value, options?: ContinuedFractionOptions): bigint[];
+    /**
+     * `continuedFraction()` in the threads of the addon (its decimals).
+     * @param value The number: a number, a bigint, a decimal, an expression without variables or a formula.
+     * @param options The largest number of terms, the cancellation, the time limit.
+     */
+    continuedFractionAsync(value: Value, options?: ContinuedFractionOptions & AsyncOptions): Promise<bigint[]>;
+    /**
+     * The value of a continued fraction, `a0 + 1/(a1 + 1/(a2 + …))`, an exact fraction. Its terms may be any integers;
+     * where they make a division by zero, it throws `MathDivisionByZeroException`.
+     * @param terms The terms, from `a0`.
+     * @example
+     * ```typescript
+     * import {ntheory} from '@lakutata/math'
+     *
+     * console.log(ntheory.fromContinuedFraction([4, 2, 6, 7]).toString())   //415/93
+     * ```
+     */
+    fromContinuedFraction(terms: readonly IntegerValue[]): Expression;
+    /**
+     * The convergents of a continued fraction: the values of its first terms, `a0`, `a0 + 1/a1`, …, exact fractions;
+     * they are the best rational approximations of its value (no fraction of a smaller denominator is closer).
+     * @param terms The terms, from `a0`.
+     * @example
+     * ```typescript
+     * import {ntheory} from '@lakutata/math'
+     *
+     * console.log(ntheory.convergents([3, 7, 15, 1]).map(String))           //['3', '22/7', '333/106', '355/113']
+     * ```
+     */
+    convergents(terms: readonly IntegerValue[]): Expression[];
+}