UsersGuideExampleApplication

Toy Example Application

The example application consists of four modules that perform very simple calculations on numbers or vectors. The emphasis of this example is on

• introducing the GUI to the batch system
• discussing different ways to describe inputs and outputs of a module

The application is not included in the default setup of the batch system. To use it, locate the installation folder of the matlabbatch software on your computer (e.g. by running

which cfg_util

in the MATLAB command window). If the batch GUI is not yet started, run

cfg_ui

in the MATLAB command window. Once the user interface is running, select Add application from the File menu and add the application examples/cfg_example_master.m. After that, a new menu Toy Example should appear in the user interface.

Modules

The example consists of different modules that perform simple computations:

• Add exactly two numbers: a + b
• Sum over a vector: sum(v), cumsum(v)
• Integer divide: mod(a,b) and rem(a,b)

To demonstrate the programming concepts for batch configurations, there are different implementations of the Add and Cumsum modules. In a real application, these modules would correspond to algorithms that solve your real-world problems.

A first Example

Select Add1 from the Add 2 Numbers menu. The module will now appear in the module list, and its details are displayed as current module. Two inputs have to be entered: Input a and Input b. After entering two numbers, the Play button will turn green, since all inputs are set and Add1 is ready to run. When the job is run, the following output appears in the MATLAB command window:

-----------------------------------------------------------------------
Running job #1
-----------------------------------------------------------------------
Running 'Add1'
Done    'Add1'
Done

The header contains an internal job number. Below, the name of each executed module follows, along with possible command line output of the module. If the job finished without error, the last line will read "Done". Otherwise, a list of failed modules follows, together with the corresponding MATLAB error messages.

Access Job Output

Although the example job finished, the result (i.e. the sum of the two numbers) is not passed automatically to MATLAB workspace. (In real applications, most computation results will probably be saved to some file, and the filename would be of interest to work with.) In this example, one can use Pass Output to Workspace from BasicIO to fetch the result from Add1. The Output Item should be set as a dependency:

The output variable name can be any valid MATLAB variable name - if an invalid name is entered, the batch system will print a runtime warning and refuse to execute Pass Output to Workspace:

-----------------------------------------------------------------------
Running job #1
-----------------------------------------------------------------------
Contents of 'name' does not meet check criteria:
'String '12' is not a valid variable name.'
Running 'Add1'
Done    'Add1'
Contents of 'name' does not meet check criteria:
'String '12' is not a valid variable name.'
No executable modules, but still unresolved dependencies or incomplete module inputs.
The following modules did not run:
Skipped: Pass Output to Workspace

As soon as a valid variable name is entered and the job is started again, both modules will be run, and the result will be accessible in the MATLAB command window.

A more complex Example

Now think of a computation like

result = mod(a+b,c);

In a batch, one would first compute a+b using one of the Add modules, pass the result on to the Div module and finally pass the mod output on to the workspace (see examples/batch_example_add1_div.m). This batch has three input items that need to be filled - the values for a, b, c.
If the computation should be

result = mod(a+b,b);

one can still use the batch above. However, a better structure is described in the next section.

Reusing Inputs

So far, the batch does not reflect the condition that b and c should be the same. Named Input from BasicIO allows to pass its input value as a dependency. The resulting batch is examples/batch_example_add1_div_reuse_b.m. There, neither Add1 and Div have open inputs anymore, because both values are entered as Named Input and passed on via dependencies.

Job Templates and Scripting

Until now, the batches were created and run through the GUI. For a small number of datasets at a time this is the easiest way to run batches. However, if data processing has to be integrated in a workflow that does not allow direct user interaction, other solutions are necessary. The batch system addresses these needs with the command line interface to cfg_util, the main configuration management utility. In a batch processing script, the following information needs to be collected:

• The script or MATLAB variable that describes the job. This can be a single job, or a cell array of jobs (e.g. 100 copies of a template job that has to be applied to 100 different data sets).
• The inputs (marked with <-X) to each of the jobs, in the order they appear in the jobs. Inputs which are already set in the template can not be changed. If a pre-set input has to be changed, the GUI can be used to clear its value using Clear Value from Edit menu.

The following code shows how to run examples/batch_example_add1_div_reuse_b.m from a MATLAB script or function:

% load batch from saved script - replace /path_to with the path to your matlabbatch installation
jobid = cfg_util('initjob', '/path_to/examples/batch_example_add1_div_reuse_b.m');
% fill in missing values for a = 3, b = 4
cfg_util('filljob', jobid, 3, 4);
% run job
cfg_util('run', jobid)

To run the computation N times on different inputs, a slightly modified batch is used which places the results in varying output variables:

% loop to assemble batch jobs (N) and inputs (3*N)
jobs   = cell(1,N);
inputs = cell(3,N); % first dimension within job, second across jobs - inputs{:} expands to inputs for job1, followed by job2 ...
for k = 1:N
    jobs{k} = 'batch_example_add1_div_reuse_b_outname.m';
    inputs{1,k} = round(10*rand(1));
    inputs{2,k} = round(10*rand(1));
    inputs{3,k} = sprintf('result%d', k);
end
% load batch from jobs variable
jobid = cfg_util('initjob', jobs);
% fill in missing values
cfg_util('filljob', jobid, inputs{:});
% run job
cfg_util('run', jobid)