RunMat
GitHub

View all functions

CategoryIo: Mat

What does the save function do in MATLAB / RunMat?

save writes variables from the current workspace to a MAT-file on disk. RunMat mirrors MATLAB semantics for choosing variables, handling structs, pattern-based selection via '-regexp', and processing options such as '-struct'.

How does the save function behave in MATLAB / RunMat?

  • save with no arguments writes every variable from the caller workspace to matlab.mat in the current working directory. Set RUNMAT_SAVE_DEFAULT_PATH to override the default target when no filename is supplied.
  • save filename writes all workspace variables to filename. If the supplied name has no extension, .mat is added automatically. Paths are resolved relative to the current directory, and parent folders must already exist.
  • save(filename, 'A', 'B') writes only the listed variables. String arrays or cell arrays of character vectors are accepted to specify multiple names.
  • save(filename, '-struct', 'S') saves each field of struct S as a separate variable. Provide additional field names ('field1', 'field2') to restrict the set.
  • save filename -regexp '^foo' 'bar$' saves every variable whose name matches any of the supplied regular expressions.
  • Existing files are overwritten unless -append is specified. RunMat currently reports an error when -append or other numeric/text format flags (for example -ascii, -double, -v6, -v7.3) are requested.
  • Unsupported types (function handles, objects, opaque graphics handles) raise descriptive errors. Numeric, logical, character, string, cell, and struct data are stored using MATLAB Level-5 MAT-file layout.
  • save returns 0 so scripts can treat it as a statement, matching MATLAB's void behaviour.

save Function GPU Execution Behaviour

save acts as a residency sink. Before serialising, RunMat gathers any GPU-resident tensors through the active acceleration provider so the MAT-file contains host data. Fusion groups terminate at this builtin and providers do not require custom hooks.

Examples of using the save function in MATLAB / RunMat

Save the entire workspace

x = 42;
y = magic(3);
save('session.mat');

Expected result: session.mat appears in the current folder containing both x and y.

Save selected variables only

a = rand(1, 3);
b = eye(2);
c = "ignore me";
save('selection.mat', 'a', 'b');

Expected result: the MAT-file stores a and b; c is omitted.

Save struct fields as individual variables

opts.output = y;
opts.answer = x;
save('opts.mat', '-struct', 'opts');

Expected result: the file contains variables output and answer populated from the struct fields.

Select variables by regular expression

result_acc = 1:3;
result_tmp = 4:6;
scratch = pi;
save('filtered.mat', '-regexp', '^result_', 'tmp$');

Expected result: only result_acc and result_tmp are saved because their names match the patterns.

Save multiple names using a string array

names = ["result_acc", "scratch"];
save('mixed.mat', names);

Expected result: both variables listed in names are written to mixed.mat.

Save GPU arrays without manual gather

G = gpuArray(magic(3));
save('gpu.mat', 'G');

Expected result: gpu.mat contains a standard double-precision matrix named G; RunMat gathered the gpuArray to host memory automatically.

Error when a variable is missing

save('bad.mat', 'missing');

Expected error:

save: variable 'missing' was not found in the workspace

GPU residency in RunMat (Do I need gpuArray?)

No manual action is required. save gathers gpuArray inputs automatically before writing the MAT-file. This matches MATLAB's behaviour when gpuArray variables are passed to save.

FAQ

Which MAT-file version is generated?

RunMat writes Level-5 (MATLAB 5.0) MAT-files, compatible with MATLAB R2006b and later as well as NumPy/Scipy readers. Structures and cell arrays are stored using standard miMATRIX elements.

Is -append supported?

Not yet. The builtin currently reports save: -append is not supported to signal the limitation. Future releases will add incremental writing.

Do text options like -ascii or -double work?

These legacy text/binary format switches are not supported. RunMat favours MATLAB's default MAT-file format.

Are objects or function handles saved?

No. RunMat matches MATLAB by raising an error when unsupported types are encountered.

Does save return a value?

Yes. The builtin returns 0, which MATLAB treats as an empty output, so scripts can ignore the return value just as they do in MATLAB.

How do I change the default filename used by bare save?

Set the environment variable RUNMAT_SAVE_DEFAULT_PATH before launching RunMat. When save is called without explicit filename arguments, the builtin writes to that path instead of matlab.mat.

Does save create parent directories automatically?

No. Parent folders must already exist; otherwise the builtin raises an error from the host filesystem.

See Also

gpuArray, gather, fileread, fopen

Source & Feedback