Cortex Compute Engine

The benchmarks directory contains tools to compare Compute Engine (CE) against other computer-algebra systems (CAS) and track performance improvements across releases.

Mathematica (the Wolfram kernel) serves as the reference baseline for all comparisons. The benchmarks compare CE and open-source competitors (like SymPy, math.js, and NumPy) against this commercial standard.

Key benchmark categories include:

• Release Baseline: Includes Capability, Marketing, Changelog tables, and three Audit harnesses (Operation audit, Wester suite, and Solving). These are used to establish performance baselines before a new release.
• Specialized Audits: Includes ODE solving, Bondarenko ∫, and Kernel microbenchmarks.
• Performance Investigation: Tools for kernel microbenchmarks and legacy compilation performance.

The Fungrim Corpus is a machine-translated MathJSON snapshot of the Fungrim mathematical formula collection, specifically annotated for use with the Compute Engine. It consists of several key files:

• MANIFEST.json: Contains schema version, generation date, upstream pins, and counts.
• corpus/<topic>.json: 57 files containing 2,551 annotated formula entries.
• declarations.json: Contains 132 symbol-shell declarations for symbols not natively defined by Compute Engine.
• properties.json: Contains 131 analytic-property records (e.g., Poles, Zeros, BranchCuts).
• skipped.json: A ledger of 448 records that were not included in the main corpus, categorized by machine-readable reason codes.

The roadmap/cortex/language-review.md file is a historical review documenting the state of the Cortex language as of 2026-07-05. It is not the current language reference.

For current behavior and proposals, users should refer to:

• Current behavior: src/cortex/docs/
• Current proposals and open questions: docs/plans/2026-08-03-cortex-language-extensions-review.md

The engine follows a specific contract regarding symbol equality and serialization:

1. Serialization is Name-Only: When symbols are serialized (e.g., converted to a string or JSON), they lose their unique binding identity and retain only their name.
2. Round-tripping Behavior: Because serialization loses identity, re-parsing or re-boxing a serialized symbol will rebind it to the current scope. This is intended behavior.
3. Equality: The engine distinguishes between symbols that share a name but belong to different binders. This ensures that mathematical operations (like integration or series expansion) do not accidentally capture or use variables from the wrong scope.

The core of the Compute Engine is the "boxed expression" model. A boxed expression is a class instance that wraps mathematical content with a consistent interface for evaluation, comparison, and serialization.

Concrete Subclasses

• BoxedNumber: Numeric literals (int, rational, radical, float, bignum, complex).
• BoxedSymbol: Symbols/identifiers (bound to a value definition when canonical).
• BoxedFunction: Function applications [operator, ...operands] (bound to an operator definition).
• BoxedString: String literals (stored NFC-normalized).
• BoxedDictionary: Key/value maps.

Note on Tensors: There is no dedicated tensor class. Vectors, matrices, and n-dimensional arrays are represented as canonical List BoxedFunction instances. Tensor properties like .shape and .rank are provided via a lazy view.

Cortex follows the principle that "errors are values".

• Runtime Errors: Problems like type errors, out-of-domain arguments, or reassigning a const do not throw exceptions. Instead, they return an embedded ["Error", ...] MathJSON value. executeCortex catches internal engine exceptions and converts them into these Error values.
• Non-final Errors: If an error occurs in a statement that is not the last one, it is emitted as a runtime-error diagnostic so the error doesn't vanish silently.
• Parse-time/Source Errors: Malformed syntax, gated pragmas, or #error directives are reported in the diagnostics array rather than being returned as an Error value.

The Compute Engine supports composing \operatorname{where} and \operatorname{for} (or custom \operatorname{with} and \operatorname{for}) clauses.

Goal: Let-bindings defined in a where clause should scope over both the expression body and the iterator range, regardless of whether where appears before or after for in the source text.

Canonical AST Shape: For successful composition, the parser should emit a Block as the outermost structure, containing declarations, assignments, and a Loop element.

Target Structure: [Block, [Declare, name], [Assign, name, value], [Loop, iterator, [Element, iterator, [Range, ...]]]]

Symbol Staleness occurs when a symbol's stored value is returned verbatim without being re-evaluated in the current environment. This happens because BoxedSymbol.evaluate()'s non-constant path returns the stored value directly, whereas other paths (like compilation or numeric approximation) perform re-evaluation.

Example of Staleness:

let d = 3x^2 + 1      // x is free here
let x = 2
d                     // Returns 3x^2 + 1 (STALE - uses old x)
N(d)                  // Returns 13 (Correct - re-evaluates x)

To ensure you are working with the most current values, prefer using the numeric approximation (N) or the compiled code path rather than raw evaluate() calls if the underlying bindings are expected to change.

In v2, generic recursion is possible for the first time. To implement a generic recursive function, you must use the declare-then-assign idiom. This involves declaring the function signature first and then assigning the body to the identifier.

This pattern ensures that the function name is available in the scope for recursive calls before the body is fully evaluated.