Overview

By default, the outputs of your Process are logged (recorded) at every sample point of the process and, as you saw in the tutorials, you can access those outputs in the output structure returned to you when the execution completes. However, you can also explicitly set some (or all) outputs to be logged only at specific times (including periodically, during certain time windows, etc.). This is known as "windowed logging".

This can be helpful if, for example, one output of your Process is a very large array of numbers and you wish to track its progression only at a few time points rather than at every sample point. Or, you may wish to see what happens to a particular output only during a particular time period, where the behaviour is of interest.

This feature is also useful if your Process uses an internal variable that is a very large data structure and you wish to track its progression during the execution. You can simply create an output from your Process for that variable and log that output at only a few time points, e.g. on a regular period.

Notes
  • Specifying the windowed logs of an output of a Process does not affect how that Process interacts with other processes. For example, Process A may continue to pass data to Process B at 100Hz, whilst you log that data at only 10Hz.
  • Currently, all windows have to be specified explicitly in advance of execution. A possible future feature is some sort of triggering of on/off logging by processes at run-time.

Instants and windows

You can request that an individual output be logged by using the following syntax (in Matlab):

M Source Code (against 995)
exe = brahms_execution; exe = exe.log('process>output');

To have a particular time instant logged, and no other, use this syntax:

M Source Code (against 995)
exe = brahms_execution; exe = exe.log('process>output', {'window', '0.2'});

This will log the output at t=0.2 seconds, and turn off logging at all other sample times. To log in a particular time range, use this syntax:

M Source Code (against 995)
exe = brahms_execution; exe = exe.log('process>output', {'window', '0.2:0.4'});

This will log from 0.2 to 0.4 seconds. Note that the output for t=0.2 is logged, that for t=0.4 is not - to include the output at t=0.4 as well, specify the t=0.4 instant explicitly:

M Source Code (against 995)
exe = brahms_execution; exe = exe.log('process>output', {'window', '0.2:0.4,0.4'});

Any number of instants and ranges (referred to as 'window specifiers') can be included in this comma-separated string, to build up any pattern of logging you require.

Periodic logging

It may happen that you want to record the logs periodically. You could specify each window explicitly using the syntax outlined above, but that may make for a very long string (made up of many, individual, window specifiers). Alternatively, you can specify a periodic window by prepending a 'repeat specifier' to the window specifier. Examine the following:

M Source Code (against 995)
exe = brahms_execution; exe = exe.log('process>output', {'window', '@0:1:10,0.2:0.4'});

This will log the window t=0.2 seconds to t=0.4 seconds, and the window t=1.2 to t=1.4, etc., up until the last at t=9.2 to t=9.4. The sub-string beginning with the '@' character is the 'repeat specifier', which specifies ten time instants (t=0, t=1, ... t=9). The window specifier is then considered relative to each of those instants, such that ten windows are logged in total.

Complex examples

Formally, the whole string passed is made up of multiple, semicolon-separated, sub-strings. Each of these must begin with a repeat specifier, except the first, which may omit this, in which case the repeat specifier '@0' is assumed. Each sub-string then continues with one or more comma-separated window specifiers, either time instants or time ranges, which are computed relative to the repeat specifier.

Most window specifier cases will be very simple - to illustrate a complex case, consider the following taken from brahms_test window.

M Source Code (against 995)
window = '0.03,0.07:0.27; @0.33:0.1:0.63,0.02:0.04,0.06,0.08; @0.7:0.04:0.9,0.01'; exe = exe.log('src>out', {'window', window});

This example will log the output src>out at t=0.03, and at all samples between t=0.07 and t=0.27 (not including t=0.27). Then, for each of the time origins t=0.33, t=0.43, t=0.53, it will log the output at t_v=0.02 to t_v=0.04, along with the instants t_v=0.06 and t_v=0.08. Then, for each of the origins t=0.7, t=0.74, t=0.78, t=0.82, t=0.86, it will log the instant at t_v=0.01. Examine brahms_test window if this sordid explanation remains unclear.

Whole system

You can set windowing for the whole system - settings for individual logs will override it, if present. Just use, for instance:

M Source Code (against 995)
window = '0.03,0.07:0.27; @0.33:0.1:0.63,0.02:0.04,0.06,0.08; @0.7:0.04:0.9,0.01'; exe.window = window;