TODO.md

MathFlow | TODO

A list of features for mathflow - based on numpy, mathjs and more.

Scope

Every mathflow value is a plain number. A function is in scope when it takes numbers and returns a single number; anything list-shaped is exposed as a variadic builtin, so a data set is written mean(1, 2, 3) rather than mean([1, 2, 3]).

Predicates return 1 or 0, since there is no boolean type.

See Not planned for what this rules out, and why.

1. Numbers

• add(a, b, ...): Adds all numbers.
• sub(a, b): Subtracts the second number from the first.
• mul(a, b, ...): Multiplies all numbers.
• div(a, b): Divides the first number by the second.
• mod(a, b): Returns the remainder of division of two numbers.
• abs(x): Returns the absolute value of a number.
• ceil(x): Rounds a number up to the nearest integer.
• floor(x): Rounds a number down to the nearest integer.
• sign(x): Returns the sign of a number: -1, 0, or 1.
• sqrt(x): Returns the square root of a number.
• pow(x, y): Raises x to the power of y.
• cbrt(x): Computes the cube root of a number.
• root(x, n): Computes the n-th root of a number.
• trunc(x): Removes the fractional part of a number.
• round(x, n?): Rounds to the nearest integer or to n decimal places.
• roundToNearest(x, step): Rounds x to the nearest multiple of step.
• precision(x, n): Adjusts a number to n significant digits.
• clamp(x, min, max): Clamps a value between a minimum and maximum.
• gcd(a, b, ...): Greatest common divisor of all numbers.
• lcm(a, b, ...): Least common multiple of all numbers.
• modExp(base, exponent, modulus): Modular exponentiation.
• lerp(a, b, t): Linear interpolation between a and b.
• hermite(p0, m0, p1, m1, t): Cubic Hermite interpolation.

2. Statistics

All variadic - mean(1, 2, 3), not mean([1, 2, 3]).

• sum(...x): Sum of all values.
• prod(...x): Product of all values.
• min(...x): Smallest value.
• max(...x): Largest value.
• mean(...x): Arithmetic mean.
• median(...x): Median value.
• mode(...x): Most frequent value, the smallest of them on a tie.
• quantile(p, ...x): Quantile at probability p, interpolated.
• variance(...x): Sample variance, the n - 1 normalization.
• std(...x): Sample standard deviation.
• mad(...x): Mean absolute deviation.
• entropy(...x): Shannon entropy in nats, over the given distribution.
• geometricMean(...x): Geometric mean.
• harmonicMean(...x): Harmonic mean.
• skewness(...x): Skewness, indicating asymmetry.
• kurtosis(...x): Excess kurtosis - 0 for a normal distribution.

3. Probability and Combinatorics

• factorial(n): Factorial of n.
• combinations(n, k): Ways to choose k items from n.
• permutations(n, k): Ways to arrange k items out of n.
• stirlingApproximation(n): Approximates n! by Stirling's formula.
• isPrime(n): 1 if n is prime, else 0.
• fibonacci(n): The n-th Fibonacci number.
• birthdayProblem(n, days?): Chance two of n share one of days days.
• random(min?, max?): Random number - unit, [0, min), or [min, max).
• randomInt(min?, max?): As random, truncated to an integer.
• pickRandom(...x): Randomly selects one of the given values.

4. Trigonometry

• deg(x): Converts the angle from radians to degrees.
• rad(x): Converts the angle from degrees to radians.
• sin(x), cos(x), tan(x): In the context's angle unit.
• sind(x), cosd(x), tand(x): Always in degrees.
• sec(x), csc(x), cot(x): Reciprocal functions.
• asin(x), acos(x), atan(x): Take a ratio, return an angle.
• atan2(y, x): Angle from the x-axis to the point (x, y).
• sinh(x), cosh(x), tanh(x): Hyperbolic, on plain reals.
• asinh(x), acosh(x), atanh(x): Inverse hyperbolic, on plain reals.
• hypot(a, b, ...): Euclidean norm.
• versin(x), coversin(x): Versine and coversine.
• versind(x), coversind(x): The same, always in degrees.

5. Exponential and Logarithmic

• exp(x): Computes e raised to the power of x.
• expm1(x): e^x - 1, accurate for small x.
• ln(x): Natural logarithm.
• log(x, base?): Logarithm of x, base 10 by default.
• log10(x), log2(x): Base-10 and base-2 logarithms.
• log1p(x): log(1 + x), accurate for small x.
• pow10(x), pow2(x): Powers of 10 and 2.

6. Special Functions

• gamma(x): Gamma function, an extension of the factorial.
• lngamma(x): Natural log of the gamma function.
• digamma(x): Logarithmic derivative of the gamma function.
• beta(a, b): Beta function.
• gammaIncomplete(a, x): Lower incomplete gamma, unregularized.
• erf(x), erfc(x): Error function and its complement.
• zeta(s): Riemann zeta function.
• lambertW(x): Lambert W function, principal branch.
• sinc(x): Unnormalized sin(x)/x, always in radians.
• heaviside(x): Step function, 0.5 at the origin.

7. Number Theory

• totient(n): Euler's totient function.
• mobius(n): Mobius function.
• isPerfectSquare(n): 1 if n is a perfect square, else 0.

8. Financial Math

• futureValue(principal, rate, periods): Future value of an investment.
• presentValue(future, rate, periods): Present value of a future sum.
• compoundInterest(principal, rate, times, periods): Accrued amount.
• annuityPayment(rate, periods, present): Level payment of an annuity.

Not planned

Ruled out to keep every value a plain number and the library small.

Needs an array value type - matrices and vectors (matrix, det, inv, transpose, dot, cross, reshape, norm, ...), signal processing (fft, dft, convolve, correlate), and vector geometry (projection, angleBetween, reflect, intersect).

Returns a list rather than a number - shuffle, primeFactors, divisors, range, lagrange, spline.

Needs two independent lists - covariance, corr, weightedMean. These cannot be written variadically.

Needs a different numeric type - complex and everything on it (re, im, arg, conj, ...), plus bignumber and fraction.

Symbolic, not numeric - simplify, expand, derivative, integrate, rationalize, and solving an equation for a variable. These need a computer algebra system, which is a different project from an evaluator.

Takes a function as a value - numericDerivative. There is no function type.

Already covered - one name per behaviour, so nothing is implemented twice: fix is trunc, sigFigs is precision, rand/randi are random/randomInt, and binomialCoefficient is combinations. parse and evaluate(expr, scope?) are the public parse and solve APIs.