smath 1.16.0 → 2.1.0

package/types/index.d.ts

@@ -5,308 +5,5 @@
  * ![NPM Downloads](https://img.shields.io/npm/d18m/smath)
  * ![NPM Last Update](https://img.shields.io/npm/last-update/smath)
  */
-/**
- * Check if two numbers are approximately equal with a maximum abolute error.
- * @param a Any number
- * @param b Any number
- * @param epsilon Maximum absolute error
- * @returns True if `a` is approximately `b`
- * @example
- * const b1 = SMath.approx(1 / 3, 0.33, 1e-6), // false
- *       b2 = SMath.approx(1 / 3, 0.33, 1e-2); // true
- */
-export declare function approx(a: number, b: number, epsilon?: number): boolean;
-/**
- * Clamp a number within a range.
- * @param n The number to clamp
- * @param min The minimum value of the range
- * @param max The maximum value of the range
- * @returns A clamped number
- * @example
- * const n1 = SMath.clamp(5, 0, 10),  // 5
- *       n2 = SMath.clamp(-2, 0, 10); // 0
- */
-export declare function clamp(n: number, min: number, max: number): number;
-/**
- * Normalize the number `n` from the range `min, max` to the range `0, 1`
- * @param n The number to normalize
- * @param min The minimum value in the range
- * @param max The maximum value in the range
- * @returns A normalized value
- * @example
- * const y = SMath.normalize(18, 9, 99); // 0.1
- */
-export declare function normalize(n: number, min: number, max: number): number;
-/**
- * Expand a normalized number `n` to the range `min, max`
- * @param n A normalized number
- * @param min The minimum value in the range
- * @param max The maximum value in the range
- * @returns A value within the number range
- * @example
- * const y = SMath.expand(0.25, 4, 6); // 4.5
- */
-export declare function expand(n: number, min: number, max: number): number;
-/**
- * Translate a number `n` from the range `min1, max1` to the range `min2, max2`
- * @param n The number to translate
- * @param min1 The minimum value from the initial range
- * @param max1 The maximum value from the initial range
- * @param min2 The minimum value for the final range
- * @param max2 The maximum value for the final range
- * @returns A translated number in the final range
- * @example
- * const C = 20,
- *       F = SMath.translate(C, 0, 100, 32, 212); // 68
- */
-export declare function translate(n: number, min1: number, max1: number, min2: number, max2: number): number;
-/**
- * Generate an array of linearly spaced numbers.
- * @param min The initial value of the linear space
- * @param max The final value of the linear space
- * @param count The number of values in the space
- * @returns The linear space as an array of numbers
- * @example
- * const space = SMath.linspace(1, 5, 6);
- * // [ 1, 1.8, 2.6, 3.4, 4.2, 5 ]
- */
-export declare function linspace(min: number, max: number, count: number): number[];
-/**
- * Generate an array of logarithmically spaced numbers.
- * @param min The initial magnitude of the space
- * @param max The final magnitude of the space
- * @param count The number of values in the space
- * @returns The logarithmic space as an array of numbers
- * @example
- * const space = SMath.logspace(0, 2, 5);
- * // [ 1, 3.2, 10, 31.6, 100 ]
- */
-export declare function logspace(min: number, max: number, count: number): number[];
-/**
- * Compute the factorial of `n`.
- * @param n Any positive integer
- * @returns `n!`
- * @example
- * const y = SMath.factorial(5); // 120
- */
-export declare function factorial(n: number): number;
-/**
- * Factorize `n` into its prime factors.
- * @param n Any positive integer
- * @returns The array of prime factors
- * @example
- * const y = SMath.factors(12); // [ 2, 2, 3 ]
- */
-export declare function factors(n: number): number[];
-/**
- * Round a number to the nearest multiple of an arbitrary
- * base. Does not round when the base is set to zero.
- * @param n Any number to round
- * @param base Any base to round to
- * @returns `n` rounded to the nearest multiple of `base`
- * @example
- * const y = SMath.round2(Math.PI, 0.2); // 3.2
- */
-export declare function round2(n: number, base: number): number;
-/**
- * Calculate the relative normalized error or deviation from any
- * value to an accepted value. An error of 0 indicates that the
- * two values are identical. An error of -0.1 indicates that the
- * experimental value is 10% smaller than (90% of) the accepted
- * value. An error of 1.0 indicates that the experimental value
- * is 100% greater (or twice the size) of the accepted value.
- * @param experimental The value observed or produced by a test
- * @param actual The accepted or theoretical value
- * @returns The relative (normalized) error
- * @example
- * const e = SMath.error(22.5, 25); // -0.1
- */
-export declare function error(experimental: number, actual: number): number;
-/**
- * Add up all the inputs.
- * If none are present, returns 0.
- * @param data An array of numeric inputs
- * @returns The sum total
- * @example
- * const y = SMath.sum([1, 2, 3]); // 6
- */
-export declare function sum(data: number[]): number;
-/**
- * Multiply all the inputs.
- * If none are present, returns 1.
- * @param data An array of numeric inputs
- * @returns The product
- * @example
- * const y = SMath.prod([2, 2, 3, 5]); // 60
- */
-export declare function prod(data: number[]): number;
-/**
- * Compute the average, or mean, of a set of numbers.
- * @param data An array of numeric inputs
- * @returns The average, or mean
- * @example
- * const y = SMath.avg([1, 2, 4, 4]); // 2.75
- */
-export declare function avg(data: number[]): number;
-/**
- * Compute the median of a set of numbers.
- * @param data An array of numeric inputs
- * @returns The median of the dataset
- * @example
- * const y = SMath.median([2, 5, 3, 1]); // 2.5
- */
-export declare function median(data: number[]): number;
-/**
- * Compute the variance of a **complete population**.
- * @param data An array of numeric inputs
- * @returns The population variance
- * @example
- * const y = SMath.varp([1, 2, 4, 4]); // 1.6875
- */
-export declare function varp(data: number[]): number;
-/**
- * Compute the variance of a **sample**.
- * @param data An array of numeric inputs
- * @returns The sample variance
- * @example
- * const y = SMath.vars([1, 2, 4, 4]); // 2.25
- */
-export declare function vars(data: number[]): number;
-/**
- * Compute the standard deviation of a **complete population**.
- * @param data An array of numeric inputs
- * @returns The population standard deviation
- * @example
- * const y = SMath.stdevp([1, 2, 3, 4]); // 1.118...
- */
-export declare function stdevp(data: number[]): number;
-/**
- * Compute the standard deviation of a **sample**.
- * @param data An array of numeric inputs
- * @returns The sample standard deviation
- * @example
- * const y = SMath.stdevs([1, 2, 3, 4]); // 1.29...
- */
-export declare function stdevs(data: number[]): number;
-/**
- * Generate a uniformly-distributed floating-point number within the range.
- * @param min The minimum bound
- * @param max The maximum bound
- * @returns A random float within the range
- * @example
- * const y = SMath.runif(-2, 2); // 0.376...
- */
-export declare function runif(min: number, max: number): number;
-/**
- * Generate a uniformly-distributed integer within the range.
- * @param min The minimum bound (inclusive)
- * @param max The maximum bound (inclusive)
- * @returns A random integer within the range
- * @example
- * const y = SMath.rint(-4, 3); // -4
- */
-export declare function rint(min: number, max: number): number;
-/**
- * Generate a normally-distributed floating-point number.
- * @param mean The mean of the population distribution
- * @param stdev The standard deviation of the population
- * @returns A random float
- * @example
- * const y = SMath.rnorm(2, 3); // 1.627...
- */
-export declare function rnorm(mean?: number, stdev?: number): number;
-/**
- * Generate a population of normally-distributed floating-point numbers.
- * @param count The number of values to generate
- * @param mean The mean of the population distribution
- * @param stdev The standard deviation of the population
- * @returns A population of random floats
- * @example
- * const dataset = SMath.rdist(3); // [ 1.051..., -0.779..., -2.254... ]
- */
-export declare function rdist(count: number, mean?: number, stdev?: number): number[];
-/**
- * Randomize an array of arbitrary elements.
- * @param stack An array of arbitrary elements
- * @returns The `stack` array in a random order
- * @example
- * const shuffled = SMath.shuffle(['a', 'b', 'c']); // [ 'c', 'a', 'b' ]
- */
-export declare function shuffle<T>(stack: T[]): T[];
-/**
- * Select a single item from an array at random with uniform weights.
- * @param stack An array of arbirary item
- * @returns A single randomly selected item
- * @example
- * const selected = SMath.selectRandom([10, 20, 30, 40]); // 30
- */
-export declare function selectRandom<T>(stack: T[]): T;
-/**
- * Select a single index in an array at random with different weights.
- * @param weights The weights for each item
- * @returns The 0-based index of the randomly selected item
- * @example
- * const index = SMath.selectRandomWeighted([3.5, 4, 1]); // 1
- */
-export declare function selectRandomWeighted(weights: number[]): number;
-/**
- * Take the limit of a function. A return value of `NaN` indicates
- * that no limit exists either due to a discontinuity or imaginary value.
- * @param f Function `f(x)`
- * @param x The x-value where to take the limit
- * @param h The approach distance
- * @param discontinuity_cutoff The discontinuity cutoff
- * @returns `lim(f(x->x))`
- * @example
- * const y = SMath.lim(Math.log, 0); // -Infinity
- */
-export declare function lim(f: (x: number) => number, x: number, h?: number, discontinuity_cutoff?: number): number;
-/**
- * Take the derivative of a function.
- * @param f Function `f(x)`
- * @param x The x-value where to evaluate the derivative
- * @param epsilon Small step value
- * @returns `f'(x)`
- * @example
- * const y = SMath.differentiate(x => 3 * x ** 2, 2); // 12
- */
-export declare function differentiate(f: (x: number) => number, x: number, epsilon?: number): number;
-/**
- * Compute the definite integral of a function.
- * @param f Function `f(x)`
- * @param a The miminum integral bound
- * @param b The maximum integral bound
- * @param Ndx The number of rectangles to compute
- * @returns `F(b)-F(a)`
- * @example
- * const y = SMath.integrate(x => 3 * x ** 2, 1, 2); // 7
- */
-export declare function integrate(f: (x: number) => number, a: number, b: number, Ndx?: number): number;
-/**
- * Convert an arbitrary decimal number into a simplified fraction (or ratio).
- * See `mixed()` for instructions on how to break out the whole number part.
- * @param n The decimal number to convert
- * @param epsilon Maximum absolute error
- * @returns An object containing the fraction's numerator and denominator
- * @example
- * const frac = SMath.rat(0.625); // { num: 5, den: 8 }
- */
-export declare function rat(n: number, epsilon?: number): {
-    num: number;
-    den: number;
-};
-/**
- * Convert an arbitrary decimal number into a simplified fraction, after
- * breaking out the whole number part first. See `rat()` for keeping the
- * number as a ratio without separating the whole number part.
- * @param n A decimal number to convert
- * @param epsilon Maximum absolute error
- * @returns An object containing the whole part and fraction numerator and denominator
- * @example
- * const frac = SMath.mixed(-8 / 6); // { whole: -1, num: 1, den: 3 }
- */
-export declare function mixed(n: number, epsilon?: number): {
-    whole: number;
-    num: number;
-    den: number;
-};
+export * as SMath from './smath.js';
+export * as DataFit from './datafit/index.js';

package/types/smath.d.ts

@@ -0,0 +1,311 @@
+/**
+ * Check if two numbers are approximately equal with a maximum abolute error.
+ * @param a Any number
+ * @param b Any number
+ * @param epsilon Maximum absolute error
+ * @returns True if `a` is approximately `b`
+ * @example
+ * const b1 = SMath.approx(1 / 3, 0.33, 1e-6), // false
+ *       b2 = SMath.approx(1 / 3, 0.33, 1e-2); // true
+ */
+export declare function approx(a: number, b: number, epsilon?: number): boolean;
+/**
+ * Clamp a number within a range.
+ * @param n The number to clamp
+ * @param min The minimum value of the range
+ * @param max The maximum value of the range
+ * @returns A clamped number
+ * @example
+ * const n1 = SMath.clamp(5, 0, 10),  // 5
+ *       n2 = SMath.clamp(-2, 0, 10); // 0
+ */
+export declare function clamp(n: number, min: number, max: number): number;
+/**
+ * Normalize the number `n` from the range `min, max` to the range `0, 1`
+ * @param n The number to normalize
+ * @param min The minimum value in the range
+ * @param max The maximum value in the range
+ * @returns A normalized value
+ * @example
+ * const y = SMath.normalize(18, 9, 99); // 0.1
+ */
+export declare function normalize(n: number, min: number, max: number): number;
+/**
+ * Expand a normalized number `n` to the range `min, max`
+ * @param n A normalized number
+ * @param min The minimum value in the range
+ * @param max The maximum value in the range
+ * @returns A value within the number range
+ * @example
+ * const y = SMath.expand(0.25, 4, 6); // 4.5
+ */
+export declare function expand(n: number, min: number, max: number): number;
+/**
+ * Translate a number `n` from the range `min1, max1` to the range `min2, max2`
+ * @param n The number to translate
+ * @param min1 The minimum value from the initial range
+ * @param max1 The maximum value from the initial range
+ * @param min2 The minimum value for the final range
+ * @param max2 The maximum value for the final range
+ * @returns A translated number in the final range
+ * @example
+ * const C = 20,
+ *       F = SMath.translate(C, 0, 100, 32, 212); // 68
+ */
+export declare function translate(n: number, min1: number, max1: number, min2: number, max2: number): number;
+/**
+ * Generate an array of linearly spaced numbers.
+ * @param min The initial value of the linear space
+ * @param max The final value of the linear space
+ * @param count The number of values in the space
+ * @returns The linear space as an array of numbers
+ * @example
+ * const space = SMath.linspace(1, 5, 6);
+ * // [ 1, 1.8, 2.6, 3.4, 4.2, 5 ]
+ */
+export declare function linspace(min: number, max: number, count: number): number[];
+/**
+ * Generate an array of logarithmically spaced numbers.
+ * @param min The initial magnitude of the space
+ * @param max The final magnitude of the space
+ * @param count The number of values in the space
+ * @returns The logarithmic space as an array of numbers
+ * @example
+ * const space = SMath.logspace(0, 2, 5);
+ * // [ 1, 3.2, 10, 31.6, 100 ]
+ */
+export declare function logspace(min: number, max: number, count: number): number[];
+/**
+ * Compute the factorial of `n`.
+ * @param n Any positive integer
+ * @returns `n!`
+ * @example
+ * const y = SMath.factorial(5); // 120
+ */
+export declare function factorial(n: number): number;
+/**
+ * Factorize `n` into its prime factors.
+ * @param n Any positive integer
+ * @returns The array of prime factors
+ * @example
+ * const y = SMath.factors(12); // [ 2, 2, 3 ]
+ */
+export declare function factors(n: number): number[];
+/**
+ * An optimized algorithm to determine if any number is prime.
+ * @param n Any positive integer
+ * @returns `true` if `n` is prime
+ */
+export declare function isPrime(n: number): boolean;
+/**
+ * Round a number to the nearest multiple of an arbitrary
+ * base. Does not round when the base is set to zero.
+ * @param n Any number to round
+ * @param base Any base to round to
+ * @returns `n` rounded to the nearest multiple of `base`
+ * @example
+ * const y = SMath.round2(Math.PI, 0.2); // 3.2
+ */
+export declare function round2(n: number, base: number): number;
+/**
+ * Calculate the relative normalized error or deviation from any
+ * value to an accepted value. An error of 0 indicates that the
+ * two values are identical. An error of -0.1 indicates that the
+ * experimental value is 10% smaller than (90% of) the accepted
+ * value. An error of 1.0 indicates that the experimental value
+ * is 100% greater (or twice the size) of the accepted value.
+ * @param experimental The value observed or produced by a test
+ * @param actual The accepted or theoretical value
+ * @returns The relative (normalized) error
+ * @example
+ * const e = SMath.error(22.5, 25); // -0.1
+ */
+export declare function error(experimental: number, actual: number): number;
+/**
+ * Add up all the inputs.
+ * If none are present, returns 0.
+ * @param data An array of numeric inputs
+ * @returns The sum total
+ * @example
+ * const y = SMath.sum([1, 2, 3]); // 6
+ */
+export declare function sum(data: number[]): number;
+/**
+ * Multiply all the inputs.
+ * If none are present, returns 1.
+ * @param data An array of numeric inputs
+ * @returns The product
+ * @example
+ * const y = SMath.prod([2, 2, 3, 5]); // 60
+ */
+export declare function prod(data: number[]): number;
+/**
+ * Compute the average, or mean, of a set of numbers.
+ * @param data An array of numeric inputs
+ * @returns The average, or mean
+ * @example
+ * const y = SMath.avg([1, 2, 4, 4]); // 2.75
+ */
+export declare function avg(data: number[]): number;
+/**
+ * Compute the median of a set of numbers.
+ * @param data An array of numeric inputs
+ * @returns The median of the dataset
+ * @example
+ * const y = SMath.median([2, 5, 3, 1]); // 2.5
+ */
+export declare function median(data: number[]): number;
+/**
+ * Compute the variance of a **complete population**.
+ * @param data An array of numeric inputs
+ * @returns The population variance
+ * @example
+ * const y = SMath.varp([1, 2, 4, 4]); // 1.6875
+ */
+export declare function varp(data: number[]): number;
+/**
+ * Compute the variance of a **sample**.
+ * @param data An array of numeric inputs
+ * @returns The sample variance
+ * @example
+ * const y = SMath.vars([1, 2, 4, 4]); // 2.25
+ */
+export declare function vars(data: number[]): number;
+/**
+ * Compute the standard deviation of a **complete population**.
+ * @param data An array of numeric inputs
+ * @returns The population standard deviation
+ * @example
+ * const y = SMath.stdevp([1, 2, 3, 4]); // 1.118...
+ */
+export declare function stdevp(data: number[]): number;
+/**
+ * Compute the standard deviation of a **sample**.
+ * @param data An array of numeric inputs
+ * @returns The sample standard deviation
+ * @example
+ * const y = SMath.stdevs([1, 2, 3, 4]); // 1.29...
+ */
+export declare function stdevs(data: number[]): number;
+/**
+ * Generate a uniformly-distributed floating-point number within the range.
+ * @param min The minimum bound
+ * @param max The maximum bound
+ * @returns A random float within the range
+ * @example
+ * const y = SMath.runif(-2, 2); // 0.376...
+ */
+export declare function runif(min: number, max: number): number;
+/**
+ * Generate a uniformly-distributed integer within the range.
+ * @param min The minimum bound (inclusive)
+ * @param max The maximum bound (inclusive)
+ * @returns A random integer within the range
+ * @example
+ * const y = SMath.rint(-4, 3); // -4
+ */
+export declare function rint(min: number, max: number): number;
+/**
+ * Generate a normally-distributed floating-point number.
+ * @param mean The mean of the population distribution
+ * @param stdev The standard deviation of the population
+ * @returns A random float
+ * @example
+ * const y = SMath.rnorm(2, 3); // 1.627...
+ */
+export declare function rnorm(mean?: number, stdev?: number): number;
+/**
+ * Generate a population of normally-distributed floating-point numbers.
+ * @param count The number of values to generate
+ * @param mean The mean of the population distribution
+ * @param stdev The standard deviation of the population
+ * @returns A population of random floats
+ * @example
+ * const dataset = SMath.rdist(3); // [ 1.051..., -0.779..., -2.254... ]
+ */
+export declare function rdist(count: number, mean?: number, stdev?: number): number[];
+/**
+ * Randomize an array of arbitrary elements.
+ * @param stack An array of arbitrary elements
+ * @returns The `stack` array in a random order
+ * @example
+ * const shuffled = SMath.shuffle(['a', 'b', 'c']); // [ 'c', 'a', 'b' ]
+ */
+export declare function shuffle<T>(stack: T[]): T[];
+/**
+ * Select a single item from an array at random with uniform weights.
+ * @param stack An array of arbirary item
+ * @returns A single randomly selected item
+ * @example
+ * const selected = SMath.selectRandom([10, 20, 30, 40]); // 30
+ */
+export declare function selectRandom<T>(stack: T[]): T;
+/**
+ * Select a single index in an array at random with different weights.
+ * @param weights The weights for each item
+ * @returns The 0-based index of the randomly selected item
+ * @example
+ * const index = SMath.selectRandomWeighted([3.5, 4, 1]); // 1
+ */
+export declare function selectRandomWeighted(weights: number[]): number;
+/**
+ * Take the limit of a function. A return value of `NaN` indicates
+ * that no limit exists either due to a discontinuity or imaginary value.
+ * @param f Function `f(x)`
+ * @param x The x-value where to take the limit
+ * @param h The approach distance
+ * @param discontinuity_cutoff The discontinuity cutoff
+ * @returns `lim(f(x->x))`
+ * @example
+ * const y = SMath.lim(Math.log, 0); // -Infinity
+ */
+export declare function lim(f: (x: number) => number, x: number, h?: number, discontinuity_cutoff?: number): number;
+/**
+ * Take the derivative of a function.
+ * @param f Function `f(x)`
+ * @param x The x-value where to evaluate the derivative
+ * @param epsilon Small step value
+ * @returns `f'(x)`
+ * @example
+ * const y = SMath.differentiate(x => 3 * x ** 2, 2); // 12
+ */
+export declare function differentiate(f: (x: number) => number, x: number, epsilon?: number): number;
+/**
+ * Compute the definite integral of a function.
+ * @param f Function `f(x)`
+ * @param a The miminum integral bound
+ * @param b The maximum integral bound
+ * @param Ndx The number of rectangles to compute
+ * @returns `F(b)-F(a)`
+ * @example
+ * const y = SMath.integrate(x => 3 * x ** 2, 1, 2); // 7
+ */
+export declare function integrate(f: (x: number) => number, a: number, b: number, Ndx?: number): number;
+/**
+ * Convert an arbitrary decimal number into a simplified fraction (or ratio).
+ * See `mixed()` for instructions on how to break out the whole number part.
+ * @param n The decimal number to convert
+ * @param epsilon Maximum absolute error
+ * @returns An object containing the fraction's numerator and denominator
+ * @example
+ * const frac = SMath.rat(0.625); // { num: 5, den: 8 }
+ */
+export declare function rat(n: number, epsilon?: number): {
+    num: number;
+    den: number;
+};
+/**
+ * Convert an arbitrary decimal number into a simplified fraction, after
+ * breaking out the whole number part first. See `rat()` for keeping the
+ * number as a ratio without separating the whole number part.
+ * @param n A decimal number to convert
+ * @param epsilon Maximum absolute error
+ * @returns An object containing the whole part and fraction numerator and denominator
+ * @example
+ * const frac = SMath.mixed(-8 / 6); // { whole: -1, num: 1, den: 3 }
+ */
+export declare function mixed(n: number, epsilon?: number): {
+    whole: number;
+    num: number;
+    den: number;
+};