runmat 0.5.0

RunMat is an open-source, high-performance runtime designed for numerical computing using MATLAB-style syntax. It is built in Rust and provides a multi-tiered execution model that targets both CPU and GPU hardware without requiring manual device management.

The system is designed to be a drop-in runtime for .m files, offering automatic operation fusion, a generational garbage collector, and a cross-platform GPU backend powered by wgpu

Key Capabilities:

• MATLAB Compatibility: Supports standard .m file syntax, including arrays, complex control flow, and over 400 built-in functions
• Automatic Fusion: Builds an internal graph of array operations to fuse elementwise math and reductions into optimized kernels
• Tiered Execution: Combines a fast-startup VM interpreter with the Turbine JIT (based on Cranelift) for hot code paths
• Cross-Platform GPU: Transparently offloads workloads to Metal, DirectX 12, Vulkan, or WebGPU using the runmat-accelerate crate
• Async Runtime: Built on Rust futures, allowing non-blocking execution in web environments and CLI tools
• Integrated Plotting: Features a GPU-accelerated 2D/3D plotting engine supporting 30+ plot types

[!NOTE] RunMat is pre-1.0 software. The core runtime, CLI, GPU engine, and TypeScript bindings are usable today, but compatibility coverage is still expanding.

Quick Start

The quickest way to get started with RunMat is to download the RunMat Desktop application.

Alternatively, you can install the CLI:

# Linux/macOS
curl -fsSL https://runmat.com/install.sh | sh

# Windows PowerShell
iwr https://runmat.com/install.ps1 | iex

Create a script hello.m:

disp("Hello, World!");
A = magic(3);
disp(sum(A));

Run the script:

runmat hello.m

See Hello World for more examples, and the Command Line Interface for the full command surface.

Other Installation Options

# Homebrew (macOS/Linux)
brew install runmat-org/tap/runmat

# Cargo (Rust)
cargo install runmat --features gui

# Build from source
git clone https://github.com/runmat-org/runmat.git && cd runmat
cargo build -p runmat --release --features gui

CLI

The CLI runs local scripts, named project entrypoints, benchmarks, snapshots, and remote project filesystems.

runmat analysis.m
runmat run analysis.m
runmat repl
runmat info
runmat accel-info

Projects can define named entrypoints in runmat.toml:

[package]
name = "demo"

[entrypoints.main]
path = "src/main.m"

Run the entrypoint:

runmat run main

For the full command surface, see Command Line Interface.

TypeScript And WebAssembly

The runmat npm package embeds the runtime in browser, worker, Electron, and Node-based hosts.

npm install runmat

import { initRunMat } from "runmat";

const session = await initRunMat({
  telemetryConsent: false,
  language: { compat: "matlab" }
});

const result = await session.executeRequest({
  source: {
    kind: "text",
    name: "<repl>",
    text: "A = magic(3); disp(A)"
  }
});

console.log(result.stdout);
console.log(result.workspace.values);

session.dispose();

The TypeScript API includes session execution, workspace snapshots, lazy variable materialization, filesystem providers, plotting surfaces, stdout subscriptions, runtime diagnostics, and GPU status reporting.

See bindings/ts/README.md and WASM & TypeScript/JavaScript.

What Is In This Repository

The runtime is host-neutral. The CLI, WASM bindings, LSP, and future application hosts all submit source through the same session/execution boundary and consume structured results.

Runtime Highlights

• MATLAB-style source execution for scripts, functions, packages, imports, classdef, indexing, cells, structs, exceptions, and common language constructs.
• A large builtin library covering array operations, math, statistics, signal processing, image I/O, file I/O, tables, plotting, strings, dates, optimization, ODEs, and control-system basics.
• A bytecode VM for predictable startup and a Cranelift JIT for hot execution paths.
• GPU acceleration through fusion, auto-offload decisions, and wgpu backends for Metal, Vulkan, DirectX 12, and WebGPU.
• Interactive 2D and 3D plotting with figure handles, subplot state, labels, legends, export, replay, and browser canvas integration.
• Session APIs for REPLs, notebooks, editors, browser sandboxes, and remote filesystem-backed projects.
• TypeScript bindings with filesystem providers for memory, IndexedDB, and remote HTTP-backed workspaces.

GPU Acceleration

RunMat's acceleration engine captures array operations into fusion plans, estimates whether CPU or GPU execution is better for the current shapes, and keeps tensors resident on device when downstream work can reuse them.

x = rand(10_000_000, 1, "single");
y = sin(x) .* exp(-x / single(10));
z = tanh(y) + single(0.1) .* y;
m = mean(z, "all");

Elementwise chains and reductions like this can be fused into larger GPU dispatches without writing kernel code. Smaller workloads can stay on CPU when transfer overhead would dominate.

See GPU Acceleration & Fusion Engine.

Plotting

RunMat includes an open plotting engine used by the CLI, browser sandbox, and TypeScript bindings.

x = 0:0.1:10;
plot(x, sin(x));
title("Sine wave");
grid on;

See Plotting System.

Documentation

Start here:

• Installation
• Command Line Interface
• Configuration Reference
• Hello World
• MATLAB Language Compatibility

Runtime internals:

• Compilation Pipeline
• Virtual Machine
• Runtime Values & Type Model
• Builtins
• Session Engine
• GPU Acceleration
• JIT Compiler
• Filesystem Abstraction
• WebAssembly & TypeScript
• Language Server Protocol
• Development

The full docs index is docs/README.md.

Benchmarks

The benchmarks directory contains reproducible cross-language comparisons against NumPy, PyTorch, Octave, and Julia where applicable.

Representative published runs include:

Run the suite:

python3 benchmarks/.harness/run_suite.py \
  --suite benchmarks/.harness/suite.json \
  --output results/suite_results.json

Benchmark results depend on hardware, driver stack, backend selection, and workload shape. The benchmark harness records device details and parity checks with each run.

Development

Install the Rust toolchain from rust-toolchain.toml, then build the workspace:

cargo build
cargo test

Build the CLI with plotting support:

cargo build -p runmat --release --features gui

Work on the TypeScript/WASM package:

cd bindings/ts
npm install
npm run build
npm test

Useful docs:

• Build System
• Testing Strategy
• Supported Architectures
• Benchmarking
• Telemetry

License

RunMat is licensed under the Apache License 2.0.

MATLAB is a registered trademark of The MathWorks, Inc. RunMat is not affiliated with, endorsed by, or sponsored by The MathWorks, Inc.