@khanacademy/kmath

Javascript Numeric Math Utilities

Overview

kmath is a collection of Javascript utility functions for performing numeric (rather than algebraic) math that isn't built into Javascript, especially geometric calculations.

For example, some computations are easy to express using vectors, but difficult to express in terms of raw real number variables. kmath lets you write vector-, point-, line-, or ray-based math naturally, and also has some real number utility methods that might be useful if you're writing a math-heavy Javascript application.

kmath emphasizes simplicity and interoperability in the interfaces provided. All kmath interfaces use standard Javascript types, usually numbers, arrays of numbers, or arrays of arrays of numbers. This means interoping with other systems (other libraries, or sending kmath types over json) is easy, but kmath doesn't have it's own object-oriented types, which may be inconvenient (for example, in debugging, you'll just see Arrays rather than, for example, Vectors).

kmath also focuses on being a high quality library of a few functions, rather than a large library of many functions which are less unified.

kmath emphasizes simplicity in design over performance, when those two are at odds. If you are writing code in an inner loop in an allocation- sensitive environment, kmath might not be for you. Each method is pure and allocates a new array for the return value.

Getting started

After cloning or downloading kmath, you can install it by running yarn or make install.

To play around with the available interfaces, you can load kmath into a Node repl:

import {vector} from "@khanacademy/kmath";
vector.add([1, 2], [3, 4]) // [4, 6]

Usage overview

kmath has 5 basic types:

• number
• vector
• point
• ray
• line

Each has its own representation:

• number: a js number (i.e. 5)
• vector: a js array of numbers (i.e. [5, 6])
• point: a js array of numbers (i.e. [5, 6])
• ray: a js array of two points (i.e. [[5, 6], [1, 2]])
• line: a js array of two points (i.e. [[5, 6], [1, 2]])

kmath functions usually take an argument of the corresponding type as the first parameter, and other parameters afterwards. For example, to rotate the point [1, 1] by 90 degrees around [0, 0], one might use:

point.rotateDeg([1, 1], 90, [0, 0])

Documentation for specific functions for each type is provided below.

number

number.DEFAULT_TOLERANCE === 1e-9

The default tolerance to kmath functions.

number.EPSILON === Math.pow(2, -42)

A small number. Not machine epsilon, but a reasonable amount of error more than generally accrued by doing repeated floating point math.

number.is(maybeANumber)

Returns true if the argument is a javascript number.

number.equal(number1, number2, [tolerance])

Compares whether number1 and number2 are equal to each other, within a difference of tolerance, which defaults to number.DEFAULT_TOLERANCE.

number.sign(aNumber, [tolerance])

Returns 0 if the number is equal to 0 within tolerance, or -1 if the number is less than 0, or 1 if the number is greater than 0.

number.isInteger(aNumber, tolerance)

Returns true if aNumber is within tolerance difference of an integer. tolerance defaults to number.DEFAULT_TOLERANCE.

number.round(aNumber, precision)

Rounds aNumber to precision decimal places.

number.roundTo(aNumber, increment)

Rounds aNumber to the nearest increment.

For example, number.roundTo(1.4, 0.5) would return 1.5

number.floorTo(aNumber, increment)

Returns the nearest multiple of increment that is no greater than aNumber.

number.ceilTo(aNumber, increment)

Returns the nearest multiple of increment that is no smaller than aNumber.

number.toFraction(decimal, [tolerance], [maxDenominator])

Returns an array containing two elements, [n, d], a numerator and denominator representing a fraction n/d that is within tolerance of decimal.

If no fraction with a denominator less than or equal to maxDenominator is found, [decimal, 1] is returned.

tolerance defaults to number.EPSILON. maxDenominator defaults to 1000.

vector

vector.is(maybeAVector, [dimension])

Returns true if maybeAVector is an array of numbers. If dimension is specified, only returns true if maybeAVector is a vector with dimension dimension.

vector.equal(v1, v2, [tolerance])

Returns true if v1 and v2 are equal within tolerance. If tolerance is not specified, number.DEFAULT_TOLERANCE is used. Each dimension is compared individually, rather than comparing length and direction.

If v1 and v2 have different lengths, this function returns false.

vector.equal([1, 2], [1, 3])
=> false
vector.equal([1, 2], [1, 2, 3])
=> false
vector.equal([1, 2], [1, 2])
=> true

vector.codirectional(v1, v2, [tolerance])

Returns true if v1 and v2 have the same direction within tolerance. If tolerance is unspecified, number.DEFAULT_TOLERANCE is used. Note that tolerance is checked after normalization.

If v1 and v2 are different lengths, this function returns false, regardless of whether they are codirectional in the existing dimensions.

This function defines the zero-vector as trivially codirectional with every vector.

vector.codirectional([1, 2], [2, 4])
=> true
vector.codirectinoal([1, 2], [0, 0])
=> true
vector.codirectional([1, 2], [1, 2, 0])
=> false
vector.codirectional([1, 2], [-2, -4])
=> false

vector.colinear(v1, v2, [tolerance])

Returns true if v1 and v2 lie along the same line, regardless of direction. This is equivalent to either v1 and v2 being codirectional, or v1 and -v2 being codirectional, or whether there is some scaleFactor such that vector.equal(vector.scale(v1, scaleFactor), v2) is true.

kmath.vector.colinear([1, 2], [-2, -4])
=> true

vector.normalize(v)

Scales the cartesian vector v to be 1 unit long.

vector.length(v)

Returns the length of the cartesian vector v.

vector.dot(v1, v2)

Returns the dot product of cartesian vectors v1 and v2.

vector.add(*vectors)

Adds multiple cartesian vectors together.

kmath.vector.add([1, 2], [3, 4])
=> [4, 6]

vector.subtract(v1, v2)

Subtracts the cartesian vector v2 from the cartesian vector v1.

kmath.vector.subtract([4, 6], [1, 2])
=> [3, 4]

vector.negate(v)

Negates the cartesian vector v. This has the same effect as scaling v by -1 or reversing the direction of v.

vector.scale(v, scalar)

Scales the cartesian vector v by scalar.

kmath.vector.scale([1, 2], 2)
=> [2, 4]

vector.polarRadFromCart(v)

Returns a polar vector [length, angle] from the two-dimensional cartesian vector v, where angle is measured in radians.

kmath.vector.polarRadFromCart([1, 1])
=> [1.4142135623730951, 0.7853981633974483]

vector.polarDegFromCart(v)

Returns a polar vector [length, angle] from the two-dimensional cartesian vector v, where angle is measured in degrees.

kmath.vector.polarDegFromCart([0, 2])
=> [2, 90]

vector.cartFromPolarRad(polar) or vector.cartFromPolarRad(length, angle)

Returns a two-dimensional cartesian vector from the polar vector input, where the input angle is measured in radians.

kmath.vector.cartFromPolarRad([2, Math.PI])
=> [-2, 0]  // Note: a very small nonzero number is actually returned here,
            // due to numerical inaccuracy.
kmath.vector.cartFromPolarRad(Math.pow(2, 0.5), Math.PI/4)
=> [1, 1]

vector.cartFromPolarDeg(polar) or vector.cartFromPolarDeg(length, angle)

Returns a two-dimensional cartesian vector from the polar vector input, where the input angle is measured in degrees.

kmath.vector.cartFromPolarRad([2, 90])
=> [-2, 0]  // Note: a very small nonzero number is actually returned here,
            // due to numerical inaccuracy.
kmath.vector.cartFromPolarRad(Math.pow(2, 0.5), 45)
=> [1, 1]

vector.rotateRad(v, angle)

Returns the rotation of the cartesian vector v by angle radians.

vector.rotateDeg(v, angle)

Returns the rotation of the cartesian vector v by angle degrees.

vector.angleRad(v1, v2)

Returns the angle between the directions of cartesian vectors v1 and v2 in radians.

vector.angleDeg(v1, v2)

Returns the angle between the directions of cartesian vectors v1 and v2 in radians.

vector.projection(v1, v2)

Returns the projection of v1 along the direction of v2

vector.round(v, precision)

Rounds each dimension of v to precision decimal places.

vector.roundTo(v, increment)

Rounds each dimension of v to the nearest increment.

vector.floorTo(v, increment)

Floors each dimension of v to the nearest increment.

vector.ceilTo(v, increment)

Ceils each dimension of v to the nearest increment.

kmath.point

point.is(maybeAPoint, [length])

Returns true if maybeAPoint is an array of numbers. If length is specified, only returns true if maybeAPoint is a point of dimension length.

point.equal(p1, p2, [tolerance])

Returns true if p1 and p2 are equal within tolerance. If tolerance is not specified, kmath.number.DEFAULT_TOLERANCE is used. Each dimension is compared individually.

If p1 and p2 have different lengths, this function returns false.

kmath.point.equal([1, 2], [1, 3])
=> false
kmath.point.equal([1, 2], [1, 2, 3])
=> false
kmath.point.equal([1, 2], [1, 2])
=> true

point.addVector(p, *vectors) or point.addVectors(p, *vectors)

Returns the point created by adding the cartesian vectors *vectors to the cartesian point p.

point.subtractVector(p, v)

Returns the point created by subtracting the cartesian vectors v to the cartesian point p.

point.distanceToPoint(p1, p2)

Returns the distance between p1 and p2.

point.distanceToLine(p, theLine)

Returns the distance between p and the line theLine.

For example, to find the distance from the origin to the y = 5 line, one could write:

kmath.point.distanceToLine([0, 0], [[-1, 5], [1, 5]])
=> 5

point.reflectOverLine(p, theLine)

Returns the reflection of p over the line theLine.

For example, to reflect the origin over the line y = 5, one could write:

kmath.point.reflectOverLine([0, 0], [[-1, 5], [1, 5]])
=> [0, 10]

point.compare(p1, p2, [equalityTolerance])

Compares two points, returning -1, 0, or 1, for use with Array.prototype.sort

Note: This technically doesn't satisfy the total-ordering requirements of Array.prototype.sort unless equalityTolerance is 0. In some cases very close points that compare within a few equalityTolerances could appear in the wrong order.

point.polarRadFromCart(p)

Returns a polar point [length, angle] from the two-dimensional cartesian point v, where angle is measured in radians.

kmath.point.polarRadFromCart([1, 1])
=> [1.4142135623730951, 0.7853981633974483]

point.polarDegFromCart(p)

Returns a polar point [length, angle] from the two-dimensional cartesian point v, where angle is measured in degrees.

kmath.point.polarDegFromCart([0, 2])
=> [2, 90]

point.cartFromPolarRad(polar) or point.cartFromPolarRad(length, angle)

Returns a two-dimensional cartesian point from the polar point input, where the input angle is measured in radians.

kmath.point.cartFromPolarRad(2, Math.PI)
=> [-2, 0]  // Note: a very small nonzero number is actually returned here,
            // due to numerical inaccuracy.
kmath.point.cartFromPolarRad(Math.pow(2, 0.5), Math.PI/4)
=> [1, 1]

point.cartFromPolarDeg(polar) or point.cartFromPolarDeg(length, angle)

Returns a two-dimensional cartesian point from the polar point input, where the input angle is measured in degrees.

kmath.point.cartFromPolarRad([2, 90])
=> [-2, 0]  // Note: a very small nonzero number is actually returned here,
            // due to numerical inaccuracy.
kmath.point.cartFromPolarRad(Math.pow(2, 0.5), 45)
=> [1, 1]

point.rotateRad(p, angle, center)

Returns the rotation of the two-dimensional point v by angle radians around the point center

point.rotateDeg(p, angle, center)

Returns the rotation of the two-dimensional point v by angle degrees around the point center.

point.round(p, precision)

Rounds each dimension of p to precision decimal places.

point.roundTo(p, increment)

Rounds each dimension of p to the nearest increment.

point.floorTo(p, increment)

Floors each dimension of p to the nearest increment.

point.ceilTo(p, increment)

Ceils each dimension of p to the nearest increment.

kmath.ray

ray.equal(r1, r2, [tolerance])

Returns true if rays r1 and r2 are equal within tolerance.

If unspecified, tolerance defaults to kmath.number.DEFAULT_TOLERANCE.

kmath.line

line.equal(line1, line2, [tolerance])

Returns true if lines line1 and line2 are equal within tolerance.

If unspecified, tolerance defaults to kmath.number.DEFAULT_TOLERANCE.

line.midpoint(theLine)

Returns the midpoint of the line theLine.

kmath.line.midpoint([[0, 5], [5, 0]])
=> [2.5, 2.5]

line.distanceToPoint(theLine, p)

Returns the distance between theLine and point p.

line.reflectPoint(theLine, p)

Returns the reflection of p over theLine.

License

MIT. See the LICENSE file for more information.