MATBOX

MATrix BOX — a clean-room, from-scratch MATLAB replica written in Rust.

  __  __       _ ____   _  __
 |  \/  | __ _| | __ ) | |/ /
 | |\/| |/ _` | |  _ \ | ' / 
 | |  | | (_| | | |_) || . \ 
 |_|  |_|\__,_|_|____(_)_|\_\

Overview

MATBOX is a fully independent, ground-up reimplementation of the MATLAB language and runtime. The compute engine is 100% Rust — no Python, no C++, no C. Every number is a complex-valued N-dimensional array, every operation is vectorized, and every function matches MATLAB semantics.

Architecture

┌──────────────────────────────────────────────┐
│            matbox-cli (REPL / runner)         │
├──────────────────────────────────────────────┤
│              matbox-lsp (LSP server)          │
├──────────────────────────────────────────────┤
│           matbox-core (Engine + Parser)       │
├──────────────────────────────────────────────┤
│           matbox-math (Linear Algebra)        │
├──────────────────────────────────────────────┤
│  matbox-graphics  │  matbox-sim  │  matbox-ffi│
└──────────────────────────────────────────────┘

Crate	Description
`matbox-core`	Lexer, parser, AST, interpreter, builtins (325+ tests)
`matbox-math`	Column-major `MxArray`, LAPACK-free linalg (QR, eig, SVD, LU, Cholesky)
`matbox-cli`	REPL and script runner
`matbox-lsp`	Language Server Protocol implementation
`matbox-graphics`	WebGL/Canvas plotting backend
`matbox-sim`	Simulink-like block diagram solver
`matbox-ffi`	C FFI for embedding (`matbox.h`)

Quick Start

Installation

git clone https://github.com/Mr-DS-ML-85/Matbox
cd Matbox
cargo build --release

REPL

cargo run --release
>> x = [1 2 3; 4 5 6]
>> sin(x)
>> disp('Hello, MATBOX!')
>> exit

Run a script

cargo run --release -- run examples/demo.mbox

Check syntax

cargo run --release -- check myscript.mbox

Language

MATBOX uses the .mbox file extension. The language is a superset of MATLAB:

Hello World

% hello.mbox
disp('Hello, MATBOX!')

Matrix Operations

A = [1 2 3; 4 5 6]
B = [7 8 9; 10 11 12]
C = A * B             % matrix multiply
D = A .* B            % element-wise multiply
E = A'                % conjugate transpose

Functions

function result = fib(n)
    if n <= 1
        result = n
    else
        result = fib(n-1) + fib(n-2)
    end
end

disp(fib(10))

Anonymous Functions & Closures

f = @(x) x^2
f(5)              % 25

adder = @(x) @(y) x + y
add5 = adder(5)
add5(3)           % 8 (closure captures x=5)

Structs

s = struct('name', 'MATBOX', 'version', 0.1)
s.description = 'A MATLAB replica in Rust'
disp(s.name)
s.('version')     % dynamic field access

Cell Arrays

C = {1, 'hello', @sin}
C{2}              % 'hello'
C{3}(pi/2)        % 1.0
cellfun(@(x) x^2, {1, 2, 3})

Language Features

Feature	Syntax	Status
Matrix arithmetic	`+ - * / \\ ^ .* ./ .^ .\\`	✅
Conjugate transpose	`A'`	✅
Non-conjugate transpose	`A.'`	✅
Broadcasting	scalar + matrix, row + col	✅
Colon ranges	`1:10`, `1:2:10`, `end-1:end`	✅
Relational	`== ~= < <= > >=`	✅
Logical	`& \| ~ && \|\|`	✅
Control flow	`if/elseif/else/end`	✅
Loops	`for/end`, `while/end`, `break`, `continue`	✅
Switch	`switch/case/otherwise/end` + cell patterns `case {1,2,3}`	✅
Try/catch	`try/catch/end`	✅
Functions	`function [a,b] = name(x,y)/end`	✅
`endfunction`	MATBOX extension for function terminators	✅
`varargin` / `varargout`	Variable-length argument lists	✅
`persistent`	Persistent variables inside functions	✅
`global`	Global variable sharing	✅
`parfor`	Parallel for loop (sequential fallback)	✅
Anonymous functions	`@(x) x^2`	✅
Closures	`@(x) @(y) x+y` (free variable capture)	✅
Function handles	`@sin`, `@cos`, `f = @(x) x^2; f(3)`	✅
Structs	`s.field`, `s.('dynamic')`, `struct()`	✅
Cell arrays	`{1, 'hello', @sin}`, brace indexing `C{1}`	✅
Multi-output	`[a, b] = func(x)`	✅
Double-quoted strings	`"hello"` (MATBOX extension)	✅
`#` comments	MATBOX extension	✅
`**` power operator	`2 ** 3` (MATBOX extension)	✅
`%{...%}` block comments	Multi-line comment blocks	✅
Line continuation	`A = [1 2 3; ...`	✅
LSP server	Completions, diagnostics, hover	✅

