SystemML Class
std/2009/source/numeric
Summary
Source of explicitly-specified numeric data
Status
Stable

Overview

A source of explicitly-specified numeric data. The data to be output is specified as part of the parametrisation of the process, either explicitly (Explicit Mode) or as a filename of a binary data file containing the data (File Mode).

Notes
  • Please see Usage Notes at the bottom of this page.

Connectivity

  • No inputs.
  • One output, the data provided.

State

This Process stores its State in DataML.

Explicit Mode

data (UINT32)
A numeric array holding the data to be output. The numeric type and complexity of the data output will be implied from the type of data supplied; its leading dimensions will give the dimensions of the output, and its last dimension the number of samples available. Hence, to supply 10 samples of [3x2] data, this parameter should be of size [3x2x10].
ndims (UINT32 scalar) OPTIONAL
Intended dimensionality of the output data (rarely required; see Usage Notes for Matlab).

File Mode

Note that in File Mode, data, type and dims (and inferred complexity, and sourceIsAdjacent if present) deliver exactly what data delivers in Explicit Mode. Once this has been read in, behaviour is identical to Explicit Mode (i.e. the last dimension is interpreted as sample number).

data (STRING)
A filename of a binary file containing the data to be output. The file must be one of two expected sizes, given type and dims (the complexity of the data is inferred from the size of the file).
type (STRING)
Explicit primitive Numeric Type, in the form (for instance), DOUBLE or INT64 or BOOL8.
dims (INT64 1xN)
Explicit dimensions. Note that this is the dimensions of the source data only; if you wish to use start and stop, this value should not be changed.
sourceIsAdjacent (BOOL) OPTIONAL
If true, and the source file is complex, it is assumed to be organised as two adjacent blocks (all real data, then all imaginary data). Otherwise, the source file is assumed to be organised in interleaved form (all real data for sample 1, all imaginary data for sample 1, all real data for sample 2, ...).

All Modes

start (INT64 scalar) OPTIONAL
If present, the first source sample available is as specified (zero-based, so default is zero). start and stop are particularly useful if you are using File Mode, and you want to source data from different places in a large file without rewriting the file every time.
stop (INT64 scalar) OPTIONAL
If present, the first source sample not available is as specified (zero-based, so default is the number of source samples present in data).
next (INT64 scalar) OPTIONAL
If present, the first source sample to be output (must fall between start and stop).
repeat (BOOLEAN scalar) OPTIONAL
If true, the Process will begin using the provided data again when it runs out (i.e. when next reaches the value of stop). If false (default), the Process will raise an exception when it runs out of data.
complex (BOOLEAN scalar) OPTIONAL
If present, the Process will produce output at the specified complexity rather than using the complexity inferred from data, outputting zero as imaginary data or discarding imaginary data, as required. If empty (default), the output complexity is inferred from the source complexity.
outputName (STRING) OPTIONAL
If supplied, the name of the single output (if not, "out" is used).

Example

Below, we illustrate Explicit Mode. For an example of File Mode usage, see brahms_test filemode.

Script

M Source Code (against 995)
fS = 3; sys = sml_system; state = []; state.data = [1 2 3]'; state.repeat = true; sys = sys.addprocess('src1', 'std/2009/source/numeric', fS, state); state = []; state.data = uint8([1 2 3 4; 5 6 7 8]); sys = sys.addprocess('src2', 'std/2009/source/numeric', fS, state); state = []; state.data = uint32(complex(8, 3)); state.repeat = true; sys = sys.addprocess('src3', 'std/2009/source/numeric', fS, state); exe = brahms_execution; exe.all = true; exe.stop = 1; out = brahms(sys, exe); out.src1.out out.src2.out out.src3.out

Expected Output

Matlab Console
ans = 1 1 1 2 2 2 3 3 3 ans = 1 2 3 5 6 7 ans = Columns 1 through 2 8 + 3i 8 + 3i Column 3 8 + 3i

Usage Notes

Complexity

The source complexity and output complexity are independent. If you do not specify the output complexity (parameter complex), it is set equal to the source complexity. If you set the output non-complex when the source is complex, the imaginary source data is discarded. If you set the output complex when the source is real, the imaginary output data is zero.

Range Parameters

Say N samples are present in the source data (e.g. you supply a data array of size [2x4xN]). By default, all the data is available, so start is zero, stop is N, and the reading starts from the first available sample (next is start). On each cycle, the data pointed to by next is output, and next is incremented. When the data runs out (next becomes equal to stop), next is either reset equal to start (if repeat is true), or an error is raised (if not).

If you explicitly set start to a new value, next starts at that value. If you explicitly set next, it starts where you set it. The internal logic is as shown below.

C/C++ Source Code
start = state_get("start", default = 0); stop = state_get("stop", default = N); next = state_get("next", default = start); case EVENT_RUN_SERVICE: { if (next == stop) { if (!repeat) error("data has run out"); next = start; } output_nth_sample(next); next++; }

Use from Matlab

Trailing Scalar Dimensions

Matlab trims trailing scalar dimensions from any matrix, since this does not change it arithmetically (try size(ones(4,3,2,1)) in Matlab). Some BRAHMS processes use dimension as valuable metadata, including this source process. If you pass a [4x3x2x1] matrix as the data parameter (below) through the Matlab DataML converter (i.e. if you use the 995 invocation bindings), this will be passed to the process as a [4x3x2] matrix, and provide 2 samples of data of size [4x3] instead of 1 sample of data of size [4x3x2]. To work around this, you can set the ndims parameter (in this case, to three) to explicitly specify the output dimension of the process (missing trailing scalar dimensions are, thus, implied).

This problem occurs most often when you wish to output a single column vector with the same value at every sample. You will pass in an [Nx1] matrix, and it will be trimmed by the DataML converter to be a matrix of dimension [N]; this is an invalid parameter for this process since it requires a trailing dimension to represent sample number. Since the inferred conditions are invalid, the process can, without ambiguity, assume in this case that there is one missing trailing scalar dimension. If more trailing scalar dimensions are missing, you should set ndims explicitly. If the missing dimension is not scalar, you have supplied a data matrix of the wrong size.

Complexity

You may wish to output complex data but, in some instances, the imaginary part of that data may be zero. Matlab will automatically truncate such matrices to be non-complex, following any operation. Therefore, note that you can force a complex representation of non-complex data in Matlab using the syntax complex(X), and pass that to the bindings for passing to the process as the data parameter.