For code generation, you can use the MATLAB® assert function to define properties
of primary function inputs directly in your MATLAB file.
Use the assert function to invoke standard MATLAB functions for specifying the class, size, and complexity of
primary function inputs.
When specifying input properties using the assert function,
use one of the following methods. Use the exact syntax that is provided; do not
modify it.
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')); ...
assert ( isfi ( param ) ) assert ( isa ( param, 'embedded.fi' ) )
Sets the input parameter param to the MATLAB class fi (Fixed-Point Designer) (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')); ...
You must specify both the fi class and the numerictype (Fixed-Point Designer). See
Specify numerictype of Fixed-Point Input. You can also
set the fimath (Fixed-Point Designer) properties,
see Specify fimath of Fixed-Point Input. If you do not set
the fimath (Fixed-Point Designer) properties,
codegen uses the MATLAB default fimath value.
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 that they
appear in the structure definition.
assert(iscell( param)) assert(isa(param, 'cell'))
Sets the input parameter param to
the MATLAB class cell (cell array). For
example, to set the class of input C to a
cell, call:
... assert(iscell(C)); ...
or
... assert(isa(C, 'cell')); ...
To specify the properties of cell array elements, see Specifying Properties of Cell Arrays.
assert ( all ( size (param) == [dims ] ) )
Sets the input parameter param to
the size that dimensions dims
specifies. For example, to set the size of input U to
a 3-by-2 matrix, call:
... assert(all(size(U)== [3 2])); ...
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)); ...
... assert(all(size(U)== [1])); ...
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.
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 nonnegative.
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]));
assert (size(param,k)==Nk); assert (size(param,k)<=Nk); assert (size(param,k)<Nk);
You can specify individual dimensions and all dimensions simultaneously. You can also specify individual dimensions 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)
assert ( isreal (param ) )
Specifies that the input parameter
param is real. To specify
that input U is real,
call:
... assert(isreal(U)); ...
assert ( ~isreal (param ) )
Specifies that the input parameter
param is complex. To
specify that input U is complex,
call:
... assert(~isreal(U)); ...
assert ( isequal ( numerictype ( fiparam ), T ) )
Sets the numerictype properties of
fi input parameter
fiparam to the
numerictype (Fixed-Point Designer) 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)); ...
Specifying the numerictype for a variable does not
automatically specify that the variable is fixed point. You must specify
both the fi class and the
numerictype.
assert ( isequal ( fimath ( fiparam ), F ) )
Sets the fimath properties of fi
input parameter fiparam to the
fimath (Fixed-Point Designer) 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));
... fimath properties using
assert, codegen uses the
MATLAB default fimath value.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'));
... 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.
For a fixed-point input, you must specify both the fi class
and the numerictype (Fixed-Point Designer). See Specify numerictype of Fixed-Point Input.
You can also set the fimath (Fixed-Point Designer) properties.
See Specify fimath of Fixed-Point Input.
If you do not set the fimath (Fixed-Point Designer) 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 nonnegative.
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.
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.
| Input | Property | Value |
|---|---|---|
pennywhistle | class | int16 |
| size | 220500-by-1 vector | |
| complexity | real (by default) | |
win | class | double |
| size | 1024-by-1 vector | |
| complexity | real (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])); ...
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.
| Property | Value |
|---|---|
| class | fi |
numerictype | numerictype object T,
as specified in the primary function |
fimath | fimath object F, as specified
in the primary function |
| size | scalar |
| complexity | real (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);You must specify both the fi class and the numerictype.
To specify the class cell (cell
array), use one of the following syntaxes:
assert(iscell(param)) assert(isa( param, 'cell'))
For example, to set the class of input C to cell,
use:
... assert(iscell(C)); ...
or
... assert(isa(C, 'cell')); ...
You can also specify the size of the cell array and the properties of the cell array elements. The number of elements that you specify determines whether the cell array is homogeneous or heterogeneous. See Code Generation for Cell Arrays.
If you specify the properties of the first element only, the
cell array is homogeneous. For example, the following code specifies
that C is a 1x3 homogeneous cell array whose elements
are 1x1 double.
...
assert(isa(C, 'cell'));
assert(all(size(C) == [1 3]));
assert(isa(C{1}, 'double'));
... If you specify the properties of the first element only, but
also assign a structure type name to the cell array, the cell array
is heterogeneous. Each element has the properties of the first element.
For example, the following code specifies that C is
a 1x3 heterogeneous cell array. Each element is a 1x1 double.
...
assert(isa(C, 'cell'));
assert(all(size(C) == [1 3]));
assert(isa(C{1}, 'double'));
coder.cstructname(C, 'myname');
...If you specify the properties of each element, the cell array is heterogeneous. For example, the following code specifies a 1x2 heterogeneous cell array whose first element is 1x1 char and whose second element is 1x3 double.
...
assert(isa(C, 'cell'));
assert(all(size(C) == [1 2]));
assert(isa(C{1}, 'char'));
assert(all(size(C{2}) == [1 3]));
assert(isa(C{2}, 'double'));
...If you specify more than one element, you cannot specify that the cell array is variable size, even if all elements have the same properties. For example, the following code specifies a variable-size cell array. Because the code specifies the properties of the first and second elements, code generation fails.
...
assert(isa(C, 'cell'));
assert(all(size(C) <= [1 2]));
assert(isa(C{1}, 'double'));
assert(isa(C{2}, 'double'));
...In the previous example, if you specify the first element only, you can specify that the cell array is variable-size. For example:
...
assert(isa(C, 'cell'));
assert(all(size(C) <= [1 2]));
assert(isa(C{1}, 'double'));
...Suppose that you defineS as the following
scalar MATLAB structure:
S = struct('r',double(1),'i',int8(4));S and
its fields: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 do not 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. At a minimum, you must specify the class of a structure field.
For structure arrays, you must choose a representative element
of the array for specifying the properties of each field. For example,
assume that you have defined S as the following
1-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 by 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) == [1 2])); assert(isa(S(1).r,'double')); assert(isa(S(1).i,'int8'));