Built-in Functions (180+)

Category	Functions
Trigonometry	`sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `sinh`, `cosh`, `tanh`, `asinh`, `acosh`, `atanh`
Exponentials	`exp`, `log`, `log10`, `log2`, `sqrt`, `abs`, `angle`, `conj`, `real`, `imag`
Rounding	`floor`, `ceil`, `round`, `fix`, `sign`, `mod`, `rem`
Special Math	`erf`, `erfc`, `erfinv`, `gamma`, `gammaln`
Array	`length`, `size`, `numel`, `ndims`, `sum`, `prod`, `mean`, `median`, `mode`, `std`, `var`, `min`, `max`, `any`, `all`, `cumsum`, `cumprod`, `diff`, `sort`, `unique`, `flip`, `fliplr`, `flipud`, `reshape`, `repmat`, `kron`, `diag`, `find`, `linspace`, `logspace`, `colon`, `meshgrid`
Linear Algebra	`inv`, `det`, `rank`, `trace`, `norm`, `lu`, `qr`, `chol`, `eig`, `svd`, `pinv`
Matrix Creation	`zeros`, `ones`, `eye`, `rand`, `randn`, `randi`, `randperm`, `magic`
Polynomials	`polyval`, `poly`, `roots`, `polyfit`
Set Operations	`intersect`, `setdiff`, `setxor`, `union`, `ismember`, `issorted`
Correlation	`corrcoef`, `cov`
Fourier / Signal	`fft`, `ifft`, `fftshift`, `ifftshift`, `conv`, `filter`
Numerical	`fzero`, `trapz`, `integral`
Strings	`strcmp`, `strcmpi`, `upper`, `lower`, `strtrim`, `deblank`, `strsplit`, `strjoin`, `sprintf`, `contains`, `startsWith`, `endsWith`, `num2str`, `int2str`, `str2double`, `strfind`, `strrep`, `regexp`, `regexpi`, `regexprep`
Cell	`cellfun`, `num2cell`, `cell2mat`, `mat2cell`, `cell2struct`, `struct2cell`, `cellstr`
Type	`ischar`, `islogical`, `isnumeric`, `isreal`, `isscalar`, `isvector`, `isrow`, `iscolumn`, `ismatrix`, `isempty`, `iscell`, `isstruct`, `isinf`, `isnan`, `isfinite`, `isa`, `double`, `single`, `char`
Integer Types	`int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`
Execution	`eval`, `evalc`
File System	`pwd`, `ls`, `dir`
Graphics (stubs)	`figure`, `plot`, `hold`, `subplot`, `xlabel`, `ylabel`, `title`, `grid`, `legend`, `axis`, `bar`, `histogram`, `scatter`
Utilities	`disp`, `error`, `warning`, `who`, `clear`, `exist`, `format`, `run`, `help`, `struct`, `isfield`, `fieldnames`, `rmfield`, `orderfields`, `deal`, `feval`, `isequal`, `isequaln`, `cat`, `tic`, `toc`, `input`, `clc`, `pause`
Introspection	`nargin`, `nargout`, `varargin`, `varargout`

Language Server

MATBOX includes a built-in LSP server for IDE integration.

cargo run --release -- lsp

Configure your editor to use matbox lsp as the language server for .mbox files.

VSCode

Install the "LSP" extension (d0x.assistant-lsp) or "vscode-lsp" from the marketplace, then create .vscode/settings.json:

{
  "LSP.languageServers": [
    {
      "name": "matbox",
      "command": ["/path/to/matbox", "lsp"],
      "filetypes": [".mbox"]
    }
  ],
  "files.associations": {
    "*.mbox": "matlab"
  }
}

Replace /path/to/matbox with the absolute path to the compiled binary (target/release/matbox after running cargo build --release).

Neovim (vim-lsp)

if executable('matbox')
    augroup LspMatbox
        autocmd!
        autocmd User lsp_setup call lsp#register_server({
            \ 'name': 'matbox',
            \ 'cmd': {server_info->['matbox', 'lsp']},
            \ 'whitelist': ['mbox'],
            \ })
    augroup END
endif

Project Status

Feature	Status
Scalar/Matrix arithmetic	✅
Linear algebra (eig, QR, SVD, LU, Cholesky)	✅
Control flow (if/else/for/while/switch/try)	✅
Function definitions (incl. `varargin`/`varargout`)	✅
Anonymous functions, closures, function handles	✅
`persistent` / `global` / `parfor`	✅
Structs & dynamic field access	✅
Cell arrays & conversion functions	✅
String operations (incl. regex)	✅
Set operations	✅
Statistics (std, var, median, mode, corrcoef, cov)	✅
Signal processing (FFT, conv, filter)	✅
Polynomials (polyval, roots, polyfit)	✅
Numerical methods (fzero, trapz, integral)	✅
Special functions (erf, erfc, gamma)	✅
Type conversion (double, char, integer types)	✅
Execution (eval, evalc)	✅
File system (pwd, ls, dir)	✅
Graphics stubs (plot, figure, subplot, etc.)	✅
180+ built-in functions	✅
LSP server (completions, diagnostics, hover)	✅
MATBOX extensions (`#`, `**`, `endfunction`, `"strings"`)	✅
Block comments `%{...%}`	✅
Graphics engine	🚧 In progress
Simulink solver	🚧 In progress
Python bindings	🚧 In progress
Tauri desktop app	🚧 In progress
Web (TypeScript) engine	📋 Planned

