- publishing free software manuals
 GNU Octave Manual Version 3 by John W. Eaton, David Bateman, Søren HaubergPaperback (6"x9"), 568 pagesISBN 095461206XRRP £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