- 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.
|