load — Load variables from a MATLAB-compatible MAT-file into the workspace or return them as a struct.
load reads variables from a MAT-file (Level-5 layout) and brings them into the current workspace. Like MATLAB, it can either populate variables directly or return a struct containing the loaded data.
How load works in RunMat
load filenamereads every variable stored infilename.matand assigns them into the caller's workspace. When no extension is supplied,.matis appended automatically. SetRUNMAT_LOAD_DEFAULT_PATHto override the defaultmatlab.mattarget when no filename argument is provided.S = load(filename)loads the file but returns a struct instead of modifying the workspace. The struct fields mirror the variables stored in the MAT-file.load(filename, 'A', 'B')restricts the operation to the listed variable names. String scalars, char vectors, string arrays, or cell arrays of character vectors are accepted.load(filename, '-regexp', '^foo', 'bar$')selects variables whose names match any of the supplied regular expressions.- Repeated names are deduplicated so that the last occurrence wins, mirroring MATLAB's behavior.
- Unsupported data classes trigger descriptive errors. RunMat currently supports double and complex numeric arrays, logical arrays, character arrays, string arrays (stored as cell-of-char data), structs, and cells whose elements are composed of the supported types.
- Files saved on platforms that produce little-endian Level-5 MAT-files (MATLAB's default) are supported. Big-endian and compressed (
miCOMPRESSED) files currently report an error.
How load runs on the GPU
load always reads data on the host. The resulting values start on the CPU. When RunMat Accelerate is active, auto-offload heuristics may later decide to promote tensors to the GPU if they participate in accelerated expressions, but no provider hooks are required during the load operation itself. GPU-resident variables that were saved earlier are gathered back to host memory as part of file serialisation, so loading them produces standard host values.
GPU memory and residency
No manual action is required. load always creates host values. When the auto-offload planner decides that downstream computations benefit from GPU execution, it will promote tensors automatically. You can still call gpuArray on loaded variables explicitly if you want to pin them to the device immediately.
Examples
Load the entire file into the workspace
weights = [0.5, 1.0, 1.5];
save('results.mat', 'weights');
load('results.mat');
disp(norm(weights))Load a subset of variables by name
time = 0:0.25:1;
state = [0, 0.5, 0.8, 0.6, 0.3];
save('sim_state.mat', 'time', 'state');
load('sim_state.mat', 'state', 'time');
plot(time, state)Load variables using regular expressions
layer_1 = ones(4, 4);
layer_2 = ones(8, 8);
save('checkpoint.mat', 'layer_1', 'layer_2');
load('checkpoint.mat', '-regexp', '^layer_\d+$')Capture loaded variables in a struct without altering the workspace
x = 3.14;
y = 2.72;
save('snapshot.mat', 'x', 'y');
S = load('snapshot.mat');
disp(fieldnames(S))Combine explicit names and regex filters
config = struct('lr', 0.01);
weights_conv = randn(3, 3);
weights_fc = randn(4, 2);
save('model.mat', 'config', 'weights_conv', 'weights_fc');
model = load('model.mat', 'config', '-regexp', '^weights_(conv|fc)')Honour a custom default filename
x = 0;
save(fullfile(tempdir, 'autosave.mat'), 'x');
setenv('RUNMAT_LOAD_DEFAULT_PATH', fullfile(tempdir, 'autosave.mat'));
load()Load character and string data
labels = 'hello';
save('strings.mat', 'labels');
values = load('strings.mat', 'labels');
disp(values.labels)FAQ
Does load support ASCII text files?
No. RunMat (like MATLAB) restricts the load builtin in modern releases to MAT-files. Text and delimited files should be read using readmatrix, readtable, or other file I/O utilities such as fileread.
How are structures handled?
Structure scalars are reconstructed as struct values whose fields match the MAT-file content. Nested structs, cells, logical arrays, and numeric data are all supported.
Will load overwrite existing variables?
Yes. When you call load without capturing the output struct, any variables with matching names in the caller's workspace are overwritten with the values from the MAT-file.
What happens if a requested variable is missing?
RunMat raises a descriptive error: load: variable 'foo' was not found in the file. This mirrors MATLAB's behavior.
Can I load into a different workspace?
Use MATLAB-compatible functions such as assignin (when available) if you need to populate a different scope explicitly. The load builtin itself targets the caller workspace by default.
How are GPU arrays handled?
GPU-resident values are serialised to host data when saved. Loading the resulting MAT-file produces standard host arrays. Downstream acceleration is handled automatically by RunMat Accelerate.
How do I detect which variables were loaded?
Use the struct form: info = load(filename); and then inspect fieldnames(info) or isfield to programmatically check what was present in the MAT-file.
Related functions to explore
These functions work well alongside load. Each page has runnable examples you can try in the browser.
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how load works, line by line, in Rust.
- View load.rs on GitHub
- Learn how the runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code — faster, on any GPU, with no license required.
- Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
- Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
- A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.