function global_demo()
%---------------------------------------------------------------
%       USAGE: global_demo()
%
%      AUTHOR: Col David S. Gibson       DATE: 11 Feb 05
%    MODIFIED: Dr. Wayne Brown           DATE: 22 Aug 05
%
% DESCRIPTION: This program demonstrates the time cost of passing
%              (copying) large arguments versus using global
%              variables for sharing large data structures.
%
%      INPUTS: None
%
%     OUTPUTS: None
%
%  REFERENCES: None
%---------------------------------------------------------------
global Big_matrix     % large global matrix used for timing

Matrix_size = 500;    % # of rows and # of columns in Big_matrix
Num_repeats = 1000;   % # of times each function gets called

Big_matrix = zeros(Matrix_size); 

% display introduction

fprintf('\n\nComparison of global variables, arguments and nested functions.\n');
fprintf('Please wait ...');

% Test 1: pass the large array as an argument

tic
for Count = 1:Num_repeats
    Big_matrix = test_argument(Big_matrix);
end
Argument_time = toc;

% Test 2: access the large array using global memory

tic
for Count = 1:Num_repeats
    test_global()
end
Global_time = toc;

% Test 3: access the large array using a nested function

Nested_time = test_nested(Matrix_size, Num_repeats);

% Report timing results

fprintf('\n\n');
fprintf('Passing an argument:     %12.4f seconds\n', Argument_time)
fprintf('Using global memory:     %12.4f seconds (%g%% faster)\n', ...
        Global_time, Argument_time / Global_time );
fprintf('Using a nested function: %12.4f seconds (%g%% faster)\n', ...
        Nested_time, Argument_time / Nested_time );

end % function global_demo

%-----------------------------------------------------------------
%
% function test_argument - uses input argument, does not do much
%
%  INPUT ARGS: Big_matrix - a very big matrix
% OUTPUT ARGS: Big_matrix - input matrix with two elements set to 1
%
%-----------------------------------------------------------------
function Big_matrix = test_argument(Big_matrix)

    Big_matrix(1,1) = 1;       % modify 2 elements of the matrix
    Big_matrix(end,end) = 1;
    
end % test_argument

%-----------------------------------------------------------------
%
% function test_gobal - uses global variable, does not do much
%
%  INPUT ARGS: Big_matrix - a very big matrix
% OUTPUT ARGS: None
%
%-----------------------------------------------------------------
function test_global()

    global Big_matrix

    Big_matrix(1,1) = 2;       % modify 2 elements of the matrix
    Big_matrix(end,end) = 2;

end % test_global

%-----------------------------------------------------------------
%
% function test_nested - uses a local variable in a nested function
%
%  INPUT ARGS: None
% OUTPUT ARGS: None
%
%-----------------------------------------------------------------
function Nested_time = test_nested(Matrix_Size, Num_repeats)

    Big_matrix = zeros(Matrix_Size); % a local variable to test_nested()

    % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
    function change_big_matrix()
      Big_matrix(1,1) = 2;       % modify 2 elements of the matrix
      Big_matrix(end,end) = 2;
    end % change_big_matrix;
    % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  

    tic
    for Count = 1:Num_repeats
      change_big_matrix()
    end
    Nested_time = toc;

end % test_global

% end of global_demo.m