Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Define Input Properties Programmatically in the MATLAB File

With MATLAB® Coder™, you use the MATLAB assert function to define properties of primary function inputs directly in your MATLAB file.

How to Use assert with MATLAB Coder

Use the assert function to invoke standard MATLAB functions for specifying the class, size, and complexity of primary function inputs.

You must use one of the following methods when specifying input properties using the assert function. Use the exact syntax that is provided; do not modify it.

Specify Any Class

assert ( isa ( param, 'class_name') )

Sets the input parameter param to the MATLAB class class_name. For example, to set the class of input U to a 32-bit signed integer, call:

... 
assert(isa(U,'int32'));
...

If you set the class of an input parameter to fi, you must also set its numerictype, see Specify numerictype of Fixed-Point Input. You can also set its fimath properties, see Specify fimath of Fixed-Point Input. If you do not set the fimath properties, codegen uses the MATLAB default fimath value.

If you set the class of an input parameter to struct, you must specify the properties of all fields in the order that they appear in the structure definition.

Specify fi Class

assert ( isfi ( param ) )
assert ( isa ( param, 'embedded.fi' ) )

Sets the input parameter param to the MATLAB class fi (fixed-point numeric object). For example, to set the class of input U to fi, call:

... 
assert(isfi(U));
...

or

...
assert(isa(U,'embedded.fi'));
...

If you set the class of an input parameter to fi, you must also set its numerictype, see Specify numerictype of Fixed-Point Input. You can also set its fimath properties, see Specify fimath of Fixed-Point Input. If you do not set the fimath properties, codegen uses the MATLAB default fimath value.

Specify Structure Class

assert ( isstruct ( param ) )
assert ( isa ( param, 'struct' ) )

Sets the input parameter param to the MATLAB class struct (structure). For example, to set the class of input U to a struct, call:

...
assert(isstruct(U));
...

or

...
assert(isa(U, 'struct'));
...

If you set the class of an input parameter to struct, you must specify the properties of all fields in the order they appear in the structure definition.

Specify Fixed Size

assert ( all ( size (param) == [dims ] ) )

Sets the input parameter param to the size specified by dimensions dims. For example, to set the size of input U to a 3-by-2 matrix, call:

...
assert(all(size(U)== [3 2]));
...

Specify Scalar Size

assert ( isscalar (param ) )
assert ( all ( size (param) == [ 1 ] ) )

Sets the size of input parameter param to scalar. To set the size of input U to scalar, call:

...
assert(isscalar(U));
...

or

...
assert(all(size(U)== [1]));
...

Specify Upper Bounds for Variable-Size Inputs

assert ( all(size(param)<=[N0 N1 ...]));
assert ( all(size(param)<[N0 N1 ...]));

Sets the upper-bound size of each dimension of input parameter param. To set the upper-bound size of input U to be less than or equal to a 3-by-2 matrix, call:

assert(all(size(U)<=[3 2]));

    Note:   You can also specify upper bounds for variable-size inputs using coder.varsize.

Specify Inputs with Fixed- and Variable-Size Dimensions

assert ( all(size(param)>=[M0 M1 ...]));
assert ( all(size(param)<=[N0 N1 ...]));

When you use assert(all(size(param)>=[M0 M1 ...])) to specify the lower-bound size of each dimension of an input parameter:

  • You must also specify an upper-bound size for each dimension of the input parameter.

  • For each dimension, k, the lower-bound Mk must be less than or equal to the upper-bound Nk.

  • To specify a fixed-size dimension, set the lower and upper bound of a dimension to the same value.

  • Bounds must be non-negative.

To fix the size of the first dimension of input U to 3 and set the second dimension as variable size with upper-bound of 2, call:

assert(all(size(U)>=[3 0]));
assert(all(size(U)<=[3 2]));

Specify Size of Individual Dimensions

assert (size(param, k)==Nk);
assert (size(param, k)<=Nk);
assert (size(param, k)<Nk);

You can specify individual dimensions as well as specifying all dimensions simultaneously or instead of specifying all dimensions simultaneously. The following rules apply:

  • You must specify the size of each dimension at least once.

  • The last dimension specification takes precedence over earlier specifications.

Sets the upper-bound size of dimension k of input parameter param. To set the upper-bound size of the first dimension of input U to 3, call:

assert(size(U,1)<=3)

To fix the size of the second dimension of input U to 2, call:

assert(size(U,2)==2)

Specify Real Input

assert ( isreal (param ) )

Specifies that the input parameter param is real. To specify that input U is real, call:

...
assert(isreal(U));
...

Specify Complex Input

assert ( ~isreal (param ) )

Specifies that the input parameter param is complex. To specify that input U is complex, call:

...
assert(~isreal(U));
...

Specify numerictype of Fixed-Point Input

assert ( isequal ( numerictype ( fiparam ), T ) )

Sets the numerictype properties of fi input parameter fiparam to the numerictype object T. For example, to specify the numerictype property of fixed-point input U as a signed numerictype object T with 32-bit word length and 30-bit fraction length, use the following code:

%#codegen
...
% Define the numerictype object.
T = numerictype(1, 32, 30);

% Set the numerictype property of input U to T.
assert(isequal(numerictype(U),T));
...

Specify fimath of Fixed-Point Input

assert ( isequal ( fimath ( fiparam ), F ) )

Sets the fimath properties of fi input parameter fiparam to the fimath object F. For example, to specify the fimath property of fixed-point input U so that it saturates on integer overflow, use the following code:

