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)
sys = sml_system;
fS = 10 ;
sub = sml_system('Sources');
state = [];
state .data = randn (3 ,fS ) + i * randn (3 ,fS );
state .repeat = true ;
sub = sub .addprocess('sourceNumeric', 'std/2009/source/numeric ', fS , state );
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 ;
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 ];
sub = sub .expose('sourceNumeric>out', 'out');
sys = sys .addsubsystem('sub', sub );
state = [];
state .order = 1 ;
sys = sys .addprocess('resampleNumeric', 'std/2009/resample/numeric ', fS * 2 , 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 );
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');
exe = brahms_execution ;
exe .stop = 1 ;
exe .all = true ;
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 ;
sub = sml_system;
state = [];
cls = 'std/2009/math/esum ';
for i = 1 :3
name = ['sum' int2str (i )];
sub = sub .addprocess(name , cls , fS , state );
sub = sub .expose([name '<in'], 'in');
end
sub = sub .expose('sum3>out', 'out');
sys = sml_system;
sys = sys .addsubsystem('sub', sub );
state = [];
state .data = 1 :fS ;
cls = 'std/2009/source/numeric ';
sys = sys .addprocess('src', cls , fS , state );
sys = sys .link('src>out', 'sub<in');
state = [];
cls = 'std/2009/math/esum ';
sys = sys .addprocess('dst', cls , fS , state );
sys = sys .link('sub>out', 'dst');
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)
X = log.X(:, end);
sz = size(log.X);
X = log.X(:, sz(end));
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.
|