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. It supports MATLAB-compatible variable selection, struct-field extraction, and option handling such as '-struct' and '-regexp'.

Syntax

status = save()
status = save(filename)
status = save(filename, varName1, varName2, ...)
status = save(filename, "-struct", structVar, field1, ...)
status = save(filename, "-regexp", pattern1, ...)

Inputs

Returns

Errors

How save works

• 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. With -append, RunMat reads the existing supported MAT variables, merges in the newly selected variables, and rewrites the file so newer variables replace older variables with the same name.
• Numeric/text format flags outside the MAT-file path (for example -ascii, -double, -v6, -v7.3) are not supported yet and report descriptive option errors.
• Function handles and opaque graphics handles raise descriptive errors. Numeric, logical, character, string, cell, scalar struct, real sparse data, and RunMat objects are stored using MATLAB Level-5 MAT-file layout. Objects are written through saveobj when registered and otherwise through an internal scalar-struct object envelope.
• save returns 0 so scripts can treat it as a statement, matching MATLAB's void behaviour.

Does RunMat run save on the GPU?

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 memory and 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

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

x = 1:5;
y = rand(1, 5);
opts = struct('output', y, '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$')

Append variables to an existing MAT-file

save('session.mat', 'x')
y = 2*x;
save('session.mat', 'y', '-append')

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')

Using save with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how save changes the result.

FAQ

Related Io functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how save is executed, line by line, in Rust.

• View the source for save in Rust on GitHub
• Learn how the RunMat runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 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.

Getting started · Benchmarks · Pricing