RunMat
GitHub

View all functions

CategoryIo: Mat

What does the load function do in MATLAB / RunMat?

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.

load Function GPU Execution Behaviour

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.

Examples of using the load function in MATLAB / RunMat

Load the entire file into the workspace

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

Expected outcome: every variable contained in results.mat becomes available in the caller's workspace.

Load a subset of variables by name

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

Only state and time are created; other variables in the file are ignored.

Load variables using regular expressions

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

All variables whose names look like layer_0, layer_1, … are loaded.

Capture loaded variables in a struct without altering the workspace

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

S contains one field per variable stored in snapshot.mat, leaving the workspace untouched.

Combine explicit names and regex filters

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

The returned struct includes the config variable and every weight matrix whose name matches either weights_conv or weights_fc.

Honour a custom default filename

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

With no arguments, load falls back to the file specified by RUNMAT_LOAD_DEFAULT_PATH.

Load character and string data

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

String arrays saved by RunMat are reconstructed faithfully from the underlying MAT-file representation.

GPU residency in RunMat (Do I need gpuArray?)

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.

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