Benchmarks

Benchmark	Workload	Time
Stress Test Suite	Arithmetic, Matrix Ops, Matrix Multiply, Statistics, FFT, Polynomial, Sets, Cells, Structs, Functions, Recursion, Strings	1.508 s
Matrix Multiplication	10 × (500×500 × 500×500) matrix multiplications	6.254 s
Large Numerical Stress	1,000,000 `sin()` evaluations + 1000×1000 matrix operations + FFT(4096) + Statistics + User Functions	5.437 s

CLI

Command	Description
`matbox repl`	Start interactive REPL
`matbox run <file.mbox>`	Execute a MATBOX script
`matbox check <file.mbox>`	Check syntax without execution
`matbox lsp`	Start Language Server Protocol (LSP) server
`matbox version`	Print version information

Benchmark Environment

Property	Value
Version	MATBOX v0.1.0
Language	Rust
Build	Release
Platform	Linux
CPU	AMD Ryzen 7 7700
RAM	32GB DDR5

Development

Running tests

cargo test              # all tests (437+)
cargo test -p matbox-core   # core tests only
cargo test -p matbox-math   # math tests only

Code style

cargo fmt
cargo clippy

Adding a builtin

Builtins are defined in crates/matbox-core/src/builtins.rs. Each builtin is a match arm in the call() function. Add the function name and implementation, then add tests in crates/matbox-core/src/eval.rs.

Disclaimer

MATBOX is an independent, open-source project developed to provide a MATLAB-compatible programming language and runtime. It is currently under active development and should be considered experimental software.

Project Status

MATBOX is not feature-complete. While many language features and built-in functions are implemented, others are still under development.

Users may encounter:

Bugs or unexpected behavior
Incomplete or missing language features
Compatibility differences with MATLAB
Performance limitations in some workloads
Breaking changes between releases

Please verify important computational results before relying on MATBOX for research, engineering, academic, or production work.

Compatibility

MATBOX aims to provide compatibility with MATLAB .m scripts wherever practical. However, compatibility is an ongoing effort, and not all MATLAB language features or built-in functions are currently supported.

Compatibility with MATLAB does not imply that MATBOX contains, copies, or redistributes any proprietary MATLAB code.

Clean-Room Implementation

MATBOX is a clean-room implementation developed independently. It is not based on copied, decompiled, reverse-engineered, or otherwise derived proprietary MATLAB source code.

The project is implemented from original code using publicly available language behavior and documentation.

Copyright & Trademarks

MATBOX is an independent project and is not affiliated with, endorsed by, sponsored by, or associated with MathWorks.

MATLAB® is a registered trademark of MathWorks. All other trademarks, product names, and company names mentioned in this project belong to their respective owners.

Open Source

MATBOX is distributed under the license included in this repository. Please read the LICENSE file for your rights and obligations regarding use, modification, and redistribution.

No Warranty

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Feedback

Bug reports, feature requests, pull requests, and community contributions are welcome and greatly appreciated. MATBOX is an evolving project, and community feedback helps improve its quality and compatibility.

MATBOX Trademark Policy

The name MATBOX™, the MATBOX logo, and the project's branding are the intellectual property of the MATBOX project owner.

You are welcome to use, modify, and redistribute the MATBOX source code under the terms of the project's software license.

However, you may not:

Redistribute a modified version under the name MATBOX.
Use the MATBOX name or logo in a way that suggests official endorsement.
Market or sell a fork as the official MATBOX project.

If you create a modified or forked version, you must use a different project name and clearly indicate that it is an unofficial fork.

This policy is intended to protect users from confusion and preserve the identity of the official MATBOX project.

The source code is licensed under AGPL-3.0, but the MATBOX name and logo may not be used for modified or redistributed versions without permission. See TRADEMARKS.md for details.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
crates		crates
docs		docs
.gitignore		.gitignore
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
TRADEMARKS.md		TRADEMARKS.md

Latest commit

History

Folders and files

Repository files navigation

MATBOX

Overview

Architecture

Quick Start

Installation

REPL

Run a script

Check syntax

Language

Hello World

Matrix Operations

Functions

Anonymous Functions & Closures

Structs

Cell Arrays

Language Features

Built-in Functions (180+)

Language Server

VSCode

Neovim (vim-lsp)

Project Status

Benchmarks

CLI

Benchmark Environment

Development

Running tests

Code style

Adding a builtin

Disclaimer

Project Status

Compatibility

Clean-Room Implementation

Copyright & Trademarks

Open Source

No Warranty

Feedback

MATBOX Trademark Policy

License

AGPLv3

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages