Overview

The SystemML Matlab Bindings provide interfaces at the matlab prompt to a SystemML Document (sml_system) and to a ReportML Log (sml_log).

Interface to the SystemML Document

Interface with SystemML Documents is provided by the Matlab class sml_system. An object of this class represents a SystemML system in Matlab, and methods of this class permit building Systems out of Sub-Systems, Processes and Links, and (un)serialization of this object to (from) a SystemML document.

Building Systems

sys = sml_system
Create and return an empty system.
sys = sys.addsubsystem(name, subsys)
Add the Subsystem subsys (must be an sml_system) to the system sys, giving it the specified name.
sys = sys.removesubsystem(name)
Remove the named subsystem from the parent system.
sys = sys.addprocess(name, class, rate, state, seed)
Add a new process to the system, giving it the specified name, SystemML class, sample rate and initial state. If the process class you are adding has no state, state may be omitted (or pass the empty object []). If the process does not need a seed, seed can be omitted.
sys = sys.removeprocess(name)
Remove the named process from the parent system.
sys = sys.link(src, dst, lag)
sys = sys.link(name, src, dst, lag)
Add a link to the system from src to dst, where src and dst are Absolute Identifiers. Optionally, provide a name for the link itself as a reference (often, naming a link will serve no purpose). The optional final parameter lag specifies the lag on the link, which defaults to one (sample periods).
sys = sys.unlink(name)
sys = sys.unlink(src, dst)
Remove a link from the system, by name or by specification (src and dst).
sys = sys.expose(what, as)
sys = sys.expose(name, what, as)
Expose what as as, where what is a Relative Identifier of a Set or a Port and as is a Partial Identifier that must be compliant with the type of what. Optionally, provide a name for the expose itself as a reference (naming an expose will usually serve no purpose apart from improving error reporting).
sys = sys.unexpose(name)
sys = sys.unexpose(what, as)
Remove an expose from the system, by name or by specification (what and as).

Serialization

sys.serialize(filename)
Serialize the document to the specified file.
sys = sys.unserialize(filename)
NOT YET IMPLEMENTED Unserialize the document from the specified file.

Example

Here is an example of using the bindings to construct a system, which is then executed using BRAHMS.

M Source Code (against SystemML Matlab Bindings)
% construct empty SystemML system sys = sml_system; fS = 10; % construct SystemML Subsystem sub = sml_system('Sources'); % add a process state = []; state.data = randn(3,fS) + i * randn(3,fS); state.repeat = true; sub = sub.addprocess('sourceNumeric', 'std/2009/source/numeric', fS, state); % add a process (alternative grammar 1) sub = sub.addprocess('sourceRandom', 'std/2009/random/numeric', fS); state = []; state.dist = 'normal'; state.pars = [0 1]; state.dims = uint32([1]); state.complex = false; sub.sourceRandom.state = state; % add a process (alternative grammar 2) sub = sub.addprocess('sourceSpikes', 'std/2009/random/spikes', fS); sub.sourceSpikes.state.dist = 'exponential'; sub.sourceSpikes.state.streams = 10; sub.sourceSpikes.state.pars = [0.1 0.2]; % expose sub/sourceNumeric>out as sub>out sub = sub.expose('sourceNumeric>out', 'out'); % add Subsystem to main system sys = sys.addsubsystem('sub', sub); % add another process state = []; state.order = 1; sys = sys.addprocess('resampleNumeric', 'std/2009/resample/numeric', fS * 2, state); % add some processes that don't need state sys = sys.addprocess('product', 'std/2009/math/eproduct', fS); sys = sys.addprocess('sum', 'std/2009/math/esum', fS); sys = sys.addprocess('resampleSpikes', 'std/2009/resample/spikes', fS * 2); % add a link or two sys = sys.link('sub>out', 'product'); sys = sys.link('sub/sourceRandom>out', 'product'); sys = sys.link('product>out', 'sum'); sys = sys.link('product>out', 'sum'); sys = sys.link('sub/sourceRandom>out', 'resampleNumeric'); sys = sys.link('sub/sourceSpikes>out', 'resampleSpikes'); % construct execution (using 995) exe = brahms_execution; exe.stop = 1; exe.all = true; % if we weren't going to invoke BRAHMS, % we might want to serialize our system directly % sys.serialize('our_system.xml'); % but the BRAHMS Matlab bindings invoke % the serialize() method on the way so % we don't need to do it explicitly out = brahms(sys, exe);

Example

Here is an example that uses expose to link multiple inputs to a single system input.

M Source Code (against SystemML Matlab Bindings)
fS = 100; % child system sub = sml_system; % add sum blocks state = []; cls = 'std/2009/math/esum'; for i = 1:3 name = ['sum' int2str(i)]; sub = sub.addprocess(name, cls, fS, state); % expose all sum inputs on the same system input sub = sub.expose([name '<in'], 'in'); end % expose sum3 output on the one system output sub = sub.expose('sum3>out', 'out'); % parent system sys = sml_system; % add sub system sys = sys.addsubsystem('sub', sub); % add src state = []; state.data = 1:fS; cls = 'std/2009/source/numeric'; sys = sys.addprocess('src', cls, fS, state); % link src to subsystem input sys = sys.link('src>out', 'sub<in'); % add dst state = []; cls = 'std/2009/math/esum'; sys = sys.addprocess('dst', cls, fS, state); % link subsystem output to dst sys = sys.link('sub>out', 'dst'); % execute exe = brahms_execution; exe.all = true; exe.stop = 1; out = brahms(sys, exe, '--show-expose');

Interface to Logs

Interface to ReportML Logs is provided by the Matlab class sml_log. An object of this class represents a ReportML Log in Matlab, and methods of this class permit the client to access (read) the Log. Note that Logs are read-only. An sml_log object is, usually, returned to you from the BRAHMS Matlab Invocation Bindings, for instance.

Notes
  • The purpose of this object is to provide a thin layer between log files and the client that manages loading of log data in a read-on-demand fashion. This aside, it behaves as if it were the data object itself.

Read Logs

X = log.X
Load the entire log field "X", and return it. This may take a long time for large log files.
X = log.X(a, b, ...)
Load the indexed portion of the log field "X", and return it. This reads just the parts of the log file necessary to return this data, and is thus much faster than loading the whole log, and indexing that.
sz = fieldsize(log, 'X')
Return the dimensions of the field "X", without loading the data.
X = struct(log)
Convert the log object into a normal structure object (i.e. load all data and return it).

Gotchas

Some Matlab calls will implicitly call the first of the above forms in order to complete. These calls, thus, lose the efficiency gains of the sml_log object. Consider using the alternative approaches listed below, which take advantage of the method fieldsize().

M Source Code (against SystemML Matlab Bindings)
% load the whole data file, measure its size, % then obtain just the last column X = log.X(:, end); % another code snippet that does exactly the % same thing as the one above sz = size(log.X); X = log.X(:, sz(end)); % an alternative code snippet that takes % advantage of the fieldsize() method to % achieve the same thing much more efficiently sz = fieldsize(log, 'X'); X = log.X(:, sz(end));

Miscellaneous

sml_utils
Provides basic utilities. Currently, installed Toolbox version.

Try help sml_utils at the Matlab prompt.