%#codegen
...
% Define the fimath object.
F = fimath('OverflowMode','saturate');

% Set the fimath property of input U to F.
assert(isequal(fimath(U),F));
... 

If you do not specify the fimath properties using assert, codegen uses the MATLAB default fimath value.

Specify Multiple Properties of Input

assert ( function1 ( params ) && 
         function2 ( params ) && 
         function3 ( params ) && ... )

Specifies the class, size, and complexity of one or more inputs using a single assert function call. For example, the following code specifies that input U is a double, complex, 3-by-3 matrix, and input V is a 16-bit unsigned integer:

%#codegen
...
assert(isa(U,'double') && 
       ~isreal(U) && 
       all(size(U) == [3 3]) && 
       isa(V,'uint16'));
... 

Rules for Using assert Function

When using the assert function to specify the properties of primary function inputs, follow these rules:

  • Call assert functions at the beginning of the primary function, before control-flow operations such as if statements or subroutine calls.

  • Do not call assert functions inside conditional constructs, such as if, for, while, and switch statements.

  • Use the assert function with MATLAB Coder only for specifying properties of primary function inputs before converting your MATLAB code to C/C++ code.

  • If you set the class of an input parameter to fi, you must also set its numerictype. See Specify numerictype of Fixed-Point Input. You can also set its fimath properties. See Specify fimath of Fixed-Point Input. If you do not set the fimath properties, codegen uses the MATLAB default fimath value.

  • If you set the class of an input parameter to struct, you must specify the class, size, and complexity of all fields in the order that they appear in the structure definition.

  • When you use assert(all(size(param)>=[M0 M1 ...])) to specify the lower-bound size of each dimension of an input parameter:

    • You must also specify an upper-bound size for each dimension of the input parameter.

    • For each dimension, k, the lower-bound Mk must be less than or equal to the upper-bound Nk.

    • To specify a fixed-size dimension, set the lower and upper bound of a dimension to the same value.

    • Bounds must be non-negative.

  • If you specify individual dimensions, the following rules apply:

    • You must specify the size of each dimension at least once.

    • The last dimension specification takes precedence over earlier specifications.

Specifying General Properties of Primary Inputs

In the following code excerpt, a primary MATLAB function mcspecgram takes two inputs: pennywhistle and win. The code specifies the following properties for these inputs:

InputPropertyValue
pennywhistleclassint16
size220500-by-1 vector
complexityreal (by default)
winclassdouble
size1024-by-1 vector
complexityreal (by default)

%#codegen
function y = mcspecgram(pennywhistle,win)
nx = 220500;
nfft = 1024;
assert(isa(pennywhistle,'int16'));
assert(all(size(pennywhistle) == [nx 1]));
assert(isa(win, 'double'));
assert(all(size(win) == [nfft 1]));
...

Alternatively, you can combine property specifications for one or more inputs inside assert commands:

%#codegen
function y = mcspecgram(pennywhistle,win)
nx = 220500;
nfft = 1024;
assert(isa(pennywhistle,'int16') && all(size(pennywhistle) == [nx 1]));
assert(isa(win, 'double') && all(size(win) == [nfft 1]));
...

Specifying Properties of Primary Fixed-Point Inputs

To specify fixed-point inputs, you must install Fixed-Point Designer™ software.

In the following example, the primary MATLAB function mcsqrtfi takes one fixed-point input x. The code specifies the following properties for this input.

PropertyValue
classfi
numerictypenumerictype object T, as specified in the primary function
fimathfimath object F, as specified in the primary function
sizescalar
complexityreal (by default)

function y = mcsqrtfi(x) %#codegen
T = numerictype('WordLength',32,'FractionLength',23,...
                'Signed',true);
F = fimath('SumMode','SpecifyPrecision',...
           'SumWordLength',32,'SumFractionLength',23,...
           'ProductMode','SpecifyPrecision',...
           'ProductWordLength',32,'ProductFractionLength',23);
assert(isfi(x));
assert(isequal(numerictype(x),T));
assert(isequal(fimath(x),F));

y = sqrt(x);

Specifying Class and Size of Scalar Structure

Assume you have defined S as the following scalar MATLAB structure:

S = struct('r',double(1),'i',int8(4));

Here is code that specifies the class and size of S and its fields when passed as an input to your MATLAB function:

function y = fcn(S)  %#codegen


% Specify the class of the input as struct.
assert(isstruct(S));

% Specify the class and size of the fields r and i
% in the order in which you defined them.
assert(isa(S.r,'double'));
assert(isa(S.i,'int8');
...

In most cases, when you don't explicitly specify values for properties, MATLAB Coder uses defaults — except for structure fields. The only way to name a field in a structure is to set at least one of its properties. As a minimum, you must specify the class of a structure field

Specifying Class and Size of Structure Array

For structure arrays, you must choose a representative element of the array for specifying the properties of each field. For example, assume you have defined S as the following 2-by-2 array of MATLAB structures:

S = struct('r',{double(1), double(2)},'i',{int8(4), int8(5)});

The following code specifies the class and size of each field of structure input S using the first element of the array:

%#codegen
function y = fcn(S)

% Specify the class of the input S as struct.
assert(isstruct(S));

% Specify the size of the fields r and i
% based on the first element of the array.
assert(all(size(S) == [2 2]));
assert(isa(S(1).r,'double'));
assert(isa(S(1).i,'int8'));

The only way to name a field in a structure is to set at least one of its properties. As a minimum, you must specify the class of all fields.

Was this topic helpful?