Algebron

Algebron is a math library written in TypeScript. The library provides: implementations of common data structures; APIs for scientific computation, numeric analysis, and statistics; CAS (Computer Algebra System) functions; an API for 2D and 3D graphics processing; and a scripting language called Praxis. This page documents the Algebron library.

Praxis

Praxis is a scripting language built with TypeScript. The language is used in Algebron's library to compile user-defined functions and perform symbolic computation procedures. This section documents Praxis's syntax, grammar, and features.

In the following sections, various REPLs and terminals are provided. For the REPLs: Click to the right of the dollar sign ($:) to begin typing expressions and hit "Enter" to execute your expression. Some of the REPL windows have code preset and entered to serve as examples. To clear a REPL, type and enter clear. Note that the REPLs are strictly for evaluating expressions. To execute a statement (or an entire program), use a terminal: Type your code, and click the run button to execute.

Basic Number Types & Arithmetic

Praxis supports basic arithmetic operations. Praxis's core arithmetic operations are displayed in the REPL below.

We used integers for the examples above, but certain operations are free to take floating point numbers (i.e., "floats"):

Integers and floats are considered primitives in Algebron. The set of primitives also includes fractions. Fractions are written with the syntax ${a|b}$, where ${a}$ and ${b}$ are integers.

Primitive Types

Primitive types in Praxis are expressions that cannot be reduced any further.

Integers

Integers are the most basic type in Praxis. The largest possible integer in Praxis is ${9,007,199,254,740,991}$ or ${2^{53} - 1.}$ Any integer greater than this will be cast to a big integer.

Floating Point Numbers

Floating point numbers in Praxis are represented in the 64-bit format.

Fractions

Fractions in Praxis are implemented as JavaScript objects.

Big Integers

In Praxis, integers larger than ${9,007,199,254,740,991}$ are automatically cast to big integers.

Strings

Strings in Praxis are always double quoted. This syntax is established to distinguish primitive strings from symbolic strings.

"a string";

Symbolic Strings

