Inplace Modification/Pass by Reference in Matlab

David Gleich

Inplace is a Matlab package for working with matrices and vectors that are passed by reference instead of by value. This package allows variables to functions to be modified inplace. Previously, this behavior was not possible in Matlab.

News

2006-06-02: Initial version released.

Getting Inplace (Latest Version: 1.0)

The files for Inplace reside on the Mathworks Matlab Central File Exchange. The lastest version is always there.

Go to the Inplace page at the Matlab File Exchange.

To install Inplace,

Download the latest link from the File Exchange and unzip it to a directory of your choosing.
Open Matlab and change directory until you get to the directory where you unzipped it.
Change into the inplace subdirectory.
Compile @ipdouble/subsasgn.c and @ipint32/subsasgn.c. (Not necessary on Windows XP.)
```
cd @ipdouble
mex -O subsasgn.c
cd ..
cd @ipint32
mex -O subsasgn.c
cd ..
```

Try the built in test.

addpath(pwd); % Add the inplace directory to the pathcd test 
cd test
test_inplace

If the above steps do not work without errors, please send me an email with any error messages you get and your system configuration.

Documentation

Documentation for this library will be fairly limited until we understand what problems people have. At a high level, the package does little. It provides two classes, ipdouble and ipint32 (inplace double and inplace int32) that wrap Matlab's double and int32 matrices and vectors. The idea behind the package is simply to provide a way to modified arguments to a function directly without the necessity of returning the result and the hence, eliminating a copy required.

% define two functions
function a = add_one_return(a)
a(1) = a(1) + 1;

function add_one_inplace(a)
a(1) = a(1) + 1;

n = 1000000;
ntrials = 1000;

a = ones(n,1);
ipa = ipdouble(a);

tic;
for ii=1:ntrials
    a = add_one_return(a);
end
fprintf('Standard Matlab: %f seconds\n', toc);

tic;
for ii=1:ntrials
    add_one_inplace(ipa);
end
fprintf('Inplace Calls: %f seconds\n', toc);

The only difference between the two calls is that add_one_return

>> example1
Standard Matlab: 12.375000 seconds
Inplace Calls: 0.078000 seconds
>> ipa(1)
ans =
        1001
>> a(1)
ans =
        1001

The reason for the speed difference is that Matlab must copy the one million element vector every time the function returns. This results in tremendous overhead for changing a single element.

Hopefully it is obvious that we have tried to make the inplace objects behave like the built-in versions.

>> ipd = ipdouble(rand(5)); 
>> ipd                           % display works
>> size(ipd)                     % size works
>> ipd(1,:)                      % subscripting works
>> ipd(1,3:end)                  % subscripting with end works
>> ipd(:) = rand(5)              % assignment works
>> ipd(1,3:end) = ones(1,3)      % partial assignment works
>> ipd(:,1) = pi*ones(5,1)       % partial assignment works

However, this was not always possible. The following commands do not work like you think they will.

>> ipd = ipdouble(ones(5)) % create a 5x5 ipdouble of ones
ipd = 
     1     1     1     1     1
     1     1     1     1     1
     1     1     1     1     1
     1     1     1     1     1
     1     1     1     1     1
>> y = pi*ones(5,5);       % create another vector 

>> ipd2 = ipdouble(ipd);   % deep copy ipd
>> ipd2 = y; % overwrites ipd with a new double vector from a copied y.
>> assign(ipd, y); % the correct way to achieve the previous result.

>> ipd(6,6) = 1; % you cannot resize ipdouble objects

>> ipd = ipd + 1;  % the plus operation isn't directly implemented yet.
>> ipd2 = double(ipd) + 1; % almost works, but the result is not an ipdouble.
>> assign(ipd, double(ipd)+1); % this works correctly.

This section will grow as we understand what troubles people have.

Limitations

Right now, the library only works with Matlab 7.0 and above and with only matrices and vectors (no tensors or higher-dimensional arrays.)

Assignments must use the assign overload. assign(ipd,y); instead of ipd = y; This limitation occurs because we do not overload the equals operator.
You CANNOT change the size of an inplace matrix/vector. This limitation occurs because the memory occupied by the vector must not change. (There may be a way around this limitation in the future.)