%% Multithreaded Computation
% Many MATLAB functions support multithreaded computation, providing
% improved performance on multicore and multiprocessor systems. These
% functions include linear algebra operations that call the BLAS library
% (e.g. matrix multiply, QR decomposition) and element-wise numerical
% operations (e.g. |sin|, |log|). This example shows the performance
% improvement for multiple functions on a dual-core system using two 
% computational threads.

%% Configuring Multithreaded Computation via the Preferences Panel
% To enable multithreaded computation, select *File* > *Preferences* >
% *General* > *Multithreading* and select *Enable multithreaded
% computation* as shown here:

%%
% <<MultithreadingPrefPanel.png>>

%%
% For optimal performance, it is recommended that you accept the default
% for *Maximum number of computational threads*, which is *Automatic*. 

%% About Helper Functions Used in this Demo 
% To illustrate performance improvement for multiple functions, this demo 
% uses the helper functions |setNumberOfComputationalThreads|,  
% |getNumberOfComputationalThreads|, and |runAndTimeOps|. These helper  
% functions are undocumented and unsupported at this time.

%% Checking that Multithreaded Computation is Enabled
% Check that multithreaded computation is enabled before proceeding. 
numThreads=getNumberOfComputationalThreads;              % Number of threads to test
if isempty(numThreads)
    fprintf('Multithreaded computation is disabled in your MATLAB session.\n');
    fprintf('Use Preferences to enable.\n');    
    return
end
%% Measuring Performance Improvement for a Single Operation
% This example uses two threads (defined in the variable |numThreads|) 
% for one sample operation, matrix multiply. You can experiment by   
% increasing the number of threads if your system has more than two CPUs. 
% There are some overhead costs associated with running code the first  
% time, so perform timing comparisons with a second and subsequent runs
% to remove effects of that overhead.

%%
% First, define some parameters and generate random data in variables |A|
% and |B|.
dataSize=500;              % Data size to test
A=rand(dataSize,dataSize); % Random square matrix
B=rand(dataSize,dataSize); % Random square matrix

%%
% Next, set the number of computational threads to one and time the
% operation of interest.
setNumberOfComputationalThreads(1); 
tic;
C=A*B;
time1=toc;
fprintf('Time for 1 thread  = %3.3f sec\n', time1);

%%
% Now, set the number of computational threads to |numThreads| and time the
% operation. You can experiment by increasing the number of threads if your
% system has more than two CPUs. 
setNumberOfComputationalThreads(numThreads); 
tic;
C=A*B;
timeN=toc;
fprintf('Time for %d threads = %3.3f sec\n', numThreads, timeN);

%%
% Calculate performance improvement.
speedup=time1/timeN;
fprintf('Speed-up is %3.3f\n',speedup);

%% Measuring Performance Improvement for Multiple Operations
% This example illustrates performance improvements for multiple functions. 
% It uses the helper function |runAndTimeOps| to compute the average of a 
% few runs. First, look at the helper function:
type runAndTimeOps

%%
% Now call the function. Set the number of computational threads to one and 
% time the operations.
setNumberOfComputationalThreads(1);         % Set number of threads
[time1thread functionNames]=runAndTimeOps;  % Time operations

%%
% Set the number of computational threads to |numThreads| and time the
% operations again.
setNumberOfComputationalThreads(numThreads); % Set number of threads
[timeNthreads functionNames]=runAndTimeOps;  % Time operations

%%
% Calculate performance improvements.
speedup=time1thread./timeNthreads;    % Speed-up for all functions

%% Plotting the Performance Improvements for the Operations
bar(speedup); % Plot speed-up for all operations as bar chart
title(['Performance Improvement with ' int2str(numThreads) ' Threads on Arrays of ' int2str(dataSize) 'x' int2str(dataSize)]);
ylabel('Performance Improvement');
set(gca, 'XTickLabel', functionNames);
ylim([0 ceil(numThreads*1.1)]); % Set Y axes to fixed max value
xlim([0 length(functionNames) + 1]); % Set X axes to fixed max value
grid;

%% Analyzing Performance Results and Other Issues
% As shown, not all functions benefit from multithreaded computation. 
% For example, simple element-wise multiplication does not because it is
% a memory-bound operation. For functions that benefit, performance gains on
% multicore and multiprocessor systems vary with data set size. You can
% experiment with the data set size in this example, or even plot improvements 
% against data set size.

%% 
% Note that element-wise operations do not run faster when directly called
% from the Command Window, or when used in cell execution or publishing, such
% as
%
% |>>y=sin(x);|

%%
% This is because element-wise multithreaded computation is provided by the 
% JIT/accelerator, which is not used in these situations.Run such code via 
% an M-file to see multithreaded computation performance gains.

%% Disabling Multithreaded Computation
% If you do not want to use multithreaded computation, disable it
% via Preferences.

displayEndOfDemoMessage(mfilename)