GNU Octave Manual Version 3 by John W. Eaton, David Bateman, Søren Hauberg Paperback (6"x9"), 568 pages ISBN 095461206X RRP £24.95 ($39.95) Get a printed copy>>>

GNU Octave Manual Version 3 Buy the book here >>> support free documentation

20.1.6.2 The Return Types of Operators and Functions

Octave attempts to return results of sparse matrix operations with an appropriate type, either sparse or full. When a matrix exceeds a certain density of non-zero elements it no longer makes sense to store it as a sparse matrix. For this reason, operators and functions that have a high probability of generating a full matrix result will always return a full matrix.

For example, adding a scalar constant to a sparse matrix returns a full matrix. This is true even if the constant is zero.

speye(3) + 0
=>   1  0  0
     0  1  0
     0  0  1

Additionally, if the optional setting sparse_auto_mutate is enabled, all sparse functions test the amount of memory occupied by their result to see if it is larger than the amount that would be used by the equivalent full matrix. Therefore speye (2) * 1 will return a full matrix, as the memory used for the full version is smaller than the sparse version.

As Octave provides a complete set of mixed operators and functions for full and sparse matrices, automatic conversion generally allows results to be computed in the most efficient way. However, a penalty can occur when a sparse matrix is promoted to a full matrix, and subsequent operations would resparsify the matrix. Such cases are rare, but can be artificially created. For example (fliplr(speye(3)) + speye(3)) - speye(3) gives a full matrix when it should give a sparse one. In general, where such cases occur, they impose only a small memory cost.

To avoid confusion, the sparse function, and other functions based on it (such as speye), always return a sparse matrix, even if the memory used will be larger than its full representation. This ensures that expressions such as diag (sparse([1,2,3]), -1) always return a sparse matrix.

Built-in Function: val = sparse_auto_mutate ()

Built-in Function: old_val = sparse_auto_mutate (new_val)

Query or set the internal variable that controls whether Octave will automatically mutate sparse matrices to real matrices to save memory. For example,

s = speye(3);
sparse_auto_mutate (false)
s (:, 1) = 1;
typeinfo (s)
=> sparse matrix
sparse_auto_mutate (true)
s (1, :) = 1;
typeinfo (s)
=> matrix

Note that the sparse_auto_mutate option is incompatible with Matlab, and so it is off by default.