Any expression surrounded by the apostrophe (') in Praxis is interpreted as a symbolic string. Symbolic strings are Praxis's data type for algebraic expressions. Only symbolic strings in Praxis may be passed to Algebron's CAS modules.

"2x^2 + 3";

Composite Data Types

Composite types in Praxis are data types with an underlying data structure, made up of primitive (or composite) data types. Where primitives are the simplest data types that cannot be reduced further (i.e., atomic), composites are those that can be reduced further.

Vectors

A vector is similar to a list, except its elements can only be integers or floating point numbers, or expressions that reduce to integers or floating point numbers. Vectors are written with square brackets. For example:

let v = [0, 1, 0, 1]

Conditionals

Conditional statements can be executed with the if-else syntax:

let x = 0;
let y = 3;

if ((x = 5)) {
  y = y + 1;
} else if (x < 5) {
  y = y + 2;
} else {
  y = y + 3;
}

Functions

A function in Praxis can be written as follows:

fn f(x) {
  return x^2;
}

Since this function comprises just one line, we can also write:

fn f(x) = x^2;

Loops

Loops can be written in Praxis in two ways. The while-loop:

var i = 0;
var x = 3;
while (i < 5) {
  x = x ^ 2;
  i++;
}

or the for-loop:

var x = 5;
for (var i = 0; i < 5; i++) {
  x = x ^ 2;
}

Algebron Core Library

The following sections document Algebron's core library. These are functions exported directly from Algebron, available for use directly in JavaScript/Typescript.

CAS Modules

Symbolic strings in Algebron are interpreted as algebraic expressions. At runtime, these expressions are represented by the Algebron MathObj class. From there, they can be passed to Algebron's various CAS (Computer Algebra System) modules. The functions below are exported by Algebron publicly.

simplify(u)

Where u is a string or MathObj, simplifies the expression. Below is an example of using simplify directly in TypeScript.

const x = simplify("(1/x) * x");
console.log(x.strung()); // "1"

Algebraic simplification, in general, is a difficult problem. In designing a simplification algorithm, there is inevitably a conflict between the user's desired output and the software engineer's preferences. For example, the following mathematical expressions are all equivalent:

If we passed an expression equivalent to either of those above, what should the expression simplify to? The engineer may be incentivized to only use sines and cosines. The user, however, may want the expression reduced to any one of these, depending on context. Of course, the more the engineer caters towards the user's preferences, the more complex the simplification algorithm.

We say this up front as a prefatory warning on the simplify function's limitations. The following sections outline some of these limitations.

Distributive Transformations

For example, the following expression will have its terms rearranged, but not simplified:

const x = simplify("(x^2 + x)/x");
console.log(x.strung()); // x^(-1) * (x + x^2)

This, however, will simplify:

const x = simplify("2x + y + (3|2) * x");
console.log(x.strung()); // 7|2 * x + y

The expression

does not simplify further because Algebron's automatic simplification algorithm only applies the distributive property when combining constant (integer, fraction, or floating point) coefficients of like terms in a sum. It does not apply the distributive property as collecting non-constant coefficients of like terms as well as constants.

There are several reasons for this:

1. "Like terms" can be ambiguous. One application of the distributive property is its reversal — collecting "like terms." Given an expression ${u,}$ it's not always clear which parts of the expression are the like terms and which aren't. For example, consider the expression:

   $$ax + bx + by.$$

   If the like terms are coefficients of ${x,}$ then the expression should simplify to ${(a + b)x + by.}$ But if the like terms are coefficients of ${b,}$ ${u}$ should simplify to ${ax + b(x + y).}$

subexs(u)

Where u is a string or MathObj corresponding to an algebraic expression, returns an array of the subexpressions of u.

const result = subexs("a * (x + 1) + 3");
console.log(result); // ['a * (x + 1) + 3', 'a * (x + 1)', 'a', '(x + 1)', 'x', '1', '3']

freeOf(u,xs)

Where u is a string or MathObj and xs is an array of strings or MathObjects, returns true if the expression u does not contain any of the subexpressions in xs; false otherwise.

const x = freeOf("2x + 1", ["x"]);
console.log(x); // false

const y = freeOf("3a^2 + 9b + c", ["y", "z"]);
console.log(y); // true

derive(u,x)

Where u is string or MathObj representing to an expression, and x is a string or MathObj representing a variable, returns a MathObj corresponding to the derivative of u with respect to x.

Using the function directly in TypeScript:

const d = derive("2x^3 + 1", "x");
console.log(d.strung()); // 6(x^2)

numerator(𝑢)

Where ${u}$ is an algebraic expression, returns the numerator of ${u.}$

const x = `(2/3) * ((x * (x + 1)) / (x + 2)) * y^n`;
console.log(numerator(x).strung()); // 2 * x * (1 + x) * (y^n)

denominator(𝑢)

Where ${u}$ is an algebraic expression, returns the denominator of ${u.}$

const k = `(2/3) * ((x * (x + 1)) / (x + 2)) * y^n`;
console.log(denominator(k).strung()); // 3 * (2 + x)

isMonomial(u,xs)

Where u is a string or MathObj representing an expression, and xs is an array of strings or MathObjs representing variables, returns true if u is a general monomial expression in the given variables; false otherwise.

const result1 = isMonomial("ax^2y^2", ["x", "y"]);
console.log(result1); // true

const result2 = isMonomial("x^2 + y^2", ["x", "y"]);
console.log(result2); // false

isPolynomial(u,xs)

Where u is a string or MathObj representing an expression, and xs is an array of strings or MathObjs representing variables, returns true if u is a general polynomial expression in the given variables; false otherwise.

const result1 = isPolynomial("x^2 + y^2", ["x", "y"]);
console.log(result1); // true

const result2 = isPolynomial("(x + 1)(x + 3)", ["x"]);
console.log(result2); // false

gpeDeg(u,xs)

Where u is a general polynomial expression and xs is a list of variables, returns the degree of u in xs.

const result = gpeDeg("(a * x^2) + (b * x) + c", ["x"]);
console.log(result.strung()); // 2

const result = gpeDeg("(2 * x^2 * y * z) + (w * x * z^6)", ["x", "z"]);
console.log(result.strung()); // 7

vars(u)

Where u is a general polynomial expression, returns an array of the variables in the expression.

const result1 = vars("(x^3) + (3 * x^2 * y) + (3 * x * y^2) + (y^3)");
console.log(result1); // ['x', 'y']

const result2 = vars("(3 * x) * (x + 1) * (y^2) * z^n");
console.log(result2); // ['1 + x', 'x', 'y', 'z^n']

coefGPE(u,x,j)

Where u is a string or MathObj, x is a string or symbol (corresponding to a variable), and j is a nonnegative integer, returns the sum of the coefficient parts of all monomials of u with variable part ${x^j.}$

const result1 = coefGPE("(a * x^2) + (b * x) + c", "x", 2);
console.log(result1.strung()); // a
const result2 = coefGPE("(3 * x * y^2) + (5 * x^2 * y) + (7 * x) + 9", "x", 1); // 7 + 3y^2
console.log(result2.strung());

lcGPE(u,x)

Where u is a string or MathObj (corresponding to a general polynomial expression), and x is a string or symbol (corresponding to a variable), returns the leading coefficient with respect to x.

const result1 = lcGPE("(3 * x * y^2) + (5 * x^2 * y) + (7 * x) + 9", "y");
console.log(result1.strung()); // 3x

expand(u)

Where u is a MathObj or an algebraic expression, expands u.

const a = expand("(2x + 1)(x + 2)");
console.log(a.strung()); // (2 + 5x + 2(x^2))

const b = expand("(x + 2)(x + 3)(x + 4)");
console.log(b.strung()); // (24 + 26x + 9(x^2) + (x^3))

distribute(𝑢)

Where ${u}$ is a string or MathObj corresponding to an algebraic expression, returns the distributed form of ${u.}$

const e1 = distribute("a * (b + c)");
console.log(e1.strung()); // a * b + a * c

const e2 = distribute("a * (b + c) * (d + e)");
console.log(e2.strung()); // a * b * (d + e) + a * c * (d + e)

const e3 = distribute("(x + y)/(x * y)");
console.log(e3.strung()); // x^(-1) + y^(-1)

⚠ There are some caveats to this function. First, the distribute function may not always return results the user expects (e.g., in the examples above, e2 and e3). This is largely because of distribute's underlying algorithm:

Take note of line 6. This line indicates that the distribute function only applies the distributive property with the first operand that is a sum. It will not distribute further past that. We do not distribute further because the expression could potentially explode in memory and space.

This leads to the second caveat: The distribute function should be used with care. Distribution tends to make expressions longer. Because the result of distribute undergoes automatic simplification, calling this function may result in stack overflows or slow processing.

collectTerms(𝑢,𝑆)

Where ${u}$ is an algebraic expression (represented as either a string or a MathObj), and ${S}$ is a list of generalized variables (represented as an array of strings or MathObjs), returns a MathObj corresponding to the collected form of ${u.}$ If ${u}$ is not a general polynomial expression, returns the MathObj Undefined.

In the example below, we define ${u}$ to be:

The collected form of this expression, where ${S = \lbrack a, b \rbrack}$ is

Note that the output string may not look exactly like the LaTeX expression above because of automatic simplification.

const x = collectTerms(
  `(2 * a * x * y) + (3 * b * x * y) + (4 * a * x) + (5 * b * x)`,
  ["a", "b"]
);

console.log(x.strung()); // a * (4 * x + 2 * x * y) + b * (5 * x + 3 * x * y)

2D Graphics

Algebron provides an API for 2D graphics. This API only performs the mathematical computations and data processing necessary for 2D graphics. Algebron does not provide actual drawing methods. Any actual rendering on a frontend is left to the user's frontend of choice (React, Svelte, etc.). For example, on this site, all diagrams are generated with React. Documentation of the React components used on this site are found in the React Components section.

SVGObj

An object corresponding to an SVG element. This object describes an SVG element. Pass this object to your frontend framework of choice to create the specified element.

On this site, the SVGObj is used as follows:

import {
  svg,
  isGroup,
  isPath,
  isLine,
  isText,
  isCircle,
  isArrowhead,
  SVG,
  Renderable,
  isPath3D,
  isPolyline,
  isPolygon,
  isEllipse,
} from "@/algebron/main";

const FIGURE = ({ children }: { children: ReactNode }) => {
  return <figure className="algebron-fig">{children}</figure>;
};

type Fig2DProps = { elements: Renderable[] };

const Fig2D = ({ elements }: Fig2DProps) => {
  return (
    <>
      {elements.map((data) => {
        if (isGroup(data)) {
          return <GROUP key={data._id} data={data} />;
        }
        if (isPath(data) || isPath3D(data)) {
          return <PATH key={data._id} data={data} />;
        }
        if (isLine(data)) {
          return <LINE key={data._id} data={data} />;
        }
        if (isText(data)) {
          return <TEXT key={data._id} data={data} />;
        }
        if (isCircle(data)) {
          return <CIRCLE key={data._id} data={data} />;
        }
        if (isPolyline(data)) {
          return <POLYLINE key={data._id} data={data} />;
        }
        if (isPolygon(data)) {
          return <POLYGON key={data._id} data={data} />;
        }
        if (isEllipse(data)) {
          return <ELLIPSE key={data._id} data={data} />;
        }
      })}
    </>
  );
};

type FigProps = {
  data: SVG;
  width?: number | string;
  paddingBottom?: number | string;
  title?: ReactNode;
};

const Fig = ({ data, width = 100, paddingBottom = width, title }: FigProps) => {
  const par = "xMidYMid meet";

  const viewbox = `0 0 ${data._width} ${data._height}`;

  const boxcss = {
    display: "block",
    margin: "0 auto",
    position: "relative",
    width: typeof width === "number" ? `${width}%` : width,
    paddingBottom:
      typeof paddingBottom === "number" ? `${paddingBottom}%` : paddingBottom,
    overflow: "hidden",
  } as const;

  const svgcss = {
    display: "inline-block",
    position: "absolute",
    top: "0",
    left: "0",
    right: "0",
    bottom: "0",
  } as const;

  return (
    <FIGURE>
      <div style={boxcss}>
        <svg viewBox={viewbox} preserveAspectRatio={par} style={svgcss}>
          <DEF elements={data._defs} />
          <g
            transform={`translate(${data._translate[0]},${data._translate[1]})`}
          >
            <Fig2D elements={data._children} />
          </g>
        </svg>
      </div>
      {title && <figcaption>{title}</figcaption>}
    </FIGURE>
  );
};

Renderable

SVG shapes are described by Renderable objects. These objects are defined by the Renderable abstract class. Subclasses of Renderable describe specific SVG shapes. As of Algebron version 1.0, the following SVG shapes are supported:

Group

SVG groups are described by Group objects. These objects are defined by the Group class. Below is an example of using the Group object with a React component:

import { isGroup, Group, } from "@/algebron/main"

type GroupProps = { data: Group };

const GROUP = ({ data }: GroupProps) => {
  return (
    <g transform={`${data._transformation}`}>
      <Fig2D elements={data.$children} />
    </g>
  );
};

Cartesian Plot

Algebron can generate data for Cartesian plots with the cplot function. For example, the plot below is generated with the cplot function and React:

Polar Plot

Tree Drawing

Trees can be generated with Algebron's tree function.

For example, the diagram above is generated using React.

Graph Drawing

Graphs can be generated in Algebron with the forceGraph and graph functions. The graph function generates a graph data structure (implemented with an adjacency list). The forceGraph function uses a physics-based graph drawing algorithm to position each of the nodes and edges.

The code generating the graph above (using React):

Splines

Given a set of points, we often want to draw a line through these points. Algebron's spline functions provide this functionality.

Convex Hull

To find the convex hull of a set of points, use the convexHull function. Below is a visualization of convexHull applied to a set of random points, with the resulting convex hull outlined and shaded green:

3D Graphics

Algebron provides various functions and methods related to 3D graphics. On this site, 3D models are rendered with React Three Fiber.

3D Plot

Three-dimensional plots can be generated with Algebron's plot3D function:

Multiple Plots

Maps

3D Function Plot Wireframes

The fplot3D function can be used to plot wireframes of 3D functions in SVG.