Compute Engine

Symbolic manipulation and numeric evaluation of MathJSON expressions

MathJSON is a lightweight mathematical notation interchange format based on JSON.

The Compute Engine can parse LaTeX to MathJSON, serialize MathJSON to LaTeX or MathASCII, format, simplify and evaluate MathJSON expressions.

Reference documentation and guides at cortexjs.io/compute-engine.

Installation

$ npm install --save @cortex-js/compute-engine

Quick Start

Basic Parsing and Evaluation

No setup required:

import { simplify, evaluate, N, assign } from "@cortex-js/compute-engine";

simplify("x + x + 1").print();
// ➔ 2x + 1

evaluate("2^{11} - 1").print();
// ➔ 2047

N("\\sqrt{2}").print();
// ➔ 1.414213562...

assign("x", 3);
evaluate("x + 2").print();
// ➔ 5

These functions use a shared ComputeEngine instance created on first use. Use getDefaultEngine() to configure it, or create your own instance for isolated configurations.

Working with Numbers (Type-Safe)

Use type guards to safely access specialized properties:

import { evaluate, isNumber } from "@cortex-js/compute-engine";

const expr = evaluate("\\frac{5}{2}");

if (isNumber(expr)) {
  console.log(expr.numericValue);  // 2.5 (type-safe access)
  console.log(expr.isInteger);     // false
}

Working with Symbols

import { parse, isSymbol, sym } from "@cortex-js/compute-engine";

const expr = parse("x + 1");

// Check if expression is a specific symbol
if (sym(expr) === "x") {
  console.log("This is the variable x");
}

// Or use full type guard for more access
const variable = parse("y");
if (isSymbol(variable)) {
  console.log(variable.symbol);  // "y"
}

Working with Functions

import { parse, isFunction } from "@cortex-js/compute-engine";

const expr = parse("2x + 3y");

// Access function structure safely
if (isFunction(expr)) {
  console.log(expr.operator);    // "Add"
  console.log(expr.ops.length);  // 2

  // Iterate over operands
  for (const op of expr.ops) {
    console.log(op.toString());
  }
}

Simplification and Manipulation

import { parse, simplify, expand } from "@cortex-js/compute-engine";

// Simplify expressions
simplify("x + x").print();
// ➔ 2x

// Expand from LaTeX or Expression
expand("(x + 1)^2").print();
// ➔ x^2 + 2x + 1

// Substitute values
const expr = parse("x^2 + 2x + 1");
expr.subs({ x: 3 }).evaluate().print();
// ➔ 16

Solving Equations

import { solve, parse } from "@cortex-js/compute-engine";

// Solve from LaTeX
solve("x^2 - 5x + 6 = 0", "x");
// ➔ [2, 3]

// Solve a linear system
const system = parse("\\begin{cases}x+y=5\\\\x-y=1\\end{cases}");
const solution = system.solve(["x", "y"]);

console.log(solution.x.json);  // 3
console.log(solution.y.json);  // 2

Epsil Language (Experimental)

Epsil is a text-syntax programming language for scientific computing whose intermediate representation is MathJSON, evaluated by the Compute Engine. It ships as a separate, experimental entry point (syntax and semantics may change between releases):

import { ComputeEngine, executeEpsil } from "@cortex-js/compute-engine/epsil";

const ce = new ComputeEngine();
const { value } = executeEpsil(ce, `
  let x = 1/2
  if (x < 1) { x + 1 } else { 0 }
`);
// value.toString() ➔ "3/2"

See the Epsil language documentation.

Epsil CLI and REPL

The package also installs an epsil command:

# Start an interactive session
npx epsil

# Evaluate source text or a file
npx epsil -e 'Simplify(2 + 2x)'
npx epsil program.epsil

# Epsil programs can also be piped over stdin
printf '1/2 + 1' | npx epsil

The interactive session preserves declarations between inputs and supports persistent history, multiline input, .load, .clear, .ast, and .time. Run epsil --help for output formats and execution-limit options.

MCP Server for AI Assistants

The epsil command includes a Model Context Protocol server, so an AI assistant can evaluate Epsil programs — exact arithmetic and symbolic computation as a tool call. For example, with Claude Code:

claude mcp add epsil -- npx -y @cortex-js/compute-engine mcp

The server exposes evaluate, check, doc, parse, and serialize tools, and serves a machine-verified language card so the assistant can learn Epsil on its own. It also has a native Streamable HTTP transport for ChatGPT and other URL-based clients:

npx -y @cortex-js/compute-engine mcp --transport streamable-http

See the MCP server guide for ChatGPT setup and HTTPS deployment options.

💡 Best Practices:

• Always use type guards (isNumber, isSymbol, isFunction) before accessing specialized properties
• Use the sym() helper for quick symbol name checks

📚 Learn More: Full documentation and guides

FAQ

Q How do I build the project?

Build instructions

Q How is the project structured?

See ARCHITECTURE.md for an overview of the codebase.

Related Projects

MathJSON

A lightweight mathematical notation interchange format

MathLive (on GitHub)

A Web Component for math input.

Support the Project

• 🌟 Star the GitHub repo (it really helps)
• 💬 Ask questions and give feedback on our Discussion Forum
• 📨 Drop a line to arno@arno.org

License

This project is licensed under the MIT License.