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

#### 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.

ISBN 095461206X | GNU Octave Manual Version 3 | See the print edition |