`load` — Load variables from MAT-files in MATLAB and RunMat.

load reads variables from MAT-files (Level-5 layout). It can populate workspace variables directly or return a struct of loaded values, consistent with MATLAB semantics.

Syntax

S = load()
S = load(filename)
S = load(filename, varName1, varName2, ...)
S = load(filename, "-regexp", pattern1, ...)
S = load(option, value, ...)

Inputs

Name	Type	Required	Default	Description
`filename`	`StringScalar`	Yes	`"matlab.mat"`	MAT-file path.
`varName`	`StringScalar`	Variadic	—	Variable names to load.
`option`	`StringScalar`	Yes	`"-regexp"`	Regular-expression selection option.
`pattern`	`StringScalar`	Variadic	—	Regex patterns matched against variable names.
`option`	`StringScalar`	Variadic	—	Compatibility options such as '-mat' and '-regexp'.
`value`	`Any`	Variadic	—	Option arguments and variable selectors.

Returns

Name	Type	Description
`S`	`Any`	Struct containing the loaded variables.

Returned values from load depend on how many outputs the caller requests.

Errors

Identifier	When	Message
`RunMat:load:InvalidArgument`	Arguments do not match a supported load invocation form.	`load: invalid argument`
`RunMat:load:InvalidOption`	An option token or option argument is invalid.	`load: invalid option`
`RunMat:load:Filename`	Filename is invalid or cannot be normalized.	`load: invalid filename`
`RunMat:load:Selection`	Requested variables are missing or no variables are selected.	`load: variable selection failed`
`RunMat:load:Io`	MAT-file data cannot be read or decoded.	`load: MAT-file I/O failure`
`RunMat:load:OutputCount`	Caller requests more outputs than supported by load.	`load: unsupported output count`
`RunMat:load:Workspace`	Statement-form load cannot assign values into workspace.	`load: workspace assignment failed`

How `load` works

load filename reads every variable stored in filename.mat and assigns them into the caller's workspace. When no extension is supplied, .mat is appended automatically. Set RUNMAT_LOAD_DEFAULT_PATH to override the default matlab.mat target 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 supports Level-5 double and single real/complex arrays, all eight native integer scalar and tensor classes, paired complex-integer components, logical arrays, character arrays, string arrays (stored as cell-of-char data), scalar structs, typed real sparse matrices, RunMat object envelopes, and cells whose elements are composed of the supported types. Integer class tags reconstruct authoritative native storage.
Little-endian, big-endian, and compressed (miCOMPRESSED) Level-5 MAT-files are supported. MATLAB v7.3 MAT-files are HDF5-backed and currently report an explicit unsupported-version error.

Does RunMat run `load` 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)

Using `load` with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how load changes the result.

Run a small load example, explain the result, then change one input and compare the output.

FAQ

Does load support ASCII text files?⌄

RunMat currently reads Level-5 MAT-files only. MATLAB also documents load(filename,"-ascii") and automatic ASCII loading for non-MAT extensions, so ASCII input remains an explicit general RunMat coverage gap; use readmatrix, readtable, or other text I/O utilities today.

How are structures handled?⌄

Structure scalars are reconstructed as struct values whose fields match the MAT-file content. Nested scalar structs, cells, logical arrays, sparse matrices, object envelopes, and numeric data are supported. Struct arrays report an explicit unsupported-data error until RunMat has a first-class struct-array value.

Does load call loadobj for saved objects?⌄

Yes for objects saved by RunMat. The MAT-file contains an internal object envelope; load restores nested payloads and dispatches registered static Class.loadobj methods when available.

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.

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how load is executed, line by line, in Rust.

View the source for load in Rust on GitHub
Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.

RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing

`load` — Load variables from MAT-files in MATLAB and RunMat.

load reads variables from MAT-files (Level-5 layout). It can populate workspace variables directly or return a struct of loaded values, consistent with MATLAB semantics.

Syntax

S = load()
S = load(filename)
S = load(filename, varName1, varName2, ...)
S = load(filename, "-regexp", pattern1, ...)
S = load(option, value, ...)

Inputs

Name	Type	Required	Default	Description
`filename`	`StringScalar`	Yes	`"matlab.mat"`	MAT-file path.
`varName`	`StringScalar`	Variadic	—	Variable names to load.
`option`	`StringScalar`	Yes	`"-regexp"`	Regular-expression selection option.
`pattern`	`StringScalar`	Variadic	—	Regex patterns matched against variable names.
`option`	`StringScalar`	Variadic	—	Compatibility options such as '-mat' and '-regexp'.
`value`	`Any`	Variadic	—	Option arguments and variable selectors.

