Documentation

Speeding Up Fixed-Point Execution with fiaccel

You can convert fixed-point MATLAB^® code to MEX functions using fiaccel. The generated MEX functions contain optimizations to automatically accelerate fixed-point algorithms to compiled C/C++ code speed in MATLAB. The fiaccel function can greatly increase the execution speed of your algorithms.

Running fiaccel

The basic command is:

fiaccel M_fcn

By default, fiaccel performs the following actions:

You can modify this default behavior by specifying one or more compiler options with fiaccel, separated by spaces on the command line.

Generated Files and Locations

fiaccel generates files in the following locations:

fiaccel/mex/M_fcn_name/html

You can change the name and location of generated files by using the options -o and -d when you run fiaccel.

In this example, you will use the fiaccel function to compile different parts of a simple algorithm. By comparing the run times of the two cases, you will see the benefits and best use of the fiaccel function.

function B = fi_matrix_column_sum(A)
% Sum the columns of matrix A.
%#codegen
    [m,n] = size(A);
    w = get(A,'WordLength') + ceil(log2(m));
    f = get(A,'FractionLength');
    B = fi(zeros(1,n),true,w,f);
    for j = 1:n
        for i = 1:m
            B(j) = B(j) + A(i,j);
        end
    end

% MATLAB
fipref('NumericTypeDisplay','short');
A = fi(randn(1000,10));
tic
B = fi_matrix_column_sum(A)
t_matrix_column_sum_m = toc

% fiaccel
fiaccel fi_matrix_column_sum -args {A} ...
-I [matlabroot '/toolbox/fixedpoint/fidemos']
tic
B = fi_matrix_column_sum_mex(A);
t_matrix_column_sum_mex = toc

% MATLAB
tic
[m,n] = size(A);
w = get(A,'WordLength') + ceil(log2(m));
f = get(A,'FractionLength');
B = fi(zeros(1,n),true,w,f);
for j = 1:n
    for i = 1:m
        B(j) = fi_scalar_sum(B(j),A(i,j));
        % B(j) = B(j) + A(i,j);
    end
end
t_scalar_sum_m = toc

% fiaccel
fiaccel fi_scalar_sum -args {B(1),A(1,1)} ...
-I [matlabroot '/toolbox/fixedpoint/fidemos']
tic
[m,n] = size(A);
w = get(A,'WordLength') + ceil(log2(m));
f = get(A,'FractionLength');
B = fi(zeros(1,n),true,w,f);
for j = 1:n
    for i = 1:m
        B(j) = fi_scalar_sum_mex(B(j),A(i,j));
        % B(j) = B(j) + A(i,j);
    end
end
t_scalar_sum_mex = toc

Data Type Override Using fiaccel

Fixed-Point Designer™ software ships with an example of how to generate a MEX function from MATLAB code. The code in the example takes the weighted average of a signal to create a lowpass filter. To run the example in the Help browser select MATLAB Examples under Fixed-Point Designer, and then select Fixed-Point Lowpass Filtering Using MATLAB for Code Generation.

You can specify data type override in this example by typing an extra command at the MATLAB prompt in the “Define Fixed-Point Parameters” section of the example. To turn data type override on, type the following command at the MATLAB prompt after running the reset(fipref) command in that section:

fipref('DataTypeOverride','TrueDoubles')

This command tells Fixed-Point Designer software to create all fi objects with type fi double. When you compile the code using the fiaccel command in the “Compile the M-File into a MEX File” section of the example, the resulting MEX-function uses floating-point data.

Specifying Default fimath Values for MEX Functions

MEX functions generated with fiaccel use the MATLAB default global fimath. The MATLAB factory default global fimath has the following properties:

RoundingMethod: Nearest
OverflowAction: Saturate
ProductMode: FullPrecision
SumMode: FullPrecision

When running MEX functions that depend on the MATLAB default fimath value, do not change this value during your MATLAB session. Otherwise, MATLAB generates a warning, alerting you to a mismatch between the compile-time and run-time fimath values. For example, create the following MATLAB function:

function y = test %#codegen 
y = fi(0); 

Generate the MEX function test_mex to use the factory setting of the MATLAB default fimath.

resetglobalfimath;
fiaccel test 

Run test_mex.

test_mex   

ans =        
  0            
       DataTypeMode: Fixed-point: binary point scaling            
       Signedness: Signed            
       WordLength: 16        
       FractionLength: 15

Modify the MATLAB default fimath value so it no longer matches the setting used at compile time.

F = fimath('RoundingMethod','Floor');
globalfimath(F); 

Clear the MEX function from memory and rerun it.

clear test_mex 
test_mex

testglobalfimath_mex 
Warning: This function was generated with a different default fimath than the current default.   
ans =        
   0            
      DataTypeMode: Fixed-point: binary point scaling            
      Signedness: Signed             
      WordLength: 16         
      FractionLength: 15