load — Load variables from a Level-5 MAT-file.
S = load(filename) returns a scalar struct containing selected variables. A zero-output statement load(filename) instead assigns the selected variables into the caller workspace. Bare load() uses matlab.mat or the RUNMAT_LOAD_DEFAULT_PATH override.
Syntax
S = load()
S = load(filename)
S = load(filename, varName1, varName2, ...)
S = load(filename, '-regexp', pattern1, ...)
S = load(option, value, ...)Inputs
filename- Type
StringScalar- Required
- Yes
- Default
"matlab.mat"- Description
- Level-5 MAT-file path.
varName- Type
StringScalar- Required
- Variadic
- Description
- Whole variable names.
option- Type
StringScalar- Required
- Yes
- Description
- Supported MAT selection or save option.
pattern- Type
StringScalar- Required
- Variadic
- Description
- Regular-expression patterns.
Returns
S- Type
Any- Description
- Scalar struct of loaded variables; zero-output calls assign workspace bindings.
Returned values from load depend on how many outputs the caller requests.
Errors
RunMat:load:InvalidArgument- When
- Inputs are not a supported load form.
- Message
load: invalid argument
RunMat:load:InvalidOption- When
- A load option or selector is invalid.
- Message
load: invalid option
RunMat:load:Filename- When
- The MAT path is invalid.
- Message
load: invalid filename
Selection and outputs
Use variable names after the filename, or -regexp with one or more patterns. -mat is accepted; ASCII/text loading and HDF5-backed v7.3 MAT-files are not supported. A missing requested variable or invalid regex raises a typed error. The zero-output form overwrites matching workspace bindings; capturing one output does not mutate the workspace. More than one output rejects before reading the file.
A filename without an extension gains .mat. The default path is read from RUNMAT_LOAD_DEFAULT_PATH only for the bare/default form. Relative paths use the provider and working folder captured for this invocation.
Values and layout
The Level-5 reader restores real and complex single/double values; all eight signed/unsigned integer classes with exact storage; logical, character, string, cell, structure, and sparse arrays; and RunMat typed object records. Shapes and column-major order are retained, including empty structure schemas. Registered static Class.loadobj callbacks restore saved objects.
Decoded values are host-resident. Saving a GPU value materializes it through its owner; loading that file does not create a GPU allocation. Use gpuArray explicitly if a device result is required.
Execution
Input bytes are obtained from the captured filesystem provider. Large or compressed files, restoration callbacks, and workspace publication can use substantially more host memory than the file size. Check available memory before loading large or untrusted MAT files.
Examples
Load into the caller workspace
weights = [0.5, 1.0, 1.5];
save('results.mat', 'weights');
clear weights;
load('results.mat');
disp(norm(weights))Select variables by name
time = 0:0.25:1;
state = [0, 0.5, 0.8, 0.6, 0.3];
save('sim_state.mat', 'time', 'state');
clear time state;
load('sim_state.mat', 'state', 'time');
plot(time, state)Select variables with a regular expression
layer_1 = ones(4, 4);
layer_2 = ones(8, 8);
save('checkpoint.mat', 'layer_1', 'layer_2');
S = load('checkpoint.mat', '-regexp', '^layer_\d+$')Capture a struct without workspace mutation
x = 3.14;
y = 2.72;
save('snapshot.mat', 'x', 'y');
S = load('snapshot.mat');
disp(fieldnames(S))Combine names and regex filters
config = struct('lr', 0.01);
weights_conv = ones(3, 3);
weights_fc = ones(4, 2);
save('model.mat', 'config', 'weights_conv', 'weights_fc');
model = load('model.mat', 'config', '-regexp', '^weights_(conv|fc)')Use a custom default MAT path
x = 0;
save('autosave.mat', 'x');
previous = getenv('RUNMAT_LOAD_DEFAULT_PATH');
setenv('RUNMAT_LOAD_DEFAULT_PATH', 'autosave.mat');
S = load();
if isempty(previous), unsetenv('RUNMAT_LOAD_DEFAULT_PATH'); else, setenv('RUNMAT_LOAD_DEFAULT_PATH', previous); endLoad character data
labels = 'hello';
save('strings.mat', 'labels');
values = load('strings.mat', 'labels');
disp(values.labels)Expected output:
helloUsing 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?⌄
No. RunMat currently reads Level-5 MAT-files only; load(filename, '-ascii') and automatic ASCII loading are a coverage gap. Use text I/O utilities such as readmatrix or readtable.
How are structures handled?⌄
Scalar and array structures retain field schema, dimensions, and column-major element order, including empty schemas. Nested cells, logical, sparse, and typed object values are supported. A struct's field names never grant it object identity.
Does load call loadobj for saved objects?⌄
Yes. RunMat typed object records dispatch registered static Class.loadobj methods during restoration when available.
Will load overwrite existing variables?⌄
A zero-output call assigns matching names in the caller workspace. S = load(...) returns a struct without those assignments.
What if a requested variable is missing?⌄
The call raises a selection error naming the missing variable.
Can I load into another workspace?⌄
load targets the caller workspace in its statement form. Capture a struct and assign explicitly when a different scope is needed.
How are GPU arrays handled?⌄
Saved resident values are materialized to host data. Loaded values remain host-resident until an explicit device conversion or later acceleration.
How do I inspect loaded names?⌄
Capture the struct output and use fieldnames or isfield.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · filesep · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · memmapfile.subsasgn · memmapfile.subsref · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · getvaropts · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · setvaropts · setvartype · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Data
commit · data.copy · data.create · data.delete · data.exists · data.export · data.import · data.inspect · data.list · data.move · data.open · DataArray.chunk_shape · DataArray.codec · DataArray.dtype · DataArray.fill · DataArray.name · DataArray.rank · DataArray.read · DataArray.resize · DataArray.shape · DataArray.write · Dataset.array · Dataset.arrays · Dataset.attrs · Dataset.begin · Dataset.get_attr · Dataset.has_array · Dataset.id · Dataset.path · Dataset.refresh · Dataset.set_attr · Dataset.set_attrs · Dataset.snapshot · Dataset.version · DataTransaction.abort · DataTransaction.commit · DataTransaction.create_array · DataTransaction.delete_array · DataTransaction.fill · DataTransaction.id · DataTransaction.resize · DataTransaction.set_attr · DataTransaction.set_attrs · DataTransaction.status · DataTransaction.write
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.