Returns

Name	Type	Description
`S`	`Any`	Struct containing the loaded variables.

Returned values from load depend on how many outputs the caller requests.

Errors

Identifier	When	Message
`RunMat:load:InvalidArgument`	Arguments do not match a supported load invocation form.	`load: invalid argument`
`RunMat:load:InvalidOption`	An option token or option argument is invalid.	`load: invalid option`
`RunMat:load:Filename`	Filename is invalid or cannot be normalized.	`load: invalid filename`
`RunMat:load:Selection`	Requested variables are missing or no variables are selected.	`load: variable selection failed`
`RunMat:load:Io`	MAT-file data cannot be read or decoded.	`load: MAT-file I/O failure`
`RunMat:load:OutputCount`	Caller requests more outputs than supported by load.	`load: unsupported output count`
`RunMat:load:Workspace`	Statement-form load cannot assign values into workspace.	`load: workspace assignment failed`

How `load` works

load filename reads every variable stored in filename.mat and assigns them into the caller's workspace. When no extension is supplied, .mat is appended automatically. Set RUNMAT_LOAD_DEFAULT_PATH to override the default matlab.mat target 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 supports Level-5 double and single real/complex arrays, all eight native integer scalar and tensor classes, paired complex-integer components, logical arrays, character arrays, string arrays (stored as cell-of-char data), scalar structs, typed real sparse matrices, RunMat object envelopes, and cells whose elements are composed of the supported types. Integer class tags reconstruct authoritative native storage.
Little-endian, big-endian, and compressed (miCOMPRESSED) Level-5 MAT-files are supported. MATLAB v7.3 MAT-files are HDF5-backed and currently report an explicit unsupported-version error.

Does RunMat run `load` on the GPU?

GPU memory and residency

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)

Using `load` with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how load changes the result.

Run a small load example, explain the result, then change one input and compare the output.

FAQ

Does load support ASCII text files?⌄

How are structures handled?⌄

Does load call loadobj for saved objects?⌄

Yes for objects saved by RunMat. The MAT-file contains an internal object envelope; load restores nested payloads and dispatches registered static Class.loadobj methods when available.

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.

Mat

matfile · save

Net

accept · read · readline · tcpclient · tcpserver · write

Repl Fs

Tabular

Audio

audioinfo · audioread

Io

clc · diary · disp · display · format · input

Filetext

fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines

Hdf5

h5disp · h5info · h5read · h5write · h5writeatt · hdf5info · hdf5read · hdf5write

Import

importdata · textscan

Json

jsondecode · jsonencode

Http

sendmail · urldecode · urlencode · weboptions · webread · websave · webwrite

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how load is executed, line by line, in Rust.

View the source for load in Rust on GitHub
Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.

RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing

load — Load variables from MAT-files in MATLAB and RunMat.

Syntax

Inputs

Returns

Errors

How load works

Does RunMat run load on the GPU?

GPU memory and residency

Examples

Load the entire file into the workspace

Load a subset of variables by name

Load variables using regular expressions

Capture loaded variables in a struct without altering the workspace

Combine explicit names and regex filters

Honour a custom default filename

Load character and string data

Using load with coding agents

FAQ

Related Io functions

Mat

Net

Repl Fs

Tabular

Audio

Io

Filetext

Archive

Hdf5

Import

Json

Http

Open-source implementation

About RunMat

Download RunMat

load — Load variables from MAT-files in MATLAB and RunMat.

Syntax

Inputs

Returns

Errors

How load works

Does RunMat run load on the GPU?

GPU memory and residency

Examples

Load the entire file into the workspace

Load a subset of variables by name

Load variables using regular expressions

Capture loaded variables in a struct without altering the workspace

Combine explicit names and regex filters

Honour a custom default filename

Load character and string data

Using load with coding agents

FAQ

Related Io functions

Mat

Net

Repl Fs

Tabular

Audio

Io

Filetext

Archive

Hdf5

Import

Json

Http

Open-source implementation

About RunMat

Download RunMat

`load` — Load variables from MAT-files in MATLAB and RunMat.

How `load` works

Does RunMat run `load` on the GPU?

Using `load` with coding agents

`load` — Load variables from MAT-files in MATLAB and RunMat.

How `load` works

Does RunMat run `load` on the GPU?

Using `load` with coding agents