RunMat
GitHub

View all functions

CategoryIo: Mat

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 does the load function behave in MATLAB / RunMat?

  • 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 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.

GPU behavior

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 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 of using load in MATLAB / RunMat

Load the entire file into the workspace

load('results.mat');
disp(norm(weights))

Load a subset of variables by name

load('sim_state.mat', 'state', 'time');
plot(time, state)

Load variables using regular expressions

load('checkpoint.mat', '-regexp', '^layer_\\d+$')

Capture loaded variables in a struct without altering the workspace

S = load('snapshot.mat');
disp(fieldnames(S))

Combine explicit names and regex filters

model = load('model.mat', 'config', '-regexp', '^weights_(conv|fc)')

Honour a custom default filename

setenv('RUNMAT_LOAD_DEFAULT_PATH', fullfile(tempdir, 'autosave.mat'));
load()

Load character and string data

values = load('strings.mat', 'labels');
disp(values.labels(1))

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.

See also

save, who, fileread, matfile

Source & Feedback