Main Content

Generate MEX Code to Accelerate Simulation of Bouncing Balls

This example shows how to accelerate MATLAB® algorithm execution using a generated MEX function. It uses the codegen command to generate a MEX function for a complicated application that uses multiple MATLAB files. You can use codegen to check that your MATLAB code is suitable for code generation and, in many cases, to accelerate your MATLAB algorithm. You can run the MEX function to check for run-time errors.

Prerequisites

There are no prerequisites for this example.

About the run_balls Function

The run_balls.m function takes a single input to specify the number of bouncing balls to simulate. The simulation runs and plots the balls bouncing until there is no energy left and returns the state (positions) of all the balls.

type run_balls
% balls = run_balls(n)
% Given 'n' number of balls, run a simulation until the balls come to a
% complete halt (or when the system has no more kinetic energy).
function balls = run_balls(n) %#codegen

coder.extrinsic('fprintf');

%   Copyright 2010-2013 The MathWorks, Inc.

% Seeding the random number generator will guarantee that we get
% precisely the same simulation every time we call this function.
old_settings = rng(1283,'V4');

% The 'cdata' variable is a matrix representing the colordata bitmap which
% will be rendered at every time step.
cdata = zeros(400,600,'uint8');

% Setup figure windows
im = setup_figure_window(cdata);

% Get the initial configuration for 'n' balls.
balls = initialize_balls(cdata, n);

energy = 2; % Something greater than 1
iteration = 1;
while energy > 1
    % Clear the bitmap
    cdata(:,:) = 0;
    % Apply one iteration of movement
    [cdata,balls,energy] = step_function(cdata,balls);
    % Render the current state
    cdata = draw_balls(cdata, balls);
    iteration = iteration + 1;
    if mod(iteration,10) == 0
        fprintf(1, 'Iteration %d\n', iteration);
    end
    refresh_image(im, cdata);
end
fprintf(1, 'Completed iterations: %d\n', iteration);

% Restore RNG settings.
rng(old_settings);

Generate the MEX Function

First, generate a MEX function using the command codegen followed by the name of the MATLAB file to compile. Pass an example input (-args 0) to indicate that the generated MEX function will be called with an input of type double.

codegen run_balls -args 0
Code generation successful.

The run_balls function calls other MATLAB functions, but you need to specify only the entry-point function when calling codegen.

By default, codegen generates a MEX function named run_balls_mex in the current folder. This allows you to test the MATLAB code and MEX function and compare the results.

Compare Results

Run and time the original run_balls function followed by the generated MEX function.

tic, run_balls(50); t1 = toc;
Iteration 10
Iteration 20
Iteration 30
Iteration 40
Iteration 50
Iteration 60
Iteration 70
Iteration 80
Iteration 90
Iteration 100
Iteration 110
Iteration 120
Iteration 130
Iteration 140
Iteration 150
Iteration 160
Iteration 170
Iteration 180
Iteration 190
Iteration 200
Iteration 210
Iteration 220
Iteration 230
Iteration 240
Iteration 250
Iteration 260
Iteration 270
Iteration 280
Completed iterations: 281
tic, run_balls_mex(50); t2 = toc;

Figure MATLAB Coder Bouncing Balls contains an axes object. The axes object contains an object of type image.

Iteration 10
Iteration 20
Iteration 30
Iteration 40
Iteration 50
Iteration 60
Iteration 70
Iteration 80
Iteration 90
Iteration 100
Iteration 110
Iteration 120
Iteration 130
Iteration 140
Iteration 150
Iteration 160
Iteration 170
Iteration 180
Iteration 190
Iteration 200
Iteration 210
Iteration 220
Iteration 230
Iteration 240
Iteration 250
Iteration 260
Iteration 270
Iteration 280
Completed iterations: 281

Figure MATLAB Coder Bouncing Balls contains an axes object. The axes object contains an object of type image.

Estimated speed up is:

fprintf(1, 'Speed up: x ~%2.1f\n', t1/t2);
Speed up: x ~2.0