RunMat
GitHub

View all functions

CategoryIo: Mat

save — Persist variables from the current workspace to a MATLAB-compatible MAT-file.

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.

GPU behavior

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.

GPU residency

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.

Examples of using save in MATLAB / RunMat

Save the entire workspace

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

Save selected variables only

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

Save struct fields as individual variables

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

Select variables by regular expression

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

Save multiple names using a string array

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

Save GPU arrays without manual gather

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

Error when a variable is missing

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

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